- 1 Setting up your development environment
- 1.1 Requirements
- 1.2 Starting from scratch: Optional
- 1.3 Connecting to the badge
- 1.4 Windows 10: install utilities for commandline
- 1.5 Download Swagbadge (Aiko Engine) firmware
- 1.6 Communicating with the badge
- 1.7 Saving your private key
- 1.8 Putting the Aiko framework onto the device, using mpfshell
- 2 Software development
Setting up your development environment
If you're doing software development, you need an environment on your computer to let you do that.
- #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. Multiplatform support.
- Edit files directly on the badge
- Run files directly on the badge
- GUI instead of command line.
Starting from scratch: Optional
All Swagbadges come with the operating system, basic firmware and aiko preinstalled (this is how you get your assigned encryption key).
If you choose 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.
Connecting to the badge
Windows 10: connecting to the badge
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
Mac OS: connecting the badge
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 [/]>
Linux: connecting to the badge
- 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!
Windows 10: install utilities for commandline
- 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:
- 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 live, for example:
Download Swagbadge firmware for a local copy of what's on the badge:
git clone https://github.com/geekscape/aiko_engine_mp.git
Communicating with the badge
Using mpfshell to communicate
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
Test that your machine can talk to the badge 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, email@example.com ** -- Running on Python 3.8 using PySerial 3.4 -- mpfs [/]>
A little program to say hello world!
>>> print("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)
Thonny, rshell or pyboard.py to communicate
Thonny is a (fabulous) 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("/")*os.statvfs("/"), "bytes free out of",os.statvfs("/")*os.statvfs("/"))' 1699840 bytes free out of 2097152
Saving your private key
Get the file: `configuration/keys.db` from the badge to your computer, via mpfshell, Thonny, or your other chosen mechanism.
Putting the Aiko framework onto the device, using mpfshell
mpfshell COM5 -s scripts\aiko.mpf#run from within the aiko_framework_mp directory