Servo Motor

Overview

Servo peripherals use PWM signals to control servo angle (0°-180°), suitable for robotic arms, pan-tilt mounts, door locks, robot joints, and other scenarios.

Supported Peripheral Types

Type	type Value	Description
PWM_SERVO	41	Servo (PWM angle control)

Hardware Wiring

SG90 / MG996R Servo

Servo Wire Color	Connection	Description
Orange/Yellow (Signal)	GPIO	PWM signal pin
Red (VCC)	5V	Power supply (external power)
Brown/Black (GND)	GND	Ground

SG90 small servos can be powered directly from ESP32's 5V pin; MG996R and other high-torque servos require an independent external power supply.

Configuration

Method 1: Web Interface Configuration (Recommended)

Before saving servo configuration, verify PWM pin, angle range, and independent power supply capability.

Step 1: Navigate to Peripheral Management Page

1. Open a browser and navigate to the ESP32 IP address
2. After logging in, click Peripheral Configuration in the left menu

Step 2: Add Servo Peripheral

1. Click the Add Peripheral button

2. Fill in the configuration:

   Field	Value	Description
   Peripheral ID	servo1	Unique identifier
   Name	SG90 Servo or Door Lock Servo	Display name
   Peripheral Type	PWM Servo (type: 41)	Servo control
   Pin Configuration	27	Signal pin
   Min Pulse Width	544	Corresponds to 0° (microseconds)
   Max Pulse Width	2400	Corresponds to 180° (microseconds)
   Default Angle	90	Power-on initial angle

3. Click Save

Step 3: Verify Configuration

1. Find the newly added peripheral in the peripheral list
2. Click the Enable toggle
3. Use the control panel to test angles (0-180)

⚠️ Tip: MG996R and other high-torque servos require external 5V/2A power supply, cannot be powered directly from ESP32

---

Method 2: JSON Configuration File Import

Add the following configuration to the peripherals array in data/config/peripherals.json:

{
  "id": "servo1",
  "name": "Servo",
  "type": 41,
  "enabled": false,
  "pins": [27],
  "params": {
    "minPulse": 544,
    "maxPulse": 2400,
    "defaultAngle": 90
  }
}

Parameter Description

Parameter	Description
minPulse	Minimum pulse width (μs), corresponds to 0°, default 544
maxPulse	Maximum pulse width (μs), corresponds to 180°, default 2400
defaultAngle	Default angle after power-on (0-180)

pins[0] = Servo signal pin

Control Commands

Send angle values via MQTT or Web interface:

[{"id": "servo1", "value": "90"}]

• Value range: 0 ~ 180 (unit: degrees)
• Send 0 to turn to minimum angle, 180 to turn to maximum angle

Peripheral Execution Integration

Web Interface Configuration Steps

Create Servo Control Rule

1. Switch to the Peripheral Execution Management tab
2. Click the Add Rule button
3. Configure trigger (event trigger, timer trigger, or platform trigger)
4. Add servo action:
   • Action Type: Set PWM (servo uses PWM control)
   • Target Peripheral: servo1
   • Action Value: 90 (angle 0-180)
5. Click Save

💡 Tip: Can use script actions to achieve servo swinging effect (PERIPH servo1 PWM angle)

---

JSON Configuration Example

Button Control Servo Angle

{
  "name": "Button Door Open",
  "enabled": true,
  "triggers": [
    {
      "type": "event",
      "params": { "periphId": "btn1", "event": "pressed" }
    }
  ],
  "actions": [
    {
      "type": "servo_write",
      "params": {
        "periphId": "servo1",
        "value": "180"
      }
    }
  ]
}

Timed Swinging

{
  "name": "Servo Swing",
  "enabled": true,
  "triggers": [
    {
      "type": "timer",
      "params": { "interval": 2000 }
    }
  ],
  "actions": [
    {
      "type": "servo_write",
      "params": {
        "periphId": "servo1",
        "value": "0"
      }
    },
    { "type": "delay", "params": { "ms": 1000 } },
    {
      "type": "servo_write",
      "params": {
        "periphId": "servo1",
        "value": "180"
      }
    }
  ]
}

Data Report Format

Current angle is reported via MQTT:

[{"id": "servo1", "value": "90"}]

Notes

1. Power Requirements: High-torque servos (MG996R) require independent 5V/2A power supply; USB power may cause ESP32 restart
2. Signal Level: ESP32 outputs 3.3V PWM, most servos can recognize it normally, no level shifting needed
3. Jitter Issues: If slight jitter occurs, adjust minPulse/maxPulse parameters to match specific servo model
4. Angle Limits: Avoid mechanical jamming; limit angle range based on actual installation
5. Pin Selection: Any ESP32 GPIO can output PWM; recommend avoiding Strapping pins (GPIO 0/2/12/15)