Skip to content
Back to search

RubberOrca

Single-chip ESP32-S3 firmware that exposes a wired USB HID keyboard, mouse, and consumer control interface to a target host while accepting wireless commands over BLE 5.0 GATT.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/atacanymc--rubberorca/badge.svg)](/listings/atacanymc--rubberorca)

HTML

<a href="/listings/atacanymc--rubberorca"><img src="/api/listings/atacanymc--rubberorca/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires [PlatformIO Core](https://platformio.org/install/cli) (`pio`).

# 1. Run host-side protocol and command unit tests
pio test -e native

# 2. Build firmware for ESP32-S3 Super Mini or N16R8
pio run -e esp32s3_supermini
pio run -e esp32s3_n16r8

# 3. Flash the connected board
pio run -e esp32s3_supermini -t upload

Plug the board's native USB-C OTG port into the target computer. Connect from any RubberOtter client over BLE Service `0000ffe0-0000-1000-8000-00805f9b34fb` and Characteristic `0000ffe1-0000-1000-8000-00805f9b34fb`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 170 lines
  1. <div align="center">
  2. <img src="assets/logo.png" alt="RubberOrca Logo" width="180" />
  3. </div>
  4. # RubberOrca
  5. [![CI](https://github.com/AtaCanYmc/RubberOrca/actions/workflows/ci.yml/badge.svg)](https://github.com/AtaCanYmc/RubberOrca/actions/workflows/ci.yml)
  6. [![Release](https://img.shields.io/github/v/release/AtaCanYmc/RubberOrca?include_prereleases&sort=semver)](https://github.com/AtaCanYmc/RubberOrca/releases)
  7. [![PyPI](https://img.shields.io/pypi/v/rubberorca.svg)](https://pypi.org/project/rubberorca/)
  8. [![Homebrew](https://img.shields.io/badge/Homebrew-AtaCanYmc%2Ftap%2Frubberorca-FBB040.svg)](https://github.com/AtaCanYmc/homebrew-tap)
  9. [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
  10. [![MCU](https://img.shields.io/badge/MCU-ESP32--S3-E7352C.svg)](docs/hardware.md)
  11. [![PlatformIO](https://img.shields.io/badge/PlatformIO-55.03.311-FF7F00.svg)](platformio.ini)
  12. [![Transport](https://img.shields.io/badge/Transport-BLE_5.0_%2B_USB_HID-0082FC.svg)](docs/protocol.md)
  13. Single-chip ESP32-S3 firmware that exposes a wired USB HID keyboard, mouse, and consumer control interface to a target host while accepting wireless commands over BLE 5.0 GATT.
  14. ## Table of Contents
  15. - [Architecture](#architecture)
  16. - [Quick Start](#quick-start)
  17. - [Supported Hardware](#supported-hardware)
  18. - [Protocol and Commands](#protocol-and-commands)
  19. - [Repository Structure](#repository-structure)
  20. - [Technical FAQ](#technical-faq)
  21. - [Contributing and Security](#contributing-and-security)
  22. - [License](#license)
  23. ## Architecture
  24. RubberOrca replaces the dual-chip `ATmega32U4` and `HM-10` UART bridge from [RubberOtter](https://github.com/AtaCanYmc/RubberOtter) with a single ESP32-S3 SoC. The target host enumerates a standard wired USB composite device without host-side Bluetooth pairing. Existing clients — including the unified **[RubberDeck Control PWA](https://atacanymc.github.io/RubberDeck/)** ([source](https://github.com/AtaCanYmc/RubberDeck)), Capacitor mobile apps, Python SDK, CLI, and MCP server — connect over BLE GATT `0xFFE0` / `0xFFE1` and USB CDC Serial without modification.
  25. ```mermaid
  26. flowchart LR
  27. CLIENTS["RubberOtter Clients\nWeb PWA / Mobile / Python"] <-->|"BLE 5.0 GATT\n0xFFE0 / 0xFFE1"| BLE["BleTransport\nNimBLE Server"]
  28. CLIENTS <-->|"USB CDC Serial"| CDC["USB CDC"]
  29. BLE --> PARSER["PacketParser\nSTX/ETX + XOR"]
  30. CDC --> PARSER
  31. PARSER --> EXEC["CommandExecutor\nChaining + Jiggler"]
  32. EXEC <--> NVS["ESP32 NVS\nMacros m0..m15 + Name"]
  33. EXEC --> HID["TinyUSB HID\nKeyboard + Mouse + Consumer"]
  34. HID -->|"USB-C OTG"| HOST["Target Host PC"]
  35. ```
  36. ## Quick Start
  37. Requires [PlatformIO Core](https://platformio.org/install/cli) (`pio`).
  38. ```bash
  39. # 1. Run host-side protocol and command unit tests
  40. pio test -e native
  41. # 2. Build firmware for ESP32-S3 Super Mini or N16R8
  42. pio run -e esp32s3_supermini
  43. pio run -e esp32s3_n16r8
  44. # 3. Flash the connected board
  45. pio run -e esp32s3_supermini -t upload
  46. ```
  47. Plug the board's native USB-C OTG port into the target computer. Connect from any RubberOtter client over BLE Service `0000ffe0-0000-1000-8000-00805f9b34fb` and Characteristic `0000ffe1-0000-1000-8000-00805f9b34fb`.
  48. ## Supported Hardware
  49. | PlatformIO Env | Board Definition | Hardware Target | Flash / PSRAM | Partition Table |
  50. | :--- | :--- | :--- | :--- | :--- |
  51. | `esp32s3_supermini` | `lolin_s3_mini` | ESP32-S3 Super Mini | 4 MB / 2 MB QSPI | `huge_app.csv` |
  52. | `esp32s3_n16r8` | `esp32-s3-devkitc1-n16r8` | ESP32-S3 N16R8 DevKitC | 16 MB / 8 MB OPI | `default_16MB.csv` |
  53. | `native` | Host toolchain | Local unit test runner | N/A | N/A |
  54. Both ESP32-S3 environments build with `-DARDUINO_USB_MODE=0` and `-DARDUINO_USB_CDC_ON_BOOT=1` so TinyUSB HID and USB CDC Serial share the native USB OTG peripheral. On the ESP32-S3 N16R8 DevKitC, connect the **`USB` (OTG)** port to the target host rather than the `UART` bridge port.
  55. ## Protocol and Commands
  56. Framed packets use the RubberOtter v1 wire format:
  57. ```text
  58. [STX: 0x02] [VER: 0x01] [SEQ: 1B] [LEN_HI: 1B] [LEN_LO: 1B] [PAYLOAD: N B] [XOR: 1B] [ETX: 0x03]
  59. ```
  60. The device replies with a 6-byte ACK frame `[0x02, 0x01, SEQ, OK, CODE, 0x03]` over BLE notify and USB CDC. Error codes are `1` for invalid version or command, `2` for payload exceeding 1024 bytes, and `3` for XOR checksum mismatch. Single-byte fallback commands (`0x11` to `0x85`) execute directly when the parser is idle.
  61. | Command | Arguments | Behavior |
  62. | :--- | :--- | :--- |
  63. | `type` | `"text"` | Types ASCII text over USB HID. Supports `\n`, `\t`, `\"`, and `\\` escapes. |
  64. | `delay` | `<ms>` | Pauses execution for `<ms>` milliseconds. |
  65. | `enter`, `tab`, `backspace` | None | Sends the corresponding single HID keystroke. |
  66. | `press` | `<mod> [ms]` | Presses `shift`, `ctrl`, `alt`, `gui`, `win`, `right`, `left`, `f5`, `gui l`, `gui d`, or `ctrl shift esc`. |
  67. | `hold` / `release` | `<mod>` | Holds or releases `shift`, `ctrl`, `alt`, `gui`, or `win`. |
  68. | `media` | `<action>` | Sends Consumer Control usage: `play_pause`, `volume_up`, `volume_down`, `next`, `prev`, or `mute`. |
  69. | `mouse move` | `<dx> <dy>` | Moves the relative USB HID pointer by signed 8-bit deltas. |
  70. | `mouse click` | `left\|right\|middle` | Clicks the specified mouse button. |
  71. | `mouse scroll` | `<amount>` | Scrolls the vertical wheel by a signed 8-bit delta. |
  72. | `jiggler` | `on\|off\|toggle` | Toggles a 20 px square return-to-origin mouse pulse every 5000 ms. |
  73. | `macro define` | `m0..m15 { body }` | Persists a command chain in ESP32 NVS under namespace `orca`. |
  74. | `macro run` | `m0..m15` | Executes a stored NVS macro with recursion depth capped at 2. |
  75. | `ble name` | `"name"` | Updates BLE advertising name and persists it in NVS across reboots. |
  76. | `ble passkey` | `<6-digit\|off>` | Configures optional static BLE bonding passkey (`100000`..`999999`) or `off` in NVS. |
  77. | `layout` | `us\|tr_q` | Switches USB HID keyboard layout (US or UTF-8 Turkish Q) and persists it in NVS. |
  78. | `vibrate` | `<ms>` | Pulses `VIB_PIN` if defined at compile time. No-op otherwise. |
  79. | `help`, `?` | None | Prints the command list to BLE and USB CDC. |
  80. Commands can be chained with `&&` or `;`. Separators inside quoted strings and `{ ... }` macro definitions are preserved.
  81. ## Repository Structure
  82. ```text
  83. RubberOrca/
  84. ├── assets/
  85. │ └── logo.png # Square project emblem
  86. ├── python/
  87. │ ├── README.md # Python SDK, CLI, and MCP server usage
  88. │ ├── pyproject.toml # rubberorca package (SDK + CLI + rubberorca-mcp)
  89. │ ├── rubberorca/ # Protocol, transports, SDK, CLI, and stdio MCP server
  90. │ └── tests/ # Python unittest suite (SDK + CLI + MCP)
  91. ├── site/
  92. │ ├── index.html # Browser Web Serial flasher (ESP Web Tools) and simulator
  93. │ ├── styles.css # Industrial Hardware Lab theme
  94. │ ├── app.js # Dual-board selector, PCB inspector, live simulator
  95. │ └── manifest-*.json # ESP Web Tools manifests (Super Mini and N16R8)
  96. ├── docs/
  97. │ ├── README.md # Documentation index
  98. │ ├── adr/ # Architecture Decision Records (ADR-0001..ADR-0004)
  99. │ ├── architecture.md # Dual-core BLE/HID flow and NVS layout
  100. │ ├── cli-and-mcp.md # Python CLI flags and stdio MCP server reference
  101. │ ├── examples.md # Python BLE/Serial, Web Bluetooth, and macro examples
  102. │ ├── hardware.md # Board specs, USB OTG port, and flashing guide
  103. │ └── protocol.md # Wire framing, ACK codes, fallbacks, and bounds
  104. ├── include/
  105. │ ├── Backend.h # Hardware-agnostic HID, transport, and NVS callbacks
  106. │ └── Protocol.h # Framing constants, buffer sizes, and BLE UUIDs
  107. ├── src/
  108. │ ├── BleTransport.h/.cpp # Thread-safe NimBLE GATT server (0xFFE0 / 0xFFE1 + passkey)
  109. │ ├── CommandExecutor.h/.cpp # Command parser, chaining, jiggler, and macro dispatch
  110. │ ├── Esp32Backend.cpp # TinyUSB HID, RGB status LED, USB CDC, and NVS backend
  111. │ ├── KeyLayout.h/.cpp # UTF-8 decoder and Turkish Q raw HID layout mapper
  112. │ ├── PacketParser.h/.cpp # Ring-buffered STX/ETX XOR frame and 1-byte parser
  113. │ ├── Utils.h/.cpp # String utilities and ACK frame serializer
  114. │ └── main.cpp # Arduino setup() and loop() entry point
  115. ├── test/
  116. │ └── test_protocol/
  117. │ └── test_protocol.cpp # Unity host unit tests for framing and commands
  118. ├── Makefile # Build, test, flash, package, and lint targets
  119. ├── platformio.ini # Super Mini, N16R8, and native test environments
  120. ├── release-please-config.json # Automated semantic versioning configuration
  121. ├── version.txt # Current firmware release version
  122. ├── CONTRIBUTING.md
  123. ├── ROADMAP.md
  124. ├── SECURITY.md
  125. └── LICENSE
  126. ```
  127. ## Technical FAQ
  128. **Why use BLE GATT `0xFFE0` / `0xFFE1` instead of native BLE HID?**
  129. Native BLE HID requires Bluetooth pairing on the target computer. Using BLE GATT for wireless control while keeping the host link strictly wired USB HID eliminates host-side Bluetooth pairing and maintains drop-in compatibility with existing RubberOtter clients.
  130. **Why store macros in NVS (`Preferences`) instead of LittleFS in v1?**
  131. ESP32 NVS is wear-leveled, power-loss safe, and requires no filesystem image upload. Sixteen 1024-byte slots cover typical macro workloads with minimal flash overhead. LittleFS storage is planned for larger script files and an on-device Web UI in [ROADMAP.md](ROADMAP.md).
  132. ## Contributing and Security
  133. - Browse full technical references in [docs/README.md](docs/README.md) ([architecture](docs/architecture.md), [hardware](docs/hardware.md), [protocol](docs/protocol.md), [cli-and-mcp](docs/cli-and-mcp.md), [examples](docs/examples.md), [ADRs](docs/adr/README.md)).
  134. - Read [CONTRIBUTING.md](CONTRIBUTING.md) for branch conventions, Conventional Commits, and local verification steps.
  135. - Report security vulnerabilities privately using [SECURITY.md](SECURITY.md).
  136. - Track upcoming milestones in [ROADMAP.md](ROADMAP.md).
  137. ## License
  138. Licensed under the Apache License 2.0. See [LICENSE](LICENSE) for full terms.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.