16 KiB
Executable File
Servo Setup Guide
Purpose
This guide is for setting up a mount axis that uses servo feedback in OnStepX.
It is written for users who want a practical bring-up sequence:
- what to configure first
- what to test before moving faster
- what to adjust when things go the wrong way
This guide is intentionally light on control theory. The goal is to help you get to a safe, working setup without having to understand every low-level detail first.
Before you begin
Have these basics sorted out first:
- the controller pinmap matches your hardware
- power wiring is correct
- motor wiring is correct enough that the driver powers up safely
- encoder wiring is correct enough that counts can be read reliably
- hard limits or other motion safeguards are planned before unattended use
Important safety note:
- do not leave a new servo setup tracking unattended until you have verified limits, stop behavior, and the direction of both the motor and encoder
- a servo that is "mostly working" can still drive hard into a stop if the setup is wrong
What "servo" means here
In OnStepX, a servo axis is a motor axis that closes the loop using encoder feedback.
In practical terms that means:
- the motor moves the axis
- the encoder tells OnStepX where the axis actually is
- OnStepX keeps correcting the motor so the axis reaches and holds the target
For the mount axes, the main items are usually:
- a servo-capable driver model such as
SERVO_PE,SERVO_EE,SERVO_TMC2209,SERVO_TMC5160, orSERVO_KTECH - an encoder type such as
AB,KTECH_IME, or another supported encoder - sensible axis scale and direction settings
- usable PID values
This guide is mainly about the built-in servo axis types. ODrive-based systems have their own workflow and deserve separate documentation.
How the current #defines tie together
If you are comparing old example configs, this is the compile-time chain that matters in the current code.
1. AXIS*_DRIVER_MODEL decides whether the axis is treated as a servo
If AXIS1_DRIVER_MODEL or AXIS2_DRIVER_MODEL is in the servo-driver range,
Config.defaults.h defines AXIS*_SERVO_PRESENT.
That is the switch that makes the mount axis build as a servo axis instead of a step/dir axis.
2. AXIS*_ENCODER selects the encoder class
When AXIS*_SERVO_PRESENT is true, Mount.axis.cpp selects the encoder from
AXIS*_ENCODER.
Examples:
ABselects a quadrature encoderKTECH_IMEselects the KTech encoder classSERIAL_BRIDGEselects the serial bridge encoder path
3. AXIS*_SERVO_FEEDBACK selects the feedback controller
Mount.axis.cpp currently uses:
PIDfor a single PID setDUAL_PIDfor separate tracking and goto PID sets
That means these defines feed directly into the live controller:
AXIS*_PID_PAXIS*_PID_IAXIS*_PID_DAXIS*_PID_P_GOTOAXIS*_PID_I_GOTOAXIS*_PID_D_GOTOAXIS*_PID_SENSITIVITY
4. AXIS*_SERVO_FLTR selects the encoder filter
Current mount-axis choices are wired in through Mount.axis.cpp:
OFFKALMANLEARNINGfor Axis1ROLLING
If you are starting fresh, OFF is the simplest baseline.
5. Some servo driver models also use motor-side scaling
For stepper-based servo drivers such as SERVO_TMC2209, SERVO_TMC5160, and
SERVO_KTECH, the code uses this ratio:
AXIS*_MOTOR_STEPS_PER_DEGREE / AXIS*_STEPS_PER_DEGREE
That ratio is passed into the servo driver in Mount.axis.cpp.
In practical terms:
AXIS*_STEPS_PER_DEGREEis still the mount axis scaleAXIS*_MOTOR_STEPS_PER_DEGREEmatters when the motor-side step scale is not the same as the encoder-side axis scale
These two are rarely the same. Sometimes the encoders are on the mount axes and there is not reduction and other times there is. Then the encoder has a resolution as well. On the other hand the motor almost always has an associated reduction and full-steps per rotation and 256 micro-steps per full-step.
6. Direction and origin are separate inputs to ServoMotor
The final ServoMotor object is built with:
AXIS*_REVERSEAXIS*_ENCODER_REVERSEAXIS*_ENCODER_ORIGIN
These do different jobs:
AXIS*_REVERSEchanges commanded motor directionAXIS*_ENCODER_REVERSEchanges encoder signAXIS*_ENCODER_ORIGINis the stored zero/origin for absolute encoder cases
There is also a runtime reverse path.
In practical terms:
AXIS*_ENCODER_REVERSEis the baseline wiring/sign correction for the encoderAXIS*_REVERSEis the baseline motion-direction choice for the axis- if the axis reverse state is changed at runtime, OnStepX also flips the control direction so the feedback loop still makes sense
That is why direction can appear to be handled at more than one level. It is. Those levels are there for different reasons.
7. AXIS*_TARGET_TOLERANCE is not servo-only, but it matters a lot for servo behavior
AXIS*_TARGET_TOLERANCE is passed into the Axis object and affects when the
system considers the axis near its target.
That is why many servo example configs override it even though it is not strictly a servo-only define.
8. Absolute encoder authority is inferred from encoder type
In Validate.h, some encoder types automatically imply absolute encoder
authority on servo axes. That affects startup trust behavior.
So for servo users, AXIS*_ENCODER is doing more than just picking a driver.
It can also affect how startup authority is determined.
Practical takeaway about old example configs
Some example servo configs are older than the current code and may not reflect today's best defaults.
Treat them as:
- examples of working combinations
- hints for starting values
- not as an exact description of the current wiring between settings
If there is a conflict, trust the current code path in:
Minimum settings to get right first
For each servo mount axis, focus on these first:
- Driver model
- set the axis driver model to the correct servo type
Example:
#define AXIS1_DRIVER_MODEL SERVO_PE
- Axis scale
- set
AXIS*_STEPS_PER_DEGREEcorrectly - for stepper-based servo drivers, also check
AXIS*_MOTOR_STEPS_PER_DEGREEif your hardware needs it
If the scale is wrong, almost everything else becomes confusing.
- Encoder type
- set
AXIS*_ENCODERto the actual encoder you are using
- Directions
AXIS*_REVERSEcontrols motor directionAXIS*_ENCODER_REVERSEcontrols encoder direction
These are separate on purpose. Do not assume that fixing one also fixes the other.
The practical rule is:
- use
AXIS*_ENCODER_REVERSEto make encoder counts agree with real motion - use
AXIS*_REVERSEto make commanded axis motion go the right way
Do not use motor reverse as a substitute for fixing an encoder that counts the wrong direction.
If the motor and encoder direction are NOT in agreement the axis will run-away. There is code that attempts to detect run-away, or oscillation, which will hopefully shut the axis down in short order if this happens.
- Conservative limits
- set reasonable axis limits before doing long moves
- keep first tests short and slow
Recommended bring-up order
This is the safest order for a fresh servo setup.
1. Bring up one axis at a time
If possible, get Axis1 behaving first, then copy the pattern to Axis2.
Trying to solve both axes at once can hide simple mistakes.
2. Verify encoder direction before worrying about motor direction
The encoder direction must make physical sense.
When the axis moves in a positive direction, the encoder should report that same direction. If it does not:
- fix
AXIS*_ENCODER_REVERSEfirst
Do this before serious PID tuning.
3. Verify motor direction
Once the encoder reads correctly:
- use a small manual move
- confirm the axis moves the expected way
- if not, fix
AXIS*_REVERSE
This order matters.
If the encoder sign is wrong, the control loop can "fight" the motion and a later motor-direction change may only hide the real problem.
4. Start with small motions only
For early tests:
- use guide moves or very short slews
- keep your hand near power-off
- do not start with full-length gotos
5. Confirm the axis can stop cleanly
Before tuning for performance, verify that:
- the axis starts moving promptly
- the axis stops when motion stops
- there is no runaway, buzzing, or repeated overshoot
If anything looks wrong, stop and correct direction, scale, or wiring before going further.
A simple way to think about PID
You do not need to be a controls engineer to get started.
Use this mental model:
Preacts to present errorIcorrects lingering offsetDhelps calm motion and reduce overshoot
OnStepX commonly uses:
- one PID set for tracking
- another PID set for slewing/goto
Those are the _GOTO values:
AXIS*_PID_P_GOTOAXIS*_PID_I_GOTOAXIS*_PID_D_GOTO
Often since this uses feed-forward the goto parameters are less important. Also these can be changed instantly at runtime from the SWS or Website Plugin which makes tuning far far faster.
How motion feed-forward works now
This is one area where older servo examples can be misleading.
In current OnStepX, the servo path does not rely on PID correction alone. The motion command already includes a feed-forward component, and the exact motor-side behavior depends on the servo driver type.
TMC stepper servos
For TMC stepper servos such as SERVO_TMC2209 and SERVO_TMC5160:
- motion feed-forward is automatic
- OnStepX combines the requested motion with the feedback correction and sends a velocity command to the driver
In user terms:
- you do not usually "turn feed-forward on"
- it is part of how these servo drivers normally work
The main coupling setting is the counts-to-steps ratio:
- it starts from the config default based on
AXIS*_MOTOR_STEPS_PER_DEGREE / AXIS*_STEPS_PER_DEGREE - that ratio is also a runtime-adjustable axis parameter
So for TMC stepper servos, the important question is usually not whether feed-forward exists, but whether the counts-to-steps coupling is correct.
DC servos
For DC servo drivers such as SERVO_PE, SERVO_EE, SERVO_TMC2130_DC, and
SERVO_TMC5160_DC:
- the same upstream motion command still includes feed-forward
- but the driver side now has more explicit runtime coupling controls
The practical runtime knobs are:
- minimum motor power
- maximum motor power
- reversal protection delay
That means DC servo behavior is more dependent on the runtime motor-output settings than the TMC stepper-servo path is.
DC servo velocity control loop
DC servos can also use the newer motor-side velocity loop.
When enabled:
- the driver uses encoder-derived velocity as a measured feedback signal
- the motor-side control becomes feed-forward plus a velocity PI correction
When not enabled:
- the motor-side control is basically feed-forward duty mapping
In practical terms:
- without the velocity loop, DC servos depend more heavily on a good power map
- with the velocity loop, DC servos can regulate motor behavior more directly from measured encoder speed
Encoder velocity support
The newer DC velocity-loop behavior depends on encoder velocity estimation.
That comes from the encoder subsystem itself, not from the PID section.
So if you are working on a DC servo and velocity control is enabled:
- encoder quality matters even more than usual
- noisy or weak encoder velocity estimates can make tuning harder
Deadband and reversal protection
Two settings in the servo path can sound similar, but they do different jobs.
Zero deadband
The servo driver also has a low-speed command deadband.
In practical terms:
- very small requested motor velocities are treated as zero
- this helps prevent constant tiny nudges near standstill
- it is not the same thing as backlash compensation or target tolerance
If this is set too high:
- the axis can feel reluctant to make very small corrections
If it is set too low:
- the motor may keep twitching or chattering around zero
Reversal protection delay
DC servos also have a direction-change delay.
This is better thought of as reversal protection:
- when the commanded direction flips, the output is briefly held at zero
- that gives the drivetrain and driver a moment before power is applied in the opposite direction
This can be helpful when:
- the motor drive does not like abrupt reversals
- the axis has noticeable mechanical shock on direction changes
- you want gentler reversal behavior during tuning
So the practical distinction is:
- zero deadband suppresses tiny commands near zero
- reversal protection delay softens direction changes
Practical PID advice
Start simple:
- begin with modest
P - keep
Ismall - use little or no
Dat first
What to watch for:
- if the axis feels weak or lags badly,
Pmay be too low - if it hunts or oscillates,
Pmay be too high - if it reaches the target but stays offset, add a little
I - if it overshoots and rings, reduce
Por add a small amount ofD
Make small changes, then test again.
Avoid changing many things at once.
About PID_SENSITIVITY
AXIS*_PID_SENSITIVITY controls how OnStepX transitions between the tracking
PID set and the slewing PID set.
A practical rule of thumb:
- for many DC servos, a nonzero value can help
- for many stepper-based servos,
0is a reasonable starting point
If you are unsure:
- start with the value used by a similar example config
About target tolerance
AXIS*_TARGET_TOLERANCE gives the axis a little room around the target.
In user terms:
- too small can make the axis fussy and restless
- too large can make the final position sloppier than you want
If the axis seems to chatter around the target, this setting may be too tight.
First successful motion checklist
Once you have basic motion, verify these before calling it "working":
- guide moves are in the correct direction
- encoder direction remains correct through the full move
- the axis does not run away when motion starts
- the axis does not oscillate badly when motion stops
- tracking starts and holds without obvious hunting
- limits and stop behavior work as expected
Only after that should you move on to longer slews and unattended use.
Absolute encoders and origin
If your servo setup uses absolute encoders:
- the encoder origin must be established correctly
- startup trust behavior depends on that origin being believable
If you are not using absolute encoders:
- skip this part for initial bring-up
- get basic motion stable first
Useful optional UI aids
Some test configs enable extra web controls such as:
DISPLAY_SERVO_MONITORDISPLAY_SERVO_ORIGIN_CONTROLSDISPLAY_SERVO_CALIBRATION
These can make bring-up easier, especially while checking direction, settling, and origin behavior.
Common mistakes
These are the usual trouble spots:
- wrong encoder direction
- wrong motor direction
- wrong steps-per-degree
- tuning before verifying scale and direction
- trying full-speed slews too early
- leaving tracking enabled before limits and stop behavior are proven
If the setup behaves strangely, go back to:
- scale
- encoder direction
- motor direction
- only then PID tuning
A good first goal
Do not aim for perfect tracking on the first pass.
A good first milestone is:
- the axis moves the right way
- encoder feedback agrees with motion
- it stops cleanly
- it holds position without obvious instability
After that, refine tracking, slewing response, and final pointing performance.
Future improvements for this guide
Useful follow-up documentation would be:
- a separate ODrive setup guide
- a short PID tuning cookbook with symptom-based advice
- a checklist for absolute encoder origin setup
- a servo troubleshooting page with "if it does this, check that"