Running code with ampy

Another way to run code on your sino:bit (or any other MicroPython board) is by copying it to the board's file system.  This is slightly different than using the web editor where you download an entire hex file to reprogram your board with both the MicroPython firmware and your program code at the same time.  Instead with this process you program your board once with a blank MicroPython firmware, then use tools to copy Python code to the board separately.  By copying files to the board you actually get a little bit more room for your program as the board's file system takes up as much free space as is available (typically about 14 kilobytes) vs. the fixed 8 kilobytes you get with web editor programs.

To copy programs to a sino:bit or MicroPython board you can use a tool called ampy.  There's actually a handy guide already on installing and using ampy, but we'll run through the basics with the sino:bit below.

Load sino:bit MicroPython Firmware

The first step is to load a general or 'blank' version of the sino:bit MicroPython firmware on your board.  If you try to copy files to your board using a firmware loaded from the web editor you won't actually see your files run as the web editor code takes over and is always run first.  Instead go to the releases page for sino:bit MicroPython and download the .hex file for the latest release.

Then just like programing from the web editor drag that .hex file (like sinobit-micropython-0.0.4.hex) to your board's MICROBIT drive.  You should see the blue light flash for a bit as the firmware is programmed.

Install ampy

After your board is programmed you're ready to copy code to it using ampy.  However on some platforms like Windows you might need to install a driver to access the board's serial port.  Check out this page on installing the mBED driver for the micro:bit--this is the same driver you need for the sino:bit too.  On Mac OSX and Linux you don't need to install any driver to access the board serial port.

Next make sure you've followed the guide on using ampy to install Python and the ampy tool with the pip package manager.  Once you have Python installed and in your path it's just a matter of running:

Download: file
pip install adafruit-ampy

Or if you're using Python 3.x:

Download: file
pip3 install adafruit-ampy

Then the ampy command should be available from your command terminal, try running it with --help to confirm:

Download: file
ampy --help

Find Board Serial Port

Before copying code to your board you'll need to figure out which serial port the board appears as on your computer.  Again be sure you installed the driver on Windows first!

On Windows, open the device manager and scroll down to the list of serial ports (typically named COM1, COM2, etc.).  If you unplug the sino:bit and then plug it back in you should see a new serial port appear--that's the port name you want to use.  If you haven't used a lot of other devices this is typically assigned COM4.

On Mac OSX, run in a terminal the ls -l /dev/tty.* command to see a list of all the serial devices.  Again try the command with and without the board attached to see which device appears after the board is plugged in (you might need to wait a few moments for the board's blue light to flash indicating it has finished talking to the computer to create the serial port).  Typically on Mac OSX you'll see a device like /dev/tty.usbmodem1411 or another number at the end.

On Linux, run in a terminal the ls -l /dev/tty* command to see a list of all serial devices.  Look for a new device to appear after running the command with the board disconnected, then connected.  Although it varies by distribution you typically will see the board under a /dev/ttyACM0 path.

If you're still having trouble finding the board serial port another way is using a tool in the PySerial package that is a cross-platform serial port list (i.e. it works on Windows, Mac OSX, and Linux).  First install PySerial with the pip tool just like you did with ampy:

Download: file
pip install pyserial

(remember if you're using Python 3.x use the pip3 command instead)

Then run the tools.serial.list_ports command provided by PySerial:

Download: file
python -m serial.tools.list_ports

(again be sure to instead run with python3 if you've installed into Python 3.x with pip3)

You can see all the serial devices are listed in a simple to read list.  On my Mac device the sino:bit appears as /dev/cu.usbmodem1412.

And if you're really unsure about the right device you can run list_ports with a -v option that prints more information about each device.  The sino:bit will appear as a device with description MBED CMSIS_DAP:

Download: file
python -m serial.tools.list_ports -v

Run Code With ampy

It's easy to run a python script on the sino:bit with ampy.  First create a simple Python script to run, for example this is a hello world that will count to 10.  Save this as a file called helloworld.py:

Download: file
print('Hello world! I can count to 10:')
for i in range(1, 11):
    print(i)

Now in a terminal navigate to the folder with the helloworld.py file and run this ampy command to send it to the sino:bit to run.  Be sure you've looked up your board serial port name like shown above!

Download: file
ampy --port <serial port name> run helloworld.py

(replace < serial port name > with your board's serial port like COM4, /dev/cu.usbmodem1411, etc.)

You should see the sino:bit blue light flash for a moment as the script is transferred, then output from it printed in the terminal.  What's happening is the Python code from helloworld.py is being sent from your computer to the sino:bit and run on it.  Anything the code prints out from the sino:bit is returned and printed by the ampy tool.  Think of it like telling the MicroPython interpreter on the sino:bit that you want it to run a Python script and grab the output!

Run Code at Startup

Running a single script is simple with ampy, but what about saving a script to the board and running it automatically when it powers up?  This is easy to do using a special file called main.py that's saved on the board's file system.  The way MicroPython works is that it looks for a main.py file at startup and if it finds one it will start running it immediately.  With ampy you can copy a file to the board's file system and name it main.py so it runs when the sino:bit powers up or resets.  This is typically how you develop and run code for a MicroPython board--put all your logic in a main.py and save it on your board to run.

To demonstrate try copying this code to a scroll.py file that will scroll a message on the display like on a micro:bit:

Download: file
from microbit import *

while True:
    display.scroll('Hello, World!')
    display.show(Image.HEART)
    sleep(2000)

Then use this ampy command to copy scroll.py to your board and save it as a file called main.py on the board's file system:

Download: file
ampy --port <serial port name> put scroll.py main.py

You won't see any output from the ampy command, but you should see the sino:bit's blue light flash for a moment and then the display spring to life scrolling the message!  Try changing the message in scroll.py, saving it, and running the ampy command again to push the updated file to the board as main.py again.

That's all there is to using ampy to copy files and run them on the sino:bit!  Be sure to read the full ampy guide for more information on using it with MicroPython boards.  Remember the sino:bit MicroPython port is still early in development so not all the features of ampy might be supported yet (like listing files or retrieving them from the board).

This guide was first published on Feb 23, 2018. It was last updated on Feb 23, 2018. This page (Running code with ampy) was last updated on Feb 23, 2018.