Ampy to transfer files to Pycom microcontroller

Introduction

This guide will demonstrate the use of thge Adafruit MicroPython tool (ampy) to load (put) and download (get) files and run code on a Pycom LoPy4 board connected to the serial port of the Raspberry Pi.

Authors

For more information contact Adam Simankowicz or Edmond Lascaris

References

• Micropython basics- Load and run code
• Ampy GitHub
• rshell alternative - not used

Updating Pycom Device Firmware

• It is very important to always keep the firmware on a microcontroller updated to the most current stable version.
• Firmware is equivalent to a small operating system pre-installed on a device that helps it perform its core functions.
• Updating firmware will help to resolve bugs, give you access to new features and fix security issues.
• In this lesson we will upgrade the firmware on the Pycom4 microcontroller using the Expansion Board version 3.1.
• Full details on how to complete the firmware upgrade are availa- ble at Updating Device Firmware (pycom.io)
• The updated was conducted on a MacOS 10.13.6

Updating Firmware on the Pycom4

• Plug the Pycom4 into the Pycom Expansion Board V3.1.
• Note that if you are using another Pycom device or expansion board you will need to refer to specific instructions for that setup.
• Download the Pycom Firmware updater tool (Mac, PC, Linux) from the URL below and install the software.

https://docs.pycom.io/updatefirmware/device/

• Connect the Pycom4/Expansion board to your computer and then start the Pycom Firmware updater software.
• In the Welcome screen ensure only the latest stable release is installed, not developmental releases.
• The latest version at the time of this writing is 1.16.6

• Follow any special setup instructions.

Communications settings

• The software should identify that the Pycom device is connected to the serial port (USB).
• Ensure that the following settings are selected then click Continue.

Pybytes resistration

• The following window will ask for Pybytes registration. Pybytes is an online programming tool for the Pycom microcontrollers.
• We will not be using this feature so press Skip.

Advanced settings

• The next window is the Advanced Settings.
• Include the following selections:
  • File System: LittleFS – filing system optimised for microcontrollers
  • Erase during update – reformat the memory using this file system
  • RESET Config and NVS partitions
  • LoRa Region – Australia and frequency AU915
• Then press Continue.

Upgrading

• The upgrade process will take less than one minute.

Successful update

• When completed the following output will be provided.
• It is not important to record these details, however you may wish to note down:
  • Firmware version (1.20.2.r6)
  • Device ID: 807D3A938770
  • LoRa MAC: 70B3D54990CFD875
• Click Done when finished.
• The Pycom board can then be disconnected from the computer.

Register the Pycom LoPy4 to The Things Network

Log into The Things Network

• Go to The Things Network in Australia

https://www.thethingsnetwork.org/country/australia/

• Create and account and login.
• Enter the Console
• Select the region Australia

Create an Application

• An Application is specially configured software that relates to a Things device.
• In this case the device is a Pycom Lopy4 microcontroller that will transmit temperature data.
• Click on Goto Applications

• Click on Create Application

• Enter
  • Application ID
  • Application name
  • Description

Register end device

• Click on Register end device to start the registration process.

• Click on Enter device specific manually
• Freq plan - Australia FSB 2
• LoRaWAN version - MAC V1.0.2
• Regional Parameters - PHY V1.0.2 REV B

Advanced Activation settings

• Activation mode - Over the air activation (OTAA)
• Additional LoRaWAN class capabilities - None (Class A only)
• Network defaults - Use network's default MAC settings

JoinEUI - formerly AppEUI

• The JoinEUI (formerly called APPEUI) is a 64 bit extended unique identified used to identify a new device during activation.
• Registering a device on The Things Network
• The JoinEUI should be a globally unique identifier for the device.
• It needs to be randomly generated using a python script in the Terminal

import secrets
secrets.token_hex(8)

• Each output will be different because the hexadecimal numbers are ramdomly generated.
• In this case the number is 0430ab1144df0a68
• Enter this number for the JoinEUI
• Click on Confirm

DevEUI

• You can run the code below on you Pycom module to retrieve its EUI.
• This code can be executed as a program ampy on the Raspberry Pi.
• See details for using ampy below.

from network import LoRa
import ubinascii

lora = LoRa()
print("DevEUI: %s" % (ubinascii.hexlify(lora.mac()).decode('ascii')))

• Save the python file using Thonny with the file name joinEUI-test.py

• Open the Terminal and enter the following command to upload the python file to the Pycom microcontroller.

ampy -p /dev/ttyACM0 put /home/pi/joinEUI-test.py /flash/joinEUI-test.py

• Run the joinEUI-test.py with the following command.

ampy -p /dev/ttyACM0 run joinEUI-test.py

• The DevEUI: 70b3d549973919c7 will appear in the output.

• Use this number to register your Device.
• Click Confirm

AppKey

• Click on Generate to create a new AppKey.
• At the bottom of the page click Register new device

New Device Created

• The new device Application will be presented in a Window.
• The status will be listed as No activity yet
• To complete the registration process we need to program the Pycom to send some data to a LoraWAN Gateway.

Using Ampy to upload software to the Pycom

Installation of Ampy

sudo pip3 install adafruit-ampy

• To check that ampy has installed correct enter the following in the Terminal.

ampy --help

• To upgrade ampy to the latest version enter the code

sudo pip3 install adafruit-ampy --upgrade

Connecting to Pycom using Ampy

• To connect to the Pycom enter the following command:

ampy -p /dev/ttyACM0 ls

• Commands need to be entered one at a time.
• This command list the main directory on the Pycom /flash
• All files on the Pycom are found within this directory.
  • -p the Pycom on the Raspberry Pi is always connected to port /dev/ttyACM0

• To list all files and directories on the Pycom enter the command:

ampy -p /dev/ttyACM0 ls -l /flash

Get files from Pycom using Ampy

• Use the get command to copy files from the pycom.
• The following commands serves as an example to get the boot.py file from the Pycom to the host computer.
• The get command will always overwrite files on the computer without warning!

ampy -p /dev/ttyACM0 get /flash/boot.py /home/pi/boot_backup.py

• The get command without a destination file name will print the contents of the file.

ampy -p /dev/ttyACM0 get /flash/boot.py

Put files onto the Pycom using Ampy

• Put files onto the Pycom with the command:

ampy -p /dev/ttyACM0 put /home/pi/test.py /flash/test.py

Run code using Ampy

• You can copy code to the Pycom and then run the code.
• Save the following code in a file named /home/pi/test.py

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