empowering creative people

Writing Code Onto MicroPython Boards

You have your shiny new MicroPython or Circuit Python board and you have Installed the Firmware and connected to REPL, but now you want to put your code onto the board. To do this we need to send the files over serial. Luckily Adafruit has made a tool for this that runs in python(This language has tools for everything!) We are going to have a look at using Ampy to copy your python files onto a MicroPython Board.

MicroPython and Circuit Python Boards

What we need

Python Files in MicroPython

MicroPython has a couple of files on it that you will need to know about so that you do not get unintended behaviours.  

boot.py

This python script runs when the MicroPython board boots up and contains a lot of the setup for the board you are using. Be careful that you do not accidentally overwrite this file with another boot.py or you may get strange results.

main.py

This will be your main python program MicroPython will run this and you can put anything you like in here. If you copy another python file such as myScript.py onto the board it will not run it unless it is called from within main.py

Install Ampy

The first thing we are going to need to do is to install Adafruit Ampy, it is in the Python repositories so we can easily do this by opening a Terminal window and running:

pip install adafruit-ampy

Note: You may need to use sudo on Linux systems

Using Ampy

We can use ampy through the command line interface shown below. We will go through what the options are and then give a demonstration of how to use it when we get to the commands.

ampy [OPTIONS] COMMAND [ARGS]...

Information Options

The first options do not need any commands and will only return information about

--version Returns the Version of Ampy you are using.

			 ampy --version

--help Displays a list of all the commands available or show specific help for a command.

			ampy --help
			ampy -p <port> <command> --help

Connection Options

  -p         Tells ampy which port you want to connect to, you need to specify this option each time you run ampy.  

  -b         Sets the Baud rate (or speed) of the serial connection. If left undefined Ampy will assume 115200

  -d          Delay in seconds before entering RAW mode

Commands:

Here is a list of the commands and options that can be used to interact and copy files to your MicroPython board. 

ls

Description: List contents of a directory on the board.

Options:

                -l             long format

                -r             Recursive Show all files and directories                  

Usage:

                ampy -p <port> ls <options>


put      

Description: Upload a file or folder to the board. Specifying a second argument will change the name of the uploaded file or folder.

Usage:

			ampy -p <port> get <localFileOrFolder> {NameOnBoard}

get

Description: Download the file specified from the board. Specifying a second argument will change the name of the downloaded file.

Usage:

			ampy -p <port> get <FileToGet> {Local File}

mkdir

Description: Make a new folder on the board

Options:

                --exists-okay     ignore this command if the folder is already there.

Usage:

			ampy -p <port> mkdir <options> <directoryName>

reset   

Description: reset or reboot the board. Some of these options may only be available on all boards.

Options:

                --bootloader      Restart the board into the bootloader

                --hard                   Hard reboot and run init.py

                --repl                    Soft reboot and into the REPL this is the default option

                --safe                    Restart without running user code and make file system available over USB

Usage:

			ampy -p <port> reset <Option>

rm  

Description: Remove a file or empty Folder from the board, it will not remove folders with files in them.

Usage:

			ampy -p <port> rm <NameOfTarget>

rmdir 

Description: Delete a folder and all the files and folders within.

Options:

                --missing-okay                  Ignore this command if the folder does not exist

Usage:

			ampy -p <port> rmdir <NameOfTarget>

run

Description: Run a script and display the output. This will not allow you to send inputs to your code.

Options:

                -n            run the script but do not wait for it to end to print the output. You should use this if your code will loop forever.

Usage:

			ampy -p <port> run <option> <LocalFileName>

Copy Files to MicroPython

 

Now we know how to use Ampy we can copy some code over to our MicroPython Board. To do this we can open a terminal window and run the mode command to find the port.

Create a python file and name it main.py and fill it with the following code.

import machine # Generic library for MicroPython Hardware
print("Hello I am MicroPython") # print some Text.
print("I can do",machine.freq(),"things per second") # Get the Frequency of the CPU

Navigate to your where you saved your python file is using the command prompt.

Terminal Commands to navigate and upload file to Micropython

Now run the ampy command to copy the file over to the MicroPython board.

                ampy -p <port> put main.py

you should now see the output of the code we just put onto the MicroPython board.

 

Files Copied!

Now we have our script copied to the board and it will run every time the board is powered up. You can play around with adding other files and creating directories as well as running local files without copying them with the run command. If you have any cool ideas or projects you want to share based on this article join the discussion at the bottom of the page. 

If you want to learn more about MicroPython have a look at our tutorials and workshops.

Thanks for following this tutorial and all the best with your MicroPython Projects. 

You have your shiny new MicroPython or Circuit Python board and you have Installed the Firmware and connected to REPL, but no...

Have a question? Ask the Author of this guide today!