diff -r 000000000000 -r 88d965579617 components/u8g2/doc/faq.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/u8g2/doc/faq.txt Tue Oct 08 12:00:31 2019 +0200 @@ -0,0 +1,274 @@ +Sections +- Wiring... Interconnect, pin/label names +- Displays... Display support, display problems +- U8g2... Setup, compilation, usage, fonts + + +Wiring + +Q: Why does my xxx_SW_I2C() device not work with my other I2C devices? +A: SW_I2C emulates I2C with digitalWrite(), which will have a conflict with other +I2C devices at the same pins. There are two options: (A) use xxx_HW_I2C() or +(B) use different pins with xxx_SW_I2C() + +Q: My display has a pin labled as "A0" (or "RS"). How to connect this pin? +A: There are different names for the "data/command" pin. In U8g2 only the name +"dc" is used. On the display side it might be also called "A0", "RS", "CD". +See also the next question. + +Q: My display has pins labled as "D0" and "D1". What is the interface and how +to connect these pins? +A: This is probably a SSD1306 OLED. The meaning of the D0 and D1 pin depends +on the configuration of the SSD1306. D0 is the clock line and D1 is the data line. + +Q: For HW SPI no pin numbers are required in the constructor. But which are +the pin numbers for wiring? +A: This depends on your board. For some official boards, this is listed here: +https://www.arduino.cc/en/Reference/SPI +You need to connect MOSI (data) and SCK (clock) pins of your board with the +corresponding pins with your display. +All U8g2 software emulated SPI constructors look like this: +U8G2_..._4W_SW_SPI u8g2(U8G2_R0, clock, data, cs, dc, reset); +All U8g2 hardware SPI constructors look like this: +U8G2_..._4W_SW_SPI u8g2(U8G2_R0, cs, dc, reset); + +Q: For HW I2C no pin numbers are required in the constructor. But which are +the pin numbers for wiring? +A: See same question for SPI. For some boards, the pins are listed here: +https://www.arduino.cc/en/Reference/Wire +All U8g2 software emulated I2C constructors look like this: +U8G2_..._SW_I2C u8g2(U8G2_R0, clock, data, reset); +All U8g2 hardware I2C constructors look like this: +U8G2_..._HW_I2C u8g2(U8G2_R0, reset); +Note: The HW_I2C allows to more arguments for hardware pin number remapping. +However, this is only supported on the ESP8266. + +Q: The pin names on my display do not fit to the pin names of U8g2. +A: Yes, each datasheet/product/controller has different names. There +is a mapping table on the wiki for this: +https://github.com/olikraus/u8g2/wiki/u8g2setupcpp#wiring + +Q: What is wrong with connecting Reset (RES) of my display with the Reset of my +Arduino Board? +A: +- Both are inputs. It does not make sense to connect two inputs +- Both pins have completly different functions: The reset of your board will reset +the Arduino board, the reset of the display will reset the display. +Please connect the reset input of the display with a normal GPIO pin of your board. + +Q: Shell I connect CS (chip select) with the SS output of the Arduino board? +A: In general this is required neither for hardware or software SPI. + +Q: My board has a MOSI and a SCK output. Do i need to connect this to the +clock and data pins of my display? +A: "Yes" if you want to use hardware SPI (u8g2 constructors ending in _HW_SPI). +You can use any pins with the software emulated SPI of u8g2 (constructors ending +in _SW_SPI). Howver in general it is better to use hardware SPI to get a better +performance of your display. + +Q: How to wire ST7920 display in 8080 mode? +A: +- See also https://github.com/olikraus/u8g2/wiki/gallery#26-nov-2016-st7920-128x64-lcd-in-8080-parallel-mode +- Connect the RW (SID) input of your ST7920 display to ground. +- In the u8g2 constructor, use U8X8_PIN_NONE for "cs" signal +- The "dc" pin is called "RS" in the ST7920 documentation. +- See also issue #90: https://github.com/olikraus/u8g2/issues/90 + +Displays + +Q: There is an x-offset on my SSD1306 128x64 OLED. +A: This is not a SSD1306 OLED, instead use the SH1106 constructor. + +Q: A T6963 misses columns on the display/has garbled output. +A: Ensure that the T6963 operates in 8x8 mode: +If the display module has two font select (FSx) pins, connect both to GND +If the display module has one font select (FS) pin, connect it to GND + +Q: My T6963 has a RD input. How shell this be connected? +A: The RD input for any 8080 interface has to be connected to power supply (5V or 3.3V, +depending on the display) + +Q: My T6963 was working with u8glib, but it does not work with U8g2 +A: The sequence of argument has changed from cs, a0, wr to wr, cs, a0: +U8GLIB_T6963_240X128 u8g(d0, d1, d2, d3, d4, d5, d6, d7, cs, dc, wr, rd, reset); +U8G2_T6963_240X128_1_8080 u8g2(U8G2_R0, d0, d1, d2, d3, d4, d5, d6, d7, wr, cs, dc, reset); + + +Q: My controller/interface combination is not listed in the examples. +A: Yes, the complete list is here: +https://github.com/olikraus/u8g2/wiki/u8g2setupcpp + +Q: My display controller is listed, but the display dimension is not supported. +A: Raise an issue in the u8g2 tracker "https://github.com/olikraus/u8g2/issues" + +Q: My controller is not listed, What can I do? +A: First check whether this controller is compatible to one of the supported +controller: +Supported: ST7565, Compatible: NT7534, UC1701, SED1565, S1D15605, S6B0723, SPLC502 +Supported: SED1330, Compatible: SED1335, RA8835, S1D3305 +Supported: LC7981, Compatible: NT7086, (maybe also: HD61830) +This table just reflects my current knowledge. It is not tested and may not be true at all. +Raise an issue in the u8g2 issue tracker, If your controller for a monochrome display is not listed. +A more detailed discussion of some controllers is listed in "controller_cmds.txt" + + +U8g2 + +Q: How to install u8g2 for Arduino? +A: The latest stable version of U8g2 is available as Arduino Library in the +"Manage Libraries..." browser. See also here: https://github.com/olikraus/u8g2/wiki/u8g2install +The latest development version is available for download here: +https://github.com/olikraus/U8g2_Arduino/archive/master.zip +In the Arduino IDE use the Sketch>Include Library>Add .ZIP Library... menu to +import the u8g2 zip library. + +Q: There is a compilation error with I2C/SPI library used by U8g2. +A: U8g2 expects standard Arduino Wire and SPI libraries. However some +none-Arduino Boards did not implement the full set of library functions. +Examples are the missing setClock() or missing beginTransaction() functions. +This is an issue with your board support library and not an issue of U8g2. +Workaround: +1. Disable (comment) U8X8_HAVE_HW_SPI and/or U8X8_HAVE_HW_I2C in u8x8.h +2. Use SW SPI/SW I2C U8g2 constructors + +Q: What is the meaning of the F/1/2 in the U8g2 constructor name? +A: "F" means full buffer mode. The entire display is rendered in RAM. Use +"sendBuffer" to transfer this RAM buffer to the display. "1" and "2" constructors +will store one or two pages of the display in RAM only. Use the firstPage/nextPage +loop to create the image for the display. + +Q: What is the meaning of "SW"/"HW" in the U8g2 constructor name? +A: "SW" means, that the protocol is emulated by software. For example +the SW_I2C will not use the I2C subsystem of your board. The "HW" constructor +will use the hardware subsystem on your uC. For an Arduino board, HW_I2C will +call the Wire library for hardware accelerated I2C communication. "HW" +constructors are much faster, but maybe debugging and setup is more +easier with a "SW" constructor. + +Q: Why does the hardware I2C accept clock and data pins? +The hardware I2C constructor looks like this: +U8G2__HW_I2C(rotation, [reset [, clock, data]]) +This means there are three options to use this constructor: +1. U8G2__HW_I2C(rotation) +2. U8G2__HW_I2C(rotation, reset) +3. U8G2__HW_I2C(rotation, reset, clock, data) +Hardware I2C usually is possible only with fixed pins. This means, the first or +second form of the constructor must be used. As of today only the ESP8266 +support pin remapping. In such a case, also the third form can be used. + +Q: How to activate 16 Bit mode? +A: Search for the line +//#define U8G2_16BIT +in "u8g2.h". Uncomment this line: +#define U8G2_16BIT +The file "u8g2.h" is located in "/libraries/U8g2_Arduino/src/clib" inside your default +sketch folder. + +Q: U8g2 requires a lot of memory. How to reduce this? +- Visit https://github.com/olikraus/u8g2/wiki/u8g2optimization +- Disable U8g2 features if possible (see u8g2.h) +- Limit the font size. If possible avoid "f" fonts, instead use "r" or "n" fonts +- If the I2C interface is not required, then uncomment #define U8X8_HAVE_HW_I2C in U8x8lib.h + (Background: Due to a problem in Wire.h, the I2C Arduino lib is always included) + +Q: There is no visible output output. What is can be done? +- Check the wiring, see first part of this FAQ. +- Check the constructor. Does it fit to your display? +- Do not output a text at (0,0): The reference point for text is lower left, so + u8g2_DrawStr(&u8g2, 0, 0, “Hello world!”); will not display anything. Instead use + u8g2_DrawStr(&u8g2, 0, 20, “Hello world!”); + +Q: Only a small fraction of the display is visible. Why? +A: With a "_1_" constructor, ensure to use the firstPage/nextPage loop. + +Q: U8g2 output is corrupted. What are possible causes? +- Do not change the output inside the firstPage/nextPage loop: +Do *not* call digitalRead/analogRead inside the firstPage/nextPage loop. +Read any sensor values into a variable *before* firstPage() and use the +variable value inside the loop. +If the output includes unicode chars, use the UTF8 procedures. + +Q: U8g2 is slow. How to improve speed? +A1: If there is sufficient RAM, use the F variant of the constructor (see the question +on F/1/2 above). +A2: Use hardware SPI or I2C communication. Software emulated SPI or I2C is much +slower (see the question on SW and HW SPI/I2C above) +A3: "firstPage/nextPage loop": Remove as much of code out of this loop. Try to +precalculate as much of possible before the loop is entered. +A4: "firstPage/nextPage loop": If the loop is still too slow, try to unroll the loop. +See the StateBufferLoop example: +https://github.com/olikraus/u8g2/blob/master/sys/arduino/u8g2_page_buffer/StateBufferLoop/StateBufferLoop.ino +A5: For SW I2C and AVR architectures: Uncomment +#define U8X8_USE_ARDUINO_AVR_SW_I2C_OPTIMIZATION +in U8x8lib.h. This will increase speed a lot for I2C on all AVR uC. However the I2C +bus is always driven by this implementation. Other I2C devices will not work on +the same pins. +A6: For HW I2C the default speed for some controllers is set 100KHz. However these +controller often work with higher speed (200KHz or 400KHz). Suggestion is +to test whether "u8g2.setBusClock(400000);" still works. + +Q: Umlaut chars or other chars with a unicode value greater than 127 do not +appear on the displays. What is wrong? +A; Check the following: +Did you use drawUTF8() instead of drawStr()? +Did you enable UTF8 when using print() with enableUTF8Print()? +Does the font include the expected char? Fonts with a 'n' (numbers), +'u' (uppercase) or 'r' (restricted) at the end of the fontname do only +include glyphs with unicode lower than 128. + +Q: How can I generate my own font. +A: The font must be available in bdf file format. Then use bdfconv to generate +the font data. The font data can be pasted into an existing file of your project. +There is also a nice Windows Bitmap Font Editor "Fony" (http://hukka.ncn.fi/?fony) +which can export .bdf files. A copy of Fony 1.4.7 is available here: +https://github.com/olikraus/u8g2/tree/master/tools/font/fony + +Q: Which commandline options are required for bdfconv? +A: "bdfconv -f 1 -m '32-255' -n fontname -o myfont.c myfont.bdf" +"-f 1" generates a u8g2 font. +"-m '32-255'" selects unicode 32 to 255. On Windows, please use double quotes: -m "32-255" +"-n fontname": This is the name of the font in C/C++/Ino files. +"-o myfont.c": The font array will be stored in this file. +"myfont.bdf": The input file with the font data (bdf format). + +Q: Where do I find bdfconv? +A: A Windows executable is available here: +https://github.com/olikraus/u8g2/tree/master/tools/font/bdfconv +Use the Makefile in this directory to create a Linux binary. + +Q: How can I use multiple SPI Displays? +A: For each additional display, separate CS (Chip select) is required. +There are two options for the RST (Reset) line: +Also use separate lines or use the same GPIO pin. + +// Setup display1 and display2, both reset lines are connected to 4, execute display1.begin() first. +U8G2_SSD1306_128X64_NONAME_F_4W_SW_SPI display1(U8G2_R0, /*CLK*/ 18, /*MOSI*/ 23, /*CS*/ 16,/*DC*/ 17, /*RST*/ 4); +U8G2_SSD1306_128X64_NONAME_F_4W_SW_SPI display2(U8G2_R0, /*CLK*/ 18, /*MOSI*/ 23, /*CS*/ 15,/*DC*/ 17, /*RST*/ U8X8_PIN_NONE); + +// Setup display1 and display2, separate reset lines +U8G2_SSD1306_128X64_NONAME_F_4W_SW_SPI display1(U8G2_R0, /*CLK*/ 18, /*MOSI*/ 23, /*CS*/ 16,/*DC*/ 17, /*RST*/ 4); +U8G2_SSD1306_128X64_NONAME_F_4W_SW_SPI display2(U8G2_R0, /*CLK*/ 18, /*MOSI*/ 23, /*CS*/ 15,/*DC*/ 17, /*RST*/ 5); + +Ensure that the buffer is sent after printing with each display as follows. + + display1.begin(); + display2.begin(); + ... + display1.setCursor(64, 32); + display1.print("DISPLAY 1"); + display1.sendBuffer(); + + display2.setCursor(64, 32); + display2.print("DISPLAY 2"); + display2.sendBuffer(); + +Q: How can I send individual/special commands to my display. +A: The sequence is: Start transfer, send data and args, close transfer. Note that +this is not portable, because these commands are specific to the display controller. +The following C++/Arduino code will send one command with one argument to the +display: + u8x8_cad_StartTransfer(u8g2.getU8x8()); + u8x8_cad_SendCmd( u8g2.getU8x8(), ); + u8x8_cad_SendArg( u8g2.getU8x8(), ); + u8x8_cad_EndTransfer(u8g2.getU8x8()); +