slopping up a platformio library for people to make rover peripherals

docs/rover-peripherals.md

@@ -77,9 +77,12 @@ Custom functions can do anything the ESP32 program can do, including:
 - Send text to a display.
 - Operate hardware through an ESP32-specific library.
 - Change several outputs as one operation.
-- Update state used by non-blocking work in `loop()`.
+- Update state used by non-blocking work in `updateRoverPeripheral()`.
 
-Application authors use string IDs such as `specialAction` or `animationSpeed`. They do not assign numeric action IDs. Firmata necessarily uses a numeric SysEx feature byte internally, but that is an implementation detail hidden by the peripheral library.
+The visible control name is also its string wire identifier, so authors provide
+one meaningful name instead of maintaining a second hidden ID. They do not
+assign numeric action IDs. Firmata necessarily uses a numeric SysEx feature byte
+internally, but that is an implementation detail hidden by the package.
 
 ## Firmata user feature
 
@@ -126,13 +129,13 @@ The receiver combines each pair:
 source byte = encoded byte 1 | (encoded byte 2 << 7)
 ```
 
-Peripheral authors never perform this encoding themselves. It belongs in the ESP32 `RoverPeripheralFirmata` library and the Go Firmata client used by `roverd`.
+Peripheral authors never perform this encoding themselves. It belongs inside the ESP32 `RoverPeripheral` package and the Go Firmata client used by `roverd`.
 
 ConfigurableFirmata's ESP32 parser accepts 252 bytes inside one incoming SysEx frame, including the feature and operation bytes. `CONTROL` values are not chunked in this deliberately simple design. The Go client checks the fully encoded message before writing it and returns an error if a particular control value cannot fit, rather than sending a frame the ESP32 would discard. Normal numeric, boolean, and short text controls fit comfortably; a text control's configured length should reflect this transport constraint.
 
 ## Peripheral description
 
-The ESP32 library builds this description from the controls registered during `setup()`. The order of the `controls` array is the registration order and is also the UI order.
+The ESP32 library builds this description from the controls registered in `configureRoverPeripheral()`. The order of the `controls` array is the registration order and is also the UI order.
 
 An example description is:
 
@@ -141,7 +144,7 @@ An example description is:
   "name": "Example peripheral",
   "controls": [
     {
-      "id": "servoPosition",
+      "id": "Servo position",
       "type": "slider",
       "name": "Servo position",
       "min": 0,
@@ -152,20 +155,20 @@ An example description is:
       }
     },
     {
-      "id": "lightBrightness",
+      "id": "Light brightness",
       "type": "slider",
       "name": "Light brightness",
       "min": 0,
       "max": 255,
       "output": {
         "type": "pwm",
-        "pin": 18
+        "pin": 17
       }
     },
     {
-      "id": "specialAction",
+      "id": "Special action",
       "type": "button",
-      "name": "Run special action",
+      "name": "Special action",
       "mode": "momentary",
       "output": {
         "type": "custom"
@@ -488,227 +491,44 @@ The Firmata toggle backend converts the logical value using `activeLow` before s
 
 ## ESP32 authoring API
 
-Peripheral authors should not write JSON, construct SysEx messages, or manually dispatch control IDs. The proposed `RoverPeripheralFirmata` Arduino library owns those tasks.
+Peripheral programs include `RoverPeripheral.h` and define
+`configureRoverPeripheral()`. The library provides serial setup, Firmata setup,
+`setup()`, and `loop()`.
 
-A long positional call such as `addRoverCameraServo(14, -15, 30, 0, 2, 900, 2100, false, false)` is deliberately not part of the API. Several adjacent numbers and booleans are too difficult to understand or review without repeatedly consulting the function signature.
+Configurations use structs. Programs assign one named field per line and then
+register the completed configuration. This avoids positional lists for settings
+such as angles, pulse widths, polarity, and ranges.
 
-The public API uses named configuration structs. Field names include units where a bare number would otherwise be ambiguous, and enums replace booleans whose meaning would be unclear at the call site.
+### Complete firmware
 
-### Proposed configuration types
+This program defines the standard camera tilt, headlight, and laser roles. It
-
+also defines slider, button, number, and text accessory controls.
-The core public types are:
 
 ```cpp
-enum class OutputPolarity {
+#include <RoverPeripheral.h>
-  ActiveHigh,
-  ActiveLow
-};
 
-enum class ButtonMode {
+namespace {
-  Toggle,
+constexpr uint8_t specialActionPin = 21;
-  Momentary
-};
 
-struct FirmataServoOutput {
+int repeatCount = 1;
-  uint8_t pin;
+String displayMessage;
-};
 
-struct FirmataPwmOutput {
+void runSpecialAction(bool pressed) {
-  uint8_t pin;
+  digitalWrite(specialActionPin, pressed ? HIGH : LOW);
-};
-
-struct FirmataDigitalOutput {
-  uint8_t pin;
-  OutputPolarity polarity = OutputPolarity::ActiveHigh;
-};
-
-struct RoverCameraServoConfig {
-  uint8_t pin;
-
-  float minimumAngleDegrees;
-  float maximumAngleDegrees;
-  float homeAngleDegrees = 0;
-  float nudgeDegrees = 2;
-
-  uint16_t minimumPulseMicroseconds = 900;
-  uint16_t maximumPulseMicroseconds = 2100;
-
-  bool allowRawPulse = false;
-  bool inverted = false;
-};
-
-struct RoverDigitalOutputConfig {
-  uint8_t pin;
-  OutputPolarity polarity = OutputPolarity::ActiveHigh;
-  bool initiallyOn = false;
-};
-
-struct SliderControlConfig {
-  String id;
-  String name;
-  int minimum;
-  int maximum;
-};
-
-struct ButtonControlConfig {
-  String id;
-  String name;
-  ButtonMode mode;
-};
-
-struct NumberControlConfig {
-  String id;
-  String name;
-  int minimum;
-  int maximum;
-};
-
-struct TextControlConfig {
-  String id;
-  String name;
-  size_t maximumLength;
-};
-```
-
-Defaults cover values that are commonly shared, but required hardware and display values remain explicit. The implementation must validate the completed struct when it is registered rather than assuming that every default-constructed object is usable.
-
-The API uses ordinary field assignments instead of C++ designated initializers. This keeps example sketches compatible with ESP32 Arduino toolchains that are not configured for C++20.
-
-### Generic-control registration
-
-A complete sketch for one servo slider, one light-brightness slider, and one custom momentary button is:
-
-```cpp
-#include <Arduino.h>
-#include <ConfigurableFirmata.h>
-#include <FirmataExt.h>
-#include <RoverPeripheralFirmata.h>
-
-/*
- * Controls are advertised in the order they are added to this object. The
- * browser preserves that order when it renders the peripheral's column.
- */
-RoverPeripheralFirmata peripheral("Example peripheral");
-FirmataExt firmataExtension;
-
-/*
- * This is ordinary application code rather than Firmata plumbing. A real
- * peripheral can replace it with any device-specific sequence or library call.
- */
-void runSpecialAction() {
-  // Start or schedule the peripheral's custom behavior here.
 }
 
-void setup() {
+void setRepeatCount(int value) {
-  Serial.begin(115200);
+  repeatCount = value;
-  Firmata.begin(Serial);
-
-  /*
-   * roverd handles this control with standard Firmata SERVO commands. The
-   * ESP32 application does not need a callback for each slider update.
-   */
-  SliderControlConfig servoPosition;
-  servoPosition.id = "servoPosition";
-  servoPosition.name = "Servo position";
-  servoPosition.minimum = 0;
-  servoPosition.maximum = 180;
-
-  FirmataServoOutput servoOutput;
-  servoOutput.pin = 14;
-
-  peripheral.addServoSlider(servoPosition, servoOutput);
-
-  /*
-   * roverd handles this control with standard Firmata PWM commands. The range
-   * is included in the generated description and displayed by the web UI.
-   */
-  SliderControlConfig lightBrightness;
-  lightBrightness.id = "lightBrightness";
-  lightBrightness.name = "Light brightness";
-  lightBrightness.minimum = 0;
-  lightBrightness.maximum = 255;
-
-  FirmataPwmOutput lightOutput;
-  lightOutput.pin = 18;
-
-  peripheral.addPwmSlider(lightBrightness, lightOutput);
-
-  /*
-   * Custom controls are delivered through the rover-peripheral Firmata feature.
-   * The library finds this registration by control ID and invokes the callback
-   * with true on press and false on release.
-   */
-  ButtonControlConfig specialAction;
-  specialAction.id = "specialAction";
-  specialAction.name = "Run special action";
-  specialAction.mode = ButtonMode::Momentary;
-
-  peripheral.addButton(
-    specialAction,
-    [](bool pressed) {
-      if (pressed) {
-        runSpecialAction();
-      }
-    }
-  );
-
-  // Register the extension with Firmata and finalize the control description.
-  peripheral.begin(firmataExtension);
 }
 
-void loop() {
+void setDisplayMessage(const String& value) {
-  // Standard Firmata messages and rover-peripheral SysEx messages share this parser.
+  displayMessage = value;
-  while (Firmata.available()) {
-    Firmata.processInput();
-  }
-
-  // Let the peripheral library perform any deferred send or callback work.
-  peripheral.update();
 }
-```
+}  // namespace
 
-The intended generic registration methods are:
+void configureRoverPeripheral(RoverPeripheral& peripheral) {
+  peripheral.name("Example rover peripheral");
 
-```cpp
-addServoSlider(const SliderControlConfig&, const FirmataServoOutput&)
-addPwmSlider(const SliderControlConfig&, const FirmataPwmOutput&)
-addDigitalButton(const ButtonControlConfig&, const FirmataDigitalOutput&)
-
-addSlider(const SliderControlConfig&, SliderCallback)
-addButton(const ButtonControlConfig&, ButtonCallback)
-addNumber(const NumberControlConfig&, NumberCallback)
-addText(const TextControlConfig&, TextCallback)
-```
-
-These helpers still produce only the four agreed UI types. The overload or method name distinguishes a standard Firmata output from a custom callback; it does not create an additional UI type.
-
-The standardized built-in replacements use separate methods because they do not create generic UI controls:
-
-```cpp
-addRoverCameraServo(const RoverCameraServoConfig&)
-addRoverHeadlight(const RoverDigitalOutputConfig&)
-addRoverLaser(const RoverDigitalOutputConfig&)
-```
-
-A rover GPIO peripheral can combine built-in replacements and additional controls:
-
-```cpp
-#include <Arduino.h>
-#include <ConfigurableFirmata.h>
-#include <FirmataExt.h>
-#include <RoverPeripheralFirmata.h>
-
-RoverPeripheralFirmata peripheral("Rover GPIO");
-FirmataExt firmataExtension;
-
-void setup() {
-  Serial.begin(115200);
-  Firmata.begin(Serial);
-
-  /*
-   * These declarations satisfy existing rover roles. They retain the normal
-   * camera, headlight, and laser UI instead of entering the generic column.
-   */
   RoverCameraServoConfig cameraServo;
   cameraServo.pin = 14;
   cameraServo.minimumAngleDegrees = -15;
@@ -719,116 +539,264 @@ void setup() {
   cameraServo.maximumPulseMicroseconds = 2100;
   cameraServo.allowRawPulse = false;
   cameraServo.inverted = false;
-
+  peripheral.addCameraServo(cameraServo);
-  peripheral.addRoverCameraServo(cameraServo);
 
   RoverDigitalOutputConfig headlight;
   headlight.pin = 18;
   headlight.polarity = OutputPolarity::ActiveHigh;
   headlight.initiallyOn = false;
-
+  peripheral.addHeadlight(headlight);
-  peripheral.addRoverHeadlight(headlight);
 
   RoverDigitalOutputConfig laser;
-  // GPIO 19 and 20 are reserved for USB on native-USB ESP32-S3 boards.
   laser.pin = 16;
   laser.polarity = OutputPolarity::ActiveHigh;
   laser.initiallyOn = false;
+  peripheral.addLaser(laser);
 
-  peripheral.addRoverLaser(laser);
+  pinMode(specialActionPin, OUTPUT);
+  digitalWrite(specialActionPin, LOW);
 
-  /*
+  SliderControlConfig brightness;
-   * This is an additional feature, so it appears below the peripheral heading
+  brightness.name = "Light brightness";
-   * in the ordered generic-control column.
+  brightness.minimum = 0;
-   */
+  brightness.maximum = 255;
-  SliderControlConfig underglowBrightness;
-  underglowBrightness.id = "underglowBrightness";
-  underglowBrightness.name = "Underglow brightness";
-  underglowBrightness.minimum = 0;
-  underglowBrightness.maximum = 255;
 
-  peripheral.addSlider(
+  PwmOutput brightnessOutput;
-    underglowBrightness,
+  brightnessOutput.pin = 17;
-    [](int brightness) {
-      setUnderglowBrightness(brightness);
-    }
-  );
 
-  peripheral.begin(firmataExtension);
+  peripheral.addSlider(brightness, brightnessOutput);
-}
 
-void loop() {
+  ButtonControlConfig action;
-  while (Firmata.available()) {
+  action.name = "Special action";
-    Firmata.processInput();
+  action.mode = ButtonMode::Momentary;
-  }
+
-  peripheral.update();
+  peripheral.addButton(action, runSpecialAction);
+
+  NumberControlConfig repeats;
+  repeats.name = "Repeat count";
+  repeats.minimum = 1;
+  repeats.maximum = 20;
+
+  peripheral.addNumber(repeats, setRepeatCount);
+
+  TextControlConfig message;
+  message.name = "Display message";
+  message.maximumLength = 64;
+
+  peripheral.addText(message, setDisplayMessage);
 }
 ```
 
-## PlatformIO firmware layout
+Controls appear in registration order. Each accessory control name must be
+non-empty and unique within its peripheral. The name is also its wire
+identifier.
 
-PlatformIO is the only supported firmware workflow. The repository contains one shared library and one complete rover GPIO peripheral project:
+### Built-in rover roles
+
+The standard roles use these configuration types:
+
+```cpp
+RoverCameraServoConfig
+RoverDigitalOutputConfig
+```
+
+They are registered with:
+
+```cpp
+peripheral.addCameraServo(cameraServo);
+peripheral.addHeadlight(headlight);
+peripheral.addLaser(laser);
+```
+
+Camera servo programs set the pin, logical angle range, home angle, nudge size,
+pulse range, raw-pulse policy, and inversion in
+`RoverCameraServoConfig`. Headlight and laser programs set the pin, polarity,
+and initial state in `RoverDigitalOutputConfig`.
+
+These roles keep the existing camera tilt, headlight, and laser HUD controls.
+They do not add entries to the accessory list.
+
+### Standard accessory outputs
+
+A servo slider combines `SliderControlConfig` with `ServoOutput`:
+
+```cpp
+SliderControlConfig position;
+position.name = "Arm position";
+position.minimum = 0;
+position.maximum = 180;
+
+ServoOutput servo;
+servo.pin = 13;
+
+peripheral.addSlider(position, servo);
+```
+
+A PWM slider combines `SliderControlConfig` with `PwmOutput`:
+
+```cpp
+SliderControlConfig brightness;
+brightness.name = "Light brightness";
+brightness.minimum = 0;
+brightness.maximum = 255;
+
+PwmOutput light;
+light.pin = 17;
+
+peripheral.addSlider(brightness, light);
+```
+
+A digital button combines `ButtonControlConfig` with `DigitalOutput`:
+
+```cpp
+ButtonControlConfig workLight;
+workLight.name = "Work light";
+workLight.mode = ButtonMode::Toggle;
+
+DigitalOutput light;
+light.pin = 21;
+light.polarity = OutputPolarity::ActiveHigh;
+
+peripheral.addButton(workLight, light);
+```
+
+### Custom accessory functions
+
+A custom slider passes its value to a callback:
+
+```cpp
+SliderControlConfig speed;
+speed.name = "Motor speed";
+speed.minimum = 0;
+speed.maximum = 100;
+
+peripheral.addSlider(speed, setMotorSpeed);
+```
+
+A custom button passes its logical state to a bool callback:
+
+```cpp
+ButtonControlConfig motor;
+motor.name = "Motor";
+motor.mode = ButtonMode::Momentary;
+
+peripheral.addButton(motor, setMotorRunning);
+```
+
+Momentary bool callbacks receive `true` on press and `false` on release. A
+zero-argument callback may be registered for a momentary action that runs only
+on press.
+
+Number and text inputs use their corresponding configuration structs:
+
+```cpp
+NumberControlConfig repeats;
+repeats.name = "Repeat count";
+repeats.minimum = 1;
+repeats.maximum = 20;
+peripheral.addNumber(repeats, setRepeatCount);
+
+TextControlConfig message;
+message.name = "Display message";
+message.maximumLength = 64;
+peripheral.addText(message, setDisplayMessage);
+```
+
+A program may define `updateRoverPeripheral()` for recurring work:
+
+```cpp
+void updateRoverPeripheral() {
+  // Update application state.
+}
+```
+
+Callbacks and recurring work must not block Firmata processing. Programs must
+not write debug output to `Serial` because Firmata uses that stream.
+
+### Library runtime
+
+The library runtime performs these steps:
+
+1. opens `Serial` at 115200 baud;
+2. calls `configureRoverPeripheral()`;
+3. sets the serial timeout to zero;
+4. initializes Firmata and the rover-peripheral feature;
+5. applies initial output states; and
+6. processes Firmata messages and optional recurring work.
+
+The zero timeout prevents ConfigurableFirmata from waiting for its receive
+buffer to fill before processing a short command.
+
+### PlatformIO package
+
+The package source and reference project are:
 
 ```text
 esp32/
 ├── libraries/
 │   └── RoverPeripheralFirmata/
 │       ├── library.json
+│       ├── LICENSE
+│       ├── README.md
+│       ├── examples/
 │       └── src/
 └── rover-gpio-peripheral/
     ├── platformio.ini
     └── src/main.cpp
 ```
 
-The local library owns control registration, description generation, rover-peripheral SysEx handling, callback dispatch, and the standard digital, PWM, and servo output subset. The sketch only declares hardware and application behavior.
+The published package name is `legop3/RoverPeripheral`. Version `2.0.0`
+contains the struct-based public API.
 
-`platformio.ini` contains two environments:
+A classic ESP32 PlatformIO project declares:
 
-| Environment | Intended hardware | Normal Linux device |
+```ini
-| --- | --- | --- |
+[env:esp32dev]
-| `esp32dev` | ESP32-WROOM-32/DevKitC boards using CH340 or CP210x USB-to-UART | `/dev/ttyUSB*` |
+platform = espressif32
-| `esp32-s3-devkitc-1` | ESP32-S3 boards using native USB CDC | `/dev/ttyACM*` |
+board = esp32dev
+framework = arduino
 
-Both environments compile the same `main.cpp`. The S3 environment only adds the Arduino USB CDC build flags needed to make its native USB serial stream active at boot. The sketch passes Arduino's `Serial` object to `Firmata.begin(Stream&)`, so neither the helper library nor the Firmata messages depend on which USB transport produced the byte stream.
+lib_deps =
+  legop3/RoverPeripheral @ ^2.0.0
+```
 
-Typical commands are:
+A native-USB ESP32-S3 uses `board = esp32-s3-devkitc-1` and:
+
+```ini
+build_flags =
+  -D ARDUINO_USB_MODE=1
+  -D ARDUINO_USB_CDC_ON_BOOT=1
+```
+
+The package manifest installs ConfigurableFirmata, ArduinoJson, and ESP32Servo.
+
+Release validation and publication use:
+
+```bash
+pio pkg pack esp32/libraries/RoverPeripheralFirmata
+pio pkg publish esp32/libraries/RoverPeripheralFirmata --owner legop3
+```
+
+Published versions are immutable. Each release uses a new version in
+`library.json`.
+
+### Building and probing
+
+Build and upload the repository reference firmware with:
 
 ```bash
 cd esp32/rover-gpio-peripheral
-
-# The TG34/CH340 DevKitC-style ESP32 used for initial testing.
 pio run -e esp32dev
 pio run -e esp32dev -t upload --upload-port /dev/ttyUSB0
-pio device monitor --port /dev/ttyUSB0 --baud 115200
-
-# A native-USB ESP32-S3 DevKitC.
-pio run -e esp32-s3-devkitc-1
-pio run -e esp32-s3-devkitc-1 -t upload --upload-port /dev/ttyACM0
-pio device monitor --port /dev/ttyACM0 --baud 115200
 ```
 
-Do not keep PlatformIO's serial monitor open while `roverd` or the probe is using the peripheral. A serial device can have only one process actively consuming the Firmata stream.
+Use `esp32-s3-devkitc-1` and the matching `/dev/ttyACM*` device for a
-
+native-USB ESP32-S3.
-After uploading, use the Go probe to perform the real handshake and print the self-description:
 
 ```bash
 cd pi/roverd
 go run ./cmd/peripheral-probe -port /dev/ttyUSB0
-
-# Exercise the standard servo slider.
-go run ./cmd/peripheral-probe -port /dev/ttyUSB0 -control servoPosition -value 90
-
-# Exercise the custom momentary callback. Run once for press and once for release.
-go run ./cmd/peripheral-probe -port /dev/ttyUSB0 -control specialAction -value true
-go run ./cmd/peripheral-probe -port /dev/ttyUSB0 -control specialAction -value false
 ```
-
-Use `/dev/ttyACM0` instead for a native-USB board. The probe waits two seconds after opening because either style of development board may reset when its serial connection opens. It then performs the standard Firmata firmware and capability queries before sending `DESCRIBE`. `-control` is intentionally a diagnostic option only; production control will enter through the server and `roverd` command path.
-
-ConfigurableFirmata's stock example disables its servo feature on ESP32. `RoverPeripheralFirmata` therefore uses ConfigurableFirmata for standard framing, parsing, capability dispatch, and firmware queries, but supplies the ESP32 servo implementation with `ESP32Servo`. Servo writes still use the standard Firmata `SERVO_CONFIG`, `SET_PIN_MODE`, and `EXTENDED_ANALOG` messages; this is an implementation substitution inside the firmware, not a custom servo protocol.
-
-The project pins ConfigurableFirmata `3.2.0` because PlatformIO's stable Espressif32 platform currently ships Arduino-ESP32 2.x. ConfigurableFirmata `3.4.0` compiles its bundled PWM source with Arduino-ESP32 3.x LEDC function names even when the sketch does not instantiate that feature. The pinned release uses the matching 2.x LEDC API and compiles for both configured boards. This pin is a build compatibility choice and does not change the Firmata messages used by the rover.
-
 ## Connection lifecycle
 
 ### Startup discovery
@@ -973,7 +941,7 @@ Payload:
   "data": {
     "peripheral": {
       "id": "firmata-0",
-      "control": "servoPosition",
+      "control": "Servo position",
       "value": 90
     }
   }
@@ -993,7 +961,7 @@ If the socket cannot drive that rover, the event acknowledgement returns an erro
   "type": "peripheral",
   "peripheral": {
     "id": "firmata-0",
-    "control": "servoPosition",
+    "control": "Servo position",
     "value": 90
   }
 }
@@ -1053,10 +1021,10 @@ A toggle sends one of the last two writes per activation. A momentary button sen
 
 ## Custom callback communication
 
-Suppose `specialAction` is pressed. `roverd` creates the JSON payload:
+Suppose `Special action` is pressed. `roverd` creates the JSON payload:
 
 ```json
-{"control":"specialAction","value":true}
+{"control":"Special action","value":true}
 ```
 
 After 8-to-7-bit encoding, it is placed in:
@@ -1074,19 +1042,18 @@ The ESP32 library:
 1. Receives the SysEx feature message through Firmata.
 2. Decodes the JSON bytes.
 3. Reads `control` and `value`.
-4. Finds the control registered as `specialAction`.
+4. Finds the control registered as `Special action`.
 5. Converts the JSON boolean to the registered button callback's `bool` argument.
 6. Calls the callback with `true`.
 
 On release the same path carries `false`.
 
-For the example sketch, only the press runs the one-shot function:
+For the reference sketch, the callback drives its output high on press and low
+again on release:
 
 ```cpp
-[](bool pressed) {
+void runSpecialAction(bool pressed) {
-  if (pressed) {
+  digitalWrite(specialActionPin, pressed ? HIGH : LOW);
-    runSpecialAction();
-  }
 }
 ```
 
@@ -1155,7 +1122,7 @@ Implementation should remain concentrated in a few clear areas.
 
 ### ESP32 library
 
-The Arduino-compatible `RoverPeripheralFirmata` library now contains:
+The Arduino-compatible `RoverPeripheral` package now contains:
 
 - Ordered control registration.
 - Standardized `cameraServo`, `headlight`, and `laser` role registration.
@@ -1164,11 +1131,18 @@ The Arduino-compatible `RoverPeripheralFirmata` library now contains:
 - `DESCRIBE` response handling.
 - `CONTROL` decoding and callback dispatch.
 - 8-to-7-bit payload encoding and decoding.
-- The standard-output and custom-control helper methods listed above.
+- The public configuration structs and registration methods listed above.
+- Arduino `setup()` and `loop()` ownership, including the zero-timeout Firmata
+  parser configuration required for immediate short-command handling.
 
-Example ESP32 sketches should use this library rather than hand-writing SysEx parsing.
+Example ESP32 sketches import only `RoverPeripheral.h` rather than exposing or
+hand-writing any Firmata setup or SysEx parsing.
 
-The first implementation lives in `esp32/libraries/RoverPeripheralFirmata`, with the complete `esp32/rover-gpio-peripheral` PlatformIO project serving as both the reference firmware and an example usable by either rover host type.
+The package source lives in `esp32/libraries/RoverPeripheralFirmata`, with the
+complete `esp32/rover-gpio-peripheral` PlatformIO project serving as the
+repository reference firmware. The package manifest, README, and examples are
+self-contained so the same directory can be published directly to the
+PlatformIO Registry as `legop3/RoverPeripheral`.
 
 ### `pi/roverd`
 
@@ -1220,19 +1194,16 @@ Add one generic peripheral control renderer that:
 
 ## Implementation sequence
 
-The smallest useful vertical implementation is:
+The implemented vertical path is:
 
-1. Build the ESP32 Firmata feature and the three-control example sketch.
+1. The public ESP32 package declares built-in roles and ordered accessory controls.
-2. Add boot-time one-device USB discovery and Firmata communication to `roverd`.
+2. Its private Firmata implementation advertises the generated description.
-3. Include the fixed description in the rover hello and server roster.
+3. `roverd` discovers all startup peripherals and resolves hardware backends.
-4. Render the ordered generic controls in the driver UI.
+4. Rover hello metadata carries the fixed renderable inventory to the server.
-5. Route generic servo and PWM controls through standard Firmata.
+5. The server preserves that inventory in the roster and applies normal driver authorization.
-6. Route the generic momentary button through the custom callback operation.
+6. The shared web renderer presents the four control types on desktop and mobile.
-7. Add the standardized ESP32 camera-servo, headlight, and laser declarations.
+7. Commands return through the existing pipeline to standard Firmata outputs or custom callbacks.
-8. Refactor built-in controllers to select native Pi or Firmata backends at startup.
+8. The package README and examples give external authors the same concise API used by the repository firmware.
-9. Verify that existing tilt, headlight, laser, keybinding, gamepad, state-event, and server-policy behavior is unchanged with both backends.
-10. Generalize startup discovery from one connection to multiple simultaneous peripherals.
-11. Add the remaining toggle, number, and text registration helpers and UI renderers.
 
 The protocol and session shapes are arrays from the beginning, so supporting multiple devices does not require changing the external contracts after the first-device vertical slice.
 
@@ -1251,16 +1222,17 @@ The completed system should be verified with a real ESP32 and rover Linux comput
 
 ### Standard controls
 
-- Move the servo slider and confirm pin 14 receives servo values across the declared range.
+- Move the reference brightness slider and confirm pin 17 receives PWM values across the declared range.
-- Move the brightness slider and confirm pin 18 receives PWM values across the declared range.
+- Register a `SliderControlConfig` with a `ServoOutput` and confirm its selected pin receives servo values across the declared range.
 - Confirm neither standard control invokes the custom callback path.
 
 ### Custom controls
 
 - Press the momentary button and confirm the ESP32 callback receives `true` once.
 - Release it and confirm the callback receives `false` once.
+- Submit number and text values and confirm their typed callbacks receive the advertised values.
 - Cancel a held pointer or leave the control layout and confirm a release is sent.
-- Confirm arbitrary non-blocking ESP32 behavior can continue from `loop()` after the callback changes its state.
+- Confirm arbitrary non-blocking ESP32 behavior can continue from `updateRoverPeripheral()` after the callback changes its state.
 
 ### Permissions
 

esp32/libraries/RoverPeripheralFirmata/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Roberts
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

esp32/libraries/RoverPeripheralFirmata/README.md

@@ -0,0 +1,218 @@
+# RoverPeripheral
+
+RoverPeripheral is an ESP32 Arduino library for MultiRoombaRover peripherals.
+The ESP32 reports its built-in rover roles and accessory controls to `roverd`
+over USB serial.
+
+## PlatformIO installation
+
+Classic ESP32 DevKitC-style board:
+
+```ini
+[env:esp32dev]
+platform = espressif32
+board = esp32dev
+framework = arduino
+
+lib_deps =
+  legop3/RoverPeripheral @ ^2.0.0
+```
+
+Native-USB ESP32-S3 DevKitC:
+
+```ini
+[env:esp32-s3-devkitc-1]
+platform = espressif32
+board = esp32-s3-devkitc-1
+framework = arduino
+build_flags =
+  -D ARDUINO_USB_MODE=1
+  -D ARDUINO_USB_CDC_ON_BOOT=1
+
+lib_deps =
+  legop3/RoverPeripheral @ ^2.0.0
+```
+
+## Program structure
+
+Include `RoverPeripheral.h` and define `configureRoverPeripheral()`:
+
+```cpp
+#include <RoverPeripheral.h>
+
+void configureRoverPeripheral(RoverPeripheral& peripheral) {
+  peripheral.name("Headlight controller");
+
+  RoverDigitalOutputConfig headlight;
+  headlight.pin = 18;
+  headlight.polarity = OutputPolarity::ActiveHigh;
+  headlight.initiallyOn = false;
+  peripheral.addHeadlight(headlight);
+}
+```
+
+The library provides `setup()` and `loop()`. Do not define them in the
+peripheral program.
+
+## Built-in rover roles
+
+Camera tilt:
+
+```cpp
+RoverCameraServoConfig cameraServo;
+cameraServo.pin = 14;
+cameraServo.minimumAngleDegrees = -15;
+cameraServo.maximumAngleDegrees = 30;
+cameraServo.homeAngleDegrees = 0;
+cameraServo.nudgeDegrees = 2;
+cameraServo.minimumPulseMicroseconds = 900;
+cameraServo.maximumPulseMicroseconds = 2100;
+cameraServo.allowRawPulse = false;
+cameraServo.inverted = false;
+peripheral.addCameraServo(cameraServo);
+```
+
+Headlight or laser:
+
+```cpp
+RoverDigitalOutputConfig headlight;
+headlight.pin = 18;
+headlight.polarity = OutputPolarity::ActiveHigh;
+headlight.initiallyOn = false;
+peripheral.addHeadlight(headlight);
+
+RoverDigitalOutputConfig laser;
+laser.pin = 16;
+laser.polarity = OutputPolarity::ActiveHigh;
+laser.initiallyOn = false;
+peripheral.addLaser(laser);
+```
+
+These registrations use the existing camera, headlight, and laser controls in
+the rover UI. They do not create accessory controls.
+
+## Accessory controls
+
+Controls appear in registration order. Each control name must be unique within
+the peripheral. The name is also used as the control identifier.
+
+### Servo slider
+
+```cpp
+SliderControlConfig position;
+position.name = "Arm position";
+position.minimum = 0;
+position.maximum = 180;
+
+ServoOutput servo;
+servo.pin = 13;
+
+peripheral.addSlider(position, servo);
+```
+
+### PWM slider
+
+```cpp
+SliderControlConfig brightness;
+brightness.name = "Light brightness";
+brightness.minimum = 0;
+brightness.maximum = 255;
+
+PwmOutput light;
+light.pin = 17;
+
+peripheral.addSlider(brightness, light);
+```
+
+### Digital button
+
+```cpp
+ButtonControlConfig workLight;
+workLight.name = "Work light";
+workLight.mode = ButtonMode::Toggle;
+
+DigitalOutput light;
+light.pin = 21;
+light.polarity = OutputPolarity::ActiveHigh;
+
+peripheral.addButton(workLight, light);
+```
+
+### Custom slider
+
+```cpp
+void setMotorSpeed(int value) {
+  // Apply value to the device.
+}
+
+SliderControlConfig speed;
+speed.name = "Motor speed";
+speed.minimum = 0;
+speed.maximum = 100;
+
+peripheral.addSlider(speed, setMotorSpeed);
+```
+
+### Custom button
+
+```cpp
+void setMotorRunning(bool running) {
+  // Start or stop the device.
+}
+
+ButtonControlConfig motor;
+motor.name = "Motor";
+motor.mode = ButtonMode::Momentary;
+
+peripheral.addButton(motor, setMotorRunning);
+```
+
+A momentary bool callback receives `true` on press and `false` on release. A
+zero-argument callback can be used for a one-shot momentary action.
+
+### Number input
+
+```cpp
+void setRepeatCount(int value) {
+  // Store or apply value.
+}
+
+NumberControlConfig repeats;
+repeats.name = "Repeat count";
+repeats.minimum = 1;
+repeats.maximum = 20;
+
+peripheral.addNumber(repeats, setRepeatCount);
+```
+
+### Text input
+
+```cpp
+void setDisplayMessage(const String& value) {
+  // Store or display value.
+}
+
+TextControlConfig message;
+message.name = "Display message";
+message.maximumLength = 64;
+
+peripheral.addText(message, setDisplayMessage);
+```
+
+## Recurring work
+
+Define `updateRoverPeripheral()` when the program needs recurring non-blocking
+work:
+
+```cpp
+void updateRoverPeripheral() {
+  // Update a state machine or device.
+}
+```
+
+Callbacks and `updateRoverPeripheral()` must not block serial processing.
+`Serial` is reserved for Firmata and must not be used for debug output.
+
+## License
+
+MIT

esp32/libraries/RoverPeripheralFirmata/examples/CompletePeripheral/CompletePeripheral.ino

@@ -0,0 +1,76 @@
+#include <RoverPeripheral.h>
+
+namespace {
+constexpr uint8_t kActionPin = 21;
+
+int repeatCount = 1;
+String displayMessage;
+
+void setActionActive(bool pressed) {
+  digitalWrite(kActionPin, pressed ? HIGH : LOW);
+}
+
+void setRepeatCount(int value) {
+  repeatCount = value;
+}
+
+void setDisplayMessage(const String& value) {
+  displayMessage = value;
+}
+}  // namespace
+
+void configureRoverPeripheral(RoverPeripheral& io) {
+  io.name("Complete rover peripheral");
+
+  RoverCameraServoConfig cameraServo;
+  cameraServo.pin = 14;
+  cameraServo.minimumAngleDegrees = -15;
+  cameraServo.maximumAngleDegrees = 30;
+  cameraServo.homeAngleDegrees = 0;
+  cameraServo.nudgeDegrees = 2;
+  cameraServo.minimumPulseMicroseconds = 900;
+  cameraServo.maximumPulseMicroseconds = 2100;
+  cameraServo.allowRawPulse = false;
+  cameraServo.inverted = false;
+  io.addCameraServo(cameraServo);
+
+  RoverDigitalOutputConfig headlight;
+  headlight.pin = 18;
+  headlight.polarity = OutputPolarity::ActiveHigh;
+  headlight.initiallyOn = false;
+  io.addHeadlight(headlight);
+
+  RoverDigitalOutputConfig laser;
+  laser.pin = 16;
+  laser.polarity = OutputPolarity::ActiveHigh;
+  laser.initiallyOn = false;
+  io.addLaser(laser);
+
+  pinMode(kActionPin, OUTPUT);
+  digitalWrite(kActionPin, LOW);
+
+  SliderControlConfig brightness;
+  brightness.name = "Light brightness";
+  brightness.minimum = 0;
+  brightness.maximum = 255;
+
+  PwmOutput brightnessOutput;
+  brightnessOutput.pin = 17;
+  io.addSlider(brightness, brightnessOutput);
+
+  ButtonControlConfig action;
+  action.name = "Special action";
+  action.mode = ButtonMode::Momentary;
+  io.addButton(action, setActionActive);
+
+  NumberControlConfig repeats;
+  repeats.name = "Repeat count";
+  repeats.minimum = 1;
+  repeats.maximum = 20;
+  io.addNumber(repeats, setRepeatCount);
+
+  TextControlConfig message;
+  message.name = "Display message";
+  message.maximumLength = 64;
+  io.addText(message, setDisplayMessage);
+}

esp32/libraries/RoverPeripheralFirmata/examples/MinimalPeripheral/MinimalPeripheral.ino

@@ -0,0 +1,11 @@
+#include <RoverPeripheral.h>
+
+void configureRoverPeripheral(RoverPeripheral& io) {
+  io.name("Headlight controller");
+
+  RoverDigitalOutputConfig headlight;
+  headlight.pin = 18;
+  headlight.polarity = OutputPolarity::ActiveHigh;
+  headlight.initiallyOn = false;
+  io.addHeadlight(headlight);
+}

esp32/libraries/RoverPeripheralFirmata/library.json

@@ -1,10 +1,25 @@
 {
-  "name": "RoverPeripheralFirmata",
+  "$schema": "https://raw.githubusercontent.com/platformio/platformio-core/develop/platformio/assets/schema/library.json",
-  "version": "0.1.0",
+  "name": "RoverPeripheral",
-  "description": "Self-describing Firmata controls for MultiRoombaRover ESP32 peripherals",
+  "version": "2.0.1",
+  "description": "Create self-describing ESP32 hardware controls for MultiRoombaRover",
+  "keywords": [
+    "esp32",
+    "firmata",
+    "robotics",
+    "rover"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/legop3/MultiRoombaRover.git"
+  },
+  "homepage": "https://github.com/legop3/MultiRoombaRover/tree/main/esp32/libraries/RoverPeripheralFirmata",
+  "license": "MIT",
   "frameworks": "arduino",
   "platforms": "espressif32",
+  "headers": "RoverPeripheral.h",
   "dependencies": {
+    "ConfigurableFirmata": "https://github.com/firmata/ConfigurableFirmata.git#3.2.0",
     "bblanchon/ArduinoJson": "^7.4.2",
     "madhephaestus/ESP32Servo": "^3.0.8"
   }

esp32/libraries/RoverPeripheralFirmata/src/RoverPeripheral.cpp

@@ -0,0 +1,78 @@
+#include "RoverPeripheral.h"
+
+#include "internal/RoverPeripheralFirmata.h"
+
+RoverPeripheral::RoverPeripheral()
+  : implementation_(new RoverPeripheralFirmata("Rover peripheral")) {}
+
+RoverPeripheral::~RoverPeripheral() {
+  delete implementation_;
+}
+
+void RoverPeripheral::name(const String& peripheralName) {
+  implementation_->setName(peripheralName);
+}
+
+void RoverPeripheral::addCameraServo(const RoverCameraServoConfig& config) {
+  implementation_->addRoverCameraServo(config);
+}
+
+void RoverPeripheral::addHeadlight(const RoverDigitalOutputConfig& config) {
+  implementation_->addRoverHeadlight(config);
+}
+
+void RoverPeripheral::addLaser(const RoverDigitalOutputConfig& config) {
+  implementation_->addRoverLaser(config);
+}
+
+void RoverPeripheral::addSlider(const SliderControlConfig& config, const ServoOutput& output) {
+  implementation_->addServoSlider(config, output);
+}
+
+void RoverPeripheral::addSlider(const SliderControlConfig& config, const PwmOutput& output) {
+  implementation_->addPwmSlider(config, output);
+}
+
+void RoverPeripheral::addButton(const ButtonControlConfig& config, const DigitalOutput& output) {
+  implementation_->addDigitalButton(config, output);
+}
+
+void RoverPeripheral::addSlider(const SliderControlConfig& config, SliderCallback callback) {
+  implementation_->addSlider(config, callback);
+}
+
+void RoverPeripheral::addButton(const ButtonControlConfig& config, ButtonCallback callback) {
+  implementation_->addButton(config, callback);
+}
+
+void RoverPeripheral::addButton(const ButtonControlConfig& config, ActionCallback callback) {
+  // One-shot callbacks apply only to momentary buttons. A toggle requires the
+  // bool callback overload because application code must receive its new state.
+  if (config.mode != ButtonMode::Momentary) {
+    abort();
+  }
+  implementation_->addButton(
+    config,
+    [callback](bool pressed) {
+      if (pressed && callback) {
+        callback();
+      }
+    }
+  );
+}
+
+void RoverPeripheral::addNumber(const NumberControlConfig& config, NumberCallback callback) {
+  implementation_->addNumber(config, callback);
+}
+
+void RoverPeripheral::addText(const TextControlConfig& config, TextCallback callback) {
+  implementation_->addText(config, callback);
+}
+
+void RoverPeripheral::begin(FirmataExt& extension) {
+  implementation_->begin(extension);
+}
+
+void RoverPeripheral::update() {
+  implementation_->update();
+}

esp32/libraries/RoverPeripheralFirmata/src/RoverPeripheral.h

@@ -0,0 +1,156 @@
+#pragma once
+
+#include <Arduino.h>
+
+#include <functional>
+
+/** Describes whether a logical on value drives an output pin high or low. */
+enum class OutputPolarity {
+  ActiveHigh,
+  ActiveLow,
+};
+
+/** Selects whether a button retains its state or is active only while held. */
+enum class ButtonMode {
+  Toggle,
+  Momentary,
+};
+
+/** Configuration for the rover's existing camera-tilt control. */
+struct RoverCameraServoConfig {
+  uint8_t pin = 0;
+  float minimumAngleDegrees = -15;
+  float maximumAngleDegrees = 30;
+  float homeAngleDegrees = 0;
+  float nudgeDegrees = 2;
+  uint16_t minimumPulseMicroseconds = 900;
+  uint16_t maximumPulseMicroseconds = 2100;
+  bool allowRawPulse = false;
+  bool inverted = false;
+};
+
+/** Configuration for the rover's existing headlight or laser control. */
+struct RoverDigitalOutputConfig {
+  uint8_t pin = 0;
+  OutputPolarity polarity = OutputPolarity::ActiveHigh;
+  bool initiallyOn = false;
+};
+
+/** Shared display and range settings for a slider control. */
+struct SliderControlConfig {
+  String name;
+  int minimum = 0;
+  int maximum = 100;
+};
+
+/** Shared display and interaction settings for a button control. */
+struct ButtonControlConfig {
+  String name;
+  ButtonMode mode = ButtonMode::Momentary;
+};
+
+/** Shared display and range settings for a number input. */
+struct NumberControlConfig {
+  String name;
+  int minimum = 0;
+  int maximum = 100;
+};
+
+/** Shared display and length settings for a text input. */
+struct TextControlConfig {
+  String name;
+  size_t maximumLength = 32;
+};
+
+/** Selects a standard Firmata servo as the destination for a slider. */
+struct ServoOutput {
+  uint8_t pin = 0;
+};
+
+/** Selects an ESP32 PWM pin as the destination for a slider. */
+struct PwmOutput {
+  uint8_t pin = 0;
+};
+
+/** Selects an ESP32 digital pin as the destination for a button. */
+struct DigitalOutput {
+  uint8_t pin = 0;
+  OutputPolarity polarity = OutputPolarity::ActiveHigh;
+};
+
+using SliderCallback = std::function<void(int)>;
+using ButtonCallback = std::function<void(bool)>;
+using ActionCallback = std::function<void()>;
+using NumberCallback = std::function<void(int)>;
+using TextCallback = std::function<void(const String&)>;
+
+class FirmataExt;
+class RoverPeripheralFirmata;
+
+/**
+ * Registration API for a self-describing rover peripheral.
+ *
+ * A sketch constructs each configuration one field at a time and registers it
+ * in configureRoverPeripheral(). Serial and protocol setup stay in the library.
+ */
+class RoverPeripheral {
+ public:
+  RoverPeripheral();
+  ~RoverPeripheral();
+
+  RoverPeripheral(const RoverPeripheral&) = delete;
+  RoverPeripheral& operator=(const RoverPeripheral&) = delete;
+
+  /** Sets the peripheral name shown above its accessory controls. */
+  void name(const String& peripheralName);
+
+  /** Registers the rover's existing camera-tilt control. */
+  void addCameraServo(const RoverCameraServoConfig& config);
+
+  /** Registers the rover's existing headlight control. */
+  void addHeadlight(const RoverDigitalOutputConfig& config);
+
+  /** Registers the rover's existing laser control. */
+  void addLaser(const RoverDigitalOutputConfig& config);
+
+  /** Registers a slider backed by a standard Firmata servo output. */
+  void addSlider(const SliderControlConfig& config, const ServoOutput& output);
+
+  /** Registers a slider backed by an ESP32 PWM output. */
+  void addSlider(const SliderControlConfig& config, const PwmOutput& output);
+
+  /** Registers a button backed by an ESP32 digital output. */
+  void addButton(const ButtonControlConfig& config, const DigitalOutput& output);
+
+  /** Registers a slider handled by application code. */
+  void addSlider(const SliderControlConfig& config, SliderCallback callback);
+
+  /** Registers a button whose callback receives its logical state. */
+  void addButton(const ButtonControlConfig& config, ButtonCallback callback);
+
+  /** Registers a momentary button whose callback runs only on press. */
+  void addButton(const ButtonControlConfig& config, ActionCallback callback);
+
+  /** Registers a number input handled by application code. */
+  void addNumber(const NumberControlConfig& config, NumberCallback callback);
+
+  /** Registers a text input handled by application code. */
+  void addText(const TextControlConfig& config, TextCallback callback);
+
+ private:
+  // The implementation is opaque so importing this header does not expose any
+  // Firmata types or require firmware authors to understand the wire protocol.
+  RoverPeripheralFirmata* implementation_;
+
+  void begin(FirmataExt& extension);
+  void update();
+
+  friend void setup();
+  friend void loop();
+};
+
+/** Called once by the library after Arduino and Serial initialization. */
+void configureRoverPeripheral(RoverPeripheral& peripheral);
+
+/** Optional non-blocking hook for recurring application work. */
+void updateRoverPeripheral();

esp32/libraries/RoverPeripheralFirmata/src/RoverPeripheralRuntime.cpp

@@ -0,0 +1,46 @@
+#include "RoverPeripheral.h"
+
+#include <ConfigurableFirmata.h>
+#include <FirmataExt.h>
+
+namespace {
+FirmataExt firmataExtension;
+RoverPeripheral peripheral;
+}  // namespace
+
+// A weak no-op preserves the zero-boilerplate case while allowing a sketch to
+// define the same function when animations or state machines need regular work.
+void __attribute__((weak)) updateRoverPeripheral() {}
+
+void setup() {
+  // The public configuration hook runs after Arduino initialization, allowing
+  // peripheral code to safely use pinMode() and initialize third-party devices.
+  Serial.begin(115200);
+  configureRoverPeripheral(peripheral);
+
+  // ConfigurableFirmata batches reads on ESP32-class boards. Arduino's default
+  // one-second Stream timeout would delay short commands while waiting for the
+  // batch buffer to fill, so consume only bytes that have already arrived.
+  Serial.setTimeout(0);
+  Firmata.begin(Serial);
+  peripheral.begin(firmataExtension);
+
+  // Applying a normal Firmata reset after registration establishes every
+  // declared initial output and makes the first host connection deterministic.
+  Firmata.parse(SYSTEM_RESET);
+}
+
+void loop() {
+  // ConfigurableFirmata retains partial parser state between iterations. Stop
+  // after each complete message so user update work cannot be starved by a
+  // sustained burst, while ordinary short commands are still drained at once.
+  while (Firmata.available()) {
+    Firmata.processInput();
+    if (!Firmata.isParsingMessage()) {
+      break;
+    }
+  }
+
+  peripheral.update();
+  updateRoverPeripheral();
+}

esp32/libraries/RoverPeripheralFirmata/src/internal/RoverPeripheralFirmata.cpp

@@ -28,31 +28,41 @@ RoverPeripheralFirmata* RoverPeripheralFirmata::instance_ = nullptr;
 
 RoverPeripheralFirmata::RoverPeripheralFirmata(const String& name) : name_(name) {}
 
-void RoverPeripheralFirmata::validateControlIdentity(const String& id, const String& name) const {
+void RoverPeripheralFirmata::setName(const String& name) {
-  if (id.length() == 0 || name.length() == 0) {
+  if (name.length() == 0) {
+    // A blank heading makes multiple attached peripherals impossible to
+    // distinguish. Treat it as a firmware-authoring error at startup rather
+    // than advertising ambiguous controls to the rover.
+    abort();
+  }
+  name_ = name;
+}
+
+void RoverPeripheralFirmata::validateControlName(const String& name) const {
+  if (name.length() == 0) {
     // Registration errors are programmer errors discovered during setup. A
     // hard stop is preferable to advertising a partially usable device whose
     // behavior depends on which malformed control the driver touches first.
     abort();
   }
   for (const ControlRegistration& existing : controls_) {
-    if (existing.id == id) {
+    if (existing.id == name) {
       abort();
     }
   }
 }
 
-void RoverPeripheralFirmata::validateRange(const String& id, int minimum, int maximum) const {
+void RoverPeripheralFirmata::validateRange(const String& name, int minimum, int maximum) const {
-  if (id.length() == 0 || minimum > maximum) {
+  if (name.length() == 0 || minimum > maximum) {
     abort();
   }
 }
 
-void RoverPeripheralFirmata::addServoSlider(const SliderControlConfig& config, const FirmataServoOutput& output) {
+void RoverPeripheralFirmata::addServoSlider(const SliderControlConfig& config, const ServoOutput& output) {
-  validateControlIdentity(config.id, config.name);
+  validateControlName(config.name);
-  validateRange(config.id, config.minimum, config.maximum);
+  validateRange(config.name, config.minimum, config.maximum);
   ControlRegistration control;
-  control.id = config.id;
+  control.id = config.name;
   control.name = config.name;
   control.type = ControlType::Slider;
   control.output = OutputType::Servo;
@@ -62,11 +72,11 @@ void RoverPeripheralFirmata::addServoSlider(const SliderControlConfig& config, c
   controls_.push_back(control);
 }
 
-void RoverPeripheralFirmata::addPwmSlider(const SliderControlConfig& config, const FirmataPwmOutput& output) {
+void RoverPeripheralFirmata::addPwmSlider(const SliderControlConfig& config, const PwmOutput& output) {
-  validateControlIdentity(config.id, config.name);
+  validateControlName(config.name);
-  validateRange(config.id, config.minimum, config.maximum);
+  validateRange(config.name, config.minimum, config.maximum);
   ControlRegistration control;
-  control.id = config.id;
+  control.id = config.name;
   control.name = config.name;
   control.type = ControlType::Slider;
   control.output = OutputType::Pwm;
@@ -76,10 +86,10 @@ void RoverPeripheralFirmata::addPwmSlider(const SliderControlConfig& config, con
   controls_.push_back(control);
 }
 
-void RoverPeripheralFirmata::addDigitalButton(const ButtonControlConfig& config, const FirmataDigitalOutput& output) {
+void RoverPeripheralFirmata::addDigitalButton(const ButtonControlConfig& config, const DigitalOutput& output) {
-  validateControlIdentity(config.id, config.name);
+  validateControlName(config.name);
   ControlRegistration control;
-  control.id = config.id;
+  control.id = config.name;
   control.name = config.name;
   control.type = ControlType::Button;
   control.output = OutputType::Digital;
@@ -90,10 +100,10 @@ void RoverPeripheralFirmata::addDigitalButton(const ButtonControlConfig& config,
 }
 
 void RoverPeripheralFirmata::addSlider(const SliderControlConfig& config, SliderCallback callback) {
-  validateControlIdentity(config.id, config.name);
+  validateControlName(config.name);
-  validateRange(config.id, config.minimum, config.maximum);
+  validateRange(config.name, config.minimum, config.maximum);
   ControlRegistration control;
-  control.id = config.id;
+  control.id = config.name;
   control.name = config.name;
   control.type = ControlType::Slider;
   control.output = OutputType::Custom;
@@ -104,9 +114,9 @@ void RoverPeripheralFirmata::addSlider(const SliderControlConfig& config, Slider
 }
 
 void RoverPeripheralFirmata::addButton(const ButtonControlConfig& config, ButtonCallback callback) {
-  validateControlIdentity(config.id, config.name);
+  validateControlName(config.name);
   ControlRegistration control;
-  control.id = config.id;
+  control.id = config.name;
   control.name = config.name;
   control.type = ControlType::Button;
   control.output = OutputType::Custom;
@@ -116,10 +126,10 @@ void RoverPeripheralFirmata::addButton(const ButtonControlConfig& config, Button
 }
 
 void RoverPeripheralFirmata::addNumber(const NumberControlConfig& config, NumberCallback callback) {
-  validateControlIdentity(config.id, config.name);
+  validateControlName(config.name);
-  validateRange(config.id, config.minimum, config.maximum);
+  validateRange(config.name, config.minimum, config.maximum);
   ControlRegistration control;
-  control.id = config.id;
+  control.id = config.name;
   control.name = config.name;
   control.type = ControlType::Number;
   control.output = OutputType::Custom;
@@ -130,12 +140,12 @@ void RoverPeripheralFirmata::addNumber(const NumberControlConfig& config, Number
 }
 
 void RoverPeripheralFirmata::addText(const TextControlConfig& config, TextCallback callback) {
-  validateControlIdentity(config.id, config.name);
+  validateControlName(config.name);
   if (config.maximumLength == 0) {
     abort();
   }
   ControlRegistration control;
-  control.id = config.id;
+  control.id = config.name;
   control.name = config.name;
   control.type = ControlType::Text;
   control.output = OutputType::Custom;

esp32/libraries/RoverPeripheralFirmata/src/internal/RoverPeripheralFirmata.h

@@ -5,95 +5,25 @@
 #include <ConfigurableFirmata.h>
 #include <ESP32Servo.h>
 #include <FirmataExt.h>
+#include <RoverPeripheral.h>
 
-#include <functional>
 #include <vector>
 
-enum class OutputPolarity {
-  ActiveHigh,
-  ActiveLow,
-};
-
-enum class ButtonMode {
-  Toggle,
-  Momentary,
-};
-
-struct FirmataServoOutput {
-  uint8_t pin = 0;
-};
-
-struct FirmataPwmOutput {
-  uint8_t pin = 0;
-};
-
-struct FirmataDigitalOutput {
-  uint8_t pin = 0;
-  OutputPolarity polarity = OutputPolarity::ActiveHigh;
-};
-
-struct RoverCameraServoConfig {
-  uint8_t pin = 0;
-  float minimumAngleDegrees = -15;
-  float maximumAngleDegrees = 30;
-  float homeAngleDegrees = 0;
-  float nudgeDegrees = 2;
-  uint16_t minimumPulseMicroseconds = 900;
-  uint16_t maximumPulseMicroseconds = 2100;
-  bool allowRawPulse = false;
-  bool inverted = false;
-};
-
-struct RoverDigitalOutputConfig {
-  uint8_t pin = 0;
-  OutputPolarity polarity = OutputPolarity::ActiveHigh;
-  bool initiallyOn = false;
-};
-
-struct SliderControlConfig {
-  String id;
-  String name;
-  int minimum = 0;
-  int maximum = 100;
-};
-
-struct ButtonControlConfig {
-  String id;
-  String name;
-  ButtonMode mode = ButtonMode::Momentary;
-};
-
-struct NumberControlConfig {
-  String id;
-  String name;
-  int minimum = 0;
-  int maximum = 100;
-};
-
-struct TextControlConfig {
-  String id;
-  String name;
-  size_t maximumLength = 32;
-};
-
-using SliderCallback = std::function<void(int)>;
-using ButtonCallback = std::function<void(bool)>;
-using NumberCallback = std::function<void(int)>;
-using TextCallback = std::function<void(const String&)>;
-
 /*
- * RoverPeripheralFirmata is both the sketch-facing registration API and one
+ * RoverPeripheralFirmata is the protocol-facing implementation behind the
- * ConfigurableFirmata feature. Keeping those responsibilities together gives a
+ * small RoverPeripheral public facade. Keeping this class private prevents
- * peripheral author one object to configure while still allowing ordinary
+ * peripheral sketches from depending on Firmata types while ordinary Firmata
- * Firmata tooling to use digital, PWM, and servo commands on the same stream.
+ * tooling can still use digital, PWM, and servo commands on the same stream.
  */
 class RoverPeripheralFirmata : public FirmataFeature {
  public:
   explicit RoverPeripheralFirmata(const String& name);
 
-  void addServoSlider(const SliderControlConfig& config, const FirmataServoOutput& output);
+  void setName(const String& name);
-  void addPwmSlider(const SliderControlConfig& config, const FirmataPwmOutput& output);
+
-  void addDigitalButton(const ButtonControlConfig& config, const FirmataDigitalOutput& output);
+  void addServoSlider(const SliderControlConfig& config, const ServoOutput& output);
+  void addPwmSlider(const SliderControlConfig& config, const PwmOutput& output);
+  void addDigitalButton(const ButtonControlConfig& config, const DigitalOutput& output);
   void addSlider(const SliderControlConfig& config, SliderCallback callback);
   void addButton(const ButtonControlConfig& config, ButtonCallback callback);
   void addNumber(const NumberControlConfig& config, NumberCallback callback);
@@ -155,8 +85,8 @@ class RoverPeripheralFirmata : public FirmataFeature {
   RoverDigitalOutputConfig laser_;
   Servo* servos_[TOTAL_PINS] = {};
 
-  void validateControlIdentity(const String& id, const String& name) const;
+  void validateControlName(const String& name) const;
-  void validateRange(const String& id, int minimum, int maximum) const;
+  void validateRange(const String& name, int minimum, int maximum) const;
   void buildAndSendDescription();
   void dispatchCustomControl(byte argc, byte* argv);
   void writeDigitalPin(byte pin, bool enabled);
@@ -167,4 +97,3 @@ class RoverPeripheralFirmata : public FirmataFeature {
   static void digitalPinValueCallback(byte pin, int value);
   static void systemResetCallback();
 };
-

esp32/rover-gpio-peripheral/platformio.ini

@@ -5,14 +5,11 @@ default_envs = esp32dev
 platform = espressif32
 framework = arduino
 monitor_speed = 115200
-lib_extra_dirs = ../libraries
 lib_deps =
-  ; 3.2.0 targets the Arduino 2.x core shipped by PlatformIO's stable ESP32
+  ; Install the local package through PlatformIO's dependency manager so this
-  ; platform. ConfigurableFirmata 3.4.0 switched its bundled PWM source to the
+  ; reference project exercises the same transitive dependency behavior as an
-  ; Arduino 3.x LEDC API even when that unused source is compiled as a dependency.
+  ; external project using the published Registry package.
-  https://github.com/firmata/ConfigurableFirmata.git#3.2.0
+  RoverPeripheral=file://../libraries/RoverPeripheralFirmata
-  bblanchon/ArduinoJson@^7.4.2
-  madhephaestus/ESP32Servo@^3.0.8
 
 ; This is the generic ESP32-WROOM-32/DevKitC target used by boards carrying a
 ; CH340 or CP210x USB-to-UART bridge. Linux normally exposes it as ttyUSB*.

esp32/rover-gpio-peripheral/src/main.cpp

@@ -1,10 +1,4 @@
-#include <Arduino.h>
+#include <RoverPeripheral.h>
-#include <ConfigurableFirmata.h>
-#include <FirmataExt.h>
-#include <RoverPeripheralFirmata.h>
-
-FirmataExt firmataExtension;
-RoverPeripheralFirmata peripheral("Rover GPIO");
 
 namespace {
 // Every example pin is present on both the classic ESP32 DevKitC and the
@@ -12,18 +6,33 @@ namespace {
 // S3 boards use them for USB D- and D+.
 constexpr uint8_t kSpecialActionPin = 21;
 
-void runSpecialAction() {
+int repeatCount = 1;
-  // This intentionally represents arbitrary device behavior rather than a raw
+String displayMessage;
-  // pin mapping. Replace it with a motor sequence, LED animation, actuator
+
-  // routine, or any other application-specific function the accessory needs.
+void runSpecialAction(bool pressed) {
-  digitalWrite(kSpecialActionPin, HIGH);
+  // Receiving both button edges lets application hardware remain active only
-  delay(80);
+  // while the driver holds the momentary control.
-  digitalWrite(kSpecialActionPin, LOW);
+  digitalWrite(kSpecialActionPin, pressed ? HIGH : LOW);
 }
 
-void registerBuiltInRoverControls() {
+void setRepeatCount(int value) {
-  // These three roles replace physical GPIO backends while preserving the
+  // A real device can use this value when it starts its next animation or
-  // existing camera, headlight, and laser commands and HUD controls.
+  // actuator sequence. Storing it keeps this reference callback non-blocking.
+  repeatCount = value;
+}
+
+void setDisplayMessage(const String& value) {
+  // Display hardware can render the stored value from updateRoverPeripheral().
+  // Avoiding Serial output is important because Serial belongs to Firmata.
+  displayMessage = value;
+}
+}  // namespace
+
+void configureRoverPeripheral(RoverPeripheral& io) {
+  io.name("Rover GPIO");
+
+  // Standard roles retain the rover's existing HUD controls while moving the
+  // electrical outputs to this ESP32 on either a Pi or laptop rover host.
   RoverCameraServoConfig cameraServo;
   cameraServo.pin = 14;
   cameraServo.minimumAngleDegrees = -15;
@@ -34,89 +43,55 @@ void registerBuiltInRoverControls() {
   cameraServo.maximumPulseMicroseconds = 2100;
   cameraServo.allowRawPulse = false;
   cameraServo.inverted = false;
-  peripheral.addRoverCameraServo(cameraServo);
+  io.addCameraServo(cameraServo);
 
   RoverDigitalOutputConfig headlight;
   headlight.pin = 18;
   headlight.polarity = OutputPolarity::ActiveHigh;
   headlight.initiallyOn = false;
-  peripheral.addRoverHeadlight(headlight);
+  io.addHeadlight(headlight);
 
   RoverDigitalOutputConfig laser;
   laser.pin = 16;
   laser.polarity = OutputPolarity::ActiveHigh;
   laser.initiallyOn = false;
-  peripheral.addRoverLaser(laser);
+  io.addLaser(laser);
-}
 
-void registerGenericControls() {
+  pinMode(kSpecialActionPin, OUTPUT);
-  // Registration order is UI order. This servo slider is handled entirely by
+  digitalWrite(kSpecialActionPin, LOW);
-  // standard Firmata SET_PIN_MODE and EXTENDED_ANALOG messages from roverd.
+
+  // Accessory controls render in precisely this registration order.
   SliderControlConfig servoPosition;
-  servoPosition.id = "servoPosition";
   servoPosition.name = "Servo position";
   servoPosition.minimum = 0;
   servoPosition.maximum = 180;
 
-  FirmataServoOutput servoOutput;
+  ServoOutput servoOutput;
   servoOutput.pin = 13;
-  peripheral.addServoSlider(servoPosition, servoOutput);
+  io.addSlider(servoPosition, servoOutput);
 
-  // PWM brightness is another standard Firmata output. No sketch callback is
-  // involved when the driver moves this slider.
   SliderControlConfig lightBrightness;
-  lightBrightness.id = "lightBrightness";
   lightBrightness.name = "Light brightness";
   lightBrightness.minimum = 0;
   lightBrightness.maximum = 255;
 
-  FirmataPwmOutput lightOutput;
+  PwmOutput lightOutput;
   lightOutput.pin = 17;
-  peripheral.addPwmSlider(lightBrightness, lightOutput);
+  io.addSlider(lightBrightness, lightOutput);
 
-  // A custom momentary control receives both press and release. This example
-  // runs a one-shot action only on press, but a motor could use both values to
-  // start while held and stop on release.
   ButtonControlConfig specialAction;
-  specialAction.id = "specialAction";
+  specialAction.name = "Special action";
-  specialAction.name = "Run special action";
   specialAction.mode = ButtonMode::Momentary;
-  peripheral.addButton(specialAction, [](bool pressed) {
+  io.addButton(specialAction, runSpecialAction);
-    if (pressed) {
+
-      runSpecialAction();
+  NumberControlConfig repeats;
-    }
+  repeats.name = "Repeat count";
-  });
+  repeats.minimum = 1;
-}
+  repeats.maximum = 20;
-}  // namespace
+  io.addNumber(repeats, setRepeatCount);
-
+
-void setup() {
+  TextControlConfig message;
-  pinMode(kSpecialActionPin, OUTPUT);
+  message.name = "Display message";
-  digitalWrite(kSpecialActionPin, LOW);
+  message.maximumLength = 64;
-
+  io.addText(message, setDisplayMessage);
-  registerBuiltInRoverControls();
-  registerGenericControls();
-
-  // Supplying Serial as a Stream keeps all protocol code identical between a
-  // CH340/CP210x UART bridge and native ESP32-S3 USB CDC. Only PlatformIO's S3
-  // build flags differ.
-  Serial.begin(115200);
-  Firmata.begin(Serial);
-  peripheral.begin(firmataExtension);
-
-  // A Firmata system reset establishes declared initial output states and also
-  // proves that all callbacks were installed before normal traffic begins.
-  Firmata.parse(SYSTEM_RESET);
-}
-
-void loop() {
-  // Processing one complete parser unit at a time prevents a long serial burst
-  // from starving application work while still draining ordinary USB traffic
-  // quickly on both supported transports.
-  while (Firmata.available()) {
-    Firmata.processInput();
-    if (!Firmata.isParsingMessage()) {
-      break;
-    }
-  }
-  peripheral.update();
 }