driver for 3.5inch RPi LCD (A) ili9486 + pbm display on nucleo-f746

[brave-ulysses]

https://www.waveshare.com/wiki/3.5inch_RPi_LCD_(A)

datasheet:
https://datasheetspdf.com/datasheet/ILI9486.html

hacked up from pythoncoder's nano gui ili9341 driver
thanks @peterhinch

the bodmer, luma.lcd and juj repos were helpful:
https://github.com/Bodmer/TFT_eSPI/blob/master/TFT_Drivers/ILI9486_Init.h
https://github.com/rm-hull/luma.lcd/blob/master/luma/lcd/device.py
https://github.com/juj/fbcp-ili9341/blob/master/ili9486.cpp

8 bit writes require padding to 16 bits
no miso from lcd, write only - this seems to be a hw limitation on this waveshare implementation
touch screen shares spi bus and presumably works (no support in this code)
pbm display is close 😬

dogbert pbm files:
dogberts.zip

pulseview trace of spi startup sequence:
spi.zip

pulseview logic analyser:
https://sigrok.org/wiki/PulseView

main.py:

import time
import sys
import os
import gc
import re
import binascii
import pyb
from math import *
from random import randint

debug=False

#spi3 = machine.SoftSPI(miso=machine.Pin.cpu.C11,mosi=machine.Pin.cpu.C12,sck=machine.Pin.cpu.C10,baudrate=1_000_000,bits=8,polarity=0,phase=0)
spi3 = machine.SPI(3,bits=8,firstbit=machine.SPI.MSB,baudrate=27_000_000)

cs3  = machine.Pin(machine.Pin.cpu.A15, mode=machine.Pin.OUT, value=1)
tp_cs = machine.Pin(machine.Pin.cpu.C8, mode=machine.Pin.OUT, value=1)
tft_cs = machine.Pin(machine.Pin.cpu.C9, mode=machine.Pin.OUT, value=1)
tft_dc = machine.Pin(machine.Pin.cpu.D2, mode=machine.Pin.OUT, value=0)
tft_reset = machine.Pin(machine.Pin.cpu.G2, mode=machine.Pin.OUT, value=1)
tft_rst=tft_reset


from ili9486 import ILI9486 as SSD

ssd=SSD(spi3,cs=tft_cs,dc=tft_dc,rst=tft_reset,width=480,height=320,dmode=0x28,pmt=False,lmt=True)

ILI9486_WHITE       = 0xFFFF
ILI9486_BLUE        = 0x001F
ILI9486_RED         = 0xF800
ILI9486_GREEN       = 0x07E0
ILI9486_CYAN        = 0x07FF
ILI9486_MAGENTA     = 0xF81F
ILI9486_YELLOW      = 0xFFE0  
ILI9486_MYSTERY1    = randint(0,0xffff)
ILI9486_MYSTERY2    = randint(0,0xffff)
ILI9486_MYSTERY3    = randint(0,0xffff)
ILI9486_MYSTERY4    = randint(0,0xffff)
ILI9486_MYSTERY5    = randint(0,0xffff)
ILI9486_MYSTERY6    = randint(0,0xffff)
ILI9486_MYSTERY7    = randint(0,0xffff)
ILI9486_MYSTERY8    = randint(0,0xffff)
ILI9486_BLACK       = 0x0000


# fill lut entries
colors=[ILI9486_WHITE,ILI9486_YELLOW,ILI9486_MAGENTA,ILI9486_CYAN,ILI9486_GREEN,ILI9486_RED,ILI9486_BLUE,ILI9486_MYSTERY1,ILI9486_MYSTERY2,ILI9486_MYSTERY3,ILI9486_MYSTERY4,ILI9486_MYSTERY5,ILI9486_MYSTERY6,ILI9486_MYSTERY7,ILI9486_MYSTERY8,ILI9486_BLACK]
for i in range(0,len(colors)):
    ssd.lut[2*i] = (colors[i]>>8)&0x00ff
    ssd.lut[2*i+1] = (colors[i])&0x00ff

def cls(bg=0):
    ssd.fill(bg)
    ssd.show()

def title(t):
    xc=ssd.width//2-len(t)*4
    ssd.text(t,xc,3,5)
    ssd.show()

# P4 formatted monochrome pbm files only
def display_pbm(fn,x_off=0,y_off=0,fg=1,bg=0,j=None):
    f=open(fn,'rb')
    buffer=f.read()
    hdr = buffer[0:12]
    if debug: print(f'{repr(hdr)} ')
    f,h,v,_=hdr.split()
    f=str(f)
    h=int(h)
    v=int(v)
    if not 'P4' in f:
       print(f'invalid file type {f}. must be P4')
       return
    if debug: print(f'f {f} h {h} v {v} {repr(hdr)} ')
    if 'c' in j.lower():
       x_off = ssd.width//2-h//2
       y_off = ssd.height//2-v//2
    if 't' in j.lower() :
       y_off = 0
    if 'b' in j.lower() :
       y_off = ssd.height-v
    if 'l' in j.lower() :
       x_off = 0
    if 'r' in j.lower() :
       x_off = ssd.width-h
    for i in range(len(hdr),len(buffer)):
        n=i-len(hdr)
        y=n//(1+(h)//8)
        X=n%(1+(h)//8)
        for j in range(0,8):
            x=X*8+j
            q=buffer[i]>>(8-j)&0x01
            ssd.pixel(x_off+x,y_off+y,fg if q else bg)
            if debug: print(f'{' ' if q else '*'}',end='')
        if debug:
            if not X: print(f'')
    ssd.show()
    print(f'')

cls()
title('F U B A R L A N D')
display_pbm('dogbert_01.pbm',fg=5,j='rc')
display_pbm('dogbert_00.pbm',fg=15,j='lc')

ili9486.py:

# ILI9486 nano-gui driver for ili9486 displays
# As with all nano-gui displays, touch is not supported.

# Copyright (c) Peter Hinch 2020
# Released under the MIT license see LICENSE

# This work is based on the following sources.
# https://github.com/rdagger/micropython-ili9341
# Also this forum thread with ideas from @minyiky:
# https://forum.micropython.org/viewtopic.php?f=18&t=9368

debug = False

from time import sleep_ms
import gc
import framebuf
import uasyncio as asyncio
from boolpalette import BoolPalette
import time

@micropython.viper
def _lcopy(dest:ptr16, source:ptr8, lut:ptr16, length:int):
    # rgb565 - 16bit/pixel
    n = 0
    for x in range(length):
        c = source[x]
        dest[n] = lut[c >> 4]  # current pixel
        n += 1
        dest[n] = lut[c & 0x0f]  # next pixel
        n += 1


class ILI9486(framebuf.FrameBuffer):

    lut = bytearray(32)

    # Convert r, g, b in range 0-255 to a 16 bit colour value
    # LS byte goes into LUT offset 0, MS byte into offset 1
    # Same mapping in linebuf so LS byte is shifted out 1st
    # ILI9486 expects RGB order. 8 bit register writes require padding
    @staticmethod
    def rgb(r, g, b):
        return (r & 0xf8) | (g & 0xe0) >> 5 | (g & 0x1c) << 11 | (b & 0xf8) << 5

    # Transpose width & height for landscape mode
    def __init__(self, spi, cs, dc, rst, height=320, width=480, usd=False, init_spi=False, dmode = 0x28, pmt=False, lmt=False):
        self._spi = spi
        self._cs = cs
        self._dc = dc
        self._rst = rst
        self.height = height
        self.width = width
        self._spi_init = init_spi
        pmode = framebuf.GS4_HMSB
        self.palette = BoolPalette(pmode)
        gc.collect()
        if debug: print(f'__init__ 0 width {self.width} height {self.height} mem free {gc.mem_free()}')
        buf = bytearray(self.height * self.width // 2)
        #buf = bytearray(320*480 // 2)
 
        self._mvb = memoryview(buf)
        super().__init__(buf, self.width, self.height, pmode)
        #super().__init__(buf, 480, 320, pmode)
        if debug: print(f'__init__ 1 width {self.width} height {self.height} mem free {gc.mem_free()}')
        self._linebuf = bytearray(self.width * 2)
        #self._linebuf = bytearray(480 * 2)
        if debug: print(f'__init__ 0 - linebuf {len(self._linebuf)}')

        # Hardware reset
        self._rst(0)
        sleep_ms(50)
        self._rst(1)
        sleep_ms(50)
        if self._spi_init:  # A callback was passed
            self._spi_init(spi)  # Bus may be shared
        self._lock = asyncio.Lock()
        # Send initialization commands

        if True:
           self._wcmd(b'\x00\x01')  # SWRESET Software reset
           sleep_ms(100)
           self._wcd(b'\x00\xb0', b'\x00\x00') 
           self._wcmd(b'\x00\x11') # sleep out
           sleep_ms(20)
           self._wcd(b'\x00\x3a', b'\x00\x55') # interface pixel format 
           self._wcd(b'\x00\x0c', b'\x00\x66') # read display pixel format
           self._wcd(b'\x00\xc2', b'\x00\x44') # # power control 3
           self._wcd(b'\x00\xc5', b'\x00\x00\x00\x00\x00\x00\x00\x00') # vcom control
           self._wcd(b'\x00\xe0', b'\x00\x0f\x00\x1f\x00\x1c\x00\x0c\x00\x0f\x00\x08\x00\x48\x00\x98\x00\x37\x00\x0a\x00\x13\x00\x04\x00\x11\x00\x0d\x00\x00') # positive gamma control
           self._wcd(b'\x00\xe1', b'\x00\x0f\x00\x32\x00\x2e\x00\x0b\x00\x0d\x00\x05\x00\x47\x00\x75\x00\x37\x00\x06\x00\x10\x00\x03\x00\x24\x00\x20\x00\x00') # negative gamma control
           self._wcd(b'\x00\xe2', b'\x00\x0f\x00\x32\x00\x2e\x00\x0b\x00\x0d\x00\x05\x00\x47\x00\x75\x00\x37\x00\x06\x00\x10\x00\x03\x00\x24\x00\x20\x00\x00') # digital gamma control 1

           self._wcd(b'\x00\x36', dmode.to_bytes(2,False)) # memory access control
           if debug: print(f'__init__ 2 width {self.width} height {self.height} dmode 0x{dmode:02x} {dmode.to_bytes(2,False)} pmt {pmt} lmt {lmt} mem free {gc.mem_free()}')

           self._wcmd(b'\x00\x11') # sleep out
           self._wcmd(b'\x00\x29') # display on


    # Write data.
    def _wdata(self, data):
        self._dc(1)
        self._cs(0)
        self._spi.write( data )
        self._cs(1)

    # Write a command.
    def _wcmd(self, command):
        self._dc(0)
        self._cs(0)
        self._spi.write( command )
        self._cs(1)

    # Write a command followed by a data arg.
    def _wcd(self, command, data):
        self._dc(0)
        self._cs(0)
        self._spi.write( command )
        self._cs(1)
        self._dc(1)
        self._cs(0)
        self._spi.write( data )
        self._cs(1)

# Time (ESP32 stock freq) 196ms portrait, 185ms landscape.
# mem free on ESP32 43472 bytes (vs 110192)
    @micropython.native
    def show(self):
        clut = ILI9486.lut
        wd = self.width // 2
        ht = self.height
        lb = self._linebuf
        buf = self._mvb
        if self._spi_init:  # A callback was passed
            self._spi_init(self._spi)  # Bus may be shared
        # Commands needed to start data write 
        scol=0
        scolh=(scol>>8&0x00ff)
        scoll=(scol&0x00ff)
        scold = bytes([0,scolh,0,scoll])
        ecol=480-1
        ecolh=(ecol>>8&0x00ff)
        ecoll=(ecol&0x00ff)
        ecold = bytes([0,ecolh,0,ecoll])
        srow=0
        srowh=(srow>>8&0x00ff)
        srowl=(srow&0x00ff)
        srowd = bytes([0,srowh,0,srowl])
        erow=320-1
        erowh=(erow>>8&0x00ff)
        erowl=(erow&0x00ff)
        erowd = bytes([0,erowh,0,erowl])


        self._wcd(b'\x00\x2a', scold + ecold)
        self._wcd(b'\x00\x2b', srowd + erowd)
        self._wcmd(b'\x00\x2c')  # WRITE_RAM
        self._dc(1)
        self._cs(0)
        for start in range(0, wd*ht, wd):  # For each line
            _lcopy(lb, buf[start :], clut, wd)  # Copy and map colors
            self._spi.write(lb)
        self._cs(1)

    async def do_refresh(self, split=4):
        async with self._lock:
            lines, mod = divmod(self.height, split)  # Lines per segment
            if mod:
                raise ValueError('Invalid do_refresh arg.')
            clut = ILI9486.lut
            wd = self.width // 2
            ht = self.height
            lb = self._linebuf
            buf = self._mvb
            # Commands needed to start data write 
            scol=0
            scolh=(scol>>8&0x00ff)
            scoll=(scol&0x00ff)
            scold = bytes([0,scolh,0,scoll])
            ecol=480-1
            ecolh=(ecol>>8&0x00ff)
            ecoll=(ecol&0x00ff)
            ecold = bytes([0,ecolh,0,ecoll])
            srow=0
            srowh=(srow>>8&0x00ff)
            srowl=(srow&0x00ff)
            srowd = bytes([0,srowh,0,srowl])
            erow=320-1
            erowh=(erow>>8&0x00ff)
            erowl=(erow&0x00ff)
            erowd = bytes([0,erowh,0,erowl])


            self._wcd(b'\x00\x2a', scold + ecold)
            self._wcd(b'\x00\x2b', srowd + erowd)


            self._wcmd(b'\x00\x2c')  # WRITE_RAM
            self._dc(1)
            line = 0
            for _ in range(split):  # For each segment
                if self._spi_init:  # A callback was passed
                    self._spi_init(self._spi)  # Bus may be shared
                self._cs(0)
                for start in range(wd * line, wd * (line + lines), wd):  # For each line
                    _lcopy(lb, buf[start :], clut, wd)  # Copy and map colors
                    self._spi.write(lb)
                line += lines
                self._cs(1)  # Allow other tasks to use bus
                await asyncio.sleep_ms(0)

[peterhinch]

That driver looks good. Have you tested it with nano_gui? In particular does it pass this test? If so, I'd be interested in adding it to the nano_gui / micro_gui set of drivers if you have no objection.

[brave-ulysses]

my filesystem size is 80k - could not do a full install of nano_gui...

refresh cleared the screen to black and the final output is this:

you are welcome to use any of the above code

[peterhinch]

Thank you. The test result looks spot-on. A few queries.

1. The constructor arg usd is unused. Do you have any plans to support rotation?
2. Constructor args pmt and lmt are used only in a debug print statement. Do these have any future application or should I just remove them?
3. Have you tried commenting out the gamma control code? With only 16 colors available on any screen it's arguable that gamma is irrelevant. On displays I've tested default values suffice (with a saving of bytes). I would experiment myself, but I don't have one of these displays.

[brave-ulysses]

hi peter,

my current use case does not require rotation. i think the rotate commands are the same as 9341; add back in?

pmt and lmt were used to transpose width/height during testing. they can be removed

i'll check on the gamma...
imo, it's small enough to not cause issues and may be instructive for someone in the future. i may try to add a psram to my system for a larger framebuffer / more colors

thanks,

clay

[brave-ulysses]

removed the 3 gamma setup lines and can not tell any difference in the output

[peterhinch]

Thanks for confirming.

For background, nanogui is optimised for minimal size, so its drivers are basic; it can even run on an ESP8266. It and microgui are designed to use a small set of colors. There is a clear case for drivers supporting a wide range of colors - the penalty of large frame buffers probably isn't an issue on (for example) hardware with SPIRAM. Such drivers would support the display of full color pictures where gamma may well be an issue. You might want to publish such a version.

[peterhinch]

First the good news. Your driver works fine with nano-gui (and hence cwriter) and probably works with micro-gui.

Alas I don't understand why it works.

The code doesn't conform with the device datasheet, particularly in regard to the zero padding. This is invalid for an SPI connected device. I have rewritten the driver to conform with the datasheet. It now supports landscape, portrait and upside-down modes. It has been tested with the above GUI's. To run micro-gui I used frozen bytecode to conserve RAM: in that mode it runs with about 75K free.

There is a peculiarity of this chip. I started out by trying to adapt your driver, replacing non-conformant code. Portrait mode worked readily, but for landscape mode I had to include a single line derived from your driver:

self._wcd(b'\x2a', b'\x00\x00\x00\x00\x00\x01\x00\xdf')

Your driver executes this after computing the bytes object. This makes no sense as the register is specified for four args, not eight. I could not find a way to do landscape mode at chip level without issuing this instruction. This is bizarre. Congratulations on finding this fix, but I'm unhappy with the solution. Hence the rewrite.

The published version runs the chip in portrait mode using only legal code. The rotation to support landscape mode is done in Viper.

[brave-ulysses]

what display are you testing with?

my understanding is that this display implements the spi bus as the input to cascaded shift registers (16 bits). register writes are 8 bits, hence the padding. the above command is effectively write(b'\x2a', b'\x00\x00\x01\xdf'). maybe this makes sense...

[peterhinch]

I am using exactly the same display. Do you have a schematic for the board or other authoritative documentation? On the face of it there seems to be no reason to modify the chip's SPI interface.

I agree that your assertion is backed up by the line I cited. But the contrary evidence is that, in portrait mode, my driver works on the basis of 8-bit data.

In particular if register numbers are 16 bit, my version should fail, but if they are 8-bit yours should. The fact that both drivers work has me baffled. I can only think that the chip, however it is being driven, is remarkably tolerant.

[brave-ulysses]

not a smoking gun, but:

2ea 74hc4094 shift registers on lcd carrier pcb. lcd connector pin 23 (sck) is routed to the clock input on both shift registers

and

from the luma.lcd repo file, starting line 787

        # Initialization sequence, adapted from MIT Licensed
        #
        #   `https://github.com/juj/fbcp-ili9341/blob/master/ili9486.cpp`
        #
        # and peer files.  The sequence targets the ILI9486-based
        # Waveshare "Wavepear" 3.5 inch 320x480 LCD (B)
        # implementation.  Per comments in the above file and issue
        # discussion for juj/fbcp-ili9341, the Waveshare
        # implementation makes use of 16-bit shift register for the
        # SPI interface, leaving the ILI9486 itself in a parallel
        # mode.
        #
        # The result of that implementation is that registers
        # effectively become 16-bit quantities.  The sequence below
        # (and in the display() function) thus ends up padding
        # commands and subsequent values.  It doesn't seem to have
        # affected pixel transfers, though.
        #
        # A different ILI9486 implementation may NOT need the padding
        # zeros.  The juj/fbcp-ili9341 code handles that possibility
        # via a DISPLAY_SPI_BUS_IS_16BITS_WIDE ifdef.

[peterhinch]

Your observation about the shift registers is persuasive. I wonder why they did it - perhaps the Pi can emit very high clock rates.

I remain foxed by the fact that (to take two random lines) your

self._wcd(b'\x00\x3a', b'\x00\x55')
self._wcmd(b'\x00\x2c')

and my

self._wcd(b'\x3a', b'\x55')
self._wcmd(b'\x2c')  # WRITE_RAM

both work. At one point I removed the zero padding throughout from addresses and data: portrait mode worked; for landscape mode the one line which required padding was the one I described above. Very puzzling.

I have ordered an ILI9486 display from eBay which lacks this extra hardware. My driver needs to work with generic hardware. The fact that it also works with this board puts me in a dilemma: I guess I'll need to put a warning in the docs pointing users to this thread and your code...

[peterhinch]

I think I've figured out what's going on, but it's rather speculative. My guess is that the board's hardware issues a write pulse to the parallel interface under two conditions:

1. If the 16-bit shift register becomes full. Or
2. On a positive going edge of DC or CS.
   All commands comprise a single byte. Consequently zero padding of a command has no effect: the LS byte of the SR is transferred to the LS byte of the interface in either case. This matches my observation that removing the padding from commands has no effect: the chip ignores the MS byte.

Commands with a single data byte will behave similarly, with the data byte ending up in the LSB whether or not it is padded.

Commands with multi-byte data will fail unless the data is padded. The fact that padding is necessary implies that the chip expects to find successive data bytes in the LS byte.

Mass transfers of image bytes use the full 16 bit width.

My non-padded version works in portrait mode because the write to register \x2a only gets 2 bytes instead of the expected 4. My guess is that the chip ignores this. The default values for \x2a and \x2b are correct for portrait mode. Landscape mode won't work with these defaults. It only worked with padded data.

self._wcd(b'\x2a', b'\x00\x00\x00\x00\x00\x01\x00\xdf')

Practical takeaways from all this are:

1. Your driver is correct on the basis of the 16 bit shift register on board.
2. Zero padding of commands could be removed, but there is little gain in doing so.
3. Code could be simplified: there is no need repeatedly to compute the data for registers \x2a and \x2b as it is constant.

I feel this all makes some sense now. Thanks for helping me with this.