Files

497 lines
16 KiB
Markdown
Raw Permalink Normal View History

2026-05-20 21:48:13 +02:00
# 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`, or `SERVO_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 `#define`s 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:
- `AB` selects a quadrature encoder
- `KTECH_IME` selects the KTech encoder class
- `SERIAL_BRIDGE` selects the serial bridge encoder path
### 3. `AXIS*_SERVO_FEEDBACK` selects the feedback controller
`Mount.axis.cpp` currently uses:
- `PID` for a single PID set
- `DUAL_PID` for separate tracking and goto PID sets
That means these defines feed directly into the live controller:
- `AXIS*_PID_P`
- `AXIS*_PID_I`
- `AXIS*_PID_D`
- `AXIS*_PID_P_GOTO`
- `AXIS*_PID_I_GOTO`
- `AXIS*_PID_D_GOTO`
- `AXIS*_PID_SENSITIVITY`
### 4. `AXIS*_SERVO_FLTR` selects the encoder filter
Current mount-axis choices are wired in through `Mount.axis.cpp`:
- `OFF`
- `KALMAN`
- `LEARNING` for Axis1
- `ROLLING`
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:
```cpp
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_DEGREE` is still the mount axis scale
- `AXIS*_MOTOR_STEPS_PER_DEGREE` matters 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*_REVERSE`
- `AXIS*_ENCODER_REVERSE`
- `AXIS*_ENCODER_ORIGIN`
These do different jobs:
- `AXIS*_REVERSE` changes commanded motor direction
- `AXIS*_ENCODER_REVERSE` changes encoder sign
- `AXIS*_ENCODER_ORIGIN` is the stored zero/origin for absolute encoder cases
There is also a runtime reverse path.
In practical terms:
- `AXIS*_ENCODER_REVERSE` is the baseline wiring/sign correction for the encoder
- `AXIS*_REVERSE` is 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:
- [Config.defaults.h](/c:/Users/hjd19/Documents/Programs/GitHub/OnStepX/src/Config.defaults.h)
- [Mount.axis.cpp](/c:/Users/hjd19/Documents/Programs/GitHub/OnStepX/src/telescope/mount/Mount.axis.cpp)
- [Validate.h](/c:/Users/hjd19/Documents/Programs/GitHub/OnStepX/src/Validate.h)
## Minimum settings to get right first
For each servo mount axis, focus on these first:
1. Driver model
- set the axis driver model to the correct servo type
Example:
```cpp
#define AXIS1_DRIVER_MODEL SERVO_PE
```
2. Axis scale
- set `AXIS*_STEPS_PER_DEGREE` correctly
- for stepper-based servo drivers, also check `AXIS*_MOTOR_STEPS_PER_DEGREE`
if your hardware needs it
If the scale is wrong, almost everything else becomes confusing.
3. Encoder type
- set `AXIS*_ENCODER` to the actual encoder you are using
4. Directions
- `AXIS*_REVERSE` controls motor direction
- `AXIS*_ENCODER_REVERSE` controls encoder direction
These are separate on purpose. Do not assume that fixing one also fixes the
other.
The practical rule is:
- use `AXIS*_ENCODER_REVERSE` to make encoder counts agree with real motion
- use `AXIS*_REVERSE` to 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.
5. 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_REVERSE` first
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:
- `P` reacts to present error
- `I` corrects lingering offset
- `D` helps 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_GOTO`
- `AXIS*_PID_I_GOTO`
- `AXIS*_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 `I` small
- use little or no `D` at first
What to watch for:
- if the axis feels weak or lags badly, `P` may be too low
- if it hunts or oscillates, `P` may be too high
- if it reaches the target but stays offset, add a little `I`
- if it overshoots and rings, reduce `P` or add a small amount of `D`
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, `0` is 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_MONITOR`
- `DISPLAY_SERVO_ORIGIN_CONTROLS`
- `DISPLAY_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:
1. scale
2. encoder direction
3. motor direction
4. 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"