Difference between revisions of "Swagbadge2021 UpdatingSoftware"

From Open Hardware Miniconf
Jump to: navigation, search
 
(16 intermediate revisions by 2 users not shown)
Line 1: Line 1:
= Updating the software framework =
+
= Setting up your development environment =
  
Swagbadge owners might want to update the software framework (Aiko). Dagbadge owners will need to put the framework onto their badge before they can use it.
+
If you're doing software development, you need an environment on your computer to let you do that.
 
 
Here's how to do that!
 
  
 
== Requirements ==
 
== Requirements ==
Line 9: Line 7:
 
* #swagbadge or #dagbadge or any ESP32 with an OLED screen
 
* #swagbadge or #dagbadge or any ESP32 with an OLED screen
 
* Micro-USB cable
 
* Micro-USB cable
* Linux, Mac OS or Linux system running Python 3
+
* Linux (including WSL), Mac OS or Windows system running Python 3
 
* Command line tools: git
 
* Command line tools: git
 +
* Optional, but very useful: [https://thonny.org/ 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).
  
== Setting up your Windows 10 system for connecting to badge hardware ==
+
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 [[Swagbadge_Reinstall|complete reinstall]] are provided here.
 +
 
 +
== Connecting to the badge ==
 +
 
 +
=== Windows 10: connecting to the badge ===
  
 
How to find your serial COM port on Windows:  
 
How to find your serial COM port on Windows:  
Line 26: Line 36:
 
By this point, you have know the serial COM port that your #swagbadge is connected to, e.g COM4
 
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 ==
+
=== Mac OS: connecting the badge ===
 
 
  
 
How to find your serial COM port on OS X:  
 
How to find your serial COM port on OS X:  
Line 34: Line 43:
  
 
Unless you have lot of dev boards (or maybe a phone) plugged in you should just see a single filename there.
 
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`
+
Use this (without the <code>/dev/</code> 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.
 
To get a working `mpfshell` install a recent version of Python (Python3.8 is known to work) using a installed DMG.
Line 45: Line 54:
 
     $ ./env/bin/pip install esptool mpfshell
 
     $ ./env/bin/pip install esptool mpfshell
  
You can then run `mpfshell` to connect:
+
You can then run <code>scripts/mpf.sh</code> to connect (do not include the leading <code>/dev/</code> when setting AMPY_PORT):
  
     $ ./env/bin/mpfshell
+
     $ export AMPY_PORT=<your device node> # for bash, adjust to suit for your shell of choice
     mpfs [/]> open <your device node as found previously>
+
    $ scripts/mpf.sh
 +
     mpfs [/]>  
  
== Setting up your Linux system for connecting to #swagbadge hardware ==
 
[Link other instructions here]
 
  
== Setting up your Windows 10 system for installing #swagbadge firmware ==  
+
{{Note|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.}}
 +
 
 +
=== 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!
 +
# Run <code>./scripts/flash_micropython.sh</code>
 +
 
 +
== Windows 10: install utilities for commandline ==
  
 
* Install [https://docs.conda.io/en/latest/miniconda.html Miniconda3] to create a specific Python development environment. (Note we are using Python3 not Python2)
 
* Install [https://docs.conda.io/en/latest/miniconda.html Miniconda3] to create a specific Python development environment. (Note we are using Python3 not Python2)
Line 70: Line 94:
 
*** <code>exit</code>  #  To exit mpfshell
 
*** <code>exit</code>  #  To exit mpfshell
  
== Download #swagbadge (Aiko Engine) firmware ==
+
== 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:
+
Within your Anaconda Prompt session, change directory to where you’d like the Swagbadge software to live, for example:
 
* <code>cd $HOME/software</code>
 
* <code>cd $HOME/software</code>
  
Download #swagbadge firmware:
+
Download Swagbadge firmware for a local copy of what's on the badge:
* <code>git clone https://github.com/geekscape/aiko_engine_mp.git</code> # NOTE: this URL will change once we're live
+
* <code>git clone https://github.com/geekscape/aiko_engine_mp.git</code>
 
* <code>cd aiko_engine_mp</code>
 
* <code>cd aiko_engine_mp</code>
  
Install MicroPython
 
* Create a directory to hold the MicroPython firmware, such as aiko_engine_mp/firmware/
 
* <code>mkdir firmware</code>
 
* Using your web browser, download: [http://micropython.org/resources/firmware/esp32-idf4-20200902-v1.13.bin esp32-idf4-20200902-v1.13.bin] (mouse right button click → [Save As …]  saving the MicroPython firmware in the firmware directory you just made.
 
** The [http://micropython.org/download/ 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
 
 
Erase #swagbadge LoLin-Lite ESP32 flash memory
 
* <code>esptool --chip esp32 --port COM3 erase_flash</code> # adjust the port to suit.
 
* You’ll know it’s worked, if the output finishes with “Hard resetting via RTS pin…”
 
 
Install microPython on the badge
 
* <code>esptool --chip esp32 --port COM3 --baud 460800 write_flash -z 0x1000 firmware\esp32-idf4-20200902-v1.13.bin</code> #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
+
== Communicating with the badge ==
* <code>mpfshell -o COM3</code> # Adjust port to suit
 
* If it has made a connection to your badge, you will see it say
 
<nowiki>Connected to esp32
 
** Micropython File Shell v0.9.1, sw@kaltpost.de **
 
-- Running on Python 3.8 using PySerial 3.4 --
 
mpfs [/]> </nowiki>
 
  
== Using mpfshell ==
+
=== 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.
 
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.
Line 113: Line 118:
  
 
Note: To get out of repl, use Ctrl-Q (on Windows) which drops you back into mpfshell
 
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
 +
* <code>mpfshell -o COM3</code> # Adjust port to suit
 +
* If it has made a connection to your badge, you will see it say
 +
<nowiki>Connected to esp32
 +
** Micropython File Shell v0.9.1, sw@kaltpost.de **
 +
-- Running on Python 3.8 using PySerial 3.4 --
 +
mpfs [/]> </nowiki>
  
 
A little program to say hello world!
 
A little program to say hello world!
Line 124: Line 137:
 
>>> pin22.value(1)</nowiki>
 
>>> pin22.value(1)</nowiki>
  
== Saving your private key ==
+
=== Thonny, rshell or pyboard.py to communicate ===
  
Use mpfshell to get the file: `configuration/keys.db`.
+
[https://thonny.org Thonny] is a (fabulous) IDE for python, with micropython support.  
  
== Putting the Aiko framework onto the device, using mpfshell ==
+
rshell is an option, but it may not be reliable in all cases. However 'pip install rshell' also installs pyboard.
* <code>mpfshell COM5 -s scripts\aiko.mpf</code> #run from within the aiko_framework_mp directory
 
 
 
=== Windows only: Patch mpfshell ===
 
 
 
''Note!'' mpfshell needs a patch applied to let it run a script under Windows.
 
  
* Inside <code>C:/users/USERNAME/Miniconda2/envs/swagbadge/Lib/site-packages/mp</code>
+
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
* edit <code>mpfshell.py</code>
 
* Search for <code>elif args.script is not None:</code>, around line 796
 
* between that line and the next, insert two lines. It should look like:
 
<nowiki>
 
    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")
 
</nowiki>
 
* Python is very particular about spacing. The rest of the code uses 4 spaces for indents so follow suit.
 
 
 
 
 
= Software development =
 
 
 
== Aiko ==
 
The Aiko Engine is what runs after boot (FreeRTOS, then microPython). Aiko provides a framework for developing applications, by providing higher level abstractions over the basic hardware, events, messaging and other conveniences. Basically, a lot of house keeping that you'd end up writing yourself. After boot, there are two background threads, one looking after Wi-Fi connectivity and the other looking after MQTT connectivity. 
 
There are also three event handlers: MQTT keep-alive, firmware upgrader and the work-in-progress SwagBadge application handler.
 
  
 
<pre>
 
<pre>
>>> aiko.event.event_list.print()
+
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])'
<function swagbadge_handler at 0x3ffe6c70> every 5000 next 23099
+
1699840 bytes free out of 2097152
<function upgrade_handler at 0x3ffedfa0> every 5000 next 23099
 
<function mqtt_ping_handler at 0x3ffe9820> every 60000 next 73672
 
 
</pre>
 
</pre>
That last handler, which every 5 seconds is updating the title bar "LCA2021" <--> "SwagBadge" (see https://github.com/geekscape/aiko_engine_mp/blob/master/applications/swagbadge.py ).
 
  
You can stop a handler, like this (this will stop the top bar status updater):
+
== Saving your private key ==
<pre>
 
>>> import applications.swagbadge
 
>>> aiko.event.remove_timer_handler(application.swagbadge_handler)
 
</pre>
 
  
== Replacing the swagbadge application with your own ==
+
Get the file: `configuration/keys.db` from the badge to your computer, via mpfshell, Thonny, or your other chosen mechanism.
  
Edit configuration/main.py and set "application": "application/yourcode"
+
== Putting the Aiko framework onto the device, using mpfshell ==
 +
* <code>mpfshell COM5 -s scripts\aiko.mpf</code> #run from within the aiko_framework_mp directory
  
 +
= Software development =
  
== Pushing new code ==
+
See [[Swagbadge2021_SoftwareDev]]
Occasionally you might find that the updated source code that you just used the mpfshell "put" command to transfer isn't properly stored on the ESP32 microPython flash filesystem. After rebooting, you might see unexpected errors. A simple way to check is to use the mpfshell "cat" command to check that the file was completely transferred. 
 
 
 
The safest way to update code is to perform a reboot after transferring all the files. Doing a soft-reboot using Control-D doesn't take long, i.e it is faster and easier than doing a hard-reboot with the reset button. The good thing about a reboot (microPython interpreter restart) is that there is no confusion about the complete state of your system, i.e what references have been held onto from your older source code that might still be running in a thread or as an event handler (via the Aiko Engine framework).
 
 
 
You can also delete all running modules:
 
<pre>
 
import sys
 
sys.modules.clear()
 
</pre>
 
 
 
More details in https://spectrum.chat/lca2021-swagbadge/software/safe-software-updates~ba541e3c-d8a2-41a8-ac47-71d87696de2d
 
 
 
== Reboot to shell / Force runaway code to stop ==
 
 
 
It's possible to write code that will leave your badge unresponsive. Rebooting just reruns the same bad code. What to do?
 
 
 
* Place a finger on each of the bottom slider pads, either side of the microprocessor.
 
* Trigger a restart by using the button on the back of the badge, or Ctrl-D in repl (if you can get into repl)
 
 
 
The badge will restart but not autorun any code, just drop you back at the repl prompt. From there you can <code>put</code> bugfixed code back onto the device.
 
 
 
See https://github.com/geekscape/aiko_engine_mp/blob/a5b5593d37509df64a3dcb4cdc3d13a411152d82/main.py#L20
 

Latest revision as of 06:28, 29 December 2021

Setting up your development environment

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

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 [/]> 


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.

Linux: connecting to the badge

  1. install the virtualwrapper https://virtualenvwrapper.readthedocs.io/en/latest/install.html
  2. 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/
  1. Create a firmware folder
  2. Download the bin file per listed above!
  3. Run ./scripts/flash_micropython.sh

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: (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 live, for example:

  • cd $HOME/software

Download Swagbadge firmware for a local copy of what's on the badge:


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, sw@kaltpost.de **
-- Running on Python 3.8 using PySerial 3.4 --
mpfs [/]> 

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)

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("/")[0]*os.statvfs("/")[3], "bytes free out of",os.statvfs("/")[1]*os.statvfs("/")[2])'
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

Software development

See Swagbadge2021_SoftwareDev