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:

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino

lib_deps =
  legop3/RoverPeripheral @ ^2.0.0

Native-USB ESP32-S3 DevKitC:

[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():

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

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:

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

SliderControlConfig position;
position.name = "Arm position";
position.minimum = 0;
position.maximum = 180;

ServoOutput servo;
servo.pin = 13;

peripheral.addSlider(position, servo);

PWM slider

SliderControlConfig brightness;
brightness.name = "Light brightness";
brightness.minimum = 0;
brightness.maximum = 255;

PwmOutput light;
light.pin = 17;

peripheral.addSlider(brightness, light);

Digital button

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

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

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

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

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:

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