Russification of the openGLCD library for Arduino
Writing Russian-language text on graphic displays with the ks0108 controller or its analogs still presents significant difficulties. The openGLCD library, which is recommended by the official Arduino sites, does not contain any Cyrillic fonts in the original configuration of the latest version at the moment, except for the cp437font8x8 font. In practice, it is of little use because it supports Win-1251 encoding in the Russian part. Consequently, in order to display characters in such a font, they must either be inserted into the text with octal or hexadecimal codes (and at the same time there are ambiguities with the lowercase letter "I", as the font creator himself points out in the commentary), or anyway write a separate conversion function like this made arduinec for Adafruit-GFX library.
Among other things, cp437font8x8 is large for 128x64 pixels. The optimal font size for auxiliary writing on this display is System5x7. Here we will focus on the Russification of the system font, although the reader can russify any other font on this model (especially if he has a bigger screen).
To begin with, let's get into the roots of the problem. The Arduino IDE is a regular Windows text editor that works in the universal UTF-8 encoding , like any other in modern versions of Windows (Notepad, for example). UTF-8 is an economical version of UNICODE multibyte encoding. In UTF-8, English-language characters, digits, comma-dots, brackets, and any other icons are represented by one byte that matches the standard ASCII character set . Therefore, their representation in the sketch code presents no difficulties: after compilation, the string of English characters is transferred to the downloaded hex file without changes and is understood by the 8-bit controller, as they say, “without translation”.
')
In the process of this transformation, each character, as in any program in any programming language, is represented directly in the form of its code, that is, the sequence number in the font table from which the program extracts the graphic outline of the corresponding character. In the openGLCD library's System5x7.h font file, the number of characters is represented by a font_Char_Count variable of type uint8_t , that is, it cannot exceed the value of one byte. Therefore, Cyrillic characters that occupy two bytes in UTF-8 cannot be transferred to the controller in the usual way.
The author did not go into the depths of library functions, but wrote an add-in for openGLCD as a function outstr () , which iterates through all the elements of the input line, passing them through the Switch operator. It catches Cyrillic characters from a string and replaces them with single-byte codes corresponding to the updated System5x7R.h font file .
For example, for the capital Russian letter “F”, the replacement string would be:
Here 0xA4 is the low byte of the letter F encoding in UTF-8 (see the link above). In accordance with this encoding, a new System5x7R.h font file has been compiled . In principle, with this approach, in the font, you can use any encoding of Russian characters and any other glyphs that you want to insert into the font. If only their total number does not exceed 128 pieces: from the beginning of the table to the character 0x7F (127 is the last character of the standard ASCII table) it is advisable to leave the font intact.
True, a couple of liberties with an ASCII table, I allowed myself. The fact is that in the original System5x7.h font, the degree icon is placed in the last row of the table, occupying the 0x80 character, which already belongs to the Cyrillic alphabet. In order not to disturb the order in which the Cyrillic table is constructed in accordance with UTF-8, this line is dropped from the file. And the degree icon is attached instead of the ASCII character “~” (number 0x7E), which in the font was still not used for its intended purpose. But such a replacement allows you to enter the degree icon in the text of the sketch directly from the keyboard as a "~" symbol.
Another liberty is due to the fact that the author does not tolerate crossed out zero - the archaic of the times of the ADC and monochrome text displays. Because zero in the modernized font is replaced by the glyph of the letter "O". Those who adhere to the puristic principles can simply delete this insert in the System5x7R.h font file (the old crossed out zero glyph is left there commented out, its code is 0x30).
In the modernized openGLCD library, which you can download via the link at the end of the article, one more correction was made - the order of connecting pins for displays with a ks0108 controller was changed. Why the author of the library chose such an order (see the table on the link on the official website of Arduino ) is unknown. In the modernized version, the display is connected (for example, the popular MT-12864J was chosen) according to this scheme:
The variable resistor R1 is connected according to the manufacturer's recommendation , and the R2 resistor is used to limit the backlight current if it is connected not to a 5 V voltage, but directly to an input power source (Vin Arduino pin) with a higher voltage.
An example of displaying the MT-12864J of the Russian alphabet interspersed with Latin, as well as numbers and a degree icon, is shown in the photo:
The sketch text for this example:
Since the files with the outstr.h function and the System5x7R.h font are located in the root directory of the upgraded library, separate links should be placed on them at the beginning of the sketch using the #include directive. For English inscriptions, it is convenient to continue using the standard println / print functions, but if you need a line feed in the Russian text, you must explicitly specify the “\ n” symbol.
A revised version of the library you can download here . The unpacked library ( openGLCD folder) should be placed in the Arduino \ libraries folder, as usual. An example of the sketch is located in the same archive separately (in the non-Examples folder of the library). Connecting the display with the controller ks0108 in accordance with this library is shown in the diagram above. If you want to additionally change the order of connecting pins, then find the PinConfig_ks0108-Uno.h file in the Arduino \ libraries \ openGLCD \ config \ ks0108 folder and edit the lines under the heading “Data pin definitions” and further, focusing on the author's corrections.
In the next publication we will try to understand the Russification of lowercase displays. As you will see, with them everything is both simpler and more complicated.
Among other things, cp437font8x8 is large for 128x64 pixels. The optimal font size for auxiliary writing on this display is System5x7. Here we will focus on the Russification of the system font, although the reader can russify any other font on this model (especially if he has a bigger screen).
What's the problem?
To begin with, let's get into the roots of the problem. The Arduino IDE is a regular Windows text editor that works in the universal UTF-8 encoding , like any other in modern versions of Windows (Notepad, for example). UTF-8 is an economical version of UNICODE multibyte encoding. In UTF-8, English-language characters, digits, comma-dots, brackets, and any other icons are represented by one byte that matches the standard ASCII character set . Therefore, their representation in the sketch code presents no difficulties: after compilation, the string of English characters is transferred to the downloaded hex file without changes and is understood by the 8-bit controller, as they say, “without translation”.
')
In the process of this transformation, each character, as in any program in any programming language, is represented directly in the form of its code, that is, the sequence number in the font table from which the program extracts the graphic outline of the corresponding character. In the openGLCD library's System5x7.h font file, the number of characters is represented by a font_Char_Count variable of type uint8_t , that is, it cannot exceed the value of one byte. Therefore, Cyrillic characters that occupy two bytes in UTF-8 cannot be transferred to the controller in the usual way.
Previous Attempts
Note that this was not always the case. Versions of Arduino 1.0.x (and, according to rumors, 1.6.0) truncated the two-byte code to one-byte, tritely discarding the most significant byte (which for Cyrillic, as follows from the UTF-8 table by reference, is either 0xD0 or 0xD1). Therefore, to refine the font in these versions of the environment, the old GLCD v3 library is suitable , in which the font array was simply supplemented with Cyrillic letters so that their positions coincided with the low byte of the UTF-8 encoding (bytes from 0x80 to 0xBF). Such modernization is described in more detail in the author’s article “Working with text on a graphic display” . I repeat - it needs one of the versions of the Arduino IDE 1.0.x in conjunction with the GLCD v3 library, and not their more modern versions.
The new versions of the Arduino IDE have become increasingly difficult. The library resolutely refuses to understand the two-byte character numbers, displaying an empty space instead, because you can’t get away with just changing the font. It is necessary to supplement it with the function of recoding double-byte characters into single-byte characters.
The new versions of the Arduino IDE have become increasingly difficult. The library resolutely refuses to understand the two-byte character numbers, displaying an empty space instead, because you can’t get away with just changing the font. It is necessary to supplement it with the function of recoding double-byte characters into single-byte characters.
Decision
The author did not go into the depths of library functions, but wrote an add-in for openGLCD as a function outstr () , which iterates through all the elements of the input line, passing them through the Switch operator. It catches Cyrillic characters from a string and replaces them with single-byte codes corresponding to the updated System5x7R.h font file .
For example, for the capital Russian letter “F”, the replacement string would be:
case '': GLCD.PutChar(0xA4); break; Here 0xA4 is the low byte of the letter F encoding in UTF-8 (see the link above). In accordance with this encoding, a new System5x7R.h font file has been compiled . In principle, with this approach, in the font, you can use any encoding of Russian characters and any other glyphs that you want to insert into the font. If only their total number does not exceed 128 pieces: from the beginning of the table to the character 0x7F (127 is the last character of the standard ASCII table) it is advisable to leave the font intact.
True, a couple of liberties with an ASCII table, I allowed myself. The fact is that in the original System5x7.h font, the degree icon is placed in the last row of the table, occupying the 0x80 character, which already belongs to the Cyrillic alphabet. In order not to disturb the order in which the Cyrillic table is constructed in accordance with UTF-8, this line is dropped from the file. And the degree icon is attached instead of the ASCII character “~” (number 0x7E), which in the font was still not used for its intended purpose. But such a replacement allows you to enter the degree icon in the text of the sketch directly from the keyboard as a "~" symbol.
Another liberty is due to the fact that the author does not tolerate crossed out zero - the archaic of the times of the ADC and monochrome text displays. Because zero in the modernized font is replaced by the glyph of the letter "O". Those who adhere to the puristic principles can simply delete this insert in the System5x7R.h font file (the old crossed out zero glyph is left there commented out, its code is 0x30).
In the modernized openGLCD library, which you can download via the link at the end of the article, one more correction was made - the order of connecting pins for displays with a ks0108 controller was changed. Why the author of the library chose such an order (see the table on the link on the official website of Arduino ) is unknown. In the modernized version, the display is connected (for example, the popular MT-12864J was chosen) according to this scheme:
Connection diagram MT-12864J
The variable resistor R1 is connected according to the manufacturer's recommendation , and the R2 resistor is used to limit the backlight current if it is connected not to a 5 V voltage, but directly to an input power source (Vin Arduino pin) with a higher voltage.
An example of displaying the MT-12864J of the Russian alphabet interspersed with Latin, as well as numbers and a degree icon, is shown in the photo:
The sketch text for this example:
The text of the sketch with the conclusion of the Russian alphabet
#include <openGLCD.h> // #include <outstr.h> // #include <System5x7R.h> // void setup() { GLCD.Init(); // GLCD.ClearScreen(); } void loop() { GLCD.SelectFont(System5x7R); // GLCD.CursorTo(0,0); // // - : outstr("ABC \n"); outstr("PRQ \n"); outstr("nts \n"); outstr("xyz \n"); GLCD.println("1234567890"); GLCD.CursorTo(19,4); // 5- GLCD.print("~C"); // GLCD.println("@;/.,|<>()=-_{}\"'"); GLCD.CursorTo(4,7); // 4 8 GLCD.print("MT-12864J"); } Since the files with the outstr.h function and the System5x7R.h font are located in the root directory of the upgraded library, separate links should be placed on them at the beginning of the sketch using the #include directive. For English inscriptions, it is convenient to continue using the standard println / print functions, but if you need a line feed in the Russian text, you must explicitly specify the “\ n” symbol.
A revised version of the library you can download here . The unpacked library ( openGLCD folder) should be placed in the Arduino \ libraries folder, as usual. An example of the sketch is located in the same archive separately (in the non-Examples folder of the library). Connecting the display with the controller ks0108 in accordance with this library is shown in the diagram above. If you want to additionally change the order of connecting pins, then find the PinConfig_ks0108-Uno.h file in the Arduino \ libraries \ openGLCD \ config \ ks0108 folder and edit the lines under the heading “Data pin definitions” and further, focusing on the author's corrections.
In the next publication we will try to understand the Russification of lowercase displays. As you will see, with them everything is both simpler and more complicated.
Source: https://habr.com/ru/post/400749/
All Articles