# 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"