Swagbadge2021 SoftwareDev

Want to write your own programs to run on your badge? This page gives a brief overview of the software architecture, an example of a program, and a reference guide on how to access the hardware.

Background

The badge runs MicroPython (written by Damien George from Melbourne!) and has the Aiko framework (written by OHMC's Andy Gelme) loaded on it.

MicroPython gives you libraries to access the ESP32 microprocessor functionality. Things like: reading and writing to specific pins on the processor or performing operating system functions such as accessing the file system).

Aiko gives you convenience libraries for driving the badge hardware like the OLED screens, as well as running threads to keep your badge connected to wifi, a connection to the MQTT server, the emergency-stop function to prevent runaway code, and an automatic upgrade function so we can ship upgrades to your device without you having to wrangle git.

Sample code

This code writes "Hello world" to one screen, while displaying the status of the wifi, MQTT connection, button presses and slider status on the left hand screen.

It demonstrates how to use the Aiko event loop to periodically poll for hardware state, as well as how to access some of the features of the badge.

You can find more example code in the ```examples``` directory of the Aiko repository on github.

Example code: use "expand" to view

 
# examples/helloworld.py
#
# Writes a message to the oled and displays some state info
#
# Usage
# ~~~~~
# import examples.helloworld as helloworld
# from examples.helloworld import run
# run()
#

from machine import Pin, TouchPad
import aiko.event as event
import aiko.oled as oled

title = "Hello!"

import configuration.main


# Buttons: underneath the screens
button_right = Pin(17, Pin.IN, Pin.PULL_UP)
button_left = Pin(16, Pin.IN, Pin.PULL_UP)

# Clean out the whole line that was there before
# Write some new text and show it
def oled_write_line(oled_target, x, y, text):
    oled_target.fill_rect(0,y,oled.width, oled.font_size, oled.bg)
    oled_target.text(text, x, y)
    oled_target.show()
    
def status():
    sliders = touch_slider_handler()
    oledL = oled.oleds[0]
    oledR = oled.oleds[1]
    oled.write_line(oledR, 1, 10, "Hello world!")
    oled_write_line(oledL, 1, 10, "Wifi: "+str(net.is_connected()))
    oled_write_line(oledL, 1, 20, "MQTT: "+str(mqtt.is_connected()))
    oled_write_line(oledL, 1, 30, " "+str(int(not(buttonL.value())))+" Button "+str(int(not(buttonR.value()))))


# Check on the status of the badge hardware and display that every 500ms          
def run():
    oled.oleds_clear(oled.bg)
    oled.set_title(title)
    event.add_timer_handler(status, 500)
    try:
        event.loop()
    finally:
        event.remove_timer_handler(statusbar)

Software reference

MicroPython environment

MicroPython docs

Special files

There are two special files which are run automatically by MicroPython if they exist on the filesystem: boot.py and main.py.

• boot.py: This file is run first on power up/reset. We don't modify it from what MicroPython ships with, but it's important to know it exists (and not to delete it), and is interesting to look into it to see what it does.
• main.py: This is run after boot.py so if you want something to automatically happen on boot/reset, this is where to put it. We use this to start up the Aiko framework, initialise the hardware (such as the network and mqtt) and start up any application that is configured inside configuration/main.py

Directory structure

What's on the processor? Where does it live?

• main.py, boot.py - files run on bootup
• lib - code in here is aiko framework code and automatically in the micropython 'path'.
  • aiko - the aiko framework
• applications - programs to run automatically on bootup. Must have an initialise function
• configuration - control the config of aiko using files in here
• examples - sample code!

You can't edit the files directly on the processor (there's no editing tooling): you edit a copy of it on your computer, then use mpfshell to put it onto the badge.