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:

pip install adafruit-ampy

Or if you're using Python 3.x:

pip3 install adafruit-ampy

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

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:

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:

python -m

(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:

python -m -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

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

Now in a terminal navigate to the folder with the 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!

ampy --port <serial port name> run

(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 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 that's saved on the board's file system.  The way MicroPython works is that it looks for a 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 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 and save it on your board to run.

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

from microbit import *

while True:
    display.scroll('Hello, World!')

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

ampy --port <serial port name> put

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, saving it, and running the ampy command again to push the updated file to the board as 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).

Last updated on 2018-02-23 at 01.51.43 AM Published on 2018-02-23 at 01.54.01 AM