This guide goes over setting up an environment for programming an assembled Atlas device. If you own an Atlas kit and have not assembled it yet you should first go through our assembly guide located here.
In the process of learning MicroPython for myself, I have used many different setups for programming microcontrollers. Through my journey, I found that the most streamlined and simple way of programming a microcontroller with MicroPython is through a program called Thonny. Thonny is a Python IDE that keeps the process of programming a microcontroller simple, which is great for beginners.
After Thonny is installed, we will go over getting Thonny setup for an Atlas device with an ESP8266 NodeMCU, flashing the MicroPython firmware, and writing a simple program for the Atlas device using MicroPython.
If you are using Linux, I recommend installing Thonny using pip. On Windows and MacOSX I recommend installing Thonny through the download links on its website.
Download the Thonny installer from thonny.org and run it.
Open a terminal and enter pip install thonny. If the process fails, try running the same command again with elevated permissions (sudo).
pip install thonny
From the Micropython website, download the binary (.bin) file for ESP8266 microcontrollers tagged as “latest”.
Take note of its location in your filesystem.
Plug your Atlas device to your computer using a microUSB cable and launch Thonny.
Open a terminal (MacOSX and Linux) or a command prompt (Windows) and enter the following command:
pip install esptool
If this works you can move on in the guide. If you get an error message saying that pip is not recognized then you may need to install Python from python.org. If you get an error mentioning permissions then you need to run the command again with elevated privileges. On MacOSX and Linux add sudo to the beginning of the command sudo pip install esptool. On Windows, open a new command prompt by right clicking on the application and select “Run as administrator”.
sudo pip install esptool
Now would be a good time to find out which port your device is on. If you are not familiar with how to to do this, you should check our guide on the subject: How To Find Your Device’s Port. Take note of what your port is.
Open a terminal on your computer (on Windows open a command prompt). Enter and run the following command in the terminal to erase the existing firmware on the device. Replace YOUR_PORT with the port value that you found for your Atlas device.
esptool --port YOUR_PORT --baud 115200 erase_flash
After a few seconds the existing firmware on the device will be erased.
To flash the firmware on the device enter the following command replacing YOUR_PORT with your device’s port and FIRMWARE_FILE.bin with the path to the MicroPython firmware file that you previously downloaded. You can easily copy the path to a file on Windows by holding shift and right clicking on a file. Then select “Copy as path”.
esptool.py --port YOUR_PORT --baud 115200 write_flash --flash_size=detect -fm dio 0 FIRMWARE_FILE.bin
This may take a few minutes. After the firmware is finished installing, you may close the shell window.
Next, in Thonny, navigate to “Run > Select Interpreter”. Under the “Which interpreter or device should Thonny use for running your code?” label, select “MicroPython (ESP8266)”.
Select the port of your Atlas device under “Port”. Then click on the “OK” button to close the dialog.
At the bottom of the Thonny window in the tab labeled “Shell” you should see text that resembles the image below.
If the last line of the repl is not >>> then your REPL isn’t ready for input. To fix this press the stop button at the top of the Thonny window. This often means that the microcontroller is running something that must be stopped before being able to be given REPL commands.
To test that the firmware is installed correctly, enter the following into the repl:
>>> import esp
You should get output that looks like the following image.
We have already written some starter code for the Atlas kit. Most of this code is contained in the Atlas class which is located in a file called atlas.py. You can download this code from the atlas-micropython Gitlab release page here. Download one of the compressed source code files in the latest release.
Extract the zip file that you downloaded to view the source files.
Go back to Thonny and make sure that you still have a repl >>> in the shell window. Then navigate to “File > Open” and click on “This computer”. Navigate to your recently downloaded and extracted “atlas-micropython” directory and open the “atlas.py” file. Then navigate to “File > Save as” and select “MicroPython device”. In the “File name” text box type “atlas.py”. Then click “Ok”.
After a few seconds the file will be uploaded to the device.
Using this same process, the sounds.py file can also be saved to the Atlas device, but we won’t be needing sounds.py for this guide.
Lets write a quick “Hello World” program to demonstrate MicroPython on the Atlas device. Write or copy the following code into the editor area in Thonny.
from atlas import Atlas
from time import sleep_ms
device = Atlas()
for _ in range(6):
for led in device.leds:
After writing the program navigate to “File > Save As”. You will then get a window asking whether to save the file to your computer or the microcontroller. Select “MicroPython device”.
Now name the file “main.py” and click “Ok”. It is important to name the file “main.py” because the MicroPython always runs “boot.py” first and then looks for “main.py” to run second.
After the program file is saved onto the Atlas device, run the program by pressing the reset button labeled as “RST” on the back of the Atlas device. You should see that the Atlas device runs the program that we wrote and all of the LEDs on the device blink cascading down the device.
You have now written and run your first program for the Atlas device. Check out the Atlas MicroPython Documentation book for full explanations and code examples for every feature on the device.
Atlas Documentation: Atlas MicroPython Documentation