> ## Documentation Index
> Fetch the complete documentation index at: https://docs.researchanddesire.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Software Overview

> Firmware architecture and development guide for the RADR wireless remote

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  |

<Info>
  Check for firmware updates regularly to access new features and device support.
</Info>

## Source Code

The complete firmware source is available on GitHub:

<Card title="RADR Firmware" icon="code" href="https://github.com/researchanddesire/radr-wireless-remote/tree/main/Software">
  Browse the source code and documentation.
</Card>

## 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](https://code.visualstudio.com/)
* [PlatformIO Extension](https://platformio.org/install/ide?install=vscode)
* USB-C cable for flashing

### Getting Started

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/researchanddesire/radr-wireless-remote.git
    cd radr-wireless-remote/Software
    ```
  </Step>

  <Step title="Open in VS Code">
    Open the `Software` folder in VS Code. PlatformIO will automatically detect the project configuration.
  </Step>

  <Step title="Build the firmware">
    Click the PlatformIO Build button or run:

    ```bash theme={null}
    pio run
    ```
  </Step>

  <Step title="Flash to device">
    Connect RADR via USB-C and click Upload, or run:

    ```bash theme={null}
    pio run --target upload
    ```
  </Step>
</Steps>

## 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

<CardGroup cols={2}>
  <Card title="Web Flasher" icon="bolt" href="/radr/tools/web-flasher">
    Flash firmware using the web-based tool.
  </Card>

  <Card title="BLE Communication" icon="bluetooth" href="/radr/Software/communication/ble">
    Bluetooth protocol details and device communication.
  </Card>
</CardGroup>

## Contributing

We welcome contributions to the RADR firmware. Before contributing:

1. Read the [contribution guidelines](https://github.com/researchanddesire/radr-wireless-remote/blob/main/CONTRIBUTING.md)
2. Join the Kinky Makers Discord to discuss changes
3. Submit pull requests against the `main` branch

<DiscordInvite community="kinky-makers" />

### 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 [licence documentation](/radr/guides/housekeeping/open-source/licence) for details.