Supporting the M5Paper's IT8951 driven epaper display

[hierophect]

Starting this issue to track how (and perhaps if) the epaper display on the M5Paper ESP32 development board from M5Stack can be supported. I think the main issue is this board's SPI display driver, the IT8951, is built around read/write commands instead of being read-only and requires 2-bit preamble words before any command. Looking at the displayIO implementation I don't believe there's any way to get around this even if I tried sneaky byte insertion into the screen data. Are there any existing display systems that are similarly incompatible with displayio that can still make use of some of Circuitpython's rendering features? Or alternatively I could be wrong here and there's a better way to integrate it with displayio directly.

The M5Paper was planned in #8290 and implemented in #8293. Screen support was put off within the PR due to the complicated driver. The datasheet for the IT8951 can be found from waveshare here.

[bablokb]

Are there any existing display systems that are similarly incompatible with displayio that can still make use of some of Circuitpython's rendering features

It depends on how you define "similarly". I own two displays from Waveshare that always need 16-bit commands (usually commands are 8-bit and data is 16-bit). For the init-sequence, it was no problem filling in the additional bytes, but for the definition of the region it was. So I ended up with a patch that I apply to my own builds for these specific displays (see: https://github.com/bablokb/circuitpython-examples/blob/master/waveshare-3.5/bus_core.patch).

[tannewt]

Here is an example write:

The trickiest bit may be toggling CS between the command and write data packets.

This is the command you'd use to load data:

I think the simplest thing would be to make an EPaperDisplay class copy, cut it down and then change it to do exactly what you need. You could also add another kwarg to EPaperDisplay to do this behavior. @bablokb, you could do that for your patch as well.

[hierophect]

I think the simplest thing would be to make an EPaperDisplay class copy, cut it down and then change it to do exactly what you need. You could also add another kwarg to EPaperDisplay to do this behavior. @bablokb, you could do that for your patch as well.

Which do you think would be clearer for dev experience? Or are you just suggesting to do the first for testing simplicity and then merge in as the second?

[tannewt]

I'd say start by modifying the existing class and see how much you change.

[bablokb]

@bablokb, you could do that for your patch as well.

I think we discussed this and the decided against doing it. We would have to change many existing board files to add this additional parameter only to support an obscure hardware-implementation. And my displays aren't e-paper, so the kwarg would go to BusDisplay which is used much more often in the code-base.

[tannewt]

@bablokb, you could do that for your patch as well.

I think we discussed this and the decided against doing it. We would have to change many existing board files to add this additional parameter only to support an obscure hardware-implementation. And my displays aren't e-paper, so the kwarg would go to BusDisplay which is used much more often in the code-base.

I don't remember that but my brain is sleep deprived. I think it's fine to PR in and just change all of the spots. It's a pain to do but not hard to maintain.

[hierophect]

I'm continuing to work on this but I'm struggling to get a screen clear test working. I've been working from the datasheet, official M5Drivers and a prior attempt at porting this driver to Circuitpython. From these sources, the display update process is as follows:

• Send a command packet with a code indicating that an image data transaction should start
• Send a data packet with endian, BPP, and rotation information
• Send data packets, of any length, to fill every pixel of the screen buffer. There may be more than one pixel per byte.
• Send a command packet with a code indicating that an image transaction should end
• Send a command packet with a code for beginning a display update transaction
• Send a series of data packets with starting location, dimension and mode data.

Would anyone be willing to sanity check my attached screen clear script to see if there's something dumb derailing me here? I also need to take a deeper dive on how hard the above steps will be to integrate in a displayio subclass.
test.txt

Edit: wrong file version

[hierophect]

I'd like to manually snoop the SPI line with the factory firmware but the pitch on the IT8951 is pretty tiny, I'd be nervous putting on magnet wire.

[hierophect]

Continuing to struggle on figuring out the correct boot sequence for this screen, which I feel is kind of a pre-requisite to integrating it with displayio. I rigged up my saleae to snoop the SD line, which is shared with the SPI for the screen itself, and got the exact sequence of SPI startup commands, which I cross referenced to the official driver. I also added in some power bus enable steps I'd missed in my original test sketch.

However, despite being able to see that I'm sending the correct SPI commands with my sanity check sketch, the screen still will not update. My suspicion is something about the power bus lines, because there's a weird phenomenon where if I enable the screen power after SPI is initialized, the code will be interpreted normally, but if I do it before SPI initialization with a short delay after the main power bus enable (as the official driver does), Circuitpython's power will dip, the sketch will crash, and the interpreter is forced into safe mode until I clear the file and reset. This does not occur with the factory firmware even when plugged directly into my computer instead of a powered hub.

@tannewt do you think it'd be ok for me to try and tag in the person who submitted the original PR for the M5Paper? They mentioned something about the M5Paper needing some kind of delay for SPI - starting out at 1MHz and then needing to be ramped up to 10 later? I don't know where they got that information and I wonder if it's relevant to this screen weirdness.

[hierophect]

Nevermind, I have ruled out power rail issues by virtue of it having done... something?? Must be something funny about the startup sequence of display modes.