{"id":17967814,"url":"https://github.com/simonprickett/m5stack-atom-micropython","last_synced_at":"2025-04-03T21:29:39.257Z","repository":{"id":215438991,"uuid":"738944342","full_name":"simonprickett/m5stack-atom-micropython","owner":"simonprickett","description":"Experiments with MicroPython on the M5 Stack Atom Matrix device.","archived":false,"fork":false,"pushed_at":"2024-01-12T16:37:44.000Z","size":1250,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-09T09:29:42.086Z","etag":null,"topics":["cheerlights","cheerlights-client","m5stack","m5stack-atom","micropython","mqtt"],"latest_commit_sha":null,"homepage":"https://simonprickett.dev/micropython-on-the-m5stack-atom-matrix/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simonprickett.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-04T12:11:04.000Z","updated_at":"2025-01-10T21:13:04.000Z","dependencies_parsed_at":"2024-01-11T23:17:29.614Z","dependency_job_id":"b3094829-48e1-4e41-8336-0c732094d673","html_url":"https://github.com/simonprickett/m5stack-atom-micropython","commit_stats":null,"previous_names":["simonprickett/m5stack-atom-micropython"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonprickett%2Fm5stack-atom-micropython","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonprickett%2Fm5stack-atom-micropython/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonprickett%2Fm5stack-atom-micropython/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonprickett%2Fm5stack-atom-micropython/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simonprickett","download_url":"https://codeload.github.com/simonprickett/m5stack-atom-micropython/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247082064,"owners_count":20880574,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cheerlights","cheerlights-client","m5stack","m5stack-atom","micropython","mqtt"],"created_at":"2024-10-29T14:09:46.540Z","updated_at":"2025-04-03T21:29:39.234Z","avatar_url":"https://github.com/simonprickett.png","language":"Python","funding_links":["https://ko-fi.com/simonprickett"],"categories":[],"sub_categories":[],"readme":"# M5Stack Atom Matrix MicroPython Live Streams\n\n![M5Stack Atom Matrix](m5stack_atom.png)\n\n## Introduction\n\nThis 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.\n\nThere's also a [short article on my website](https://simonprickett.dev/micropython-on-the-m5stack-atom-matrix/) that covers this project.\n\n## Videos\n\nCheck out the videos on YouTube (click the images to view -- come on GitHub we need YouTube embeds in README files!)...\n\n[![Episode 1](m5stack_atom_matrix_micropython_episode_1.png)](https://www.youtube.com/watch?v=bwvli5pEA0A)\n\nIn 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.\n\nIn 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.\n\n[![Episode 2](m5stack_atom_matrix_micropython_episode_2.png)](https://www.youtube.com/watch?v=-Ej06U2x-i8)\n\nIn 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.\n\n[![Episode 3](m5stack_atom_matrix_micropython_episode_3.png)](https://www.youtube.com/watch?v=f3BA2R5eIJU)\n\nSubscribe on [YouTube](https://www.youtube.com/@simonprickett) or [follow me on Twitter](https://twitter.com/simon_prickett) to be notified when future project streams are scheduled.  My live streams also go out on [LinkedIn](https://www.linkedin.com/in/simonprickett/), [Twitch](https://twitch.tv/simonprickett) and [Twitter](https://twitter.com/simon_prickett) if you prefer.\n\n## The M5Stack Atom Matrix Device\n\nThe 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.\n\nIt features:\n\n* ESP32 chip with onboard WiFi.\n* 4Mb flash memory.\n* 5x5 RGB LED matrix - the LEDs are the \"neopixel\" type that can be individually addressed and set to RGB colors.\n* A programmable button (press on the LED matrix!).\n* Inertial sensor / gyroscope.\n* Grove and USB C connectors.\n\nCheck out the full specification sheet on the M5Stack documentation site [here](https://docs.m5stack.com/en/core/ATOM%20Matrix).\n\nThere are other devices in the M5Stack Atom range, but this project specifically works with the Matrix model.\n\nThese devices cost around US$15 and you can buy them from the usual places:\n\n* Direct from [M5Stack](https://shop.m5stack.com/products/atom-matrix-esp32-development-kit).\n* [Pimoroni](https://shop.pimoroni.com/products/atom-matrix-esp32-development-kit?variant=31880178532435) (UK based, worldwide shipping).\n* [The Pi Hut](https://thepihut.com/products/atom-matrix-esp32-development-kit) (UK based, worldwide shipping).\n* [Adafruit](https://www.adafruit.com/product/4497) (US based, worldwide shipping).\n* Others...\n\n## Installing MicroPython on the Device\n\nThe device doesn't come with MicroPython pre-installed (it's set up to work with C and the [Arduino IDE](https://www.arduino.cc/en/software)).  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.\n\nInstructions are provided on the [device's page on the MicroPython site](https://micropython.org/download/M5STACK_ATOM/).\n\nOnce you've installed MicroPython you can start a REPL using [mpremote](https://docs.micropython.org/en/latest/reference/mpremote.html), [Thonny](https://thonny.org/), or your usual preferred MicroPython development toolchain.  I chose Thonny for the live streams.\n\nWhen 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.\n\n## Support for this Device in MicroPython\n\nThe 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](https://github.com/micropython/micropython/blob/master/ports/esp32/boards/M5STACK_ATOM/modules/atom.py).\n\nI used this in the first stream to work with the LED matrix and the button.  Check out [`main.py`](first-livestream/main.py) from the first stream for example code.\n\nDuring 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).\n\nI 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](https://github.com/micropython/micropython/pull/13350).\n\n## Code from the First Live Stream\n\nIn the first live stream I demonstrated how to control the LEDs (all at once and individually) using the `Matrix` class in the `atom` module.\n\nWe 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.\n\nI then demonstrated how to connect to a wifi network and use MicroPython's [MQTT client](https://pypi.org/project/micropython-umqtt.simple/) to receive messages from the [Cheerlights](https://cheerlights.com/) MQTT broker.  Cheerlights is a global network of connected lights that can be set to show different colours.\n\nMQTT is a lightweight protocol that uses the publish/subscribe model.  Read more about it and watch the video on [kevsrobots.com](https://www.kevsrobots.com/resources/how_it_works/mqtt.html) if you'd like to learn more.\n\nThe 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.\n\nI 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.\n\nThe code from the first live stream can be found in this repo in the [`first-livestream`](first-livestream/) folder.\n\n## Find this Useful?\n\nIf you found this useful and would like to see me make more of this sort of thing, please consider [buying me a coffee](https://ko-fi.com/simonprickett).  All proceeds will be spent on purchasing more devices / sensors etc for future projects which will all be open sourced.  Thanks!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonprickett%2Fm5stack-atom-micropython","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimonprickett%2Fm5stack-atom-micropython","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonprickett%2Fm5stack-atom-micropython/lists"}