Updating the software framework

If you're doing software development, you need an environment on your computer to let you do that.

Requirements

#swagbadge or #dagbadge or any ESP32 with an OLED screen
Micro-USB cable
Linux (including WSL), Mac OS or Windows system running Python 3
Command line tools: git
Optional, but very useful: Thonny - Python IDE with micropython support
- Edit files directly on the badge
- Run files directly on the badge
- GUI instead of command line.

Starting from scratch

All Swagbadges come with the operating system, basic firmware and aiko preinstalled (this is how you get your assigned encryption key). If you would like to wipe your board and start again to ensure you know exactly what's on there, you can do so. Instructions for performing a complete reinstall are provided here.

Setting up your Windows 10 system for connecting to badge hardware

How to find your serial COM port on Windows:

Use the Device Manager.
Under the "Ports" category, you'll see one or more entries. Hopefully one of which is your badge! It will tell you what Port it is on.
If you can't see your badge, you might need to go up to the View menu and use "Show hidden devices" and see if that helps.

Windows 10 may automatically discover your #swagbadge USB hardware and automatically install the correct USB serial hardware driver, or if nothing still shows up, you might need to update your USB drivers for supporting the USB hardware CP210x on your #swagbadge, please follow these instructions:

Download the CP210x drivers from Silicon Labs Windows Universal Driver
Unpack the zip file
Follow the Silicon Labs instructions for INF only install (Section 5 on page 9)

By this point, you have know the serial COM port that your #swagbadge is connected to, e.g COM4

Setting up your Mac OS system for connecting to #swagbadge hardware

How to find your serial COM port on OS X:

   $ ls /dev/tty.usb*

Unless you have lot of dev boards (or maybe a phone) plugged in you should just see a single filename there. Use this (without the /dev/ prefix) when using the open command in mpfshell

To get a working `mpfshell` install a recent version of Python (Python3.8 is known to work) using a installed DMG. Then create a *venv* and install the necessary tools using pip. For example:

   $ mkdir swag
   $ cd swag
   $ python3.8 -m venv env
   $ ./env/bin/pip install esptool mpfshell

You can then run scripts/mpf.sh to connect (do not include the leading /dev/ when setting AMPY_PORT):

   $ export AMPY_PORT=<your device node> # for bash, adjust to suit for your shell of choice
   $ scripts/mpf.sh
   mpfs [/]>

Mac users beware: If you Ctrl-C mpfshell, (or disconnect USB cable while the badge connected to mpfshell), you could crash your desktop, due to the poor kernel drivers the Lolin32 Lite uses.

Setting up your Linux system for connecting to #swagbadge hardware

install the virtualwrapper https://virtualenvwrapper.readthedocs.io/en/latest/install.html
Add the below code to your .bashrc

  export WORKON_HOME=$HOME/.virtualenvs
  export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3
  export VIRTUALENVWRAPPER_VIRTUALENV=/usr/bin/virtualenv
  export PROJECT_HOME=$HOME/Programming
  source /usr/local/bin/virtualenvwrapper.sh
  export AMPY_PORT=ttyUSB0   # note: no leading /dev/

Create a firmware folder
Download the bin file per listed above!
Run ./scripts/flash_micropython.sh

Setting up your Windows 10 system for installing #swagbadge firmware

Install Miniconda3 to create a specific Python development environment. (Note we are using Python3 not Python2)
Create specific Python 3 environment for playing around with your #swagbadge
- Start an Anaconda Powershell Prompt (aka Windows Terminal)
- conda create --yes -n swagbadge python=3
- conda activate swagbadge
Your command prompt should now look like: (swagbadge) C:\Users\[Username]>

Install some python tools to let us prepare and communicate with the badge
- pip install esptool mpfshell

To test that the required tools are installed, trying running the following commands
- esptool # Should show you help on running the esptool
- mpfshell # Should show three lines of output
  - exit # To exit mpfshell

Download #swagbadge (Aiko Engine) firmware

Within your Anaconda Prompt session, change directory to where you’d like the #swagbadge software to be downloaded, for example:

cd $HOME/software

Download #swagbadge firmware:

git clone https://github.com/geekscape/aiko_engine_mp.git # NOTE: this URL will change once we're live
cd aiko_engine_mp

Install MicroPython

Create a directory to hold the MicroPython firmware, such as aiko_engine_mp/firmware/
mkdir firmware
Using your web browser, download: esp32-idf4-20200902-v1.13.bin (mouse right button click → [Save As …] saving the MicroPython firmware in the firmware directory you just made.
- The MicroPython download list has a link to a bunch of firmware drivers, we are using the one for the esp32 device, with the latest 1.4 generic

STOP! Make a copy of your badge's encryption key and network settings before proceeding. Use mpfshell to get configuration/net.py and configuration/keys.db

Erase #swagbadge LoLin-Lite ESP32 flash memory

esptool --chip esp32 --port COM3 erase_flash # adjust the port to suit.
You’ll know it’s worked, if the output finishes with “Hard resetting via RTS pin…”

You may get this error, if so, try esptool.py instead:

sauron [mc]$ esptool --chip esp32 --port /dev/ttyUSB0 erase_flash
esptool.py v2.8
Serial port /dev/ttyUSB0
Connecting....
Chip is ESP32D0WDQ6 (revision 1)
Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None
Crystal is 40MHz
MAC: 7c:9e:bd:ed:79:24
Enabling default SPI flash mode...
Erasing flash (this may take a while)...

A fatal error occurred: ESP32 ROM does not support function erase_flash.
sauron [mc]$ esptool.py --chip esp32 --port /dev/ttyUSB0 erase_flash
esptool.py v2.6
Serial port /dev/ttyUSB0
Connecting....
Chip is ESP32D0WDQ6 (revision 1)
Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None
MAC: 7c:9e:bd:ed:79:24
Uploading stub...
Running stub...
Stub running...
Erasing flash (this may take a while)...
Chip erase completed successfully in 11.8s
Hard resetting via RTS pin...

Install microPython on the badge

esptool --chip esp32 --port COM3 --baud 460800 write_flash -z 0x1000 firmware\esp32-idf4-20200902-v1.13.bin #adjust port and firmware location if necessary
You’ll know it’s worked, if the output finishes with “Hard resetting via RTS pin…”

Test that the software is installed correctly by using mpfshell

mpfshell -o COM3 # Adjust port to suit
If it has made a connection to your badge, you will see it say

Connected to esp32
** Micropython File Shell v0.9.1, sw@kaltpost.de **
-- Running on Python 3.8 using PySerial 3.4 --
mpfs [/]>

Using mpfshell

mpfshell has two functions: it lets you put files on/off the device, and it can give you a python shell to execute code on the device.

Getting files on/off the device is a bit like commandline ftp
- ls - looks at the files on your micropython device
- lls - looks at the files on your local computer in the current directory
- put - puts a file to the device
- cat - shows you the contents of the file
- help() - gives you more information on the commands
- repl - opens up the python shell on the badge

Note: To get out of repl, use Ctrl-Q (on Windows) which drops you back into mpfshell

A little program to say hello world!

>>> print("hello world")
Output: hello world

A little program to turn the blue light on the board on and off (this is on the underside of the Swagbadge, visible through a circular cutout)

>>> import machine
>>> pin22=machine.Pin(22, machine.Pin.OUT, machine.Pin.PULL_UP)
>>> pin22.value(0) 
>>> pin22.value(1)

Alternatives to mpfshell: Thonny, rshell and pyboard.py

Thonny is an IDE for python, with micropython support.

rshell is an option, but it may not be reliable in all cases. However 'pip install rshell' also installs pyboard.

pyboard.py is the official tool that ships with micropython and is more flexible and reliable: http://docs.micropython.org/en/latest/reference/pyboard.py.html

sauron [mc]$ pyboard.py --device /dev/ttyUSB0 -c 'import os; print(os.statvfs("/")[0]*os.statvfs("/")[3], "bytes free out of",os.statvfs("/")[1]*os.statvfs("/")[2])'
1699840 bytes free out of 2097152

Saving your private key

Use mpfshell to get the file: `configuration/keys.db`.

Putting the Aiko framework onto the device, using mpfshell

mpfshell COM5 -s scripts\aiko.mpf #run from within the aiko_framework_mp directory

Windows only: Patch mpfshell

Note! mpfshell used to need a patch applied to let it run a script under Windows. This is no longer required, but recorded here for archival purposes.

Inside C:/users/USERNAME/Miniconda2/envs/swagbadge/Lib/site-packages/mp
edit mpfshell.py
Search for elif args.script is not None:, around line 796
between that line and the next, insert two lines. It should look like:

    elif args.script is not None:

        if platform.system() == "Windows":  #INSERT THIS LINE
            mpfs.use_rawinput = True        #INSERT THIS LINE

        f = open(args.script, "r")

Python is very particular about spacing. The rest of the code uses 4 spaces for indents so follow suit.

Software development

See Swagbadge2021_SoftwareDev

Swagbadge2021 UpdatingSoftware

Contents

Updating the software framework

Requirements

Starting from scratch

Setting up your Windows 10 system for connecting to badge hardware

Setting up your Mac OS system for connecting to #swagbadge hardware

Setting up your Linux system for connecting to #swagbadge hardware

Setting up your Windows 10 system for installing #swagbadge firmware

Download #swagbadge (Aiko Engine) firmware

Using mpfshell

Alternatives to mpfshell: Thonny, rshell and pyboard.py

Saving your private key

Putting the Aiko framework onto the device, using mpfshell

Windows only: Patch mpfshell

Software development

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Tools