diff --git a/README.md b/README.md index 3abe1f6d..35f8bd22 100644 --- a/README.md +++ b/README.md @@ -411,62 +411,6 @@ Victor Brutskiy's [ESPlorer](https://github.com/4refr0nt/ESPlorer) is written in package.loaded["ds18b20"]=nil ``` -####Operate a display with ucglib -Ucglib is a graphics library with support for color TFT displays. - -Ucglib v1.3.3 - -#####SPI connection -The HSPI module is used, so certain pins are fixed: -* HSPI CLK = GPIO14 -* HSPI MOSI = GPIO13 -* HSPI MISO = GPIO12 (not used) - -All other pins can be assigned to any available GPIO: -* CS -* D/C -* RES (optional for some displays) - -Also refer to the initialization sequence eg in [GraphicsTest.lua](lua_examples/ucglib/GraphicsRest.lua): -```lua -spi.setup(1, spi.MASTER, spi.CPOL_LOW, spi.CPHA_LOW, 8, 8) -``` - -#####Library usage -The Lua bindings for this library closely follow ucglib's object oriented C++ API. Based on the ucg class, you create an object for your display type. - -ILI9341 via SPI: -```lua -cs = 8 -- GPIO15, pull-down 10k to GND -dc = 4 -- GPIO2 -res = 0 -- GPIO16, RES is optional YMMV -disp = ucg.ili9341_18x240x320_hw_spi(cs, dc, res) -``` - -This object provides all of ucglib's methods to control the display. -Again, refer to [GraphicsTest.lua](lua_examples/ucglib/GraphicsTest.lua) to get an impression how this is achieved with Lua code. Visit the [ucglib homepage](https://github.com/olikraus/ucglib) for technical details. - -#####Displays -To get access to the display constructors, add the desired entries to the display table in [app/include/ucg_config.h](app/include/ucg_config.h): -```c -#define UCG_DISPLAY_TABLE \ - UCG_DISPLAY_TABLE_ENTRY(ili9341_18x240x320_hw_spi, ucg_dev_ili9341_18x240x320, ucg_ext_ili9341_18) \ - UCG_DISPLAY_TABLE_ENTRY(st7735_18x128x160_hw_spi, ucg_dev_st7735_18x128x160, ucg_ext_st7735_18) \ -``` - -#####Fonts -ucglib comes with a wide range of fonts for small displays. Since they need to be compiled into the firmware image, you'd need to include them in [app/include/ucg_config.h](app/include/ucg_config.h) and recompile. Simply add the desired fonts to the font table: -```c -#define UCG_FONT_TABLE \ - UCG_FONT_TABLE_ENTRY(font_7x13B_tr) \ - UCG_FONT_TABLE_ENTRY(font_helvB12_hr) \ - UCG_FONT_TABLE_ENTRY(font_helvB18_hr) \ - UCG_FONT_TABLE_ENTRY(font_ncenR12_tr) \ - UCG_FONT_TABLE_ENTRY(font_ncenR14_hr) -``` -They'll be available as `ucg.` in Lua. - - ####Control a WS2812 based light strip ```lua -- set the color of one LED on GPIO2 to red diff --git a/docs/en/modules/ucg.md b/docs/en/modules/ucg.md new file mode 100644 index 00000000..690660b8 --- /dev/null +++ b/docs/en/modules/ucg.md @@ -0,0 +1,222 @@ +# ucg Module +Ucglib is a graphics library developed at [olikraus/ucglib](https://github.com/olikraus/ucglib) with support for color TFT displays. The NodeMCU firmware supports a subset of these: + +- ILI9163 +- ILI9341 +- PCF8833 +- SEPS225 +- SSD1331 +- SSD1351 +- ST7735 + +This integration is based on [v1.3.3](https://github.com/olikraus/Ucglib_Arduino/releases/tag/v1.3.3). + +## Overview + +### SPI Connection + +The HSPI module is used, so certain pins are fixed: + +* HSPI CLK = GPIO14 +* HSPI MOSI = GPIO13 +* HSPI MISO = GPIO12 (not used) + +All other pins can be assigned to any available GPIO: + +* CS +* D/C +* RES (optional for some displays) + +Also refer to the initialization sequence eg in [GraphicsTest.lua](https://github.com/nodemcu/nodemcu-firmware/blob/master/lua_examples/ucglib/GraphicsRest.lua): +```lua +spi.setup(1, spi.MASTER, spi.CPOL_LOW, spi.CPHA_LOW, 8, 8) +``` + +### Library Usage +The Lua bindings for this library closely follow ucglib's object oriented C++ API. Based on the ucg class, you create an object for your display type. + +ILI9341 via SPI: +```lua +cs = 8 -- GPIO15, pull-down 10k to GND +dc = 4 -- GPIO2 +res = 0 -- GPIO16, RES is optional YMMV +disp = ucg.ili9341_18x240x320_hw_spi(cs, dc, res) +``` + +This object provides all of ucglib's methods to control the display. +Again, refer to [GraphicsTest.lua](https://github.com/nodemcu/nodemcu-firmware/blob/master/lua_examples/ucglib/GraphicsTest.lua) to get an impression how this is achieved with Lua code. Visit the [ucglib homepage](https://github.com/olikraus/ucglib) for technical details. + +### Displays +o get access to the display constructors, add the desired entries to the display table in [app/include/ucg_config.h](https://github.com/nodemcu/nodemcu-firmware/blob/master/app/include/ucg_config.h): +```c +#define UCG_DISPLAY_TABLE \ + UCG_DISPLAY_TABLE_ENTRY(ili9341_18x240x320_hw_spi, ucg_dev_ili9341_18x240x320, ucg_ext_ili9341_18) \ + UCG_DISPLAY_TABLE_ENTRY(st7735_18x128x160_hw_spi, ucg_dev_st7735_18x128x160, ucg_ext_st7735_18) \ +``` + +### Fonts +ucglib comes with a wide range of fonts for small displays. Since they need to be compiled into the firmware image, you'd need to include them in [app/include/ucg_config.h](https://github.com/nodemcu/nodemcu-firmware/blob/master/app/include/ucg_config.h) and recompile. Simply add the desired fonts to the font table: +```c +#define UCG_FONT_TABLE \ + UCG_FONT_TABLE_ENTRY(font_7x13B_tr) \ + UCG_FONT_TABLE_ENTRY(font_helvB12_hr) \ + UCG_FONT_TABLE_ENTRY(font_helvB18_hr) \ + UCG_FONT_TABLE_ENTRY(font_ncenR12_tr) \ + UCG_FONT_TABLE_ENTRY(font_ncenR14_hr) +``` +They'll be available as `ucg.` in Lua. + +## Display Drivers + +Initialize a display via Hardware SPI. + +- `ili9163_18x128x128_hw_spi()` +- `ili9341_18x240x320_hw_spi()` +- `pcf8833_16x132x132_hw_spi()` +- `seps225_16x128x128_univision_hw_spi()` +- `ssd1351_18x128x128_hw_spi()` +- `ssd1351_18x128x128_ft_hw_spi()` +- `ssd1331_18x96x64_univision_hw_spi()` +- `st7735_18x128x160_hw_spi()` + +#### Syntax +`ucg.st7735_18x128x160_hw_spi(cs, dc, res)` + +#### Parameters +- `cs`: GPIO pin for /CS. +- `dc`: GPIO pin for DC. +- `res`: GPIO pin for /RES (optional). + +#### Returns +ucg display object. + +#### Example +```lua +spi.setup(1, spi.MASTER, spi.CPOL_LOW, spi.CPHA_LOW, spi.DATABITS_8, 0) + +cs = 8 -- GPIO15, pull-down 10k to GND +dc = 4 -- GPIO2 +res = 0 -- GPIO16, RES is optional YMMV +disp = ucg.st7735_18x128x160_hw_spi(cs, dc, res) +``` + +## Constants +`ucg.FONT_MODE_TRANSPARENT`, `ucg.FONT_MODE_SOLID`, `ucg.DRAW_UPPER_RIGHT`, +`ucg.DRAW_UPPER_LEFT`, `ucg.DRAW_LOWER_RIGHT`, `ucg.DRAW_LOWER_LEFT`, `ucg.DRAW_ALL` + +`ucg.font_7x13B_tr`, ... + +# ucg.disp Sub-Module + +## [ucg.disp:begin()](https://github.com/olikraus/ucglib/wiki/reference#begin) + +## [ucg.disp:clearScreen()](https://github.com/olikraus/ucglib/wiki/reference#clearscreen) + +## [ucg.disp:draw90Line()](https://github.com/olikraus/ucglib/wiki/reference#draw90line) + +## [ucg.disp:drawBox()](https://github.com/olikraus/ucglib/wiki/reference#drawbox) + +## [ucg.disp:drawCircle()](https://github.com/olikraus/ucglib/wiki/reference#drawcircle) + +## [ucg.disp:drawDisc()](https://github.com/olikraus/ucglib/wiki/reference#drawdisc) + +## [ucg.disp:drawFrame()](https://github.com/olikraus/ucglib/wiki/reference#drawframe) + +## [ucg.disp:drawGlyph()](https://github.com/olikraus/ucglib/wiki/reference#drawglyph) + +## [ucg.disp:drawGradientBox()](https://github.com/olikraus/ucglib/wiki/reference#drawgradientbox) + +## [ucg.disp:drawGradientLine()](https://github.com/olikraus/ucglib/wiki/reference#drawgradientline) + +## [ucg.disp:drawHLine()](https://github.com/olikraus/ucglib/wiki/reference#drawhline) + +## [ucg.disp:drawLine()](https://github.com/olikraus/ucglib/wiki/reference#drawline) + +## [ucg.disp:drawPixel()](https://github.com/olikraus/ucglib/wiki/reference#drawpixel) + +## [ucg.disp:drawRBox()](https://github.com/olikraus/ucglib/wiki/reference#drawrbox) + +## [ucg.disp:drawRFrame()](https://github.com/olikraus/ucglib/wiki/reference#drawrframe) + +## [ucg.disp:drawString()](https://github.com/olikraus/ucglib/wiki/reference#drawstring) + +## [ucg.disp:drawTetragon()](https://github.com/olikraus/ucglib/wiki/reference#drawtetragon) + +## [ucg.disp:drawTriangle()](https://github.com/olikraus/ucglib/wiki/reference#drawrtiangle) + +## [ucg.disp:drawVLine()](https://github.com/olikraus/ucglib/wiki/reference#drawvline) + +## [ucg.disp:getFontAscent()](https://github.com/olikraus/ucglib/wiki/reference#getfontascent) + +## [ucg.disp:getFontDescent()](https://github.com/olikraus/ucglib/wiki/reference#getfontdescent) + +## [ucg.disp:getHeight()](https://github.com/olikraus/ucglib/wiki/reference#getheight) + +## [ucg.disp:getStrWidth()](https://github.com/olikraus/ucglib/wiki/reference#getstrwidth) + +## [ucg.disp:getWidth()](https://github.com/olikraus/ucglib/wiki/reference#getwidth) + +## [ucg.disp:print()](https://github.com/olikraus/ucglib/wiki/reference#print) + +## [ucg.disp:setClipRange()](https://github.com/olikraus/ucglib/wiki/reference#setcliprange) + +## [ucg.disp:setColor()](https://github.com/olikraus/ucglib/wiki/reference#setcolor) + +## ucg.disp:setFont() +ucglib comes with a wide range of fonts for small displays. Since they need to be compiled into the firmware image, you'd need to include them in [app/include/ucg_config.h](https://github.com/nodemcu/nodemcu-firmware/blob/master/app/include/ucg_config.h) and recompile. Simply add the desired fonts to the font table: +```c +#define UCG_FONT_TABLE \ + UCG_FONT_TABLE_ENTRY(font_7x13B_tr) \ + UCG_FONT_TABLE_ENTRY(font_helvB12_hr) \ + UCG_FONT_TABLE_ENTRY(font_helvB18_hr) \ + UCG_FONT_TABLE_ENTRY(font_ncenR12_tr) \ + UCG_FONT_TABLE_ENTRY(font_ncenR14_hr) +``` +They'll be available as `ucg.` in Lua. + +#### Syntax +`disp:setFont(font)` + +#### Parameters +- `font`: Constant to identify pre-compiled font. + +#### Returns +`nil` + +#### Example +```lua +disp:setFont(ucg.font_7x13B_tr) +``` + +#### See also +- [ucglib setFont()](https://github.com/olikraus/ucglib/wiki/reference#setfont) + +## [ucg.disp:setFontMode()](https://github.com/olikraus/ucglib/wiki/reference#setfontmode) + +## [ucg.disp:setFontPosBaseline()](https://github.com/olikraus/ucglib/wiki/reference#setfontposbaseline) + +## [ucg.disp:setFontPosBottom()](https://github.com/olikraus/ucglib/wiki/reference#setfontposbottom) + +## [ucg.disp:setFontPosCenter()](https://github.com/olikraus/ucglib/wiki/reference#setfontposcenter) + +## [ucg.disp:setFontPosTop()](https://github.com/olikraus/ucglib/wiki/reference#setfontpostop) + +## [ucg.disp:setMaxClipRange()](https://github.com/olikraus/ucglib/wiki/reference#setmaxcliprange) + +## [ucg.disp:setPrintDir()](https://github.com/olikraus/ucglib/wiki/reference#setprintdir) + +## [ucg.disp:setPrintPos()](https://github.com/olikraus/ucglib/wiki/reference#setprintpos) + +## [ucg.disp:setRotate90()](https://github.com/olikraus/ucglib/wiki/reference#setrotate90) + +## [ucg.disp:setRotate180()](https://github.com/olikraus/ucglib/wiki/reference#setrotate180) + +## [ucg.disp:setRotate270()](https://github.com/olikraus/ucglib/wiki/reference#setrotate270) + +## [ucg.disp:setScale2x2()](https://github.com/olikraus/ucglib/wiki/reference#setscale2x2) + +## [ucg.disp:undoClipRange()](https://github.com/olikraus/ucglib/wiki/reference#undocliprange) + +## [ucg.disp:undoRotate()](https://github.com/olikraus/ucglib/wiki/reference#undorotate) + +## [ucg.disp:undoScale()](https://github.com/olikraus/ucglib/wiki/reference#undoscale)