ben-hawks / bados

CircuitPython Mini Operating System for Pimoroni Badger2040 Electronic Badge

BadOS

Badge Operating System for Pimoroni Badger2040 Electronic Badge Using CircuitPython

Overview

The default installation for the Badger2040 is MicroPython, but since CircuitPython offers an easier and more user-friendly system for designing custom applications, it was chosen for this system. The inspiration for this mini-OS / launcher came from both the original MicroPython version as well as a CircuitPython version created by BeBoX.

Since this is a major restructure and rewrite of both systems, it was decided to create an entirely new repo rather than a fork of either of those systems; but since BadOS retains some of the look and feel of those systems and uses some of their code in several areas, it's only appropriate to give proper credit to both of those systems.

A good resource for learning about the badge and starting with the original MicroPython system can be found at Pimoroni with this link: https://learn.pimoroni.com/article/getting-started-with-badger-2040

---

Installation of CircuitPython and BadOS

The installation consists of two very simple steps.

1. Replace the badge's MicroPython system with CircuitPython.
2. Install the BadOS system onto the badge.

Replacing the MicroPython system with CircuitPython.

The Badger2040 hardware/firmware design makes this very easy. First, download the latest version of CircuitPython for this hardware from the following link. It will be a file with the .UF2 extension. https://circuitpython.org/board/pimoroni_badger2040/

Then plug the badge into a USB port. Locate the two small buttons on the back of the badge at the top. While holding the button labeled 'boot/usr', press the nearby Reset button labeled 'rst'. The badge will reset, make a USB connection and expose part of its storage as a flash drive named 'RPI-RP2'. Simply copy (or click-drag) the downloaded CircuitPython .UF2 file onto the root directory of this drive (alongside the .HTM and .TXT files). Once the UF2 file is in place, just press the Reset button again and the badge firmware will install CircuitPython. That completes step one!

Install BadOS

Download the files from this repo. After CircuitPython is installed and the badge has been restarted by pressing only the Reset button, it will expose a different partition of its storage as a new flash drive called 'CIRCUITPY'.

Copy all of the files/directories from the CIRCUITPY directory of this repo onto the root CIRCUITPY directory on the badge. At that point, the directory on the badge should have 'main.py' and three folders named 'apps', 'assets' and 'lib'. That completes step two!

Your badge should now be ready to go. Just press Reset to restart it with BadOS running on CircuitPython.

---

BadOS Directory Structure

The 'main.py' Python program in the root directory is the main launcher program for BadOS.

The 'apps' directory is where the launcher finds all of the application programs for the user to select. All sub-directories contain a single application listed in the launcher menu.

The 'assets' directory contains three sub-dirs with various fonts, icons and images used by the system.

The 'lib' directory is where the libraries to assist with using the hardware and the BadOS functions are stored.

---

Applications

• BADGE - This is the main function of the badge hardware. It allows you to customize and display a badge with your own image and information.

• CLOCK - Digital and text clock.

• D20 - Random roll of a D20 die.

• DEMO - Demonstration of graphics.

• EBOOK - Read an electronic book.

• FRAC - Generate a fractal graphic of a section of the Mandelbrot set.

• IMAGE - Select and display bitmaps.

• INFO - Information about the badge hardware and BadOS.

• KEYBD - Emulate a keyboard when connected to USB.

• PREFS - Preferences. Select the keyboard language country (France or USA).

• THERML - Future program to support capture and display of real-time images from a thermal camera accessory for the badge.

• WORLD - Generate and show simple world map graphic.

---

Customizing the Badge Layout

To customize a badge with your information, you need to create a text file with your info and a bitmap of the image to display. The bitmap needs to be a valid .bmp file with a black/white single-bit depth palette 104 pixels wide by 128 high or smaller.

In the /badge directory are several example badges. The easiest option is to duplicate or rename one of those directories and the included files to whatever name you like, and change the data in the corresponding .txt file to your information. Some of those fields are displayed on the badge, others are used to create a vcard QR code so you can easily provide your contact information to anyone with a smartphone camera.

---

Custom Applications

To add a custom application, simply create a new folder in 'apps' named for your application. Since space is limited on the menu screen of the badge, any application named more than 6 characters is truncated, so keep that in mind when you name your application.

Within your new application folder, create two files with the same name as your application but with extensions '.bmp' and '.py'. These will be used by the launcher to create the icon for your application in the menu and for your Python program that will be launched. If the launcher doesn't find a '.bmp', it will use a default icon for your app.

---

Libraries

The best way to see the various functions that are available in the libraries is to review the code for the main.py launcher and the various apps to see how they're imported and used.

---

Issues and Work-In-Process

The Keybd app is currently not operational and is also being rewritten. At that point, it will include the HID capability.

The Ebook app does a simple line-wrap of the text without regard to any words which are split. It also needs to handle some special characters which currently perform line-feeds and other control functions at inappropriate locations. This will be fixed soon.

The Therml app is a future application requiring hardware which is currently not available.

Documentation explaining how to use the BadOS library functions for Screen, Buttons, Menu and other capabilities is being written and should be available here soon. Until then, you can at least see how they are used in the various sample applications.

Thank you for your patience! I hope you enjoy using BadOS.

bados's Issues

Support low power/sleep states for badge to improve battery life

At the moment, the Pico W or any of the peripherals don't generally go to sleep ever, which makes the badge drain batteries somewhat fast despite using an ePaper display. This is an overarching task to add a general system for deep sleep support to BadOS, likely requiring some sort of state save/load management along with careful (re)design of some aspects of the firmware to accommodate this.

Additionally, this heavily relies upon the RTC, which the implementation is not currently complete/validated yet, as mentioned in #8 . That issue may potentially act as a blocker for some aspects of this task.

Sub-tasks TBD

Write basic usage documentation for user facing funcationality

Write documentation so users know how to create, modify, and upload display badges for the "Badge" app

Add SD Card Support

Add SD Card support for the onboard microSD/TF Card slot on the AIV DC31 Badge, as CircuitPython on the PicoW/Badger 2040W uses up 1.5/2MB onboard flash alone, before BadOS + it's assets and any user code.

• Understand/explore if SD Card is interfered with by Circuitpython FW setting up the built in display object
  https://github.com/adafruit/circuitpython/blob/main/ports/raspberrypi/boards/pimoroni_badger2040w/board.c
  • if CircuitPython does perform any transactions over the SPI bus to the screen during boot (outside of the boot.py/main.py scripts), understand correct procedure/modifications to make to circuitpython firmware to init the SD card properly. Also figure out how to build a new circuitpython firmware binary.
  • if the firmware simply constructs the object and doesn't send any data across the SPI bus during init, then we can likely get away with initalizing the sd card like normal first thing in the boot/main.py
• figure out how to manage ocationally checking for a new SD card, or at least keeping the bus in a state that will not make the SD card unhappy until we reboot or init the card
  • modify next version of the badge to use a card detect pin????

Add board config system

Create/add a system to support different boards and their hardware configurations, as well as simplify accessing common values/functions across apps.

Likely implemented as done in this project:
https://github.com/bablokb/circuitpython-clock/blob/main/src/main.py#L27
https://github.com/bablokb/circuitpython-clock/blob/main/src/config/pimoroni_badger2040w.py

Create LLM Interface Frontend App

Depends on # and #

Application that records audio while a user is holding down a button, then sends that audio to some endpoint over wifi, waiting for response text back to display on the screen.

Major Components/considerations:

• Audio recording

  • We're limited by the RP2040's low RAM, so we might have to be creative here, maybe using rp2PIO?
  • Likely will have to play around with bitrate/sample depth of the audio we're recording, it doesn't have to be great, just good enough for whatever's required for transcription
  • compression likely isn't super helpful on the badge side of things, but depending on how the backend/infra goes, it might be required. In this case, its might be worth looking into stuff re: Mel Spectrograms and mfcc (or maybe just use plain old regular compression techniques?)

• Network Connection (Relies on #2 )

  • This might be streaming data as talking is happening, or might be just reading from a file once it's complete. Depends on the above limitations/solutions

• Response Display

  • Probably should have the ability to scroll through the history, including transcribed audio from user (text message style?). No Images, only text.

• Hackability

  • API Key/Endpoint/etc. should all just be in an easy config file that the use can swap out later if they want to run their own self hosted version after DC32
  • all conversation logs should be saved to SD card

Add Support for RTC

The Badger2040w uses a pcf85063a Real Time Clock to manage extreme low power states, allowing for the badge to sleep (without the pico w turning on) for up to 1 month.

Basic support is already implemented in the CircuitPython firmware for the Badger 2040W, backing the built in rtc module, which is subsequently used to back the time and alarms modules, but further functionality and improvements are possible.

Minimum features

set the pcf85063a alarm to a given amount of time in the future
ability to use RTC value for alarms, checking and resetting the alarming flag

Intended features

(if wifi implemented) Sync RTC time with NTP server
sleep/deep sleep support using rtc alarms

Long term features

Ultra deep sleep (fully powering off the pico) until pcf85063a alarm or user interaction

Update firmware and BadOS to use/support SSD1680 based display

Due to Cost, Availability, and other issues, we are moving from the UC8151D based 2.9" ePaper Display to a SSD1680 based 2.9" ePaper Display for the DC32 version of the badge.

This is a critical and important part of this project, and will be a blocking issue until a certain sub-tasks are completed. This requires (re) building the CircuitPython distribution to initialize and connect to the new display properly, validating part pin outs/specifications to ensure compatibility, and re-writing certain parts of BadOS to support the new display (if required).

Additionally, the new display technically offers some improved performance and options over the old one, namely in terms of faster refresh times (1.5s vs 3s) and/or 4 color/2b grayscale. These features are less documented and require greater understanding of the ePaper display hardware to properly implement, so they will not be high priority tasks.

Outline of tasks required:

• Validate compatible connector, pinout, and electrical characteristics between displays

  • Validate display in hand (Waveshare 2.9" ePaper display module v2) is the same as the intended display from the Alibaba supplier (Good Display GDEY029T94)
  • Validate that the new display is pin/electrically the same as the old display (Good Display GDEW029I6FD)

• Test and do first attempt at configuring and driving new display via CircuitPython library

• Update configuration and initialization of display within the CircuitPython board definition and firmware image itself so the new display is used as the "Builtin" display for the badge

  • This relies on/is part of a larger issue to build a custom CircuitPython distribution (and ideally upstream it) for the badge instead of using the Badger2040w's build
  • Figure out a solution to potentially support both displays if possible, at least during development.

• Update BadOS to support and use the new display properly

  • Validate what updates/changes to BadOS are due to the new screen vs CircuitPython 9.0+

• Explore the use of the enhanced capabilities of the new screen (Refresh Rate, grayscale, etc.)

Add Wifi support/Network Manager

Add in support for connecting to wifi, allow apps to connect (through existing connection or new connection each app?), configuration support via file on badge, basic control (wifi enable/disable, reconnect, status, etc.) on device through dedicated app

Write Docuntation for BadOS API objects, example apps

Write documentation so that users have a reference and examples to create new applications

Fix crash when displaying user badge QR Code if data is too long for miniQR lib

Currently, if the data a user has entered for their badge is too long, the miniQR library from adafruit cannot handle it and the badge crashes.

Update BadOS to be compatible with CircuitPython 9.0+

Originally BadOS was based on CircuitPython 8.2.0, but with the release of 9.0 certain things have changed that require debugging and updating the existing code to work with 9.0+

This task requires some research potentially, so changes needed will be added to this issue as they're discovered.

• displayio changes

  • Update display.show(x) to display.root_group = x
  • ???

• Update library mpy files to most recent versions

Add SAO specific class for interfacing with SAO ports

Build out a basic SAO class to simplify process of interfacing with the SAO ports on the AIV DC31 Badge

Sponsor Logo Support

As part of the village's sponsorship commitments this year, we're required to include sponsor logos on the badge in some capacity. Currently the best path forward for this is displaying them as a splash screen on boot/in a special "thank you" application.

Finish USB Rubber Ducky/HID Keyboard Emulation mode

Finish the intended USB Rubber Ducky mode from BadOS upstream. Current intended implementation plan is as follows:

1. User opens Ducky app
2. List scripts in /ducky
3. user selects a specific script
4. write selected file to NVmem? File? Something??
5. reboot pico
6. boot.py checks for ducky mode flag, unsets flag, if true configures USB as a keyboard, else boots into normal mode
7. duck_main.py sets USB Device Descriptor, manu, product, etc. to a keyboard
8. try/except loop trying to open a USB_HID connection, waiting for user to plug in USB
9. once USB is plugged in, have present a "Run" "Stop" and "Exit" option
10. run script when RUN pressed (calls apps/ducky/... functions)
11. stop when STOP pressed twice rapidly, change option to "Run" "Restart" "Exit"
12. when "restart" pressed, start from the top of the script, "run" continues from where left off
13. when EXIT pressed three times rapidly (while running or stopped) or once (once done or before running), reboot board