Generated on Sunday, October 6, 23:17:08
Introduction
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.
The Swadge GitHub repository can be found at https://github.com/AEFeinstein/Super-2024-Swadge-FW. The corresponding hardware repository for the Super Magfest 2024 Swadge can be found at https://github.com/AEFeinstein/Super-2024-Swadge-HW.
This is living documentation, so if you notice that something is incorrect or incomplete, please fix or complete it, and submit a pull request.
Most discussions happen in the Magfest Slack, in the #circuitboards channel. If you are interested in joining and contributing to this project, email circu.nosp@m.itbo.nosp@m.ards@.nosp@m.magf.nosp@m.est.o.nosp@m.rg.
General Swadge design principles can be found here.
Where to Start
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
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
- hdw-temperature.h: Learn how to use the temperature sensor
Network APIs
- hdw-esp-now.h: Broadcast and receive messages. This is fast and unreliable.
- p2pConnection.h: Connect to another Swadge and exchange messages. This is slower and more reliable.
Persistent Memory APIs
- hdw-nvs.h: Learn how to save and load persistent runtime data
- cnfs.h: Learn how to load and use assets from the CNFS blob! These file types have their own loaders:
- settingsManager.h: Set and get persistent settings for things like screen brightness
Graphics APIs
- hdw-led.h: Learn how to use the LEDs
- hdw-tft.h: Learn how to use the TFT
- palette.h: Learn about available colors
- color_utils.h: Learn about color manipulation
- fill.h: Learn how to fill areas on the screen
- shapes.h: Learn how to draw shapes and curves on the screen
- wsg.h: Learn how to draw sprites on the screen
- font.h: Learn how to draw text on the screen
Graphical UI APIs
- menu.h and menuManiaRenderer.h: Make and render a menu within a mode
- dialogBox.h: Show messages and prompt users for a response
- touchTextEntry.h: Edit an arbitrary single line of text by selecting each letter at a time with up & down keys
- textEntry.h: Edit an arbitrary single line of text with a virtual QWERTY keyboard
- wheel_menu.h: Show a menu wheel which is navigable with a circular touch-pad
Audio APIs
- hdw-dac.h: Learn how to use the DAC (speaker)
- hdw-mic.h: Learn how to use the microphone
- 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
Math APIs
- trigonometry.h: Fast math based on look up tables
- vector2d.h: Basic math for 2D vectors
- geometry.h: Basic math for 2D shapes, like collision checks
- fp_math.h: Fixed point decimal math. This is faster an less precise than using floating point
Other Useful APIs
Espressif Documentation
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