Environment Setup

The main programming interface and language for the flow3rbadge is Python. More exactly, it’s Micropython, which is a fairly sizeable subset of Python that can run on microcontrollers.

Good news: if you’ve ever used Micropython on an ESP32, then you probably already have all the tools required to get started. However, while the tools to program the badge might be the same as for stock Micropython on ESP32, our APIs are quite different.

If you haven’t used Micrpython, don’t worry. It’s not that difficult other than wrapping your head around file access.

The st3m framework is the main Python codebase you’ll be writing against. Instead of using standard Micropython libraries like machine or low level display drivers, you’ll be writing applications that implement st3m classes like Responder or Application.

But, enough intro for now, let’s get started.

Accessing the badge

When the badge runs (for example, when you see the main menu), you can connect it to a PC and it should appear as a serial device. On Linux systems, this device will be usually called /dev/ttyACM0 (sometimes /dev/ttyACM1).

You can then use any terminal emulator program (like picocom, GNU screen, etc) to access the badge’s runtime logs. Even better, use a dedicated micropython-specific program, as that will actually let you transfer files. These are the tools we’ve tested and are known to work:

Tool

Platforms

mpremote

Linux, macOS, Windows

Micro REPL

Android

In the rest of these docs we’ll use mpremote. But you should be able to follow along with any of the aforementioned tools. If you are on Linux and your flow3r came up as /dev/ttyACM1, add an a1 after mpremote.

After connecting your badge and making sure it runs:

$ mpremote
Connected to MicroPython at /dev/ttyACM0
Use Ctrl-] or Ctrl-x to exit this shell
[... logs here... ]

The badge will continue to run.

Warning

Your flow3r is not showing up using Linux?

To let mpremote to work properly your user needs to have access rights to ttyACM.

Quick fix: sudo chmod a+rw /dev/ttyACM[Your Device Id here]`

More sustainable fix: Setup an udev rule to automatically allow the logged in user to access ttyUSB

  1. To use this, add the following to /etc/udev/rules.d/60-extra-acl.rules: KERNEL=="ttyACM[0-9]*", TAG+="udev-acl", TAG+="uaccess"

  2. Reload udevadm control --reload-rules && udevadm trigger

Now, if you press Ctrl-C, you will interrupt the firmware and break into a Python REPL (read-eval-print-loop) prompt:

Traceback (most recent call last):
  File "/flash/sys/main.py", line 254, in <module>
  [... snip ...]
KeyboardInterrupt:
MicroPython c48f94151-dirty on 1980-01-01; badge23 with ESP32S3
Type "help()" for more information.
>>>

The badge’s display will now switch to ‘In REPL’ to indicate that software execution has been interrupted and that the badge is waiting for a command over REPL.

Congratulations! You can now use your badge as a calculator:

>>> 5 + 5
10

But that’s not super interesting. Let’s try to turn on some LEDs:

>>> import leds
>>> leds.set_rgb(0, 1, 0, 0)
>>> leds.update()

The LED right next to the USB connector should light up red. You can continue experimenting with different APIs (like leds, audio, etc).

Transferring files over REPL

You can also access the filesystem over the same Micropython serial port:

$ mpremote
MicroPython c48f94151-dirty on 1980-01-01; flow3r with ESP32S3
Type "help()" for more information.
>>> import os
>>> os.listdir('/')
['flash']
>>> os.listdir('/flash/sys')
['main.py', 'st3m', '.sys-installed']
>>>

$ mpremote ls :/flash/sys
ls :/flash/sys
           0 main.py
           0 st3m
           0 .sys-installed

Disk Mode

For larger file transfers (eg. images, sound samples, etc.) you can put the badge into Disk Mode by selecting Settings -> Disk Mode in the badge’s menu.

You can then select whether to mount the 10MiB internal flash or SD card (if present) as a pendrive. The selected device will then appear as a pendrive on your system, and will stay until it is ejected. The serial connection will disconnect for the duration of the badge being in disk mode.

Disk Mode can also be enabled when the badge is in Recovery Mode.

Distributing applications

We have an “App Store” where you can submit your applications: https://flow3r.garden/apps/

To add your application, follow the guide in this repository: https://git.flow3r.garden/flow3r/flow3r-apps

Using the simulator

The flow3r badge firmware repository comes with a Python-based simulator which allows you to run the Python part of st3m on your local computer, using Python, Pygame and wasmer.

Currently the simulator supports the display, LEDs, the buttons, accelerometer (in 2D) and some static input values from the gyroscope, temperature sensor and pressure sensor.

It does not support most of the audio APIs. It also does not support positional captouch APIs.

To set the simulator up, clone the repository and prepare a Python virtual environment with the required packages:

$ git clone https://git.flow3r.garden/flow3r/flow3r-firmware
$ cd flow3r-firmware
$ python3 -m venv venv
$ venv/bin/pip install pygame requests pymad
$ venv/bin/pip install wasmer wasmer-compiler-cranelift

Warning

The wasmer python module from PyPI doesn’t work with Python versions 3.10 or 3.11. You will get ImportError: Wasmer is not available on this system when trying to run the simulator.

Instead, install our rebuilt wasmer wheels using

venv/bin/pip install https://flow3r.garden/tmp/wasmer-py311/wasmer_compiler_cranelift-1.2.0-cp311-cp311-manylinux_2_34_x86_64.whl
venv/bin/pip install https://flow3r.garden/tmp/wasmer-py311/wasmer-1.2.0-cp311-cp311-manylinux_2_34_x86_64.whl

TODO: set up a pyproject/poetry/… file?

You can then run the simulator:

$ venv/bin/python sim/run.py

Grey areas near the petals and buttons can be pressed.

The 3-way switches can be controlled with keyboard keys and have a default mapping of 1, 2, 3 for the left and 8, 9, 0 for the right switch. This mapping can be changed by copying sim/config.py.default to sim/config.py and adjusting it to personal preference.

The simulators apps live in python_payload/apps copy you app folder in there and it will appear in the simulators menu system.

If you want to start an app directly, simply give its name (the [app] -> name in flow3r.toml) as an argument:

$ venv/bin/python sim/run.py Worms