Airfrog

piers.rocks/u/airfrog

Tiny wireless co-processor/programmer/debugger for ARM. Uses $3 WiFi module. Written in Rust.

• Tiny: Coin sized 16×28mm
• Wireless: No cables
• Low Cost: $3 ESP32-C3 module
• Open: Fully open source

Hardware

The size of a postage stamp/quarter. $3 BOM. Hand solderable.

Use Cases and Features

Key Features

Quick Start

To install the default Airfrog firmware:

1. Install the dependencies

2. Connect the Airfrog via USB serial

3. Build and flash the default firmware

   AF_STA_SSID=your-ssid AF_STA_PASSWORD=your-password cargo run --release -p airfrog
   

4. Point a browser to http://airfrog-ip/ (IP from DHCP) to access the web interface

Coming Soon

• OTA upgrades of Airfrog firmware
• Support for more ARM targets
• Memory viewer enhancements
• Run STA and AP modes in parallel
• Support target RTT logging

Technical Summary

Firmware:

• Built from the ground-up in Rust using embassy and esp-hal for speed and reliability
• Web, REST and binary interfaces provided out of the box
• Supports SWD protocol at configurable speeds between 500KHz - 4MHz
• Supports controlling Software Defined Retro ROM
• Default firmware uses IPv4 and DHCP for network configuration and supports captive AP for easy setup
• Build custom firmware using libraries and examples provided
• Integration with probe-rs for programming and debugging tasks
• Fully open source, no closed source dependencies

Hardware:

• ESP32-C3-MINI-1 RISC-V core with integrated WiFi, RAM and flash
• 5-pin 0.1" pitch connector to power Airfrog and connecting to target ARM devices
• Exposes separate UART for Airfrog firmware programming
• Powered by 5V, includes on-board 3.3V regulator
• SWD pins 3.3V
• All passives 0603 for hand soldering
• 2-layer PCB, default single sided assembly
• Fully open-source, no restrictions on commercial use

Documentation

• FAQ - frequently asked questions
• Build Instructions - build and flash the default firmware
• PCB Designs - design or fab your own Airfrog
• Technical Overview - how Airfrog works
• Examples - start here for building custom Airfrog applications
• Software - start here to use Airfrog with existing SWD tools
• REST API - to interact with the default Airfrog firmware via web APIs
• Binary API - Airfrog's highest performance network API
• SWD Protocol - to understand the core SWD protocol
• Changelog
• Licence

Example Use Case - Remote Telemetry

Airfrog is used to add remote telemetry support to the Software Defined Retro ROM (SDRR) which is based on the STM32F4 ARM MCU.

SDRR has no network interface or spare MCU cycles to transmit data, so Airfrog is installed. It reads a counter directly from the MCU's RAM and sends it via MQTT over WiFi to be graphed on a remote system.

Airfrog can also be used to dynamically control SDRR during run-time, and reprogram it over WiFi.

This demonstration was developed in 2-3 hours with

• 200 lines of Rust for the Airfrog firmware
• 90 lines of Python to produce the real-time graph.

If you are interested in precisely what is being shown here:

• Three SDRRs are installed in a Commodore 64, operating as Kernal, BASIC and Character ROMs repspectively.
• SDRR increments a counter in its RAM every time that ROM's chip select line(s) are asserted.
• Airfrog reads that counter directly from the MCU RAM every second. It subtracts it from the previous value (to get a 1Hz sample rate) and sends it to an MQTT broker.
• The Python script subscribes to the appropriate MQTT topics and plots the data in real-time using matplotlib.

Contributing

Contributions are welcome!

• Report an issue
• Submit a PR

Licence

• Software: MIT Licensed
• Hardware: CC-BY-SA-4.0