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.

I thought I might design and 3D-print something to repurpose components salvaged from a disassembled Harbor Freight mini LED flashlight. I still might do that, but another thought occurred to me: for the purpose of CadQuery practice, I don’t need to invent something new, I can try to model the salvaged components themselves.

So I pulled out my calipers and started taking down dimensions for the front window, shiny reflector module, and the circuit board hosting the array of nine LEDs. The front window is trivial, a single flat cylinder, but it got more complex from there.

The good news is that, despite some worrisome early signs, CadQuery has proven to give me better feedback on my mistakes than FreeCAD has. Especially from code centric aspect of Python syntax errors because that gives me a line number of the problem. CQ-Editor also gives a very code centric capability to step through my CadQuery design line by line, which makes debugging much easier than trying to understand where I went wrong in a FreeCAD design.

The bad news is that I have yet to build a mental understanding of how CadQuery coordinate spaces work. I’m frequently confused by parts popping up at positions or orientations different than where I had expected. For some of these mistakes I could see my misunderstanding after the fact, for other mistakes I still don’t understand where I went wrong.

    p = cq.Workplane("XZ")
    p = p.polygon(8,led_ring_diameter, forConstruction=True)
    p = p.vertices()
    p = p.eachpoint(
        lambda pos: (
            ring.add(
                make_led(),
                loc = pos,
                color = color_clear_plastic
                )
            )
        )

In this code snippet, I am working on the XZ plane and I drew a construction octagon on this plane. I then placed an LED at each vertex of that octagon, but they were position on the XY plane instead of the XZ plane.

Why did this happen? I have yet to figure out the root cause. So far I only have a workaround: insert extraneous intermediate CadQuery assemblies for the sake of rotating parts to where I had expected them. I know it isn’t the right tool for the job, but I appreciate CadQuery giving me such tools to bludgeon my way to an imperfect but acceptable state. This is much preferred over FreeCAD’s unhelpful “recompute failed!” leaving me staring at the screen with no recourse.

One of my long standing to-do list items is to understand and master control of brushless DC motors. My goal is small robots, so I want to work with motors bigger than tiny multirotor aircraft motors and smaller than beefy electric car motors. Towards the upper range of my interest (before their voltage/amperage start to get scary) are motors used in two-wheeled balance scooters. As a Back to the Future fan, I am offended these devices have been marketed under the name “hoverboard” but that is out of my control.

I’ve been waiting for their prices to drop and they seemed to have settled near the $100 mark. When my local Target advertised a sale dropping a “Jetson Rogue” below $100, I got one with the intent of taking it apart to see what’s inside. But I have yet to do so and it has since gathered a thick layer of dust. It occurred to me I should charge up the battery occasionally. I plugged in the charger and… nothing. Hmm. Not good.

Opening it up, I found its battery pack had a single commodity XT60 connector and nothing else. I can work with that.

I’m mildly concerned by the fact this device had wires that didn’t go anywhere. This white wire has a crimped metal end but it’s not part of any connector I could find.

This properly crimped connector is likewise missing anything to plug into.

Those are mysteries to be solved later. Right now I want to see if the battery is dead or if it can be revived. I unplugged the XT60 connector and measured approximately 3V across its terminals. This is low even for a single cell. The label said it was a 7S2P battery pack with a nominal voltage of 25.9V so yeah, I had waited too long to keep it properly charged. Over-discharging is bad, but it is not necessarily fatal.

I set my bench power supply to deliver up to the full 29.4V appropriate for seven lithium-ion cells in series, but limited to a current of 50 mA. This is 5% of the rate delivered by its charging power adapter and should be very gentle on the battery cells in their delicate over-discharged state. I connected the battery, and my power supply control panel showed power delivery was jumping around. 8V for a second, then no power draw at all for several seconds. Then 9V for a second, and things cut out again. This was unexpected. I disconnected my power supply to investigate further.

Thankfully this battery pack enclosure was held together with screws, so I could open it up for a look inside. Aha! It is not a raw package of 14 cells in 7S2P configuration, they are under care of a battery management system (BMS) board. Similar to the 3S BMS board I had played with, but this one handles 7S cells. There are spot-welded tabs to monitor voltage of each 2P group. Some of those spot welds are… not textbook, let’s say. But they have continuity and they let me measure voltage. The situation looks even better here. Each 2P group (B- to B1, B1 to B2, etc. through B6 to B+) ranged from 1.1V to 1.9V. The pack as a whole is actually hovering around 10V across its “B+” and “B-” terminals. This is still over-discharged but in far better shape than 3V I measured across output terminals. (P+ and P-)

While the BMS chip is designed to allow charging across P+ and P- terminals, a over-discharged battery is outside of its normal operating range. For reasons I don’t understand, this chip is cutting in and out as I tried to charge with gentle low amperage. The chip may be taking deliberate action to work with over-discharged cells, but it may be getting confused by either the low voltage or my low amperage. There’s a chance the chip’s algorithm is confused and is on a path to destroy itself, the battery cells, or both.

I decided not to trust the chip and go with what I know: steady charge at a gentle low rate. With the pack open, I could connect my bench power supply directly to B+ and B- terminals. This bypassed the BMS chip and allowed me to slowly bring up voltage across the whole pack. Many hours later, pack voltage was up to its nominal 25.9V and I disconnected my power supply. I left the pack sitting overnight so internal chemistries can take its time balancing everything out. It was left outdoors in a bucket, just in case the chemistry decided to get angry. The next day I was happy to see it did not burst into flames. I put it back into the scooter. Now the scooter was willing to power up, and was also willing to take power from its charging adapter. I think we are back in business.