Servo Config API

ArmorLink 0.4.0 adds a servo configuration helper for firmware that exposes servo positions to the ArmorLink App and Web Node Configurator.

The helper stores servo settings in an ArmorLinkServoConfig struct and expands them into normal configuration fields with servo-specific semantics.

Data Structure

struct ArmorLinkServoConfig {
  int pin = -1;
  int openPosition = 90;
  int closedPosition = 90;
  int minPulseUs = 500;
  int maxPulseUs = 2400;
};

Member	Description
pin	ESP32 GPIO used by the servo. -1 means not configured.
openPosition	Servo angle used for the open state.
closedPosition	Servo angle used for the closed state.
minPulseUs	Minimum pulse width passed to ESP32Servo::attach.
maxPulseUs	Maximum pulse width passed to ESP32Servo::attach.

Registering a Servo

ArmorLinkServoConfig servo1{16, 10, 158, 500, 2400};

module.config()
    .addServoConfig("servo1", &servo1)
    .section("Servo 1")
    .gpio(16)
    .openPosition(10)
    .closedPosition(158)
    .pulseRange(500, 2400);

This creates a coherent servo setup block for setup tools while still using standard config fields internally.

Generated Fields

For addServoConfig("servo1", &servo1), the helper creates fields based on the builder calls:

Builder call	Generated key	Semantic
.gpio(16)	servo1Pin	servo.gpio
.openPosition(10)	servo1Open	servo.openPosition
.closedPosition(158)	servo1Closed	servo.closedPosition
.pulseRange(500, 2400)	servo1MinPulseUs, servo1MaxPulseUs	servo.minPulseUs, servo.maxPulseUs

All generated fields share semanticGroup("servo1") so UI tools can understand that they belong to the same servo.

Optional Servos

Use visibleWhen(...) to show a servo only when it is enabled by another setting.

int servoCount = 2;
ArmorLinkServoConfig servo3{-1, 90, 90, 500, 2400};

module.config()
    .addInt("servoCount", &servoCount, 2)
    .label("Servo Count")
    .section("Faceplate")
    .range(2, 3)
    .step(1)
    .rebootRequired();

module.config()
    .addServoConfig("servo3", &servo3)
    .section("Servo 3")
    .visibleWhen("servoCount", 3)
    .gpio(-1)
    .openPosition(90)
    .closedPosition(90)
    .pulseRange(500, 2400);

Servo Test Command

The Web Node Configurator can move a configured servo through the serial command path.

Request shape:

{
  "type": "servo_move",
  "servo": "servo1",
  "position": 90
}

ArmorLink validates that the servo exists and that its GPIO is configured before moving it.

Recommended Ranges

Field	Suggested range
GPIO	-1..48
Open/closed position	0..180
Pulse width	Usually 500..2400 microseconds

Use conservative values while testing physical builds. Always verify servo direction and travel before connecting full mechanical load.