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.

After a quick warm-up exercise of verifying activity over expected serial transmission lines, I updated my code to use CircuitPython’s busio.uart to interpret that activity as asynchronous serial data. Based on earlier analysis, I expect to receive data at least once every 9.2ms, so I set up an asynchronous task to constantly process incoming data. The good news is that I saw a constant stream of 0x80 0x40, which was as expected. I had established 0x80 was the value reported for “no buttons are pressed” so I had expected that value to change if I pressed a button. It did not! Apparently key matrix scan code reporting doesn’t start by default.

In order to parrot the initialization sequence decoded by my logic analyzer, I need to write another asynchronous task. This one transmits given data and then wait for the receiver task to see an 0x20 acknowledgement byte before returning. Once up and running and initialization sequence sent, the receiver task started reporting key matrix scan code values. Success!

Up until this point I still had the Neopixel sample code running as a system heartbeat indicator. With serial communication up and running, I thought I’d switch over to using one of the LEDs on the control panel. I created another asynchronous task, this one loops to turn the “In Use/Memory” LED on and off at one second intervals while leaving the “WiFi” LED off. I have already decoded the bit flags necessary to toggle LEDs and I got a LED that blinked for a few seconds.

Then it got stuck.

Debugging indicated that my code got stuck because the data transmission to update LED state never received that 0x20 acknowledgement, which meant the transmit task never returned to caller. I quickly whipped up a timeout mechanism by checking timestamp in a loop. It worked, but then I realized there was already a mechanism built into CircuitPython. So I deleted my timestamp checking loop and replaced it with a single call to asyncio.wait_for().

I needed to write this timeout code and retry transmission for robust error recovery no matter the reason, but I want to know the reason why I never got 0x20 acknowledgement. Maybe there are times when the chip is not listening to my commands? Or maybe there’s a problem in my data transmission? I think it’s very likely the chip isn’t always receptive, but that’s not as important as the discovery there was indeed a problem with my data transmission.

I have a rough idea on how I would use CircuitPython’s asyncio capability to structure my learning project, but jumping straight into async/await in a new platform is too bold for me. I would rather ramp up gradually starting with running a few CircuitPython samples. Once I was satisfied my KB2040 board is generally working as expected, I started poking at project-specific needs. First task: see if I’ve soldered serial communication wires correctly by checking for activity on those pins in reaction to enable pin status. (Toggled via CircuitPython’s digitalio module.) I expect activity on the receive pin when the enable pin is high, and no activity when enable is low. The transmit pin should have no activity in both cases.

I had originally intended to check pin status by polling pins in a loop, which is not guaranteed to catch all activity but probably good enough for an “is there activity” check. Polling in a loop would have been trivial in an Arduino test sketch, but CircuitPython made it just as easy to pull in something more sophisticated: countio module counts rising/falling edges driven by hardware interrupts, which would have taken a bit more work to set up on Arduino. Great! Let’s do that.

I copied sample code from documentation and modified it for my purposes of watching pins D0 and D1, which were default UART transmit and receive pins on my KB2040. I saved my file and promptly got an error telling me I am not allowed to do this on D0. Huh? Re-reading countio documentation I saw a paragraph I had missed:

Limitations: On RP2040, Counter uses the PWM peripheral, and is limited to using PWM channel B pins due to hardware restrictions. See the pin assignments for your board to see which pins can be used.

Reviewing KB2040 pinout reference, I see D0 is also PWM0A and D1 is PWM0B. So they are both PWM-capable pins satisfying the first restriction, but only D1 satisfied the second restriction of channel B. Fortunately D1 on PWM0B is the default UART receive pins, so that’s the one I was more interested in checking status for anyway. And the check was good: when enable pin is high, there is a steady stream of activity on D1. When enable pin is low, activity stops. Good enough to take the next step, connect UART peripheral to those pins.

I want to apply my CircuitPython lessons to a project that will require importing the busio library to utilize asynchronous serial communication hardware on board a RP2040 chip. This is a pretty common microcontroller scenario, but example projects usually only deal with one direction, either just sending or just receiving. Adafruit’s CircuitPython UART serial introduction only received data and did not send. Things will get more complex as I intend to implement bidirectional communication, and even more so because there’s interaction between the two directions: I need to send data and listen for an acknowledgement.

If that’s the only thing being communicated, it would be easy: one line of code to send data, followed by a line of blocking code to wait for response data. But it’s more complicated in this project because the K13988 chip on the control panel sends key scan matrix reports on a regular basis. (Every ~9ms.) If I wrote my code in the naive way, that wait for response may pick up a key scan matrix report byte instead of the acknowledgement byte. What I need is something that is constantly receiving and processing data, mostly key scan report bytes. After the data sender code runs, it will have to wait on the receiver loop to pick out any acknowledgement bytes as they come through in between key scan reports.

This is doable within an Arduino-style loop(), and I’ve done it before, but I end up with code that’s hard to follow as it rapidly switches between multiple contexts. That’s why I was happy to learn CircuitPython implements the async/await pattern with its asyncio library, which should theoretically allow cleaner code structure. My prior experiences with this pattern mostly centered around JavaScript client/server networking code and not microcontrollers, but never fear, as per usual for Adafruit there’s an excellent guide Cooperative Multitasking in CircuitPython with asyncio putting the pattern in context for microcontroller tasks.

It also highlights an important simplifying characteristic of CircuitPython: it has only a single thread of execution running a single event loop, so there is no concern of race conditions between multiple threads/loops and we don’t have to worry about protecting critical sections. Eliminating concurrency eliminates all the huge headaches of writing concurrent code, at the performance cost of running only a single core. A RP2040 has two cores, like an ESP32, but apparently one core sits idle while the other runs CircuitPython. For this project (and most of my potential CircuitPython projects) a single CPU core will suffice. I’m not going to worry about the lack of dual-core operation until I run into an actual problem that needs it. Right now my problems are simple, like checking to see if there’s any activity on a pin.

---

Installation note: for most CircuitPython libraries in the bundle, we install it by copying its single corresponding *.mpy file into the \lib\ subdirectory on our microcontroller’s CIRCUITPY storage volume. But asyncio is actually a directory containing multiple *.mpy files and we copy the entire directory under \lib\ so all its components are under \lib\asyncio\*.mpy.

For my first nontrivial CircuitPython project, I thought I would try getting a microcontroller to communicate with control panel salvaged from a Canon MX340 multi-function inkjet. Like most microcontrollers, the RP2040 chip at the heart of my KB2040 board can handle asynchronous serial communication via its UART hardware peripheral. Under CircuitPython, this peripheral is exposed by an uart class. It is under the umbrella of busio library, which includes hardware-accelerated communication of popular serial buses I2C, SPI, and asynchronous serial. CircuitPython has several libraries with the io suffix, and given their hardware-focused nature they appear to be a big chunk of the work required to port CircuitPython to a new microcontroller.

One aspects of CircuitPython (and MicroPython) I found enticing is the ideal that I could develop and debug code on my desktop computer and then copy it to run on a microcontroller. Unfortunately this goes out the window when I want to use hardware-accelerated features like busio.uart. Its name clearly announces that it is not trying to act like PySerial on the desktop. If I want to write something that works on both desktop Python and microcontroller CircuitPython, I would have to write an abstraction layer restricted to the small subset of common features I need in my project. Learning how to write such adapter code is on my Python learning to-do list, but it is out of scope for my first CircuitPython project. I’ll stick with busio.uart and develop/debug strictly on microcontroller.

One Python skill area I want to improve is structuring my code to better handle non-sequential events. The relevant scenario today is sending serial data out the transmit pin while simultaneously responsive to serial data coming in over the receive pin. Plus handling when the two interact: for example waiting to receive an acknowledgement after sending data. My earlier serial data filtering tool handled reading from two serial ports by rapidly switching between polling the two ports, but in hindsight, that was not elegant code and it didn’t handle interaction between the two streams. In the search for a better way, I recall Python supported the async/await pattern I’ve encountered earlier in JavaScript and C#. Furthermore, CircuitPython supports some form of the pattern as well, so I’m going to give it another go.

After reading through AdaFruit’s “Welcome to CircuitPython” guide, the obvious next step is to tackle a project to apply what I’ve learned. I do want to apply it to a rover project, but I fear that’s too big of a first step. Looking around at what I have, I decided to communicate with the control panel I salvaged out of a Canon Pixma MX340 multi-function inkjet.

During my teardown I mapped out the pinout of its ribbon cable connector to printer logic board. I then connected my logic analyzer (and other tools) to understand its communication to the best of my ability, with findings summarized here. In theory, all I have to do is to use CircuitPython to tell my KB2040 how to replicate what I observed coming from MX340 logic board, and I will have a control panel I can use for a future project. In practice, I’m sure it wouldn’t be quite that easy but hey that’s the fun part!

Examining my deciphered pinout list, I connected the three pins leading to the NEC K13988 chip on board. Asynchronous serial transmit, receive, and the chip enable pin. I also need to supply +3.3V DC logic power and connect ground, but that doesn’t strictly need to be on the small 1.0mm pitch connector. I found a few capacitors that presented a larger surface for soldering my wires. For this first round I won’t bother wiring up the direct connection to two buttons (Power and Stop) and two LEDs (Power and Alarm) as getting those working should be fairly straightforward for a microcontroller project and I don’t foresee any educational challenges there. I can do that after I tackle the more interesting challenge of CircuitPython serial communication.