I have built up a rough set of CircuitPython code that sends a bitmap to show on LCD screen of a salvaged Canon Pixma MX340 multi-function inkjet. I abandoned my effort to get sprite compositing via displayio, but I still want to do something fun with this screen. As an experiment, I wrote a loop that continuously sent LCD frames to display, exploring its theoretical ~14fps top speed. The result was very jerky, and CircuitPython console output showed a lot of my error message indication transmission failures that had to be retried.

The first data point was adding a small delay between frames to see if that changes behavior. It did not, so I believe these failures were not caused by a relentless nonstop stream of frames. The next data point was to remove my heartbeat LED, and that stopped the stream of errors. Interesting.

The heartbeat LED is a separate task, with asyncio switching back and forth between LCD updates and heartbeat LED updates. Heartbeat is a simple loop that blinks the “In Use/Memory” LED on and off by transmitting corresponding control flags. Each toggle is a two-byte transmission, but the LCD screen update is a much longer sequence of data transmissions.

Task switching could occur at any await statement, which means it is possible for heartbeat LED update command to barge in the middle of a LCD sequence. The most inconvenient time would be right after the 0x04 0xC4 command “Bulk transfer of 196 bytes incoming”. If the next transmission is a two-byte LED toggle instead of the expected 196 byte transfer, everything would understandably go awry.

To prevent interleaving data transmission between tasks, I need to add a locking mechanism so heartbeat LED updates will hold off until LCD screen update is complete. And in case of continuous nonstop LCD animation, it needs to make sure heartbeat LED update gets a chance in between frames. Out of habit I started writing my own locking mechanism but then realized I was being silly. I went to read documentation and confirmed a lock is already available as asyncio.Lock. I only had to create a single instance of the object, then as per documentation add an “async with” statement on that instance to prevent my two data transmission tasks from stepping into each other’s sequences.

It worked! I could put my heartbeat LED back into the system, spin the LCD animation updates to full speed, and they both run. No longer interrupt each other and causing transmission errors. But this experience really gives me a feeling I’m wielding powers beyond my comprehension. I barely understand async/await and now I’m adding “with” context management which I also barely understand. This is probably a good time to pause my uninformed code-slinging and read some tutorials and/or specifications to understand what’s going on.

After a small (if not necessarily elegant) enhancement to adafruit_framebuf class, I can use it for basic graphical operations on the bit-mapped LCD of a salvaged Canon Pixma MX340 multi-function inkjet control panel. I then set my sights on adapting it to work with Adafruit’s graphics compositing engine displayio, but that turned out to be more difficult than I had thought.

I don’t know the full history but looking in hindsight I think displayio was optimized for sprite rendering, the most performance-critical part of a 2D game engine. Such a system would support products like Adafruit PyGamer. Not so important for this inkjet control panel LCD, whose refresh rate tops out at just under 14 frames per second. But I thought it would be fun anyway.

Adafruit has displayio drivers for their most popular screens and obviously my LCD is none of them. Looking for an appropriate tool, I found their framebufferio class which takes a frame buffer and returns a display object. Its target usage scenario allows using displayio with a RGB LED matrix, which has resolutions with similar order of magnitude as my LCD. This looks promising.

When I fed framebufferio my FrameBuffer class, I crashed my KB2040 which restarted in safe mode. (Indicated by triple blinking yellow LED.) Annoyingly, when a CircuitPython device crashes and reboots like this, Mu closes its serial terminal so I couldn’t read the error message before it immediately disappeared. I had to bring in a different serial monitor tool in order to see the error:

TypeError: 'FrameBuffer' object does not support 'protocol_framebuffer'

Darn. Looks like the CircuitPython frame buffer object I had been working on, isn’t the CircuitPython frame buffer object expected by framebufferio. If I want this to work, I have to implement “protocol_framebuffer“, but what is it? Clicking on the link brought me to something called circuitpython_typing.FrameBuffer, which forwards to rgbmatrix.RGBMatrix. I added methods to my FrameBuffer-derived class in order to match those listed for RGBMatrix, but that was not good enough.

Digging deeper meant going into core CircuitPython written in C. I found framebufferio/FrameBufferDisplay.c which had this line:

self->framebuffer_protocol = mp_proto_get_or_throw(MP_QSTR_protocol_framebuffer, framebuffer);

I think this is where my error message came from, so the next step is to find more information on the expected protocol which was declared in the associated header file FrameBufferDisplay.h.

typedef struct _framebuffer_p_t {
    MP_PROTOCOL_HEAD // MP_QSTR_protocol_framebuffer

    // Mandatory
    framebuffer_get_bufinfo_fun get_bufinfo;
    framebuffer_swapbuffers_fun swapbuffers;
    framebuffer_deinit_fun deinit;
    framebuffer_get_width_fun get_width;
    framebuffer_get_height_fun get_height;

    // Optional getters
    framebuffer_get_bytes_per_cell_fun get_bytes_per_cell; // default: 2
    framebuffer_get_color_depth_fun get_color_depth; // default: 16
    framebuffer_get_first_pixel_offset_fun get_first_pixel_offset; // default: 0
    framebuffer_get_grayscale_fun get_grayscale; // default: grayscale if depth < 8
    framebuffer_get_native_frames_per_second_fun get_native_frames_per_second; // default: 60
    framebuffer_get_pixels_in_byte_share_row_fun get_pixels_in_byte_share_row; // default: false
    framebuffer_get_reverse_pixels_in_byte_fun get_reverse_pixels_in_byte; // default: false
    framebuffer_get_reverse_pixels_in_word_fun get_reverse_pixels_in_word; // default: false
    framebuffer_get_row_stride_fun get_row_stride; // default: 0 (no extra row padding)

    // Optional -- default is no brightness control
    framebuffer_get_brightness_fun get_brightness;
    framebuffer_set_brightness_fun set_brightness;

} framebuffer_p_t;

This is beyond my current understanding of CircuitPython code. Does it mean framebufferio only works with Adafruit’s own frame buffer objects written in C? Or is this compatible with user-created Python code somehow? Again I tried modifying my FrameBuffer-derived class to fit this signature, but either I made a mistake somewhere or it is fundamentally impossible. I wish I could get finer-grained error message telling me where exactly I failed to support protocol_framebuffer, but I just keep getting the same failure leaving me stabbing in the dark.

After a few hours of fiddling without success, I abandoned displayio compatibility and wrote up this page in case my future self wants to pick up where I left off today. Without displayio I’ll learn what I can from using adafruit_framebuf. First lesson: updating LCD at a high frame rate required task synchronization.

I’m playing with a LCD screen built inside the control panel I salvaged from a Canon Pixma MX340 multi-function inkjet. I tried using CircuitPython’s adafruit_framebuf library for drawing operations. Out of all supported frame buffer formats, the closest is MVLSB but those bits are in reversed order. I added code to reverse bits, which put a picture on screen but the real solution is to add proper buffer format support.

I was encouraged by adafruit_framebuf‘s description in its documentation: “CircuitPython pure-python framebuf module, based on the micropython framebuf module.” If this library was itself implemented in Python, I should be able to figure something out. Clicking “Edit on GitHub” link on the upper right, I was brought to the GitHub repository for adafruit_framebuf and I quickly found source code file for the module.

At the top of adafruit_framebuf.py are a series of classes, each representing one of the supported buffer formats and implements four static methods: set_pixel(), get_pixel(), fill(), and fill_rect(). I found the implementation for MVLSBFormat and it looks like it’s within my skill level to copy it and reverse its bit manipulation operators to create a MVMSBFormat counterpart. The next problem is: how do I use my custom MVMSBFormat class with the FrameBuffer class? FrameBuffer‘s __init__() assigns a format class in response to initialization parameter, and it raises a ValueError() if it doesn’t recognize the parameter.

That’s when I remembered I am still thinking like a C/C++ programmer and Python doesn’t have a concept of private properties. I could create an instance of FrameBuffer for MVLSB format, and then immediately replace the .format property to point to my MVMSBFormat class. As a C/C++ programmer, this feels extremely icky. Is this the correct Python-ic approach? I doubt it, but I don’t know the right way. So right or wrong this is what I have now.

With my FrameBuffer.format pointing to my MVMSBFormat class, adafruit_framebuf drawing operations render correctly on screen without the need for bit reversal utilities. As a bonus, eliminating bit reversal overhead also meant I could draw text again without encountering “RuntimeError: pystack exhausted“. I think that’s good enough to declare victory with basic bitmap operations and move on to a sprite compositing engine.

Once I found and fixed a missing command within my initialization sequence, I have gained full programmatic control over the LCD screen of a control panel I salvaged from a Canon MX340 multi-function inkjet. The main point of the exercise was to learn, because it’s a relatively simple black-and-white screen 196 pixels wide by 34 pixels tall and not terribly exciting on its own. Still, now that I know how to send it frame buffer data… what can I do with it?

I’m not interested in re-implementing standard graphics routines myself, so I went looking for one already available. While learning about MicroPython I recall coming across mention of a framebuf utility class for basic graphical operations on a frame buffer. As a fork of MicroPython, Adafruit has a corresponding CircuitPython implementation named adafruit_framebuf so I thought I’d take a look.

One of the frame buffer byte formats supported is called MVLSB. The M stands for monochrome, and the V means each byte represents a vertical column of eight pixels. LSB means least significant bit is the highest pixel, and the most significant bit is the lowest. This is very close to what I have on hand except for the bit order. On this screen, the least significant bit is the lowest pixel and they go up from there.

This is the result of drawing a diagonal line from upper left (0,0) to lower right (195,33). Since bit order is reversed within each byte, each horizontal stripe of data gets rendered vertically inverted from what they are supposed to be.

Drawing text results in gibberish when it crosses stripes. But if I position the text so it sits entirely within a single stripe, the result is legible as vertically inverted text. “Hello Framebuffer” in this case.

I could write some code to laboriously step through each bits in a byte and generate a bit-reversed counterpart value, but since there are only 256 possibilities, a lookup table would be much faster at the expense of a bit of memory. I went online looking for such a lookup table and found one in this Stack Overflow thread: Efficient Algorithm for Bit Reversal (from MSB->LSB to LSB->MSB) in C.

I modified that lookup table from C to Python syntax, and used it to reverse a stripe of frame buffer data before transmitting it to the LCD. Now my diagonal line renders as expected. Unfortunately, text rendering now fails with “RuntimeError: pystack exhausted“. This was unexpected. The lookup table itself would have consumed at least 256 bytes, and there’s an additional 196 bytes of working buffer for me to perform bit reversal on a single stripe. I didn’t think I was skating close to RP2040 limits yet here we are. Also, it’s not a general out of memory error, but specifically about call stack size and the bit reversal mechanism didn’t increase the call depth at all. Weird!

Well, reversing bits was just a hack anyway. The right approach is to add support for this byte format directly so convoluted bit reversal workaround becomes unnecessary. And it restored text rendering, too.

I had incorrectly configured asynchronous serial communication parameters between my KB2040 microcontroller running CircuitPython and NEC K13988 chip on a control board salvaged from a Canon MX340 multi-function inkjet. But once I sorted that out (two stop bits, not just one) I could successfully send a full set of frame buffer data to the LCD with minimal transmission failures. This allowed me to follow up on an observation I had from my first test: the vertical frame buffer byte offsets are not as expected.

The pattern I saw via logic analyzer indicated the top 8 pixels of the screen were dictated by sending pixel data with the offset 0x4D to start the sequence. But when I tried doing the same thing with my KB2040, the stripe rendered two pixels lower than expected. This pattern continued for the rest of the screen, with successively lower rows corresponding to 0xCD, 0x2D, and 0xAD. When I decoded frame buffer data captured by logic analyzer, offset 0x6D dictated the bottom-most two rows of pixels. (The least significant six bits are not visible.) However, now data sent to 0x6D is not visible at all. Experimenting with other offsets, I stumbled on the fact I could transmit data to 0x8D and that data would help me fill in the top two rows of pixels. (The most significant six bits are not visible.)

Even though it was unexpected, that was good enough for my next experiment: I changed the program so instead of a fixed value, each byte counts up one. This gave me get a precise delineation and count for all horizontal and vertical pixels. Thanks to this test pattern I am now confident this LCD has 196 pixels horizontally and 34 pixels vertically.

But what about that unexpected offset? The most likely suspect is a mistake in my initialization sequence, and a double-check found the culprit. There was a two-byte sequence 0x04 0x42 in my decoded notes, but I forgot to put that in my KB2040 initialization sequence. Once I put that back in, my LCD frame buffer renders at the expected location. On my to-do list is to play with my initialization sequence, selectively skipping them to see what effect they have on behavior. Looks like I inadvertently started that experiment early! This little side trip also suggested an interesting possibility: that the LCD controller has extra frame buffer memory available, possibly allowing vertical scrolling without re-sending the entire frame buffer.

Without the datasheet, though, that’s mostly an empty thought. It’s more productive to try to pair this display with a graphics library.

I’ve got an Adafruit KB2040 microcontroller connected to a control panel salvaged from a Canon MX340 multi-function inkjet. Using CircuitPython busio.uart, I’m trying to emulate MX340 main logic board with my KB2040, communicating with the NEC K13988 chip on board the control panel hoping to access its capabilities. I saw some initial success, but I had to retry many data transmissions which hinted something was amiss. I forged onward to get more data about what might be wrong.

The first experiment was to test my hypothesis that the first LCD update sent by MX340 main board was a “clear screen” sequence. I sent 0x04 0xF5, the command I suspect to be “start displaying data from frame buffer”, but without transmitting the clear screen sequence of zeroes. I was rewarded by an awakened LCD displaying gibberish, proving the command and “clear screen” data hypothesis.

Pulling up my notes on decoding LCD frame buffer data, I followed that pattern to transmit a single stripe of 0x55 as frame data. Hexadecimal 0x55 translates to binary 0b01010101 and I expected this to show up as four horizontal lines across the screen. The first few attempts failed, with no visible change and no 0x20 acknowledgement byte. Then a transmission went through with visible change and 0x20 acknowledgement, but it looks wrong.

Instead of four horizontal lines all the way across, the line is broken as it hopped up and down across the screen. The fact that it came up on screen at all told me I’m very, very close but there’s definitely a problem. At every byte (vertical slice of 8 pixels) there was supposed to be an alternating sequence of bright and dark, but I see several sections where two white pixels separate black pixels, and less frequently two dark pixels side by side without a white pixel separating them.

What might cause these off-by-one-bit errors? My first guess was that the baud rate sent by KB2040 was a tiny bit off from what the control panel expected, so I tried 250001 baud and 249999 baud but that just made things worse. Even parity and 8 data bits had to be correct or I wouldn’t have gotten this far, leaving stop bits as the final parameter. I changed my busio.uart configuration from 1 stop bit to 2 stop bits and that seemed to have been the answer.

Running with 250000 8E2, I could reliably send five full stripes of 0x55 for a screen full of clean horizontal lines. This makes sense in hindsight. When I examined logic analyzer trace one byte at a time, I wouldn’t have seen anything obviously differentiating between 2 stop bits or just 1 stop bit and delay between each byte of transmission. A mistake that went unnoticed until now. However, I still see the occasional transmit failure, so there might be another bug still lurking. I hope to get more data about it as I continue my experiments.