Badge Software Development
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.
# 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
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.