Maestro Setup

Maestro Setup

Pololu Maestro servo controllers are how NaviCore moves servos — locally over a wired bus, and remotely over ESP‑NOW. Getting multiple Maestros to share a bus is the most common stumbling block, so this page walks through it end to end. For the action syntax see Actions Reference; for pins see Hardware and Wiring.

---

The model: 8 logical slots

NaviCore has 8 logical Maestro slots (1–8). A Maestro action targets a slot; where that slot physically lives is set once in Config → Maestro (Locations):

Slot type	Where the bytes go
Local	Out the wired Maestro bus on GPIO6 (Serial2), at the local‑Maestro baud.
Remote	Broadcast over ESP‑NOW; any WCB with Kyber_Remote enabled forwards them to its Maestro port.
Disabled	Slot ignored.

Each slot also stores a device number — see below.

In the config schema this is the maestros[] array (8 entries) plus auxBaud.maestro. See Configuration Schema.

---

Device numbers are mandatory

NaviCore always speaks Pololu protocol (never "compact"), which means every command is addressed to a specific device number. This is what lets several Maestros sit on one wire (or one ESP‑NOW broadcast bus) and only the addressed one act.

Every Maestro must have a unique device number, and that number must match what you enter for its slot in NaviCore. Two Maestros with the same number on one bus will both react — and collide.

Set it in Maestro Control Center

1. Connect the Maestro to a PC via USB, open Pololu Maestro Control Center.
2. Serial Settings tab:
   • Serial mode: UART, fixed baud rate (set it to 115200 to match NaviCore's default), or UART, detect baud rate.
   • Device Number: give each Maestro a unique value (0–127).
   • CRC: disabled (NaviCore doesn't send CRC).
3. Apply Settings (writes to the Maestro's own flash).

Then in NaviCore's Maestro Locations panel, set that slot's device number to the same value and choose Local or Remote.

---

Wiring a local Maestro

• NaviCore TX = GPIO6 → Maestro RX.
• Common GND.
• Maestro TX → NaviCore RX on GPIO7 is optional for fire‑and‑forget commands, but required to use the 2‑way Read live queries (Get Position / Moving State / Errors). Without this wire those reads simply time out. See Reading back from a Maestro below.
• Baud defaults to 115200 (auxBaud.maestro). Either set the Maestro to fixed 115200 or use detect baud rate.
• Multiple local Maestros: daisy‑chain their serial lines on the same bus; unique device numbers keep them independent.

---

Remote Maestros (over WCB)

No wire from NaviCore. NaviCore broadcasts the Maestro bytes on the Kyber path; a WCB elsewhere forwards them to the Maestro wired to that WCB. Set the slot to Remote and give it the right device number.

For the bytes to actually reach servos, the receiving WCB needs two things: (1) Kyber forwarding enabled — ?KYBER,REMOTE (forward broadcasts) or ?KYBER,LOCAL,S<port> — and (2) a Maestro port configured on that WCB so it knows where to send the forwarded bytes. Miss either and the broadcast is silently dropped. See WCB Network.

Discrete Maestro writes to a Remote slot travel as raw Pololu bytes on the broadcast bus (device‑number filtered), exactly as a Local slot would receive them. Only Maestro reads (the Read live queries) and the explicit Maestro (via WCB) command board use the ;M<dev>,<verb> text form instead — see below.

---

Command forms

A Maestro action's cmd is one of:

cmd	Effect
setTarget,<ch>,<pos>	Move servo channel <ch> (0–31) to <pos> quarter‑µs (e.g. 4000–8000). Clamped to 14‑bit (0–16383).
setSpeed,<ch>,<spd>	Set channel speed limit (0–16383; 0 = unlimited). Sticky — see below.
setAccel,<ch>,<acc>	Set channel acceleration limit (0–255; 0 = unlimited). Sticky.
setSpeedAccel,<ch>,<spd>,<acc>	Set both the speed and acceleration limit on <ch> in one action.
goHome	Send all channels to their configured home positions.
stopScript	Stop the Maestro's onboard script.
restartScript,<n>[,p<N>][,o]	Start the onboard script at subroutine <n> (0–127). Optional p<N> selects the action's own easing profile (p0–p5); optional o lets a switch's active easing override it. See Easing below.
subParam,<sub>,<param>	Run onboard subroutine <sub> (0–127), first pushing <param> (0–16383) onto the Maestro's script stack (Pololu command 0x28). Surfaced in the library as Run subroutine + parameter.
setEasing,<pN|off|release>	Set this Maestro's active (fallback) easing — a profile p0–p5, off (full speed), or release (impose nothing). Usually emitted by a Set active easing switch action. See Easing below.

⚠️ Speed and acceleration limits are sticky: once set on a channel they persist — affecting every later move, including joystick pass‑through — until you reset them to 0.

Knobs/sliders/gimbal axes can also drive a Maestro continuously (Maestro Pass‑Through) — pick a slot, a servo channel, and the quarter‑µs range at the stick's min/max. Each pass‑through output can also carry an easing profile (below) and two per‑output options, Center = closed and Release when idle — see Pass‑through servo options. See Config Tool Guide.

You author these commands in the Action Editor → Command Library from one of two Maestro boards — see Authoring Maestro commands below and Action Editor and Command Library.

---

Easing (formerly smoothing)

Easing ramps a servo's speed and acceleration in the Maestro's own hardware (an S‑curve) so moves glide instead of snapping. It is configured in the Smoothing Profiles tab.

• There are exactly 6 named profiles (wire form p0–p5; profile 0 is named Default). Each profile is a per‑(Maestro 1–8, channel 0–31) map of a Maestro Speed and Accel value.
• Each channel row has a Speed and an Accel slider on a 0–100 scale — slide right = more easing (slower / gentler). An All channels master pair sets every enabled channel in the profile at once.
• A pass‑through knob can reference one profile (None = instant), and a Set active easing switch action can load one on demand, so the same servos can glide or snap under a switch.

Easing is re‑applied on config save — a changed profile or knob takes effect immediately, no reboot.

Priority: local‑first, with an opt‑in switch override

The old binary Snappy toggle is gone. Easing now resolves by priority:

• A knob or script that has its own easing wins by default.
• A knob/script with no easing follows the switch's active easing (setEasing).
• To let the switch win anyway, tick Allow switch to override on that knob or sequence (wire suffix ,o on restartScript).

The Set active easing switch action's dropdown is the 6 profile names plus Off – full speed and Release – local only (the default, which imposes nothing). This active easing is a fallback, not a master override.

---

Reading back from a Maestro (Read live)

NaviCore is normally fire‑and‑forget, but each Local or Remote slot row in the Maestro Locations panel has a Read live row — a channel dropdown plus Position, Moving?, and Errors buttons. These issue Pololu queries and show the reply inline. The same queries are available as CLI Commands:

Query	CLI form	Reply
Get Position	?MAE,GET,<slot>,<ch>	2‑byte value in quarter‑µs
Get Moving State	?MAE,MOVING,<slot>	0/1 (still ramping?)
Get Errors	?MAE,ERR,<slot>	2‑byte error bitmask — clears the register on read

• Local slots answer synchronously off Serial2 RX (GPIO7) with a ~25 ms deadline — the RX wire must be connected.
• Remote slots broadcast the query as a ;M<dev>,<verb> text verb; the hosting WCB is expected to read its Maestro and unicast the reply home as :MQR,…. That WCB relay is not shipped yet, so remote reads currently return "(no response)".
• Only one query can be outstanding at a time (replies carry no address — the caller tracks which it sent), and Get Moving State is Mini Maestro 12/18/24 only, not the Micro 6.

---

Authoring Maestro commands: two boards

The Command Library offers two Maestro boards for the same verb set:

• Maestro (Pololu servo) — targets a configured slot 1–8 via Send to (Maestro) and emits the bare cmd (e.g. setTarget,0,6000). Use this for Local or Remote slots you've set up in Maestro Locations.
• Maestro (via WCB) — every command is a ;M<id>,verb string (Maestro id 0 = all, 1–8 = board, 9 = local), routed like any other WCB verb with a WCB/Serial destination on the action row.

---

Pass‑through servo options

A newly added pass‑through output defaults (in the config tool) to both options on; the firmware struct defaults are off. Configure them per output in the knob editor:

• Center = closed (midClosed) — the stick center maps to posMin (closed); only the upper half of stick travel (center → full) sweeps posMin → posMax. Keeps a servo closed at rest, at the cost of the lower half of stick range.
• Release when idle (releaseIdleMs, default 1500 ms; min 100, max 60000) — after this many ms with no stick movement, NaviCore sends Set Target 0 so the Maestro stops pulsing and the servo goes limp and silent; the next stick move re‑energizes it.

⚠️ A released servo has no holding torque. Use Release when idle only where gravity, friction, or a magnet holds the mechanism — never on a servo bearing a load.

---

Troubleshooting

Symptom	Likely cause
Nothing moves (local)	TX/RX swapped, no common GND, baud mismatch (set Maestro to 115200 or detect‑baud), or slot not set Local.
Nothing moves (remote)	Receiving WCB has no Maestro port configured, or Kyber forwarding isn't enabled on it (?KYBER,REMOTE / ?KYBER,LOCAL,S<port>); wrong device number; or slot not set Remote.
Every Maestro reacts to one command	Duplicate device numbers — give each a unique number in Control Center and match it in NaviCore.
Servo jitters / wrong range	setTarget qus out of the servo's range; clamp posMin/posMax to a safe travel.
Read live shows "(no response)"	Local: GPIO7 (Serial2 RX) not wired, wrong device #, or Get Moving State on a Micro 6 (Mini‑only). Remote: expected — the WCB :MQR relay isn't shipped yet.
Servo goes limp / silent at rest	Release when idle is on (no holding torque while released) — raise its ms or turn it off.
Stick can't open the servo from center‑down	Center = closed is on — only the upper half of stick travel opens it.
Servo won't ramp / moves stay snappy	No easing profile selected on the knob/script, or a sticky setSpeed/setAccel of 0. Set a Smoothing profile or non‑zero limits.
Works on the bench, not in the droid	Power — servos can brown out the bus; give the Maestro its own servo‑power supply with shared ground.

More in Troubleshooting.

---

See also: Actions Reference · Action Editor and Command Library · Hardware and Wiring · WCB Network · CLI Commands