init
This commit is contained in:
Executable
+496
@@ -0,0 +1,496 @@
|
||||
# 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"
|
||||
Reference in New Issue
Block a user