How to fail with CircuitPython

 

All code will have errors. You might find it sooner or later, or the error might be in your code, in a library that you are using or even in CircuitPython itself!

It is also very common to write some code on your lab environment, test it a bunch of times, then take it out into the field and watch it fail in lots of ways you would never though of. Exactly the same happens when you give your device to a user or a kid who will test it in ways that will make your coding skills feel silly.

In my case this is happening for a weather station. This should be a simple project, right? Grab some data from a sensor like a Stemma QT thermometer, then send that data to Adafruit.IO and watch it get graphed in a lovely dashboard. Or at least that was my expectation for this project.

As you can see, I started getting missing data for days, and only when I went to the semi-remote location where I am testing my weather station, and manually rebooted the devices, I would get start getting data again. But now the graph is ruined, it has a large gap in the data and to all whom I showed the graphs, the first thing they mentioned is 'what happened to the missing data?'. Now what do I do?

Look at the last hours of the graph. Even if I am missing only a little bit of data, it looks terrible right? You, the reader have no idea how hot it is during the day, how cold it is during the night, or what is the coldest hour. Your eyes go straight to the missing data at the end, with the graphs looking like a shark tooth and being jumpy. What a disaster.

I thought about blaming Adafruit.IO or maybe CircuitPython or maybe it's the fault of the ESP32 that is reading the data. Then I thought about adding extra hardware to it like a TPL5110 power timer but that would require some soldering and would break the wifi workflow that I love so much from CircuitPython 8.

I cloud also get my code full of try and except Python blocks on all of the parts of my code. To be honest, I did tried to do it this way, but things would still keep failing so I kept adding more try/except blocks until the code looked terrible. I was this close to having a project that was not fun for me, and that I would not like to share how it works with this amazing community that makes CircuitPython what it is. Not sharing? That doesn't sound like me at all. Time to do things a different way.

Loving to fail

There is a bit of a hidden gem in CircuitPython and it's the supervisor module. I was only able to find a little bit of technical documentation without a simple example that I could just copy and paste into my project, and I also found another example which was close to what I wanted to do in Tod's CircuitPython tricks.

After staring at the code I had available for a couple of minutes, I realized that this is what I had to do. I needed to let go of my impulse of keep the code failure free, and embrace CircuitPython failing. I would let if fail any time it wanted, and then I would ask it to try again.

With two simple lines, my weather station code can now fail because the wifi router is down, because the Stemma QT cables had a problem with talking to the sensor, because it was running for so long that it was finding errors in the CircuitPython base code or the request library. It doesn't matter, the board will accept that something weird happened, and would try again. Try this in your code and love to fail as much as I do now!

import supervisor

supervisor.set_next_code_file(filename='code.py', reload_on_error=True)

It should not be this simple, right? Here's how it works:

In the first line of code we are calling a library called supervisor. Don't worry, you don't have to install anything, it comes as a standard CircuitPython library and will probably work on any board that you have CircuitPython running on. What it does, is talk to one of the internal parts of CircuitPython and modify how it will behave.

The second like, is the one that changes how it works. It's using a function called set_next_code_file. It's normally used so that you can run the well known code.py file and if something happens, you can define a second file with another name and that code would do something like recover things, blink a light or beep to indicate that it will not behave as it would normally do. I am not calling a second file, instead I'm telling it to go to code.py so that it can try again.

And my favorite part comes with the code that says reload_on_error=True. The way CircuitPython works is that when it fails it will take you to the REPL console, and show you why it failed. This is a good thing as that is the way that we learn, we make mistakes, the REPL shows us what those mistakes are, and we go and fix them.

But for my weather station, once the code was ready and it was doing what I wanted, if there is a failure like the wifi is down, it would go to the console and wait for me to do something. This weather station is located on a dry forest in Costa Rica and it doesn't know that is not next to my computer where it's easy for me to tell it to try again. So what reload_on_error=True tells it to do, is to change what it would have usually do and take me to the console, and instead it will do something similar as if I was close so the board, pushing the RESET button every time something unexpected happens.

This way, CircuitPython will keep on trying over and over until wifi comes back, and hopefully the graphs will have smaller gaps in the data, and they will look much better and should be able to work like a weather station should. Read the thermometer. Send it to Adafruit.IO. Go to sleep to save some battery.

I love you CircuitPython! You and me can fail as many times as we need to, as long as we do it together and without feeling bad. <3.

 

Inspiration

This project was born from two desires. One, see if our dog could be taught to use buttons without spending piles of money. Two, to make use of an ancient Raspberry Pi.

Lots of people have done a project like this, and it isn’t necessary to use a Raspberry Pi. That just happened to be the only unused piece of electronics I had on hand with audio output. But, I will say that I definitely recommend this approach for a couple reasons. Firstly, it’s very easy to get running in Python with Adafruit’s Blinka library. Second, it leaves lots of room for growth (both in number of buttons and features like button presses sending digital messages).

Be sure to read all the way to the bottom for a cute puppy photo!

Materials Used

• Raspberry Pi (low cost model A)
  • Gifted by a coworker who was going to throw it out
• 16GB (full size) SD card
  • Came with my 3D printer, but is overkill for that purpose
• Audio cable
  • From a box of junk computer parts
• Audio amplifier
  • Included in a box of junk that got shipped to me
• Speakers
  • From an old CRT TV
• Jumper wires
  • Reused from multiple projects
• Keyboard breakout
  • Hand made from salvaged diodes, jumper headers, perf-board, wires, and solder.  Let's call it 50% recycled.
• 3D printed buttons (and some hotglue)
  • Technically new, but I don't count 3D prints if they displace buying other plastic
• Electronic buttons inside the prints (also a boot button shutdown switch)
  • All salvaged from ewaste or otherwise discarded
• Wooden mounting board
  • Had to buy it from a hobby store

Salvage percentage ~83%!  Hard to give an exact number... do you measure by count?  By volume?  By mass?  By value?  Do you count new tools you had to buy?  Whatever, I'm going to call it 83%.

C3P0 can talk. R2D2 expresses what he's thinking with beeps and boops. What can you do with a Neo Trinkey?

 

How about.....Morse code? It's simple, and four neopixels is more than enough to say anything! Here's how I set about doing it.

The great thing about Circuit Python is you can just plug in a device and use any editor on the code, but I like to use thonny as my IDE. Thonny gives you easy access to the REPL and you can have plenty of print() statements for debugging.

 

I love using the random library - it's a simple way to introduce variety into simple programs and here's one example, what I call "Spock on a Chip." Here's a link to the repository.

Copy the files to a NeoTrinkey, changing "spock.py" to "code.py" - when it runs, it occasionally blinks lights, but when you touch one of the pads, it will blink and then pick a random quote out of the "spock" file and print it. If REPL=True, you'll need to be in an editor like mu to see the text. IF you change REPL to be False, then it will use HID support to send the text as if typed on a keyboard! Just the way to jazz up your email! Edit the "spock" file to add your own favorite quotes from everyone's favorite Vulcan.

 

What's going on?

There are two functions that are used to deliver the quotes. len_file(filename),

def file_len(filename):
    with open(filename) as f:
        for i, _ in enumerate(f):
            pass
    return i + 1

 

and wisdom(file_name).

def wisdom(filename):

    qs = open(filename)
    for i in range(random.randrange(file_len(filename))+1):
        quote = qs.readline()
        quote = quote.rstrip()
    cmpthink()
    qs.close()
    return (quote.rstrip())

 

Give a file name, wisdom() calls len_file() to determine how big the file is, then uses random.randrange() to select the text - that means you can add or subtract from the "spock" file without needing to update the program.

 

The fun thing with this code is, it can be reused for other purposes. I've already used it to put together a "story" program that uses multiple source files (aliens, suns, planets, etc.) that can be drawn from to generate story lines. It could be used for a diceware style passphrase generator. And, of course, it doesn't have to be Spock on a chip - you can fill the "spock" file with any quotes you choose.

 

 

Better SD write performance is probably a common goal. My project uses the Adafruit SD Micro SDIO breakout, the Adafruit OV5640 Camera breakout and the Unexpected Maker ESP32S3 feather in a compact stack (with a custom PCB to connect them) that fits in a GoPro waterproof case. I want GoPro-like video recording but with BLE time synchronization and start/stop functions with multiple cameras. It's like a GoPro but it's not, it's a NoPro!

I'm programming with the Arduino IDE and using the SD_MMC library. The ESP32S3 has an SDIO interface with programmable pins, which the library supports. But for the longest time, I could only get sustainable write speeds of 150-200 kilobytes per second. I'm using a Sandisk Extreme V30 32GB which should get 30MB/s. For the frame rates and resolution I want, I need about 3MB/s.

I initially played with the file system buffer size but never got consistent results. I might occasionally get a few frames written at target speeds but never a whole video. So I set my code aside and started from scratch to explore how to get better speed.

There definitely seemed to be a dependence on file buffer size as well as on the size of data being written. So I tried lots of combinations and got the same results - usually about 150-200 kB/s but occasionally over 3MB/s.

But I had noticed a pattern of good performance when the write lengths were certain powers of 2 so I tried multiples of 512 bytes and got much better speeds. With a file buffer size of 4096 and data sizes over 75kB I could get consistent speed over 3MB/s, just what I need.  4096 also gets consistent small writes at over 1MB/s.  Buffer sizes of 8192 and greater actually worked worse.

I was looking for a clock that would tell the time in words rather than just hands (analog) or numbers (digital). I found a few for sale on places like Amazon and eBay, but none of those particularly stood out, so I decided to create a customizable one myself.

I designed and built two variants. Both use the same RGB matrix panel. Both use CircuitPython on the ESP32-S3, but one uses the Matrix Portal S3, and the other uses a standalone Feather ESP32-S3 with an Adafruit RGB Matrix Featherwing Kit. The Matrix Portal version requires no soldering; the Feather version requires some simple soldering. I will show both here.

The text is left justified, vertically centered on the display and each line is in a random color which changes every time the minute changes. Since you control the CircuitPython code, you can change this formatting any way you choose, e.g. same color lines, individually horizontally centered lines, etc.

Common Hardware

I'm in a radical marching band called Brass Your Heart, and I wanted to make our instruments light up when we play them. I started this project by making one for my friend who plays a marching baritone. Below is a mostly step by step process for how I made them using: sewable neopixels, conductive thread, snaps, a Gemma M0, and an electret microphone. 

 

 

Step One:

The diameter of the baritone measured 26 inches, so I used tailor's chalk to draw the outer circle you see here. Then I drew another circle, about an inch in for the lights, so that the neopixels and the conductive thread is far away from the metal of the instrument. I also make 8 markings where the neopixels would go and started to sew them into position with regular black thread.

 

This project was a personal desire to put Adafruit IO through it's paces, and see how far I could go in recreating a project designed for ESPHome + Home Assistant. Traditionally I would have assumed it was too complex for the Actions and Dashboard of Adafruit IO if I used a Wippersnapper device, instead relying on Node-RED to string things together, but now that I work on the WipperSnapper project I was curious how far it had come / could go.

The basic idea was to take a £60 "dumb" air purifier with a 3-speed dial (£70 with carbon filter) and add a WiFi micro-controller, so that it can be switched on and the speed controlled according to the values sent from a separate Air Quality sensor (Particulate Matter <2.5µm), and a user-adjustable control panel hosted as an Adafruit IO Dashboard.

Is this another silly idea / tribute to insanity, by needlessly bolting the internet and a subscription service to a device, which usually degrades performance and adds built-in obsolescence (not to mention a 22second boot-time)?

Well maybe, or maybe it's just a way of providing people with alternatives, but either way it involves Adafruit IO as an alternative to Home-Assistant / Node-RED or the official IKEA smart-hub + smart devices, and Adafruit's open-source IOT firmware called WipperSnapper as an alternative to ESPHome.

It's possible to use on the free-plan on Adafruit IO (you do NOT need IO+), or offline with a little coding, so I don't feel bad about suggesting it...

Here's a demo video of it in action: (Adafruit IO Dashboard on left, WipperSnapper device page on right, Speed dial of Air Purifier + Wind Sock on Picture-in-Picture video)

The first step is to get BrickLink Studio 2.0. This CAD program is intuitive to use, includes almost all bricks available, and features to test your model strength, render 3D visuals of it, view what parts you use and even generate instructions on how to build your model. This is not a guide on how to use Studio 2.0, but it includes a built in tutorial that makes getting started a breeze.

John Park wrote an excellent guide Lego Set Lighting. I used this guide to light up the LEGO Christmas Tree (set #40573) making the candles flicker away. My problem was how do I hide the electronics running everything.

I had the idea to design and build a LEGO model in the shape of a present, but the question was how.

It turns out there is an easily accessible CAD program and method of ordering parts (maybe too easy!).

The Weather Chimes project fills that need. It connects to the Adafruit NTP service for network time and to OpenWeatherMap.org for wind speed data. The wind speed data is retrieved every twenty minutes and is used to adjust wind chime playback in a pseudo random pattern. The chime voice synthesizer is provided by the CircuitPython_Chimes class and for this project, is sent to an Adafruit MAX98357A I2S amplifier driving an Adafruit 40mm 4-ohm 3-watt speaker. Although an Unexpected Maker Feather S2 was used for this project, the code should work on just about any ESP32 device that's capable of running CircuitPython.

The Weather Chimes project consists of two primary code files, weather_chimes_code.py and weather_chimes_wifi.py. The weather_chimes_code.py code is imported via the default code.py file contained in the Feather S2's root directory. This code contains the primary non-wifi device definitions and the master while... loop that plays the chimes. It also imports the WeatherChimesWiFi class from weather_chimes_wifi.py.

The WeatherChimesWiFi class takes care of all the networking details for connecting and retrieving data from the internet. It also provide helpers for updating and retrieving time and weather as well as properties for including the local time and wind speed. The WiFi class uses the settings.toml file for connecting to a home WiFi router as well as parameters needed for Adafruit NTP and the OpenWeatherMap.org API.

A fictional settings.toml file:

A CircuitPython project for indoor "windless" garden chimes that play along with the outdoor wind speed.

Weather_Chimes GitHub repository

Circuit Diagram

The diagram below provides a general visual reference for wiring of the components once you get to the Assembly page. This diagram was created using the software package Fritzing. Note that we will be using all available GPIO pads on the QT Py, so there will be a good bit of soldering involved.

Overview

Modern electronics are capable of incredible things. Even the simplest gadgets now have clocks, gyroscopes, radios, GPS, touch screens, literally anything you can imagine, built right in. Sometimes though, the devices that are capable of doing several things don't do all of them particularly well. Touch screens are often bolted onto things that really don't benefit from them, or even worse, detract from the experience. Anyone who has accidentally grazed the touch panel on an Apple TV remote while grasping for it in the dark knows exactly what I'm talking about. Sometimes I just want to have a remote with a few simple buttons I can press to make things happen, and that's it!

Most of the lights in my apartment are WiFi-connected, and offer MQTT capability. I took advantage of this and set up a local MQTT broker (https://mosquitto.org/) on a Raspberry Pi 4 wired to an old Apple Airport router/hub I had lying around (my internet provider makes me use their router for my internet). Now, it's easier than ever to control my lights...from a browser. Or some phone interface. Or an app. Wait a second...each of those still requires multiple steps just to get me to the point where I can actually control anything. And I probably still have to use a touch screen. Leading me back to my original point, and thus the motivation for the imaginatively named:

WiFi Matrix Keypad Remote

I've been a DIY remote control enthusiast for almost as long as I've been hacking around with microcontrollers (at least a few years now). One thing that I've found really hard to source as a hobbyist is good, pre-made button panels intended to be mounted into a small space, such as a remote control. So far, one of my favorite sources for a dense panel of decent quality, inexpensive buttons are these old-school 3x4 matrix keypads:

Part one : Where's the mic? 

"Breaker breaker , any takers? This is the the one and only Delchi hunting for bear on I-95 South , keeping that double nickel and keeping the sunny side up & the greasy side down! We gone!" ¹

I was looking for some new gaming frontiers when I came across truck simulators! All the skill & thrill of a big rig from your PC. As with all simulators there are button boxes and realistic cockpits to buy, but one thing I didn't see was a CB radio mic! They expect us to use desktop mics, headsets or some other hoo-haw instead of the ol jabberjaw microphone! A little deeper digging showed that you can buy adapters, but they ranged from $180 to $300! ( Granted the $300 one is an awesome button box and has a lot of realistic controls along with the mCB mic.) 

Well the first thing I did was say "Belgium" to that, and pulled Rolling Thunder across the room to my workbench and got to work. This was going to be a project that would work with Truck simulators, sub simulators and more! Grab that soldering iron, the wire clippers and that drill over there! It's time to start making! 

 

Notes : 

1. CB radio jargon was around long before IRC , and was its own language designed to obfuscate communication and have a grand ol time. "Handles" were common, and yes CB radio handles are where the hacking community got the term handles for hacker aliases! 

Translation? Why not ? 

• "Breaker breaker , any takers?"
  • In cb radio ( less formal than ham radio ) it was common to ask permission before talking on an open channel. Calling for a "break" was like requesting permission to chime in , and was normally answered with "Go ahead breaker"
• "This is the the one and only Delchi"
  • Handles were a point of pride and very often unique, but when they did collide they politely adjusted to be like "The New Orleans Joker " vs "The Chicago Joker" and so on.
• "hunting for bear on I-95 South"
  • Truckers took great lengths to avoid being caught by the police in speed traps. "Smokey Bear" referred to the Smokey The Bear hat most often worn by police patrolling the interstates. If you were hunting for bear that meant you were on the lookout for police, and sometimes were asking for a "Smokey report" if anyone had seen any police.  You usually followed this with the interstate you were on and the direction you were traveling and sometimes the mile marker you had passed most recently.
• "keeping that double nickel"
  • This referred to the speed limit of 55 miles per hour that was enforced back then. Sadly there is no clever phrase for the 65 mph speed limit.
• "keeping the sunny side up & the greasy side down!"
  • Multiple meanings here, but for the most part this meant keeping your truck upright ( sunny side was the cabin, greasy side was the road ). It was like wishing someone safe travels and no accidents. 
• "We gone!"
  • When a conversation ended people would signal this with a number of phrases like "we gone" , or "On the side". Sometimes it also included the "10-code" messages such as "10-10 Till I see you again"

Related Links : 

• Truck Simulator
  • https://americantrucksimulator.com/
• Button Box
  • https://www.simpanel.com/ats
• 10- Code & other jargon
  • https://www.rightchannelradios.com/blogs/newsletters/cb-radio-slang-and-10-codes

 

Part Two : Requirements

So then at the workbench with graph paper and pencil in hand ( or Lucidchart if you will ) let's determine what we need to make this CB mic project roll down the road : 

• Utilizing a CB Microphone
  • Be able to attach the microphone to the computer
  • Be able to use the button on the microphone to activate the  PTT ( Push to talk ) feature on the computer / in game
  • Make it look realistic! 
  • Make it as clean as possible ( minimum number of wires / software / configuration )

 

I recently released another retrocomputer miniature that incorporates a handful of Adafruit boards so I thought that I'd share the details here.

The original Connection Machines were built in the late 80s and early 90s to provide a few thousand hyper-connected processors which at the time was rather unique. If you're interested, here's a wikipedia page about them.

My Patreon supporters vote for which miniatures I make and I was pretty happy when the Connection Machine was chosen. I was also happy to find that Adafruit sells pretty much exactly what I needed to make the blinking light panels:

• QT Py ESP32-S3 x1
• Red LED matrix x4
• Matrix driver board x4
• Stemma QT cable x4

Assembly requires me to solder the four matrix driver boards to the four LED matrix boards and then plugging in the Stemma QT cables between the QT Py and a chain of the driver boards.

Then I assemble these printed parts. The little C shaped parts on the lower left of this photo are what hold the two-board sandwich of the LED maxtrix board and the driver board.

Then I install CircuitPython on the QT Py and then load it with my code from Codeberg. There you'll find the default blinkenlights script but also a script that uses the network to fetch the time and then turn the Connection Machine into a clock. It took a bit of work to figure it all out so hopefully the code will be a handy starting point for similar projects.

Once everything is assembled I box it up and put it on my gumroad store.

I post pretty much every day about what I'm working on over on Mastodon at @[email protected] and for maker-y types of conversations I like that place much more than the other social media sites. Maybe I'll see you there!

Playing animated GIFs was added to CircuitPython in early 2023 and I had successfully had them running on TFT displays and even to a monitor via HDMI. I recently setup my MatrixPortal and two 64x32 matrices that I had been using to show animated GIFs. But the MatrixPortal was running Arduino code.

Time for an update and to take the code from Using Animated GIF Files in CircuitPython and Creating Projects with-the CircuitPython MatrixPortal Library and smush them together to play animated GIFs on a MatrixPortal with CircuitPython. Both guides do a great job of explaining the details of their own area and the code here combines them both.

The first half of the code sets up the matrix on DisplayIO and the second half uses OnDiskGif from the gifio module to display the animated GIF.

The code displays all GIFs found in the /gifs/ directory on the MatrixPortal. Each animated GIF will display for 30 seconds before moving to the next animation.

One major difference from the Animated GIF guide: for speed, the code in the guide sends the raw bitmap data directly to an attached display. In theory that is possible to do on the MatrixPortal but it is more complicated and likely would be slower then using DisplayIO. This is because the matrices have fewer pixels then most screens and the speed of the protomatter library that powers the matrix display.