BLE protocol

This page documents the Bluetooth Low Energy protocol used by ServoMote. Use this as a reference if you want to implement your own ESP32 firmware or build a custom client.

Service and characteristic

Property	Value
Service UUID	4fafc201-1fb5-459e-8fcc-c5c9c331914b
Characteristic UUID	beb5483e-36e1-4688-b7f5-ea07361b26a8
Properties	Read, Write, Notify
Advertising name	ServoMote (configurable in sketch)

The characteristic supports CCCD (Client Characteristic Configuration Descriptor) for enabling notifications.

Commands

Commands are sent as text strings to the characteristic.

Set servo angle

servo_id:angle

Parameter	Type	Range	Description
servo_id	integer	1–16	The servo channel to control
angle	integer	0–180	The target angle in degrees

Example: 1:90 — set servo 1 to 90 degrees.

Get servo angle

servo_id

Parameter	Type	Range	Description
servo_id	integer	1–16	The servo channel to query

Requests the current angle of a servo. The ESP32 responds with OK:servo_id:angle. If the servo has not been set since power-on, the returned angle is -1.

Example: 1 — get the current angle of servo 1.

The app uses this on connect to determine whether each servo needs to be initialized to its configured initial position.

Responses

Responses are sent as notifications from the characteristic.

Success

OK:servo_id:angle

Confirms the servo was set to the requested angle.

Example: OK:1:90

Error

ERROR:message

Indicates that the command could not be executed.

Example: ERROR:Invalid servo ID

Implementation notes

• Commands and responses are plain UTF-8 text strings
• Each command controls a single servo — send multiple commands for multiple servos
• The ESP32 processes commands sequentially
• Angle values outside 0–180 are rejected with an error
• The characteristic must support both Write and Notify for bidirectional communication