This repository contains the code that accompanies my live streaming series in which I played around with installing and running MicroPython code on the M5Stack Atom Matrix device.
There's also a short article on my website that covers this project.
Check out the videos on YouTube (click the images to view -- come on GitHub we need YouTube embeds in README files!)...
In episode 1 I installed MicroPython and wrote code to use the LEDs and button. Then I demonstrated how to connect to WiFi and read and display the current Cheerlights color using an MQTT broker.
In Episode 2 I showed a small pull request that I'd made to improve MicroPython's utility module for the M5Stack Atom Matrix and we played with the accelerometer.
In Episode 3 I connected three different sensors to the device using the Grove connector that's built into it. These were a light sensor, a DHT11 temperature/humidity sensor and a PIR motion sensor.
Subscribe on YouTube or follow me on Twitter to be notified when future project streams are scheduled. My live streams also go out on LinkedIn, Twitch and Twitter if you prefer.
The M5Stack Atom Matrix is a small (24mm square by 14mm tall) IoT device that packs a lot into a small space for a decent price.
It features:
- ESP32 chip with onboard WiFi.
- 4Mb flash memory.
- 5x5 RGB LED matrix - the LEDs are the "neopixel" type that can be individually addressed and set to RGB colors.
- A programmable button (press on the LED matrix!).
- Inertial sensor / gyroscope.
- Grove and USB C connectors.
Check out the full specification sheet on the M5Stack documentation site here.
There are other devices in the M5Stack Atom range, but this project specifically works with the Matrix model.
These devices cost around US$15 and you can buy them from the usual places:
- Direct from M5Stack.
- Pimoroni (UK based, worldwide shipping).
- The Pi Hut (UK based, worldwide shipping).
- Adafruit (US based, worldwide shipping).
- Others...
The device doesn't come with MicroPython pre-installed (it's set up to work with C and the Arduino IDE). Installing MicroPython is a relatively simple process: use the esptool Python script to erase the flash, download the right MicroPython image for it, and use the same esptool to copy the image to the device.
Instructions are provided on the device's page on the MicroPython site.
Once you've installed MicroPython you can start a REPL using mpremote, Thonny, or your usual preferred MicroPython development toolchain. I chose Thonny for the live streams.
When I installed MicroPython, I found that the esptool command to copy the runtime onto the device gave an error. Omitting the baud rate option --baud 460800 fixed it for me.
The device-specific MicroPython build for the Atom series comes with a utility module that makes working with the LEDs and button easier, abstracting the hardware details away a bit. The module is part of the MicroPython project, so is pre-installed in the runtime for the device. Check out the source for it on GitHub.
I used this in the first stream to work with the LED matrix and the button. Check out main.py from the first stream for example code.
During the first stream, I realized that the Matrix class could benefit from an extra function to set the color of an LED given its x, y position on the matrix. The existing class takes a LED position number with the first one being 0. So, to set the first LED on the 2nd row you have to know it's number 5 (0-4 being the first row).
I added my own set_pixel_color_x_y in my code and talked about doing a pull request to get something similar added to the MicroPython build for this device. After the stream I created a pull request to add set_pixel_color_x_y and get_pixel_color_x_y functions. Let's see if it makes it into a future MicroPython release! Follow its progress on GitHub here.
In the first live stream I demonstrated how to control the LEDs (all at once and individually) using the Matrix class in the atom module.
We then moved on to writing a utility function that took x, y co-ordinates to identify each LED in the matrix before seeing how to react to button presses with a callback function.
I then demonstrated how to connect to a wifi network and use MicroPython's MQTT client to receive messages from the Cheerlights MQTT broker. Cheerlights is a global network of connected lights that can be set to show different colours.
MQTT is a lightweight protocol that uses the publish/subscribe model. Read more about it and watch the video on kevsrobots.com if you'd like to learn more.
The current Cheerlights color is published to a few different MQTT topics on their broker. To display the current color on the Atom Matrix we need to translate the information on a topic to R, G, B values and pass those into the set_pixels_color function in the Matrix class.
I chose to do this with a set of if / elif statements so that I could specify my own R, G, B values for each color that Cheerlights can be set to. This allowed me to pick representations that worked well with the camera and lighting I had for the live stream - avoiding the situation where the LEDs shine so brightly that the camera blurs them or becomes saturated with their color.
The code from the first live stream can be found in this repo in the first-livestream folder.
If you found this useful and would like to see me make more of this sort of thing, please consider buying me a coffee. All proceeds will be spent on purchasing more devices / sensors etc for future projects which will all be open sourced. Thanks!