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.
What we need
- MicroPython Board with MicroPython flashed onto it.
- Pycom
- Adafruit Huzzah32
- ESP32 Thing
- Circuit Playground Express
- micro:bit
- Anything that runs MicroPython or CircuitPython
- Python 3 (included in the PATH on windows systems)
- Micro USB Cable
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.
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.
