components/u8g2/doc/faq.txt

changeset 0
88d965579617
equal deleted inserted replaced
-1:000000000000 0:88d965579617
1 Sections
2 - Wiring... Interconnect, pin/label names
3 - Displays... Display support, display problems
4 - U8g2... Setup, compilation, usage, fonts
5
6
7 Wiring
8
9 Q: Why does my xxx_SW_I2C() device not work with my other I2C devices?
10 A: SW_I2C emulates I2C with digitalWrite(), which will have a conflict with other
11 I2C devices at the same pins. There are two options: (A) use xxx_HW_I2C() or
12 (B) use different pins with xxx_SW_I2C()
13
14 Q: My display has a pin labled as "A0" (or "RS"). How to connect this pin?
15 A: There are different names for the "data/command" pin. In U8g2 only the name
16 "dc" is used. On the display side it might be also called "A0", "RS", "CD".
17 See also the next question.
18
19 Q: My display has pins labled as "D0" and "D1". What is the interface and how
20 to connect these pins?
21 A: This is probably a SSD1306 OLED. The meaning of the D0 and D1 pin depends
22 on the configuration of the SSD1306. D0 is the clock line and D1 is the data line.
23
24 Q: For HW SPI no pin numbers are required in the constructor. But which are
25 the pin numbers for wiring?
26 A: This depends on your board. For some official boards, this is listed here:
27 https://www.arduino.cc/en/Reference/SPI
28 You need to connect MOSI (data) and SCK (clock) pins of your board with the
29 corresponding pins with your display.
30 All U8g2 software emulated SPI constructors look like this:
31 U8G2_..._4W_SW_SPI u8g2(U8G2_R0, clock, data, cs, dc, reset);
32 All U8g2 hardware SPI constructors look like this:
33 U8G2_..._4W_SW_SPI u8g2(U8G2_R0, cs, dc, reset);
34
35 Q: For HW I2C no pin numbers are required in the constructor. But which are
36 the pin numbers for wiring?
37 A: See same question for SPI. For some boards, the pins are listed here:
38 https://www.arduino.cc/en/Reference/Wire
39 All U8g2 software emulated I2C constructors look like this:
40 U8G2_..._SW_I2C u8g2(U8G2_R0, clock, data, reset);
41 All U8g2 hardware I2C constructors look like this:
42 U8G2_..._HW_I2C u8g2(U8G2_R0, reset);
43 Note: The HW_I2C allows to more arguments for hardware pin number remapping.
44 However, this is only supported on the ESP8266.
45
46 Q: The pin names on my display do not fit to the pin names of U8g2.
47 A: Yes, each datasheet/product/controller has different names. There
48 is a mapping table on the wiki for this:
49 https://github.com/olikraus/u8g2/wiki/u8g2setupcpp#wiring
50
51 Q: What is wrong with connecting Reset (RES) of my display with the Reset of my
52 Arduino Board?
53 A:
54 - Both are inputs. It does not make sense to connect two inputs
55 - Both pins have completly different functions: The reset of your board will reset
56 the Arduino board, the reset of the display will reset the display.
57 Please connect the reset input of the display with a normal GPIO pin of your board.
58
59 Q: Shell I connect CS (chip select) with the SS output of the Arduino board?
60 A: In general this is required neither for hardware or software SPI.
61
62 Q: My board has a MOSI and a SCK output. Do i need to connect this to the
63 clock and data pins of my display?
64 A: "Yes" if you want to use hardware SPI (u8g2 constructors ending in _HW_SPI).
65 You can use any pins with the software emulated SPI of u8g2 (constructors ending
66 in _SW_SPI). Howver in general it is better to use hardware SPI to get a better
67 performance of your display.
68
69 Q: How to wire ST7920 display in 8080 mode?
70 A:
71 - See also https://github.com/olikraus/u8g2/wiki/gallery#26-nov-2016-st7920-128x64-lcd-in-8080-parallel-mode
72 - Connect the RW (SID) input of your ST7920 display to ground.
73 - In the u8g2 constructor, use U8X8_PIN_NONE for "cs" signal
74 - The "dc" pin is called "RS" in the ST7920 documentation.
75 - See also issue #90: https://github.com/olikraus/u8g2/issues/90
76
77 Displays
78
79 Q: There is an x-offset on my SSD1306 128x64 OLED.
80 A: This is not a SSD1306 OLED, instead use the SH1106 constructor.
81
82 Q: A T6963 misses columns on the display/has garbled output.
83 A: Ensure that the T6963 operates in 8x8 mode:
84 If the display module has two font select (FSx) pins, connect both to GND
85 If the display module has one font select (FS) pin, connect it to GND
86
87 Q: My T6963 has a RD input. How shell this be connected?
88 A: The RD input for any 8080 interface has to be connected to power supply (5V or 3.3V,
89 depending on the display)
90
91 Q: My T6963 was working with u8glib, but it does not work with U8g2
92 A: The sequence of argument has changed from cs, a0, wr to wr, cs, a0:
93 U8GLIB_T6963_240X128 u8g(d0, d1, d2, d3, d4, d5, d6, d7, cs, dc, wr, rd, reset);
94 U8G2_T6963_240X128_1_8080 u8g2(U8G2_R0, d0, d1, d2, d3, d4, d5, d6, d7, wr, cs, dc, reset);
95
96
97 Q: My controller/interface combination is not listed in the examples.
98 A: Yes, the complete list is here:
99 https://github.com/olikraus/u8g2/wiki/u8g2setupcpp
100
101 Q: My display controller is listed, but the display dimension is not supported.
102 A: Raise an issue in the u8g2 tracker "https://github.com/olikraus/u8g2/issues"
103
104 Q: My controller is not listed, What can I do?
105 A: First check whether this controller is compatible to one of the supported
106 controller:
107 Supported: ST7565, Compatible: NT7534, UC1701, SED1565, S1D15605, S6B0723, SPLC502
108 Supported: SED1330, Compatible: SED1335, RA8835, S1D3305
109 Supported: LC7981, Compatible: NT7086, (maybe also: HD61830)
110 This table just reflects my current knowledge. It is not tested and may not be true at all.
111 Raise an issue in the u8g2 issue tracker, If your controller for a monochrome display is not listed.
112 A more detailed discussion of some controllers is listed in "controller_cmds.txt"
113
114
115 U8g2
116
117 Q: How to install u8g2 for Arduino?
118 A: The latest stable version of U8g2 is available as Arduino Library in the
119 "Manage Libraries..." browser. See also here: https://github.com/olikraus/u8g2/wiki/u8g2install
120 The latest development version is available for download here:
121 https://github.com/olikraus/U8g2_Arduino/archive/master.zip
122 In the Arduino IDE use the Sketch>Include Library>Add .ZIP Library... menu to
123 import the u8g2 zip library.
124
125 Q: There is a compilation error with I2C/SPI library used by U8g2.
126 A: U8g2 expects standard Arduino Wire and SPI libraries. However some
127 none-Arduino Boards did not implement the full set of library functions.
128 Examples are the missing setClock() or missing beginTransaction() functions.
129 This is an issue with your board support library and not an issue of U8g2.
130 Workaround:
131 1. Disable (comment) U8X8_HAVE_HW_SPI and/or U8X8_HAVE_HW_I2C in u8x8.h
132 2. Use SW SPI/SW I2C U8g2 constructors
133
134 Q: What is the meaning of the F/1/2 in the U8g2 constructor name?
135 A: "F" means full buffer mode. The entire display is rendered in RAM. Use
136 "sendBuffer" to transfer this RAM buffer to the display. "1" and "2" constructors
137 will store one or two pages of the display in RAM only. Use the firstPage/nextPage
138 loop to create the image for the display.
139
140 Q: What is the meaning of "SW"/"HW" in the U8g2 constructor name?
141 A: "SW" means, that the protocol is emulated by software. For example
142 the SW_I2C will not use the I2C subsystem of your board. The "HW" constructor
143 will use the hardware subsystem on your uC. For an Arduino board, HW_I2C will
144 call the Wire library for hardware accelerated I2C communication. "HW"
145 constructors are much faster, but maybe debugging and setup is more
146 easier with a "SW" constructor.
147
148 Q: Why does the hardware I2C accept clock and data pins?
149 The hardware I2C constructor looks like this:
150 U8G2_<display>_HW_I2C(rotation, [reset [, clock, data]])
151 This means there are three options to use this constructor:
152 1. U8G2_<display>_HW_I2C(rotation)
153 2. U8G2_<display>_HW_I2C(rotation, reset)
154 3. U8G2_<display>_HW_I2C(rotation, reset, clock, data)
155 Hardware I2C usually is possible only with fixed pins. This means, the first or
156 second form of the constructor must be used. As of today only the ESP8266
157 support pin remapping. In such a case, also the third form can be used.
158
159 Q: How to activate 16 Bit mode?
160 A: Search for the line
161 //#define U8G2_16BIT
162 in "u8g2.h". Uncomment this line:
163 #define U8G2_16BIT
164 The file "u8g2.h" is located in "/libraries/U8g2_Arduino/src/clib" inside your default
165 sketch folder.
166
167 Q: U8g2 requires a lot of memory. How to reduce this?
168 - Visit https://github.com/olikraus/u8g2/wiki/u8g2optimization
169 - Disable U8g2 features if possible (see u8g2.h)
170 - Limit the font size. If possible avoid "f" fonts, instead use "r" or "n" fonts
171 - If the I2C interface is not required, then uncomment #define U8X8_HAVE_HW_I2C in U8x8lib.h
172 (Background: Due to a problem in Wire.h, the I2C Arduino lib is always included)
173
174 Q: There is no visible output output. What is can be done?
175 - Check the wiring, see first part of this FAQ.
176 - Check the constructor. Does it fit to your display?
177 - Do not output a text at (0,0): The reference point for text is lower left, so
178 u8g2_DrawStr(&u8g2, 0, 0, “Hello world!”); will not display anything. Instead use
179 u8g2_DrawStr(&u8g2, 0, 20, “Hello world!”);
180
181 Q: Only a small fraction of the display is visible. Why?
182 A: With a "_1_" constructor, ensure to use the firstPage/nextPage loop.
183
184 Q: U8g2 output is corrupted. What are possible causes?
185 - Do not change the output inside the firstPage/nextPage loop:
186 Do *not* call digitalRead/analogRead inside the firstPage/nextPage loop.
187 Read any sensor values into a variable *before* firstPage() and use the
188 variable value inside the loop.
189 If the output includes unicode chars, use the UTF8 procedures.
190
191 Q: U8g2 is slow. How to improve speed?
192 A1: If there is sufficient RAM, use the F variant of the constructor (see the question
193 on F/1/2 above).
194 A2: Use hardware SPI or I2C communication. Software emulated SPI or I2C is much
195 slower (see the question on SW and HW SPI/I2C above)
196 A3: "firstPage/nextPage loop": Remove as much of code out of this loop. Try to
197 precalculate as much of possible before the loop is entered.
198 A4: "firstPage/nextPage loop": If the loop is still too slow, try to unroll the loop.
199 See the StateBufferLoop example:
200 https://github.com/olikraus/u8g2/blob/master/sys/arduino/u8g2_page_buffer/StateBufferLoop/StateBufferLoop.ino
201 A5: For SW I2C and AVR architectures: Uncomment
202 #define U8X8_USE_ARDUINO_AVR_SW_I2C_OPTIMIZATION
203 in U8x8lib.h. This will increase speed a lot for I2C on all AVR uC. However the I2C
204 bus is always driven by this implementation. Other I2C devices will not work on
205 the same pins.
206 A6: For HW I2C the default speed for some controllers is set 100KHz. However these
207 controller often work with higher speed (200KHz or 400KHz). Suggestion is
208 to test whether "u8g2.setBusClock(400000);" still works.
209
210 Q: Umlaut chars or other chars with a unicode value greater than 127 do not
211 appear on the displays. What is wrong?
212 A; Check the following:
213 Did you use drawUTF8() instead of drawStr()?
214 Did you enable UTF8 when using print() with enableUTF8Print()?
215 Does the font include the expected char? Fonts with a 'n' (numbers),
216 'u' (uppercase) or 'r' (restricted) at the end of the fontname do only
217 include glyphs with unicode lower than 128.
218
219 Q: How can I generate my own font.
220 A: The font must be available in bdf file format. Then use bdfconv to generate
221 the font data. The font data can be pasted into an existing file of your project.
222 There is also a nice Windows Bitmap Font Editor "Fony" (http://hukka.ncn.fi/?fony)
223 which can export .bdf files. A copy of Fony 1.4.7 is available here:
224 https://github.com/olikraus/u8g2/tree/master/tools/font/fony
225
226 Q: Which commandline options are required for bdfconv?
227 A: "bdfconv -f 1 -m '32-255' -n fontname -o myfont.c myfont.bdf"
228 "-f 1" generates a u8g2 font.
229 "-m '32-255'" selects unicode 32 to 255. On Windows, please use double quotes: -m "32-255"
230 "-n fontname": This is the name of the font in C/C++/Ino files.
231 "-o myfont.c": The font array will be stored in this file.
232 "myfont.bdf": The input file with the font data (bdf format).
233
234 Q: Where do I find bdfconv?
235 A: A Windows executable is available here:
236 https://github.com/olikraus/u8g2/tree/master/tools/font/bdfconv
237 Use the Makefile in this directory to create a Linux binary.
238
239 Q: How can I use multiple SPI Displays?
240 A: For each additional display, separate CS (Chip select) is required.
241 There are two options for the RST (Reset) line:
242 Also use separate lines or use the same GPIO pin.
243
244 // Setup display1 and display2, both reset lines are connected to 4, execute display1.begin() first.
245 U8G2_SSD1306_128X64_NONAME_F_4W_SW_SPI display1(U8G2_R0, /*CLK*/ 18, /*MOSI*/ 23, /*CS*/ 16,/*DC*/ 17, /*RST*/ 4);
246 U8G2_SSD1306_128X64_NONAME_F_4W_SW_SPI display2(U8G2_R0, /*CLK*/ 18, /*MOSI*/ 23, /*CS*/ 15,/*DC*/ 17, /*RST*/ U8X8_PIN_NONE);
247
248 // Setup display1 and display2, separate reset lines
249 U8G2_SSD1306_128X64_NONAME_F_4W_SW_SPI display1(U8G2_R0, /*CLK*/ 18, /*MOSI*/ 23, /*CS*/ 16,/*DC*/ 17, /*RST*/ 4);
250 U8G2_SSD1306_128X64_NONAME_F_4W_SW_SPI display2(U8G2_R0, /*CLK*/ 18, /*MOSI*/ 23, /*CS*/ 15,/*DC*/ 17, /*RST*/ 5);
251
252 Ensure that the buffer is sent after printing with each display as follows.
253
254 display1.begin();
255 display2.begin();
256 ...
257 display1.setCursor(64, 32);
258 display1.print("DISPLAY 1");
259 display1.sendBuffer();
260
261 display2.setCursor(64, 32);
262 display2.print("DISPLAY 2");
263 display2.sendBuffer();
264
265 Q: How can I send individual/special commands to my display.
266 A: The sequence is: Start transfer, send data and args, close transfer. Note that
267 this is not portable, because these commands are specific to the display controller.
268 The following C++/Arduino code will send one command with one argument to the
269 display:
270 u8x8_cad_StartTransfer(u8g2.getU8x8());
271 u8x8_cad_SendCmd( u8g2.getU8x8(), <display command>);
272 u8x8_cad_SendArg( u8g2.getU8x8(), <display-command-arg>);
273 u8x8_cad_EndTransfer(u8g2.getU8x8());
274

mercurial