hackrva / badge2023

Software for electronic badges for RVASec 2023

badge2023

RVASec Badge 2023 Firmware

Initial Setup

There are two ways you can run the badge software:

1. You can build the badge software and run it on hardware. This is helpful when seeing how well something works on the badge itself.
2. You can build a simulator that can run the badge software on your computer. This is usually more helpful when developing an app, since debugging tools on your computer are more sophisticated and easier to set up.

They need a few different things in order to set yourself up to build and run the badge software.

In both cases, you will need CMake, which is a build system / build system generator. (Version 3.13 or higher)

Git Setup

We're using git for version control, and there's one submodule being used. This means that after cloning the repository, you'll need to run the command

	git submodule update --init --recursive

to get the submodule.

Building for Hardware

For more info, see the Pico SDK README.

When building the software for badge, you will need a cross-compiler. This takes code written on your computer and compiles it into machine code for the badge. The compiler used is the ARM Embedded GCC compiler.

This may be available in your package manager (maybe called "gcc-arm-none-eabi"), or here. If downloaded from the ARM site, you will need to take steps to add it to your $PATH or equivalent environment variable. (If it works, when you open a new terminal window, the arm-none-eabi-gcc program can be run).

Visual Studio Code Setup

There are various editors and plugins you can add to better support CMake. A common setup is using Visual Studio Code with its CMake Tools plugin. (When you open the project folder with VS Code, it will suggest installing this plugin automatically, which you should do.)

CMake Tools has a couple of additional concepts: Kits that define compilers it can find, and Variants that define build parameters. If you've installed the ARM Embedded GCC compiler, the plugin should be able to scan for kits and automatically find your cross-compiler (you'll see one named arm-none-eabi).

If using VS Code with CMake Tools, you'll be able to use the Pico Variant (alongside the Kit for the embedded compiler). Make sure to pick both the Kit and Variant that correspond with each other! To switch Variants, you can click on the information icon in the blue bar the bottom of the VS code window. To switch Kits, you can click on the wrench icon in the same bar. Find more information on CMake Tools here

You will want to change the target from [all] in the same bar at the bottom to [badge2023_c].

The build folder will be named build-pico if using the VS Code variants.

Command Line Build

If not using an IDE or VS code, you can use the following command to set up the build:

./run_cmake.sh

which just does this:

cmake -S . -B build/ -G "Unix Makefiles"

to configure the build. This generates a bunch of makefiles. To build the firmware:

	cd build
	make

(You can clean the build by running make clean.)

If the build is successful, a firmware blob will be produced at build/source/badge2023_c.uf2.

A note for Windows users

This link has a bunch of useful information for getting started and installing prerequisites. Note that you don't need to do the PICO_SDK_PATH setting portion, and when running and building this repository, you will want to use "NMake Makefiles" instead of "Unix Makefiles" (unless you want to install and use make as well).

Alternatively for Windows users

Installing the development environment on Ubuntu, or another distro of your choice in WSL2 has been successfully accomplished, and was a fairly straightforward process. The best docs, surprisingly, came from Microsoft. Don't skip the VS Code integration with WSL.

You can use Ninja, if you like, as well. (Specify -G Ninja instead of Makefiles in the cmake command.)

Flashing the Badge

To flash your firmware to the badge, press and hold the small white button just to the right of the screen on the badge, and connect the badge via micro usb cable to your computer and release the button. This will cause the badge to act as a USB storage device, and you should see a filesystem mounted on your computer. On linux this will typically appear at /media/*username*/RPI-RP2. Copy the firmware to this location:

	cp source/badge2023_c.uf2 /media/*username*/RPI-RP2/

Building the Simulator

The simulator is intended to run on a Posix-y (that is, Linux or Mac) environment. Windows can build and run it, although by using Windows Subsystem for Linux if your Linux subsystem has a desktop environment set up.

To build the simulator, you will need a C compiler for your computer ("apt-get install build-essential" on Debian based distros). The simulator relies on SDL2 for graphics and keyboard/mouse/game controller support, so you will need to install SDL2. For images, libpng is needed. ("apt-get install libsdl2-dev" package on Debian based distros, libpng-dev is usually already present, on Mac, "brew install sdl2" and "brew install libpng"). In addition, portaudio is needed, the debian package names might be libportaudio2 and portaudio19-dev. If you want to compile the simulator without audio support, in the top level CMakelists.txt, make the following change:

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 4b58925e..8c7eab01 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -5,7 +5,7 @@ set(PICO_SDK_FETCH_FROM_GIT ON CACHE BOOL "Download Pico SDK from Git. Default o
 set(PICO_EXTRAS_FETCH_FROM_GIT ON CACHE BOOL "Download Pico SDK Extras from Git. Default on.")
 set(TARGET "PICO" CACHE STRING "Target hardware. For now, only Pico, in the future, badge/simulator")
 set(PRODUCT "badge2023_c")
-set(SIMULATOR_AUDIO "yes") # change to "no" to avoid compiling audio code in simulator
+set(SIMULATOR_AUDIO "no") # change to "no" to avoid compiling audio code in simulator
 
 if (${TARGET} STREQUAL "PICO")
     # Pull in SDK (must be before project).

Visual Studio Code Setup

If you're using VS Code with CMake Tools, you should be able to pick the Simulator Variant (alongside the Kit for your local computer's compiler to build the simluator). Make sure to pick both the Kit and Variant that correspond with each other!

The build folder will be named build-simulator if using the VS Code variants.

Command Line Build

In a similar way to the hardware target, you can generate makefiles via CMake.

./run_cmake_sdl_sim.sh

which just does this:

cmake -S . -B build_sdl_sim/ -DTARGET=SDL_SIMULATOR -G "Unix Makefiles"

Note that to make the simulator, there is an extra flag that gets passed in: -DTARGET=SDL_SIMULATOR.

After which, you can cd into the build_sdl_sim/ directory and run make to build the simulator target. The output program is called build_sdl_sim/source/badge2023_c, which you can run. It is compiled with debug information and with address sanitizer and undefined behavior sanitizer to help catch bugs early and so you can easily debug things with gdb.

Off-Target Unit Tests

Off-target unit tests are run using CTest (part of CMake). The test_key_value_storage executable provides a template that can be used.

Generating Documentation

The code has doxygen-style comments that can be pulled out to an HTML site (or the other formats doxygen supports). To generate it locally, you'll need doxygen and graphviz to be installed in your local environment. Once you do, running doxygen in the source folder will create a folder called docs with the documentation output.

Adding Your Own Apps

Apps are mostly contained within a single .c/.h file in the apps folder. Take a look at the comments inside the badge-app-template files for help getting started. See also BADGE-APP-HOWTO.md

Current Status

The overall structure of the repository is:

• CMakeLists.txt in the root directory is the main project definition. It includes subdirectories to add files/ modules to the build. pico_sdk_import.cmake is provided by the Pico SDK.
• Code for apps and games is in the source/apps folder.
• Code for an interactive terminal (which may or may not be useful after the main application is running) is the source/cli folder. To run the CLI, hold the D-Pad left button down as the badge is starting. The display will show noise, and if you connect to the serial terminal that shows up on your computer, you can enter commands.
• Code that depends on Pico interfaces is within source/hal/*_rp2040.c files, with a platform agnostic header in the corresponding source/hal/*.h file. Code built for the simulator is in source/hal/*_sim.c.
• Generally helpful system code (main menus, screensavers, and the like) is in the source/core folder.
• Code for display buffers and drawing is in the source/display folder.

What's working

Here's a list of major functional blocks and their current availability in software.

• ✔️ indicates the functionality is there!
• ❌ indicates the functionality still needs to be implemented.

Component	Badge Hardware	Simulator
LCD Display	✔️	✔️
3-Color LED	✔️	✔️
D-Pad	✔️	✔️
IR Tx/RX	✔️	✔️
Rotary Encoder	✔️	✔️
Audio Output	✔️	✔️
Audio/Jack Input	❌	❌

To Do:

Basic Bringup:

• Add audio driver

Other Extensions:

• Add a unit test framework (perhaps for mocks?)
• Add a Rust build?
• MicroPython setup for badge hardware?
• Improve documentation for beginners
• GitHub Actions integration (build firmware/run tests/build docs)
• Add audio to simulator

badge2023's Issues

How can I run clang scan-build on this Cmake project?

The internet seems to claim that I can do the following:

$ export CC=/usr/bin/clang
$ export CXX=/usr/bin/clang++
$ scan-build cmake ...
$ cd build_sdl_sim
$ scan-build make

However, this doesn't work in two different ways.

First, cmake (or perhaps our usage of cmake) does not seem to honor CC and CXX. Instead, it invariable uses /usr/bin/cc

On my system, /usr/bin/cc is a symlink to /etc/alternatives/cc, which is a symlink to /usr/bin/gcc

I tried changing this to link to /usr/bin/clang (a bit ham-fisted, but that seemed to work, and made Cmake compile with clang, though I did have to run cmake again, and it detected that it was using clang.)

However, when I ran

$ scan-build cmake ...
$ scan-build make ...

It didn't do the scan, instead it just compiled as usual. I suspect whatever cmake is doing is thwarting whatever interposing mechanism scan-build uses to make the build scan rather than compile.

Heavy use of rotary encoders may cause badge to lock up

A couple of times, I've seen the badge lock up with heavy use of rotary encoders. Not sure if the encoders caused it. Difficult to reproduce.

Bug in pathfinding in goodbye gulag

Not sure how this happened:

READ of size 1 at 0x55a7bc5c2cea thread T1
    #0 0x55a7bc553479 in cost_fn /home/scameron/github/badge2023/source/apps/gulag.c:1948
    #1 0x55a7bc5686ba in a_star /home/scameron/github/badge2023/source/core/a_star.c:232
    #2 0x55a7bc55f2d3 in move_soldier /home/scameron/github/badge2023/source/apps/gulag.c:4165
    #3 0x55a7bc5614d7 in move_objects /home/scameron/github/badge2023/source/apps/gulag.c:4388
    #4 0x55a7bc56151e in gulag_run /home/scameron/github/badge2023/source/apps/gulag.c:4399
    #5 0x55a7bc562b20 in gulag_cb /home/scameron/github/badge2023/source/apps/gulag.c:4707
    #6 0x55a7bc56c77f in menus /home/scameron/github/badge2023/source/core/menu.c:263
    #7 0x55a7bc568f95 in ProcessIO /home/scameron/github/badge2023/source/core/badge.c:177
    #8 0x55a7bc52e6dc in badge_main /home/scameron/github/badge2023/source/main.c:79
    #9 0x55a7bc5760d7 in main_in_thread /home/scameron/github/badge2023/source/hal/init_sdl_sim.c:47
    #10 0x7f05e32bc608 in start_thread /build/glibc-SzIz7B/glibc-2.31/nptl/pthread_create.c:477
    #11 0x7f05e31e1132 in __clone (/lib/x86_64-linux-gnu/libc.so.6+0x11f132)

0x55a7bc5c2cea is located 10 bytes to the right of global variable 'room_cost' defined in '/home/scameron/github/badge2023/source/apps/gulag.c:229:22' (0x55a7bc5c28e0) of size 1024
0x55a7bc5c2cea is located 22 bytes to the left of global variable 'nodeset1' defined in '/home/scameron/github/badge2023/source/apps/gulag.c:233:22' (0x55a7bc5c2d00) of size 8200
SUMMARY: AddressSanitizer: global-buffer-overflow /home/scameron/github/badge2023/source/apps/gulag.c:1948 in cost_fn
Shadow bytes around the buggy address:
  0x0ab5778b0540: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
  0x0ab5778b0550: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
  0x0ab5778b0560: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
  0x0ab5778b0570: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
  0x0ab5778b0580: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
=>0x0ab5778b0590: 00 00 00 00 00 00 00 00 00 00 00 00 f9[f9]f9 f9
  0x0ab5778b05a0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
  0x0ab5778b05b0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
  0x0ab5778b05c0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
  0x0ab5778b05d0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
  0x0ab5778b05e0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
Shadow byte legend (one shadow byte represents 8 application bytes):
  Addressable:           00
  Partially addressable: 01 02 03 04 05 06 07 
  Heap left redzone:       fa
  Freed heap region:       fd
  Stack left redzone:      f1
  Stack mid redzone:       f2
  Stack right redzone:     f3
  Stack after return:      f5
  Stack use after scope:   f8
  Global redzone:          f9
  Global init order:       f6
  Poisoned by user:        f7
  Container overflow:      fc
  Array cookie:            ac
  Intra object redzone:    bb
  ASan internal:           fe
  Left alloca redzone:     ca
  Right alloca redzone:    cb
  Shadow gap:              cc
Thread T1 created by T0 here:
    #0 0x7f05e34ba815 in __interceptor_pthread_create ../../../../src/libsanitizer/asan/asan_interceptors.cc:208
    #1 0x55a7bc5761e7 in hal_run_main /home/scameron/github/badge2023/source/hal/init_sdl_sim.c:57
    #2 0x55a7bc52e791 in main /home/scameron/github/badge2023/source/main.c:97
    #3 0x7f05e30e6082 in __libc_start_main ../csu/libc-start.c:308

==31563==ABORTING

asset_converter.py requires new python

Traceback (most recent call last):
File "../github/badge2023/tools/asset_converter.py", line 124, in
def get_c_file_name(asset: dict[str, str | int]) -> str:

| was added in python 3.10, so not available in python 3.8.

Python 3.10 was released on October 4, 2021.

That's too fucking new.

Solder on back side of rotary encoders is quite sharp

Playing the Tank vs. Tank game, it's quite natural to squeeze the top of the encoder with fingers on the underside of the badge to fire the main gun, and the solder on the back side is quite sharp. We might want to put some tape over it or something.

test-screensavers app seems to mess up the color palette

Specifically, the disp_asset_saver(). The normal screensaver (called from badge.c) doesn't seem to have this problem.

Symptoms: background goes white, or colors are messed up.

To reproduce: Select Settings/Screensaver/TEST, then use the left/right dpad to select different screensavers. Eventually, you'll notice the colors are all wrong, or maybe the screen goes completely white.

To recover, the badge can be rebooted, nothing else seems to completely clear the problem.

The problem only occurs on the actual badge, the simulator does not replicate the problem.

Some linux test code breaks the build for pico

I made the commit below which enables the build to work, but it just comments out the test code that causes the breakage.

c64bce0

See source/core/CMakeLists.txt

I'm not knowledgeable enough with cmake to know how to fix it correctly.

wasm: call `emscripten_set_main_loop`

It seems that the wasm build is missing the call to emscripten_set_main_loop

reference:
https://emscripten.org/docs/api_reference/emscripten.h.html#c.emscripten_set_main_loop
https://emscripten.org/docs/porting/emscripten-runtime-environment.html#emscripten-runtime-environment

a simple example (using SDL): https://github.com/dfirebaugh/spritely/blob/main/src/main.c#L19-L33

I tried to get this working with a change like the following. However, it doesn't seem to work.

--- a/source/hal/init_sdl_sim.c
+++ b/source/hal/init_sdl_sim.c
@@ -95,10 +95,21 @@ static void process_options(int argc, char **argv)
        }
 }

+static int (*main_loop_func)(int, char **) = NULL;
+#ifdef __EMSCRIPTEN__
+#include <emscripten.h>
+void emscripten_main_loop_callback(void *arg) {
+  if (main_loop_func) {
+    main_loop_func(sim_argc, sim_argv);
+  }
+}
+#endif
+
 int hal_run_main(int (*main_func)(int, char**), int argc, char** argv) {

     sim_argc = argc;
     sim_argv = argv;
+               main_loop_func = main_func;

     pthread_t app_thread;
     pthread_create(&app_thread, NULL, main_in_thread, main_func);
@@ -107,6 +118,9 @@ int hal_run_main(int (*main_func)(int, char**), int argc, char** argv) {
     audio_init();
     hal_start_sdl(&argc, &argv);

+#ifdef __EMSCRIPTEN__
+  emscripten_set_main_loop_arg(emscripten_main_loop_callback, NULL, -1, 0);
+#endif
     return 0;
 }

side note emsdk includes a little web server for testing if you are running source emsdk_env.sh -- emrun --port 8080 source/badge2023_c.html

Also, I'm not sure how much we actually care about this.

Reflashing the badge does not clear user data saved in flash

For example, the username and badge monsters persist across re-flashes.

There should probably be a way to clear this out.

Abort encountered

=================================================================
==34881==ERROR: AddressSanitizer: global-buffer-overflow on address 0x5590e28d5750 at pc 0x5590e2823864 bp 0x7f0e912fcb80 sp 0x7f0e912fcb70
READ of size 2 at 0x5590e28d5750 thread T3
    #0 0x5590e2823863 in display_menu /home/scameron/github/badge2023/source/core/menu.c:233
    #1 0x5590e282519d in menus /home/scameron/github/badge2023/source/core/menu.c:423
    #2 0x5590e281ee7f in ProcessIO /home/scameron/github/badge2023/source/core/badge.c:191
    #3 0x5590e275ac9c in badge_main /home/scameron/github/badge2023/source/main.c:79
    #4 0x5590e275c5d1 in main_in_thread /home/scameron/github/badge2023/source/hal/init_sdl_sim.c:55
    #5 0x7f0e97580608 in start_thread /build/glibc-SzIz7B/glibc-2.31/nptl/pthread_create.c:477
    #6 0x7f0e9698d132 in __clone (/lib/x86_64-linux-gnu/libc.so.6+0x11f132)

0x5590e28d5750 is located 16 bytes to the left of global variable 'screen_lock_m' defined in '/home/scameron/github/badge2023/source/core/settings.c:254:21' (0x5590e28d5760) of size 160
0x5590e28d5750 is located 16 bytes to the right of global variable 'main_m' defined in '/home/scameron/github/badge2023/source/core/menu.c:75:28' (0x5590e28d56c0) of size 128
SUMMARY: AddressSanitizer: global-buffer-overflow /home/scameron/github/badge2023/source/core/menu.c:233 in display_menu
Shadow bytes around the buggy address:
  0x0ab29c512a90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
  0x0ab29c512aa0: 00 00 00 00 00 00 00 00 00 00 00 00 f9 f9 f9 f9
  0x0ab29c512ab0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
  0x0ab29c512ac0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
  0x0ab29c512ad0: 00 00 00 00 f9 f9 f9 f9 00 00 00 00 00 00 00 00
=>0x0ab29c512ae0: 00 00 00 00 00 00 00 00 f9 f9[f9]f9 00 00 00 00
  0x0ab29c512af0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
  0x0ab29c512b00: f9 f9 f9 f9 00 00 00 00 00 00 00 00 00 00 00 00
  0x0ab29c512b10: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
  0x0ab29c512b20: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
  0x0ab29c512b30: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
Shadow byte legend (one shadow byte represents 8 application bytes):
  Addressable:           00
  Partially addressable: 01 02 03 04 05 06 07 
  Heap left redzone:       fa
  Freed heap region:       fd
  Stack left redzone:      f1
  Stack mid redzone:       f2
  Stack right redzone:     f3
  Stack after return:      f5
  Stack use after scope:   f8
  Global redzone:          f9
  Global init order:       f6
  Poisoned by user:        f7
  Container overflow:      fc
  Array cookie:            ac
  Intra object redzone:    bb
  ASan internal:           fe
  Left alloca redzone:     ca
  Right alloca redzone:    cb
  Shadow gap:              cc
Thread T3 created by T0 here:
    #0 0x7f0e97851815 in __interceptor_pthread_create ../../../../src/libsanitizer/asan/asan_interceptors.cc:208
    #1 0x5590e275ca77 in hal_run_main /home/scameron/github/badge2023/source/hal/init_sdl_sim.c:104
    #2 0x5590e275ad51 in main /home/scameron/github/badge2023/source/main.c:97
    #3 0x7f0e96892082 in __libc_start_main ../csu/libc-start.c:308

==34881==ABORTING

Pretty sure this is a consequence of the new ITEM_DESC type in struct menu_t I added earlier today.

Consider converting simulator to use SDL2 instead of GTK2

Encountered a Mac user expressing some interest in writing a badge app tonight. Can the GTK2 based simulator run on Mac? Probably, but it would probably be easier with SDL2, and I'm not sure how easy it is to get a GTK2 based app working on Mac. Using SDL2 instead would probably make it easier to get it to run natively on Windows as well, though it apparently runs ok under WSL as is, so maybe native windows isn't really a priority.

I'll probably try to work up a port to SDL2 soon and see how it goes.