Welcome to the Swadge 2024 API documentation! Here you will find information on how to use all hardware features of a Swadge and write a Swadge mode. A Swadge is Magfest's electronic swag-badges. They play games and make music and shine bright and do all sorts of cool things.
If you just want to run the Swadge emulator without setting up a development environment, see the Emulator User Manual for an installation guide and usage instructions.
If you want to learn about creating MIDI song files for the Swadge, see the MIDI Specifications guide. See also the Emulator User Manual which you can use to listen to MIDI files.
If you're just starting Swadge development, you're already at the right place to start! Here's a good sequence of pages to read from here.
First, follow the guide to Configuring a Development Environment. This will walk you through setting up the toolchain and compiling the firmware and emulator.
Next, read about the basics of a Swadge Mode at swadge2024.h.
Once you understand the basics of a Swadge Mode, check out the Swadge Mode Example to see a simple mode in action.
After you grasp the example, you can go deeper and read the full API Reference to understand the full capability of the Swadge firmware.
If you have any crashes on real hardware, read and use Serial Debug Output to help debug the issue.
When you're ready to make a contribution, read the Contribution Guide first to see how to do it in the most productive way.
If you want to bring a mode forward from last year's Swadge, take a look at Porting 2023 Swadge Modes.
Finally, if you want to do lower level or component programming, read the Espressif Documentation to understand the full capability of the ESP32-S2 chip.
Swadge Mode Example
The Pong mode is written to be a relatively simple example of a Swadge mode. It is well commented, demonstrates a handful of features, and uses good design patterns. Look out for things like:
How the pong_t struct contains all variables the mode needs, is allocated when the mode is entered, and is freed when the mode exits
How immutable strings are declared static const
How a menu is initialized in pongEnterMode(), updated and drawn in pongMainLoop(), and deinitialized in pongExitMode()
How fonts, WSG, and MIDI assets are loaded in pongEnterMode() and freed in pongExitMode()
How fonts and WSGs are drawn in pongDrawField()
How background music is used in pongResetGame() and sound effects are used in pongUpdatePhysics()
How a background is drawn in pongBackgroundDrawCallback()
How LEDs are lit in pongDrawField()
How the main loop runs depending on the screen currently being displayed in pongMainLoop() and pongGameLoop()
How an accumulating timer pattern is used in pongFadeLeds()
How user input is handled in pongControlPlayerPaddle()
How the game state is updated in pongUpdatePhysics()
API Reference
What follows are all the APIs available to write Swadge modes. If something does not exist, and it would be beneficial to multiple Swadge modes, please contribute both the firmware and API documentation. It's a team effort
Swadge Mode APIs
swadge2024.h: Write a mode. This is a good starting place
Input APIs
hdw-battmon.h: Learn how to check the battery voltage
hdw-btn.h: Learn how to use both push and touch button input
touchUtils.h: Utilities to interpret touch button input as a virtual joystick, spin wheel, or cartesian plane
hdw-imu.h: Learn how to use the inertial measurement unit
soundFuncs.h: Helper functions to use either the buzzers or DAC speaker, depending on build configuration. These macros should be used instead of calling buzzer or DAC functions directly!
swSynth.h: Learn how to generate oscillating output for the DAC speaker
midiPlayer.h: Learn how to play MIDI files on the DAC speaker
The Swadge uses an ESP32-S2 micro-controller with firmware built on IDF 5.0. The goal of this project is to enable developers to write modes and games for the Swadge without going too deep into Espressif's API. However, if you're doing system development or writing a mode that requires a specific hardware peripheral, this Espressif documentation is useful:
1.10.0