Overhaul of the API

[kdschlosser]

I am going to be overhauling the API for the SPI, I8080, RGB bus drivers. I really do not care for how it is currently done and I want to unify everything into the machine module with an understandable hierarchy.

my plan is to have the organization be as follows. This is going to be located in the machine module

from typing import Union, Optional, ClassVar
import array


class DisplayDevice:

    def __init__(self, *args, **kwargs):
        ...

    def allocate_buffer(self, num_bytes: int, momde: int = -1) -> memoryview:
        ...

    def release_buffer(self, buffer: memoryview) -> None:
        ...

    def init(
        self,
        display_width: int,
        display_height: int,
        bpp: int,
        buffer_size: int,
        rgb565_byte_swap: bool,
        cmd_bits: int,
        param_bits: int
    ) -> None:
        ...

    def rx_data(
        self,
        cmd: int,
        receive_buf: Union[array.array, bytes, bytearray, memoryview],
        out_params: Optional[Union[array.array, bytes, bytearray, memoryview]] = None
    ) -> None:
        ...

    def tx_data(
        self,
        cmd: int,
        params: Optional[Union[array.array, bytes, bytearray, memoryview]] = None
    ) -> None:
        ...

    def tx_color(
        self,
        cmd: int,
        data: Union[array.array, bytes, bytearray, memoryview],
        start_x: int,
        start_y: int,
        end_x: int,
        end_y: int
    ) -> None:
        ...


class SPI:
    MSB: ClassVar[bool] = True
    LSB: ClassVar[bool] = False

    class SDCardDevice:
        ...

    class SPIDevice:
        def __init__(self, *args, **kwargs):
            ...
        
        def deinit(self) -> None:
            ...

        def read(
            self, 
            num_bytes: int,
            cmd: int = -1
        ) -> bytes:
            ...
        
        def readinto(
            self, 
            dst_buffer: Union[array.array, bytes, bytearray, memoryview],
            cmd: int = -1
        ) -> None:
            ...
        
        def write(
            self,
            src_buffer: Union[array.array, bytes, bytearray, memoryview],
            cmd: int = -1
        ) -> None:
            ...
            
        def write_readinto(
            self, 
            src_buffer: Union[array.array, bytes, bytearray, memoryview], 
            dst_buffer: Union[array.array, bytes, bytearray, memoryview]
        ) -> None:
            ...

    def __init__(
        self,
        host: int,
        mosi: Optional[Union[machine.Pin, int, str]] = None,
        miso: Optional[Union[machine.Pin, int, str]] = None,
        sclk: Optional[Union[machine.Pin, int, str]] = None
    ):
        ...

    def Display(
        self,
        freq: int,
        dc: Union[machine.Pin, int, str],
        cs: Optional[Union[machine.Pin, int, str]] = None,
        cs_active_low: bool = True,
        polarity_low: bool = True,
        reverse_phase: bool = False,
        dc_data_low: bool = False
    ) -> DisplayDevice:
        ...

    def SDCard(
        self,
        freq: int,
        wp: Optional[Union[machine.Pin, int, str]] = None,
        cd: Optional[Union[machine.Pin, int, str]] = None,
        cs: Optional[Union[machine.Pin, int, str]] = None,
        wp_active_low: bool = True
    ) -> SDCardDevice:
        ...

    def Touch(
        self,
        freq: int,
        cs: Optional[Union[machine.Pin, int, str]] = None,
        cs_active_low: bool = True,
        polarity_low: bool = True,
        reverse_phase: bool = False,
    ) -> SPIDevice:
        ...

    def Device(
        self,
        freq: int,
        cs: Optional[Union[machine.Pin, int, str]] = None,
        cs_active_low: bool = True,
        polarity_low: bool = True,
        reverse_phase: bool = False,
        bits: int = 8,
        bit_order_msb: bool = MSB,
        byte_order_msb: bool = MSB
    ) -> SPIDevice:
        ...


class I8080:
    MSB: ClassVar[bool] = True
    LSB: ClassVar[bool] = False

    def __init__(
        self,
        dc: Union[machine.Pin, int, str],
        wr: Union[machine.Pin, int, str],
        data0: Union[machine.Pin, int, str],
        data1: Union[machine.Pin, int, str],
        data2: Union[machine.Pin, int, str],
        data3: Union[machine.Pin, int, str],
        data4: Union[machine.Pin, int, str],
        data5: Union[machine.Pin, int, str],
        data6: Union[machine.Pin, int, str],
        data7: Union[machine.Pin, int, str],
        data8: Optional[Union[machine.Pin, int, str]] = None,
        data9: Optional[Union[machine.Pin, int, str]] = None,
        data10: Optional[Union[machine.Pin, int, str]] = None,
        data11: Optional[Union[machine.Pin, int, str]] = None,
        data12: Optional[Union[machine.Pin, int, str]] = None,
        data13: Optional[Union[machine.Pin, int, str]] = None,
        data14: Optional[Union[machine.Pin, int, str]] = None,
        data15: Optional[Union[machine.Pin, int, str]] = None
    ):
        ...

    def Display(
        self,
        freq: int,
        cs: Optional[Union[machine.Pin, int, str]] = None,
        cs_active_low: bool = True,
        dc_idle_low: bool = True,
        dc_cmd_low: bool = True,
        dc_dummy_low: bool = True,
        dc_data_low: bool = False,
        pclk_active_low: bool = False,
        pclk_idle_low: bool = False,
        bit_order_msb: bool = MSB,
        byte_order_msb: bool = MSB
    ) -> DisplayDevice:
        ...


class RGB:

    def __init__(
        self,
        hsync: Union[machine.Pin, int, str],
        vsync: Union[machine.Pin, int, str],
        de: Union[machine.Pin, int, str],
        pclk: Union[machine.Pin, int, str],
        data0: Union[machine.Pin, int, str],
        data1: Union[machine.Pin, int, str],
        data2: Union[machine.Pin, int, str],
        data3: Union[machine.Pin, int, str],
        data4: Union[machine.Pin, int, str],
        data5: Union[machine.Pin, int, str],
        data6: Union[machine.Pin, int, str],
        data7: Union[machine.Pin, int, str],
        data8: Optional[Union[machine.Pin, int, str]] = None,
        data9: Optional[Union[machine.Pin, int, str]] = None,
        data10: Optional[Union[machine.Pin, int, str]] = None,
        data11: Optional[Union[machine.Pin, int, str]] = None,
        data12: Optional[Union[machine.Pin, int, str]] = None,
        data13: Optional[Union[machine.Pin, int, str]] = None,
        data14: Optional[Union[machine.Pin, int, str]] = None,
        data15: Optional[Union[machine.Pin, int, str]] = None
    ):
        ...

    class DisplayTimings:
        def __init__(
            self,
            front_porch: int,
            back_porch: int,
            pulse_width: int,
            idle_low: int
        ):
            ...

    def Display(
        self,
        freq: int,
        hsync_timings: DisplayTimings,
        vsync_timings: DisplayTimings,
        de_idle_low: bool = True,
        pclk_idle_low: bool = True,
    ) -> DisplayDevice:
        ...


class I2C:

    def read(self, num_bytes: int) -> bytes:
        ...

    def readinto(
        self,
        dst_buffer: Union[array.array, bytes, bytearray, memoryview]
    ) -> None:
        ...

    def write(
        self,
        src_buffer: Union[array.array, bytes, bytearray, memoryview]
    ) -> None:
        ...
    
    class I2CDevice:

        def __init__(self, *args, **kwargs):
            ...
        
        def read(
            self, 
            num_bytes: int,
            mem_addr: int = -1
        ) -> bytes:
            ...

        def readinto(
            self,
            dst_buffer: Union[array.array, bytes, bytearray, memoryview],
            mem_addr: int = -1
        ) -> None:
            ...
        
        def deinit(self) -> None:
            ...

        def write_vector(
            self,
            src_buffer: Union[array.array, bytes, bytearray, memoryview]
        ) -> None:
            ...

        def write(
            self,
            src_buffer: Union[array.array, bytes, bytearray, memoryview],
            mem_addr: int = -1
        ) -> None:
            ...

        def write_readinto(
            self,
            src_buffer: Union[array.array, bytes, bytearray, memoryview],
            dst_buffer: Union[array.array, bytes, bytearray, memoryview]
        ) -> None:
            ...
        
    def __init__(
        self, 
        host: int, 
        scl: Union[machine.Pin, int, str], 
        sda: Union[machine.Pin, int, str]
    ):
        ...

    def scan(self) -> list[int]:
        ...
    
    def start(self) -> None:
        ...
    
    def stop(self) -> None:
        ...
    
    def Device(
        self,
        addr: int,
        freq: int,
        mem_bits: int = 8
    ) -> I2CDevice:
        ...
    
    def Display(
        self,
        freq
    ) -> DisplayDevice:
        ...
    
    def Touch(
        self,
        addr: int,
        freq: int,
        mem_bits: int = 8
    ) -> I2CDevice:
        ...


class LEDString:
    RGB: ClassVar[int] = 0
    RBG: ClassVar[int] = 1
    GRB: ClassVar[int] = 2
    GBR: ClassVar[int] = 3
    BRG: ClassVar[int] = 4
    BGR: ClassVar[int] = 5

    APA104: ClassVar[int] = 0
    APA105: ClassVar[int] = 1
    APA109: ClassVar[int] = 2
    WS2811: ClassVar[int] = 3
    WS2812: ClassVar[int] = 4
    WS2812B: ClassVar[int] = 5
    WS2813: ClassVar[int] = 6
    WS2814: ClassVar[int] = 7
    WS2815: ClassVar[int] = 8
    WS2815B: ClassVar[int] = 9
    WS2816A: ClassVar[int] = 10
    WS2816B: ClassVar[int] = 11
    WS2816C: ClassVar[int] = 12
    WS2818: ClassVar[int] = 13
    WS2818A: ClassVar[int] = 14
    WS2818B: ClassVar[int] = 15
    WS2851: ClassVar[int] = 16
    SK6805: ClassVar[int] = 17
    SK6812: ClassVar[int] = 18
    SK6813: ClassVar[int] = 19
    SK6818: ClassVar[int] = 20
    SK6822: ClassVar[int] = 21
    CUSTOM: ClassVar[int] = 0xFF
    
    class LEDDevice:
        def __init__(self, *args, **kwargs):
            ...

        def allocate_buffer(
            self,
            num_bytes: int,
            momde: int = -1
        ) -> memoryview:
            ...

        def release_buffer(self, buffer: memoryview) -> None:
            ...
        
        def tx_color(
            self, 
            buf: Union[array.array, bytes, bytearray, memoryview]
        ):
            ...
    
    class BitTiming:
        
        def __init__(
            self,
            first_duration: int,
            second_duration: int
        ):
            ...
    
    def __init__(
        self,
        data: Union[machine.Pin, int, str, SPI],
        freq: int = 10000000,
        ic_type: int = CUSTOM,
        byte_order: int = GRB,
        leds_per_pixel: int = 3,
        white_color_temp: int = 3000,
        blue_correct: bool = False,
        bit0_timing: Optional[BitTiming] = None,
        bit1_timing: Optional[BitTiming] = None,
        res_duration: int = -1
    ):
        ...
    
    def Display(self) -> DisplayDevice:
        ...
    
    def Device(self) -> LEDDevice:
        ...
    

My purpose to doing it this way it to keep the API the same across all of the bus types which will make it easier for the user to use and it will also make it easier on the development side of things because the API will be the same.

The above is a rough draft and I didn't put in what function parameters are keyword only and positional only.

I am looking for thoughts and or suggestion...

[hemonu]

Just one proposal. For the i8080 bus I recommend to include the rd pin in the defintion. I have faced a long term problem with a display having that pin connected. Finally I realised that I had to set that pin into a defined high state to get your great job running. I might be able to help in getting the read routines running to check status registers and read the display ram for test purposes.

[kdschlosser]

if memory serves the wr pin is the same thing as the rd pin. It's just a different name for it. It's kind of like the disp pin on the RGB interface which is actually the power pin. I still have to remove that pin from the bus as it doesn't need to be there because the power pin is handled by the display driver not the bus driver.

[hemonu]

On i8080 bus write and read are different signal. With rd you can read back the color data or status registers.

[hemonu]

This is from ili9488 datasheet. Please be aware that direction of RD signal is wrong. RD is controlled from the CPU not the display!

[kdschlosser]

Both the WR and the RD are controlled by the MCU. WR = Write, as in the MCU wants to write data to the display and RD = Read as in the MCU wants ro read data from the display.

The reason why the rd pin is not added is because there really is no need to collect anything from the display in the way of registers. Everything gets set when the display is first started. If you want to control what is going on then you can subclass the display driver and override the init function and alter the initialization of the display. You can place the current settings into instance variables and you would then be able to check to see what they are set to.

The display doesn't do anything on it's own. It has to be told what to do. it's not like it is going to change the color mode on it's own so there is no need to read what it is set to from the display because what it has been set to is known because that is what you set it to.

For example...
If you specify RGB888 as the color format the color mode is going to be 24 bit color. If you specify RGB565 it is going to be 16 bit color. that is what the display gets set to when it gets initialized. So having the ability to read what the color mode is when you are the one that has set it in code add a heap load of extra code and that in turn means more memory used on a device that has a very limited amount of memory.

If what you are using is a board that has the MCU and display already attached then the board was made wrong. The company that manufactured it should have pull up resistors on the RD and also on the WR lines. There are no settings that control the idle state of those pins. That is a failure on the board manufacturers part.

If you are connecting a display to an MCU using jumper wires then all you need to do is connect that pin on the display to +3.3v. That's all there is to it.

My suggestion is if you are using a premade board is to send an e-mail to the board manufacturer about it. A good board manufacturer should actually have that pin connected to the ESP32 by way of a solder jumper point and on the ESP32 side of the jumper point the pin should be broken out so you can use it for something else if the solder point is not connected. On the display side of the jumper point there should be a resistor connected to +3.3v to pull that wire up... The same thing should also be done with the CS pin on the display as well.

• CS: optional (pull direction depends on what the active state is. You want to pull the pin in that direction, most times it is low)
• RES: optional (pull direction depends on what the active state is. You want to pull the pin in the opposite direction)
• DC : required (controllable via driver)
• WR : required (pull up)
• RD : optional (pull up)
• D[17:0] : required

The I8080 bus is like SPI in that you can have multiple displays connected to the same pins only having to add a new CS pin for each display that is connected. the CS pin doesn't need to be connected to the MCU if there is only a single display attached to the bus. It's a waste of a pin. The same thing holds true for the RD pin and in my opinion the reset (RES) as well because you can reset the display by sending a command to it or powering off the display.