This guide goes over setting up an environment for creating projects with 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.


Prerequisite Guides

  • None


Supplemental Guides


You Will Need

Assembled Atlas Kit
MicroUSB Cable
Computer running Windows, Linux, or MacOSX


Background

I have tried many different setups for programming microcontrollers with MicroPython and I have found that the best and most streamlined way of working with MicroPython is with a program called Thonny. Thonny is a Python IDE that is great for beginners and is also very helpful for programming microcontrollers with MicroPython. The rest of this article 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.


Downloads

Thonny

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.


Install Thonny from Thonny.org

Download the Thonny installer from thonny.org and run it.

Download Thonny from its website.
Download Thonny from its website.


Install Thonny using Pip

Open a terminal and enter pip install thonny. If the process fails, try running the same command again with elevated permissions (sudo).


Acquiring Micropython Firmware

From the Micropython website, download the binary (.bin) file for ESP8266 microcontrollers tagged as “latest”. Take note of its location in your filesystem.

Download the latest MicroPython firmware for ESP8266 microcontrollers.
Download the latest MicroPython firmware for ESP8266 microcontrollers.


Thonny Setup

Plug your Atlas device to your computer using a microUSB cable and launch Thonny.

Immediately navigate to “Tools > Manage plug-ins…” and enter “esptool” into the search bar. Then click on the “Find packages from PyPI” button. An entry for esptool should appear in the space below. Click on the “install” button to install it. After it is finished installing the plug-ins window can be closed. Then close and reopen Thonny.

Install the esptool plug-in for Thonny.
Install the esptool plug-in for Thonny.

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.

In Thonny, navigate to “Tools > Open System Shell”. Enter and run the following command into the shell window to erase the existing firmware on the device. Replace YOUR_PORT with the port value that you found for your Atlas device.

esptool.py --port YOUR_PORT --baud 115200 erase_flash

After a few seconds the existing firmware on the device will be erased.

With my setup using Windows, I found my Atlas device to be on port COM6.
With my setup using Windows, I found my Atlas device to be on port COM6.

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.

esptool.py --port YOUR_PORT --baud 115200 write_flash --flash_size=detect -fm dio 0 FIRMWARE_FILE.bin

This command will now erase any existing firmware and then flash the MicroPython firmware on your Atlas device. This may take a few minutes. After the firmware is finished installing, you may close the shell window.

Flash the MicroPython firmware onto the Atlas device.
Flash the MicroPython firmware onto the Atlas device.

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.

Set the interpreter and the port.
Set the interpreter and the port.

At the bottom of the Thonny window in the tab labeled “Shell” you should see text that resembles the image below.

MicroPython repl ready for input.
MicroPython repl ready for input.

If the last line of the repl is not >>> then your REPL is not 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 and as a result needs to be stopped before being given REPL commands.

Issue stop command to microcontroller.
Issue stop command to microcontroller.

To test that the firmware is installed correctly, enter the following into the repl:

>>> import esp
>>> esp.check_fw()

You should get output that looks like the following image.

Verify MicroPython firmware on the ESP8266.
Verify MicroPython firmware on the ESP8266.

This means that you have done everything up to this point successfully.


Loading the Atlas Files

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 Github release page here. Download the latest version of the files marked as “Latest release” by clicking on one of the zip files.

The release page for the Atlas MicroPython code.
The release page for the Atlas MicroPython code.

Extract the zip file that you downloaded to view the source files.

Contents of the Atlas MicroPython zip file.
Contents of the Atlas MicroPython zip file.

Go back to Thonny and make sure that you still have a repl >>> in the shell window. 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”.

Saving the atlas.py file to the Atlas device.
Saving the atlas.py file to the Atlas device.

After a few seconds the file will be uploaded to the device.

Using this same process, upload the “sounds.py” file to the Atlas device.


Hello World

Lets write a quick “Hello World” program to demonstrate MicroPython on the Atlas device. 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:
        device.toggle_pin(led)
        sleep_ms(90)
Blinking LEDs is the hardware version of a 'Hello World' program.
Blinking LEDs is the hardware version of a 'Hello World' program.

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”.

Select the option to save the file to the 'MicroPython device'.
Select the option to save the file to the '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.

Name the file 'main.py'.
Name the file 'main.py'.

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.

The Atlas device running the cascading blink script.
The Atlas device running the cascading blink script.

You have now written and run your first program for your 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