DigoleBasic - WimWWimW/touchScreen GitHub Wiki

Table of Contents

class DigoleBasic:

This class is a subclass of DigolePrimitive and superclass of DigoleDisplay. It implements the hardware functions of the display. Originally closely following the manual I later changed to aletering some names tomake them more comprehensible and changed the signature of some of the methods into more usable forms.

  • methods:*

Text functions

printText(v):

Display a string. This command displays v at the current position. The position is subsequently adjusted automatically; if it reaches the right edge of the screen, it is moved to the beginning of next line. The module calculates the next character line according to the currently used font's size. + The values 10 and 13 (\n and \r) move the current position to the next line and the the beginning of current line respectively. +

parameters
v :: (any type convertible to string)

printTextAt(x, y, v, align):

Print text relative to (x, y), aligned according to the value of align. This method replaces the rather unfathomable TextAlignment (ALIGNd) function of the display. +

parameters
x :: (integer) the horizontal left, centre or right position of the text
y :: (integer) represents the baseline of the text, not the top
v :: (any tpe convertible to string)
align :: 0 (left), 1 (centre) or 2 (right aligned)

newLine():

Moves the text position to the start of the next line, respecting font size.

setTextPosition(c, r):

Set the current text cursor . + The values of c and r represent the column and row value that MCU calculates based on the font's size (usually the width of a space (#32)). The top-left position is (0, 0).

parameters
c :: (byte) character column
r :: (byte) character row

returnToLastTextPos():

Return the text cursor to the last set position. + After each character is printed on screen, the current position is adjusted. The MCU rememberes the previous position, so if you want print multiple characters at same position, you can use this function.

offsetTextPosition(x, y):

Move the text cursor relatively by (x, y). + The range of x,y value is -127~127, it adjusts the current position with the relative value. eg.: if current position is (46, 30), after calling offsetTextPosition(-10, 5) the new position is: (36, 35). +

parameters
x :: (integer) x-position offset (-127:127)
y :: (integer) y-position offset (-127:127)

Font management

setFont(index):

set the active font. + WARNING: the internal font 6 has numbers only +

parameters
index :: (byte) index of the selected font (0-6 or 200-203)

uploadUserFont(index, fileName):

Upload a user font. + The font us stored into flash memory (conserved during power-off). Note that when the required memory space is insufficient, the display may crash or store a corrupted font. Fonts can be found at https://codeload.github.com/olikraus/u8glib/zip/master (byte code in c sources). Not all of these fonts are accepted so try them after uploading to the display.

parameters
index :: (byte) index of the selected font (0-6 or 200-203)
fileName :: (string) name of the file

useUserFontInFlashChip(address):

Use user font in flash chip. + Command: SFF, follow by 3 bytes of address which the font data in flash chip start from. + (not supported by my display, so not tested)

parameters
address :: flash memory address

Graphics

clearScreen():

Clear screen. + Erases the screen panel and fills the screen with the current background color. This function also resets the current font to 0, screen rotation to 0, x position to 0, draw mode to 'C', draw window to full screen, an the line pattern to 0xff.

setGraphicPosition(x, y):

Set the current cursor with pixel precision. Like setTextPosition, but now (x, y) represents a pixel postion rather than a character location. The top-left position is (0, 0).

parameters
x :: (integer) x-position (0:screen width)
y :: (integer) y-position (0:screen height)

drawPixel(x, y):

Draws a pixel. + This function draw a pixel at the (x,y) position using foreground color (set by commands "SC" or "ESC"), taking into effect the current draw-mode. This function doesn't change the graphic position.

parameters
x :: (integer) x-position (0:511)
y :: (integer) y-position (0:511)

drawLine(x1, y1, x2, y2):

Draw line from (x1, y1) to (x2, y2) +

parameters
x1 :: (integer) x-position,
y1 :: (integer) y-position,
x2 :: (integer) x-position,
y2 :: (integer) y-position,

drawLineTo(x, y):

Draw line to (x, y) originating from the current graphic postion. +

parameters
x :: (integer) x-position (0:511)
y :: (integer) y-position (0:511)

drawRectangle(x, y, w, h, filled):

Draw (filled) rectangle. The current graphic position moves to the lower-rigt corner.

parameters
x :: (integer) x-position (0:511)
y :: (integer) y-position (0:511)
w :: (integer) width,
h :: (integer) height,
filled :: True (or 1) to fill the rectangle in the current forground color

drawCircle(x, y, r, filled):

Draw circle with radius r. + This function is affected by foreground color and draw mode, but not affected by line pattern. The current grapch position moves to (x,y).

parameters
x :: (integer) x-position (0:511)
y :: (integer) y-position (0:511)
r :: (byte) radius,
filled :: True (or 1) to fill the rectangle in the current forground color

drawImage(mode, x, y, w, h, imageData):

draws an image at (x, y). Not very useful in this form since it moves all image data over the stack. See drawImageFile instead.

parameters
mode :: ...
x :: (integer) x-position (0:511)
y :: (integer) y-position (0:511)
w :: (integer) width,
h :: (integer) height,
imageData :: see manual

drawImageFile(mode, x, y, w, h, fileName):

see drawImage, only data are read from file, thus saving a lot of memory.

parameters
mode :: ...
x :: (integer) x-position (0:511)
y :: (integer) y-position (0:511)
w :: (integer) width,
h :: (integer) height,
fileName :: (string) name of the file
NOTE: it seems sensible instead of memorizing the size and mode of the image file to deviate from Digole's image format by adding a 8-byte header to the file, e.g. "IMGmwwhh". Here's the design for reading such a file that could't be completed before the display gave out (the size assertion is incorrect for mode 0): 
def drawImageFile(self, x, y, fileName):
    # see drawImage, only data are read from file, thus saving a lot of memory.
    # tested: OK
    size = self._getFileSize(fileName)
    
    with open(fileName, "rb") as f:
        tag = f.read(3)
        mode= int.from_bytes(f.read(1), "big")
        w   = int.from_bytes(f.read(2), "big")
        h   = int.from_bytes(f.read(2), "big")
        
    assert (tag == b'IMG'), "not an IMaGe-file (tag='%s')" % tag.decode("utf-8")
    assert (size ==8+ mode * w * h), "image file data size mismatch"

    # only now send introduction, for open file might fail and then the display keeps waiting for 
    # a load of data (if this happens, keep writing strings until they are diaplayed)
    
    
    print(mode, int(mode), w, type(w))
    self.drawImage(mode, x, y, w, h, None)        

    with open(fileName, "rb") as f:
        while True:
            print(end='.')
            chunk = f.read(128)
            if not chunk:
                print()
                break
            self._write(chunk)

videoBox(x, y, w, h, f, videoData):

Video Box + This command let user to send raw image data to the LCD panel directly, after command "VIDEO", followed by 2 integer data x, y to indicate the top-left position counted as pixels where of the video box, the available value of x,y are from 0 to 65535 but not exceed the LCD panel size, then 2 bytes of value to indicate the box width and height, the available value are from 0 to 255. + After defined the video box, the next byte of value indicate the color depth of each pixel, if value is 0, the color depth is 16BIT(2 bytes data) + NOT tested +

parameters
x :: (integer) x-position (0:511)
y :: (integer) y-position (0:511)
w :: (integer) width,
h :: (integer) height,
f :: (boolean) logical-flag
videoData :: ...

moveArea(x, y, w, h, ox, oy):

Move area on the screen. + Move the area(x,y)-(x+width,y+height) to new top-left position of(x+Ox,y+Oy), the value of Ox, Oy are -127~127. + This function is useful to scroll screen in 4 directions. +

parameters
x :: (integer) x-position (0:511)
y :: (integer) y-position (0:511)
w :: (integer) width,
h :: (integer) height,
ox :: (integer) x-position offset (-127:127)
oy :: (integer) y-position offset (-127:127)

Graphic Settings

setColor(c):

set the foreground colour. +

parameters
c :: (byte) colour: either a 1-byte index value, or an rgb-tuple

setBgColor(color):

Set background color(BGC) (esc = 53) + WARNING: with a light background the display draws more current; if the supply stalls, it may freeze in an error state. +

parameters
color :: 1-byte index value

setLineStyle(b):

Set line pattern. + b: byte indicate which pixel should display or not, there + are 8 bits in a byte, so when drawing line, the module will repeat every 8 bits according to the line pattern value. eg.: "SLP\x55" command will let the draw line/rectangle function to draw a dotted line, because "\x55" equal: 0B01010101, if the bit is 0, that pixel will not displayed. If the line pattern value is: 0B11010111, the drawing line is dashed. +

parameters
b :: (byte) bit pattern

setOrientation(direction):

Set screen orientation. +

parameters
direction :: 0 to 3 for original resp. 90, 180 and 270 degrees rotation clockwise

setDrawMode(m):

Set drawing mode. + Command: DM, followed by a byte of draw mode which only one letter can be used from {C,|,!,~,&,^,O,o}. Draw mode is used to tell the module how to display the color of pixel using current foreground color operating with the existing pixel, there are 6 modes available: 'C'-Copy, doesn't matter the existing pixel on screen, this mode use current foreground color to over _write the pixel, for "TT" command, it also clear the char box as back ground color, all other modes will not clear the char box. +

parameters
m :: (character) {C,|,!,~,&,^,O,o}

setDrawWindow(x, y, w, h):

Set output/draw window. + Draw window was embedded since firmware version 3.2 and later, instead of output to full screen, user can set a smaller rectangle area as draw window, then all following output will be showing in this window and the coordinate also refers to the top-left corner of draw window. This ability provide user a new way to relocate an area of content on the screen to different location easily, just change the draw window to the desired location, then done. Command: DWWIN, follow by top-left coordinate value (x,y), then draw window's width (w) and height (h) all value in pixels.

parameters
x :: (integer) x-position (0:511)
y :: (integer) y-position (0:511)
w :: (integer) width,
h :: (integer) height,

resetDrawWindow():

Reset draw window + Cancel drawing mode and reset the coordinate system to the whole screen.

clearDrawWindow():

Clear draw window + Clear the draw window using background color. +

setImageBackgroundTransparent(f):

Set image's background transparent + When we show an image (256, 65K or 262K color) on the screen, the image occupy a rectangle area, this command can change the image shape on the screen, the black pixels in the rectangle area can be transparent +

parameters
f :: (boolean) True or 1 to make the images transparent

Command sets

runCommandSet(a):

Run command set. + Command: FLMCS, followed by 3 bytes of address which indicate the beginning of command set, 3 bytes address format allow the module access all 2MB memory in flash chip. + Not tested +

parameters
a :: (unsigned int) address

EEPROM utilities

writeDataToEeprom(a, l, data):

Write data to EEPROM + Command: WREP, followed by 2 bytes of address, 2 bytes of data length (MSB-LSB format), then the data. + not tested +

parameters
a :: (unsigned int) address
l :: (unsigned int) size
data :: binary

readDataFromEeprom(a, l):

Read data from EEPROM + Command: RDEP, followed by 2 bytes of address, 2 bytes of data length (MSB-LSB format), after these 8 bytes of command sent to the module, the master controller need to wait the data available on the communication port, read out all desired data from the port. + not tested +

parameters
a :: (unsigned int) address
l :: (unsigned int) size

FLASH utilities

writeDataToFlash(a, l, data):

Write data to flash + This command applicable to internal 16KB flash or external flash chip. Command: FLMWR, followed by 3 bytes of start address, 3 bytes of data length (MSB, LSB format), then the data. This command can write data to flash chip or internal flash memory. + not tested +

parameters
a :: (unsigned int) address
l :: (unsigned int) size
data :: binary

readDataInFlashChip(a, l):

Read data in flash chip + This command only applicable to external flash chip. If the flash chip installed on the board, you can use it to save user data, and read the data when you need it. Command: FLMRD, followed by 3 bytes of address, then 3 bytes of data length, all MSB format. After this command issued, the master controller can read data from the communication port when data in module ready + not tested +

parameters
a :: (unsigned int) address
l :: (unsigned int) size

eraseFlashMemory(a, l):

Erase flash memory in flash chip + This command only applicable to external flash chip. + Only writing data to flash chip need this command, this command can erase only specific range of address on all ! color module. Because the erasing on the chip is operating as block, the module will save the useful data in the block to the RAM on screen panel, erase whole block, then restore the useful data back, so, you may see a block of screen at the left-bottom corner show some wild image, that is the data from the erased block + not tested +

parameters
a :: (unsigned int) address
l :: (unsigned int) size

Touch panel

In the current firmware (V4.0) the touch functionality is poorly implemented and should best be avoided.

calibrateTouchScreen():

Calibrate touch screen + starts a calibration procedure during which a few points have to be clicked on.

readTouchScreen():

Read touched coordinate + Read touch screen coordinate as soon as it is touched.

readClick():

Read touched coordinate + Read touch screen coordinate as sson as it is released.

checkTouchScreen():

Read touch panel instantly + The 2 functions above will drive the module frozen until the touch screen pressed. If you only want to check the touch screen pressed or not, this is the function for the software, it returns a pair of out of range value of no press on touch screen. You also can check a hardware signal on the module when screen pressed, there is a PENIRQ signal on the 9pin header, this signal will go low when screen pressed. This is the easiest way to quote the touch screen if there were a free I/O pin on your master controller. note: a call to this method *also* causes te interrupt to fire. +

readVoltage():

Read voltage + Connect a voltage on the Vbat pin on the 9pin header, then send command: RDBAT to module, the module will return 2 bytes of data of voltage on the Vbat pin, MSB format, the unit is mV, the range is 0~10,000. eg.: if the 2 bytes of value is: 18, 192, the voltage is: 18x256+192=4800mV, is 4.8V. The input impedance is: 10kO! Hint: if the measured voltage is over 10V, a 2R voltage divider is needed. +

readAnalog():

Read analog + Connect the analog to the AUX pin on the 9pin header, then use this command to read it, we didn't adjust the 2 bytes result here, the data range is 0~4095, and represent 0~2.5V. Use this format to calculate the real voltage: V=d*2.5/4096. (d is the reading data) +

readTemperature():

Read temperature + This command read the temperature of the chip, the format to calculate the temperature is: T=(653-(d*2500/4096))/2.1 degree C, d is the reading data. Note, the temperature on the chip may be affected by the backlight heat of LCD screen.

Power management

backlightBrightness(percentage):

Backlight brightness + The backlight brightness on all color LCD and MonoChrome GLCD modules! can be adjusted continuously by use command: BL, followed by a byte of value 0~100, 0 will turn backlight full off, and 100 will turn backlight full on. The backlight on all OLED modules are not adjust-able. +

parameters
percentage :: brigthtness step

turnScreenOn(f):

Turn screen on + Command: SOO, followed by a byte value 0/1, when d=0, the screen and the backlight will be turned off immediately, that will save much power on the module, this function work on all module. On most of modules, the module only consume few mA after screen turned off. The content on the screen unchanged if screen turn off then turn on later. + not tested +

parameters
f :: (boolean) logical-flag

turnMcuOff():

Turn MCU off( + Command: DNMCU, no following data needed, the module will check if there were more pending commands in buffer before entering sleep. If there were, the module will not enter sleep mode. The module wakes up automatically when new data are received, but if the COM mode is I2C, some dummy data are needed to act as waking signal, so, use few write(0) then a delay 10ms is a good practice to wake up the MCU from deep sleep. The screen will keep on, and all content on the screen unchanged when MCU off. not tested +

turnModuleOff():

Turn module off + This command put all power off: backlight off, screen off, MCU enter deep sleep, the module will only consume <0.05mA of current, the wake up sequence is same with wake up MCU, the module will restore backlight and put screen on also after wake up, the content on the screen unchanged. +

turnBackOn():

Send a couple of zeros to reactivate the screen

Configuration

uploadStartScreen(fileName):

upload start screen to module + Command: SSS, followed by 2 bytes of data length of start screen, then the data, as described before, the data structure are different for monochrome module and color module. In V3.2 and earlier version on color module, the command set also need 2 bytes of data to indicate the command set length, when you uploading this format of start screen to module, 2 bytes of length follow to SSS to indicate the length of rest data, and in the rest of data, the first 2 bytes to indicate the length of command set, their relationship is: SSS (length+2) (length) (...data...). + This function could not be made to work. Can't make sense of what the manual writes about this (cited here above). +

parameters
fileName :: (string) name of the file

enableStartScreen(f):

Enable/disable start screen + Command: DSS, if the following value is 0, the start screen is not show up on next power on. +

parameters
f :: (boolean) logical-flag

showConfiguration(f):

Configuration show on/off + In default, the module will show start screen when power on, and also show the current COM mode after start screen showed up, that will tell you what is the Baud on UART mode or the slave address on I2C mode. If you want to manage this configuration show on the screen, use command: DC, then follow by a byte value 0 or 1, if d=0, the configuration will not show on the screen on next power on.

parameters
f :: (boolean) logical-flag

changeI2Caddress(a):

Change I2C address + When you connect multiple modules on a I2C bus, every slave modules MUST be assigned with different address, this function can change the default address of 0x27 to other value. This command only work at I2C COM mode, you can't use it at UART or SPI mode. Command: SI2CA, followed by a byte of new address. The module use the new address instantly, it also save this new address in internal memory, you don't need to change it on the next power recycle. + not tested +

parameters
a :: (byte) i2c address

other functions

delay(p):

Delay a period + This command only available since V3.9, but this is a bug in V3.9: it will be halt if on I2C/SPI mode, fixed in V4.0. Command: "DLY", + following with a byte of delay period, value 1 for about 0.25s. + not tested +

parameters
p :: (byte) delay period in presumably qurter seconds

sendCommandToScreen(b):

send command to screen (MCD) (esc = 33) + (undocumented, "manualCommand" in arduino-lib) + test: causes display to blackout until next power-on +

parameters
b :: (byte) ?

sendDataToScreen(b):

send data to screen (MDT) (esc = 34) + (undocumented, "manualData" in arduino-lib) + not tested +

parameters
b :: (byte) ?
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️