Software Overview

This section covers the RADR firmware, including architecture, development setup, and how to modify or contribute to the codebase.

Firmware Overview

RADR runs on an ESP32-S3 microcontroller with custom firmware written in C++ using the Arduino framework and PlatformIO.

Component	Technology
MCU	ESP32-S3 with PSRAM
Framework	Arduino for ESP32
Build System	PlatformIO
Language	C++
Display Library	TFT_eSPI
BLE Stack	NimBLE

Firmware Version

Component	Version
Major Version	1
Minor Version	0
Patch Version	24
Full Version	1.0.24

Check for firmware updates regularly to access new features and device support.

Source Code

The complete firmware source is available on GitHub:

RADR Firmware

Browse the source code and documentation.

Architecture Overview

Main Components

Component	Purpose
State Machine	Manages screen states and navigation flow
Device Manager	Handles Bluetooth device discovery and connection
Display Driver	Renders UI using TFT_eSPI with canvas buffering
Input Handler	Processes encoder, button, and bumper inputs
Feedback System	Controls LEDs, buzzer, and vibration
Device Registry	Maps Bluetooth UUIDs to device types

Key Services

├── BluetoothService    # BLE scanning and connection
├── DisplayService      # Screen rendering
├── InputService        # Encoder and button handling
├── FeedbackService     # LED, buzzer, vibration
├── DeviceService       # Connected device control
├── WiFiService         # WiFi and OTA updates
└── StorageService      # LittleFS configuration

Development Environment

Prerequisites

Visual Studio Code
PlatformIO Extension
USB-C cable for flashing

Getting Started

Clone the repository

git clone https://github.com/researchanddesire/radr-wireless-remote.git
cd radr-wireless-remote/Software

Open in VS Code

Open the Software folder in VS Code. PlatformIO will automatically detect the project configuration.

Build the firmware

Click the PlatformIO Build button or run:

pio run

Flash to device

Connect RADR via USB-C and click Upload, or run:

pio run --target upload

Key Features

Canvas-Based Rendering

RADR uses double-buffered canvas rendering for smooth display updates:

Full-screen sprites prevent flickering
Partial updates for performance-critical areas
Consistent 60fps UI refresh rate

State Machine Architecture

The UI uses a hierarchical state machine:

Clear transitions between screens
Isolated state logic for each screen
Event-driven input handling

Device Registry

RADR supports multiple device types through a two-tier registry:

Registry	Description
Built-in	Hardcoded R+D device support (OSSM)
Dynamic	JSON-based Buttplug.io device definitions

The dynamic registry (registry.json) can be updated via firmware updates to add new device support without code changes.

Configuration Files

File	Purpose
`platformio.ini`	Build configuration and dependencies
`src/config.h`	Hardware pin definitions and constants
`data/registry.json`	Buttplug.io device UUID mappings

Technical Reference

Web Flasher

Flash firmware using the web-based tool.

BLE Communication

Bluetooth protocol details and device communication.

Contributing

Read the contribution guidelines before submitting a change against the main branch.

Code Style

Follow existing code formatting
Use descriptive variable and function names
Document public functions and complex logic
Test changes on actual hardware before submitting

License

RADR firmware is released under the CERN Open Hardware Licence Version 2 - Strongly Reciprocal (CERN-OHL-S v2). See the repository license for details.