Generated on Thursday, June 11, 12:45:53
Introduction
Welcome to the Swadge 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. This single repository hosts firmware for multiple years. See the releases for different year's final firmware. The corresponding hardware repositories for the Super Magfest Swadges can be found at:
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 #super-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 in the Swadge Design Principles.
Where to Start
If you're just starting Swadge development, you're already at the right place to start! Here's a quick recommended order to exploring the repository:
- First, follow the guide to Configuring a Development Environment. This will walk you through setting up the toolchain and compiling the firmware and emulator.
- Note
- 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.
- Next, read about the basics of a Swadge Mode at swadge.h.
- Once you understand the basics of a Swadge Mode, check out the Swadge Mode Example to see a simple mode in action.
- Note
- If you're new to developing code and want a guided experience, try the How to Make a Swadge Mode tutorial! It will walk you through creating a whole game with explanations on why certain options are picked.
- 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.
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.
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-btn.h: Learn how to use push button input
- hdw-touch.h: Learn how to use touch pad input
- touchUtils.h: Utilities to interpret touch button input as a virtual joystick, spin wheel, or cartesian plane
- wheel_menu.h: Show a menu wheel which is navigable with a circular touch pad
- Text Entry
- 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
- hdw-imu.h: Learn how to use the inertial measurement unit (motion controls)
- hdw-battmon.h: Learn how to check the battery voltage
- hdw-temperature.h: Learn how to use the temperature sensor
LED APIs
Graphics APIs
- 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
- wsgCanvas.h: Tools for mixing WSGs into one file to save on memory space
- wsgPalette.h: A layer on top of WSGs to allow the colors to be changed without new WSGs
- font.h: Learn how to draw text on the screen
Audio APIs
Persistent Memory APIs
Network APIs
- hdw-esp-now.h: Broadcast and receive messages. This is fast and unreliable, like UDP.
- p2pConnection.h: Connect to another Swadge and exchange messages. This is slower and more reliable, like TCP.
- swadgePass.h: Send and receive small amounts of data like avatars or high scores while the Swadge is idle.
USB APIs
Game Element APIs
- cutscene.h Renders and makes sound effects for character dialogue. Generic enough to use for any game with any yearly theme.
- dialogBox.h: Show messages and prompt users for a response
- helpPages.h: Show multiple pages of multi-line text
- highScores.h: System to simplify keeping a high score table with SwadgePass support
- nameList.h: A method of generating nice strings for swadgepass data that are small.
- swadgesona.h: Data structures for using Swadgesonas, user created avatars.
- trophy.h: Add trophies to the swadge mode.
Menu UI APIs
- menu.h: A tree-like data structure to represent multi-level menus with static and dynamic entries
- menu_utils.h: Utilities for working with a menu data structure
- Renderers
Data Structures
Math APIs
- fp_math.h: Fixed point decimal math. This is faster an less precise than using floating point
- geometry.h: Basic math for 2D shapes, like collision checks
- quaternions.h: Quaternions useful for 3D calculations
- trigonometry.h: Fast math based on look up tables
- vector2d.h: Basic math for 2D vectors
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.17.0