This commit is contained in:
sagiferi
2026-05-20 21:48:13 +02:00
parent a907d8ba74
commit d3c13f997e
446 changed files with 70716 additions and 0 deletions
+437
View File
@@ -0,0 +1,437 @@
# CAN Notes
## Purpose
These notes describe the current CAN interface in its most useful practical
role: interconnecting remote OnStepX peripheral features.
This note is mainly about using CAN so the main controller can talk to:
- a remote rotator
- one or more remote focusers
- a remote auxiliary-features node
It is not mainly about low-level motor/axis CAN protocols. Those are better
left for a later axis-oriented note.
## Quick Summary
The cleanest mental model is:
1. the main OnStepX controller runs the mount as usual
2. some peripherals can live on their own CAN-connected nodes
3. the main controller forwards the normal rotator, focuser, or auxiliary
feature operations to those remote nodes
So the current CAN feature set is best thought of as a way to distribute
peripherals around the system, not as "the whole mount over CAN."
## What CAN Is Good For Here
This design is most useful when you want the mount controller and some
peripheral functions to be physically separate.
Typical reasons include:
- keeping focuser or rotator electronics close to the OTA
- reducing long motor/sensor wiring runs
- letting one small remote node host accessory features near where they are used
- building a more modular system where peripherals can be added or moved more
easily
In this arrangement:
- the rotator, focusers, and auxiliary-feature controllers can stay with an OTA
- plugging in one CAN/power cable brings that whole peripheral set online
- the correct functionality and settings can then appear at the mount
controller immediately and work as one integrated system from Android App,
Smart Hand Controller, Smart Web Server, ASCOM, and similar clients
So the CAN link is not just carrying commands. It also helps turn an OTA
assembly into a more self-contained module that can be moved from one mount
controller to another with much less rework.
In other words, CAN is being used here as a practical interconnect between
cooperating OnStepX feature nodes.
## Connectors And Cable
For this CAN interconnect role, the preferred connector choices are:
- RJ12 as the standard light-duty connector
- GX12-6 as the standard rugged connector
The standard 6-pin wiring order is:
1. `GND`
2. `+12V`
3. `CAN_L`
4. `CAN_H`
5. `+12V`
6. `GND`
This duplicates power and ground at the outer pairs and keeps the CAN pair
together in the middle.
With quality connectors and cables, this arrangement is intended to carry:
- `12V @ 2A`
Recommended cable guidance:
- twisted-pair `24 AWG` is optimal
- straight quality RJ12 cable of `26 AWG` is acceptable for short runs of about
`2 to 3 meters`
So the practical idea is:
- use RJ12 for lighter-duty short interconnects
- use GX12-6 where a more rugged connector is needed
- keep cable quality high if you expect the same cable to carry both CAN and
accessory power
## Termination
The mount controller is treated as one terminating end of the CAN bus.
In the standard arrangement:
- the mount controller has a built-in `120 Ohm` termination resistor
- the remote nodes are daisy-chained in the normal CAN fashion
- the far end of the chain gets the second `120 Ohm` termination resistor
For this system, that far-end termination can be provided by plugging a custom
terminating modular jack or `GX12-6` connector into the last node in the chain.
So the intended layout is the normal two-ended CAN termination pattern:
- one `120 Ohm` terminator at the mount controller
- one `120 Ohm` terminator at the last node
not a terminator at every intermediate node.
## The Current Remote Peripheral Types
The current CAN remote-node support is centered on three feature families:
### Rotator
The main controller can treat a rotator as remote.
That means:
- the rotator logic still looks like rotator functionality from the user side
- but the actual rotator feature can live on a CAN-connected node
- the remote node hosts the local Axis3 rotator implementation and answers the
requests
This is a natural fit when the rotator hardware is physically mounted on the
instrument side and you do not want all of that wiring returning to the main
controller.
### Focusers
The focuser support is especially useful for distributed systems.
The current model allows:
- up to six remote focusers
- heartbeat-based discovery/presence tracking
- the main controller to proxy focuser operations over CAN
This is a good fit for:
- separate main and guide focusers
- multiple optical trains
- distributed focus hardware mounted near different instruments
From the system-design point of view, this is one of the more attractive uses
of CAN in the current tree because focusers are naturally peripheral and often
benefit from being located close to the mechanics they drive.
### Auxiliary Features
Auxiliary features can also live on a remote CAN node.
This is useful for things such as:
- switches
- dew-heater style outputs
- analog outputs
- intervalometer or related accessory functions
- other feature-board style I/O that is convenient to place away from the main
controller
So a remote auxiliary node can act like a small distributed utility board for
the telescope system.
## The Main Idea: Proxy And Remote Roles
For these feature families, CAN is used in a client/server style arrangement.
On the main controller:
- `ON` means "this feature is reached through CAN"
- the main controller becomes a client/proxy for that feature
On the remote feature node:
- `REMOTE` means "this node hosts the real implementation"
- that node answers the CAN requests for its local feature
So the usual pattern is:
- the mount/main controller proxies
- the physically-near peripheral node serves
## Example Assignments
Here is a typical main-controller configuration when the mount controller is
meant to talk to remote CAN-connected peripheral nodes:
```c
#define CAN_ROTATOR ON
#define CAN_FOCUSER ON
#define CAN_FEATURES ON
#define CAN_SEND_RATE_MS 2
#define CAN_RECV_RATE_MS 10
#define CAN_PLUS CAN2_TEENSY4
#define CAN_BAUD 250000
```
In that role:
- `CAN_ROTATOR ON` means the main controller expects the rotator to be remote
- `CAN_FOCUSER ON` means the main controller expects focuser control to be remote
- `CAN_FEATURES ON` means the main controller expects the auxiliary-features
provider to be remote
Typical remote-node assignments then look like this.
Remote rotator node:
```c
#define CAN_ROTATOR REMOTE
#define CAN_SEND_RATE_MS 2
#define CAN_RECV_RATE_MS 10
#define CAN_PLUS CAN2_TEENSY4
#define CAN_BAUD 250000
```
Remote focuser node:
```c
#define CAN_FOCUSER REMOTE
#define CAN_FOCUSER_NUMBER 1
#define CAN_SEND_RATE_MS 2
#define CAN_RECV_RATE_MS 10
#define CAN_PLUS CAN2_TEENSY4
#define CAN_BAUD 250000
```
Remote auxiliary-features node:
```c
#define CAN_FEATURES REMOTE
#define CAN_SEND_RATE_MS 2
#define CAN_RECV_RATE_MS 10
#define CAN_PLUS CAN2_TEENSY4
#define CAN_BAUD 250000
```
These examples mirror the common case where the CAN interface is on the ST4
port through `CAN2_TEENSY4`, with `250000` baud and the faster `2ms` send
pacing.
The repeated send/receive-rate lines in those examples are mainly there for
documentation clarity. They make the intended CAN setup obvious in one place,
not because every line is a special non-default requirement.
## Platform Guidance
In current practical use, a Teensy 4.1 makes a very good mount controller when
CAN is involved.
That is the preferred direction because:
- it has worked well as the main controller side
- `CAN2_TEENSY4` on the ST4 port is a natural fit for this role
ESP32 is a different story.
Using the built-in TWAI interface on ESP32:
- ESP32 can feel slow as a CAN client/proxy on the main controller side
- but ESP32 is perfectly reasonable as a remote CAN server for things like a
rotator, focuser, or auxiliary-features node
The push toward `250000` baud is intentional.
The reason is mainly practical:
- `250000` gives more wiring freedom
- it is a better fit for the kind of real-world cable runs and connectors these
distributed peripheral nodes are likely to use
This whole CAN peripheral-interconnect feature set is still fairly new and
experimental.
So the current practical guidance is:
- prefer Teensy 4.1 as the CAN mount controller
- ESP32 is fine for remote peripheral-server roles
- treat `250000` as the preferred default unless there is a clear reason to do
otherwise
- do not assume other CAN platforms are equally proven
Important reality check:
- other platforms have not really been tested in this role yet
## Important Rule: Remote Or Local, Never Both
For each feature family, a build must choose whether that feature is local or
reached through CAN.
That means:
- if `CAN_ROTATOR == ON`, do not also configure a normal local rotator in that
same build
- if `CAN_FOCUSER == ON`, do not also configure normal local focusers in that
same build
- if `CAN_FEATURES == ON`, do not also configure local auxiliary features in
that same build
`REMOTE` is the opposite role:
- a `REMOTE` rotator node must actually host the local rotator it is serving
- a `REMOTE` focuser node must actually host the local focuser it is serving
- a `REMOTE` auxiliary node must actually host the local features it is serving
So the rule is not "both local and remote at once." The rule is:
- main controller build: client/proxy
- remote peripheral build: local provider/server
## What This Feels Like In Practice
From the user-facing point of view, this is meant to feel like the feature is
still part of the overall system.
Conceptually:
- you talk to the main controller in the ordinary way
- the main controller forwards the relevant focuser/rotator/auxiliary operation
over CAN
- the remote node performs the work and reports back
So the goal is not to create a second separate user workflow. The goal is to
let the feature live somewhere else electrically and physically while still
participating in the same overall system.
## Presence And Heartbeats
The remote-node model uses simple heartbeats.
That matters because the main controller should not treat a remote feature as
available just because it was configured at compile time.
Instead:
- remote nodes emit a heartbeat about once per second
- the client side considers the feature present only while that heartbeat
remains fresh
This is especially helpful for distributed peripherals because it gives the
main controller a simple way to decide whether a remote focuser, rotator, or
feature board is really there and alive right now.
For focusers, the model is a little richer:
- each remote focuser has its own heartbeat slot
- the main controller can therefore keep track of multiple remote focusers
independently
## Typical System Layouts
Some natural ways to use the current CAN feature set are:
### Main Mount Controller Plus Remote Rotator
Use the main controller for the mount itself, and put the rotator logic on a
CAN-connected node near the camera train.
That helps when:
- the rotator is physically far from the main controller
- you want cleaner wiring through the moving instrument area
### Main Mount Controller Plus Remote Focusers
Keep the mount local, but move one or more focusers onto remote CAN nodes.
That is useful when:
- focusers are spread around the instrument package
- you have more than one focuser role
- you want each focuser controller physically near its motor and sensors
### Main Mount Controller Plus Remote Auxiliary Board
Use a CAN-connected auxiliary node as a distributed accessory board.
That is a good fit for:
- dew-heater outputs
- power or switch functions
- intervalometer or small observatory accessory control
### Mixed Peripheral Layout
These roles can be mixed.
For example:
- main controller handles the mount
- a remote node handles the rotator
- one or more remote nodes handle focusers
- another remote node hosts accessory features
That is the real strength of this CAN feature set: it lets the system be
physically distributed while still acting like one coordinated instrument.
## What This Note Is Not Trying To Cover
This note is intentionally not trying to go deep into:
- low-level frame packing details
- backend-specific controller quirks
- direct CAN motor/encoder protocols
- a future "axis over CAN" design
Those are all real topics, but they are different topics.
For this note, the important point is simply:
- CAN is currently a practical interconnect for remote rotator, focuser, and
auxiliary-feature nodes
## Related Notes
For the current command-family coverage, see
[COMMAND_REFERENCE.md](COMMAND_REFERENCE.md).
For serial transport/background comparison, see
[SERIAL_NOTES.md](SERIAL_NOTES.md).
## Good Mental Summary
The cleanest way to think about the current CAN feature set in OnStepX is:
- the mount controller stays central
- selected peripherals can live on their own CAN-connected nodes
- rotator, focusers, and auxiliary features are the current distributed-feature
sweet spot
So CAN is best understood here as a practical peripheral-interconnect feature
for building a cleaner, more modular telescope system.
+861
View File
@@ -0,0 +1,861 @@
# OnStepX Command Reference
This reference is derived from the current command handlers in the source tree, primarily the `*.command.cpp` files plus the shared command processor in `src/libApp/commands/ProcessCmds.cpp`.
Scope notes:
- This covers the command families implemented in the current tree, not older wiki pages.
- Many commands are compile-time feature gated. If a subsystem is not enabled in the build, its commands will not exist.
- Plugin-defined commands are not documented here because they come from the active plugin set, not the core command handlers.
- A few command comments in source are stale. Where the code and comment disagree, this document follows the code path.
## Protocol Basics
### Frames
- Normal ASCII command frame: `:CC...#`
- Checksummed frame: `;CC...CCS#`
- `;` starts a checksummed command.
- The command processor validates the checksum and sequence character before dispatch.
- The parser ignores ASCII space, LF, and CR.
- Internal command buffer size is 80 bytes including framing, so current implementations are not limited to the older 40-character LX200 convention.
### Command Parsing
- `CC` is effectively a 1- or 2-character command family. The rest of the payload is the parameter string.
- Replies are either:
- payload replies, usually terminated with `#`
- numeric/boolean replies, returned as `1` for success and `0` for failure
- Some commands suppress the trailing `#` on purpose.
### Global Reply/Error Behavior
- Commands that leave `numericReply=true` return:
- `1` for `CE_NONE` or `CE_1`
- `0` for any other error
- `:GE#` returns the last command error code as a 2-digit payload.
### Command Error Codes
These are the codes returned by `:GE#`:
| Code | Symbol | Meaning |
| --- | --- | --- |
| 00 | `CE_NONE` | No error |
| 01 | `CE_0` | False/fail without a protocol error |
| 02 | `CE_CMD_UNKNOWN` | Unknown command |
| 03 | `CE_REPLY_UNKNOWN` | Invalid reply |
| 04 | `CE_PARAM_RANGE` | Parameter out of range |
| 05 | `CE_PARAM_FORM` | Bad parameter format |
| 06 | `CE_ALIGN_FAIL` | Align failed |
| 07 | `CE_ALIGN_NOT_ACTIVE` | Align not active |
| 08 | `CE_NOT_PARKED_OR_AT_HOME` | Not parked or at home |
| 09 | `CE_PARKED` | Already parked |
| 10 | `CE_PARK_FAILED` | Park failed |
| 11 | `CE_NOT_PARKED` | Not parked |
| 12 | `CE_NO_PARK_POSITION_SET` | No park position set |
| 13 | `CE_GOTO_FAIL` | Goto failed |
| 14 | `CE_LIBRARY_FULL` | Library full |
| 15 | `CE_SLEW_ERR_BELOW_HORIZON` | Target below horizon limit |
| 16 | `CE_SLEW_ERR_ABOVE_OVERHEAD` | Target above overhead limit |
| 17 | `CE_SLEW_ERR_IN_STANDBY` | Controller in standby |
| 18 | `CE_SLEW_ERR_IN_PARK` | Mount parked |
| 19 | `CE_SLEW_IN_SLEW` | Goto already active |
| 20 | `CE_SLEW_ERR_OUTSIDE_LIMITS` | Outside configured limits |
| 21 | `CE_SLEW_ERR_HARDWARE_FAULT` | Hardware fault |
| 22 | `CE_SLEW_IN_MOTION` | Mount already in motion |
| 23 | `CE_SLEW_ERR_UNSPECIFIED` | Other slew error |
| 25 | `CE_1` | Explicit true/success |
## Global Processor Commands
These come from `ProcessCmds.cpp`, not from a subsystem `*.command.cpp`.
| Command | Reply | Description |
| --- | --- | --- |
| `:SBB#` | `1` then switches to 460800 baud | Set serial baud rate |
| `:SBA#` | `1` then switches to 230400 baud | Set serial baud rate |
| `:SB0#` | `1` then switches to 115200 baud | Set serial baud rate |
| `:SB1#` | `1` then switches to 56700 baud | Set serial baud rate |
| `:SB2#` | `1` then switches to 38400 baud | Set serial baud rate |
| `:SB3#` | `1` then switches to 28800 baud | Set serial baud rate |
| `:SB4#` | `1` then switches to 19200 baud | Set serial baud rate |
| `:SB5#` | `1` then switches to 14400 baud | Set serial baud rate |
| `:SB6#` | `1` then switches to 9600 baud | Set serial baud rate |
| `:SB7#` | `1` then switches to 4800 baud | Set serial baud rate |
| `:SB8#` | `1` then switches to 2400 baud | Set serial baud rate |
| `:SB9#` | `1` then switches to 1200 baud | Set serial baud rate |
| `:GE#` | `CC#` | Get last command error code |
| `<0x06>` | `A`, `P`, or `CK_FAIL` style response | Special LX200 status query/checksum-fail path handled by the buffer/processor |
## Dispatcher Notes
In the full telescope build, command dispatch order is:
1. mount
2. guide
3. GPIO/plugin status helpers
4. goto
5. park
6. library
7. site
8. limits
9. home
10. PEC
11. axis 1 / axis 2
12. rotator
13. focuser
14. auxiliary features
That matters because some command names are reused by different subsystems, especially `:hP#` and `:hR#`. In an integrated mount build, mount park/unpark wins before the rotator/focuser handlers ever see those frames. The rotator/focuser `h*` commands are still valid for standalone or remote-node builds.
## Core Telescope / Firmware / Environment
| Command | Reply | Description |
| --- | --- | --- |
| `:B+#` | none | Increase reticle brightness |
| `:B-#` | none | Decrease reticle brightness |
| `:ECtext#` | none | Echo text to debug output. `_` becomes space, trailing `&` becomes newline. |
| `:ERESET#` | none | Reset the MCU |
| `:ENVRESET#` | text | Mark NV storage to be cleared on next boot |
| `:ESPFLASH#` | `1`/none depending on build path | Put addon/ESP device into firmware flashing mode when supported |
| `:GVD#` | `MTH DD YYYY#` | Firmware build date |
| `:GVM#` | `name version#` | Firmware name plus version |
| `:GVN#` | `M.mm...#` | Firmware version number |
| `:GVP#` | `name#` | Product name |
| `:GVT#` | `HH:MM:SS#` | Firmware build time |
| `:GVC#` | `string#` | Firmware config/product description |
| `:GVH#` | `string#` | Firmware hardware/pinmap string |
| `:GX9A#` | `sn.n#` | Ambient temperature in C |
| `:GX9B#` | `n.n#` | Pressure in mbar |
| `:GX9C#` | `n.n#` | Relative humidity in percent |
| `:GX9E#` | `sn.n#` | Dew point in C |
| `:GX9F#` | `n#` or `0` | MCU temperature in C |
| `:SX9A,sn.n#` | `0/1` | Set ambient temperature |
| `:SX9B,n.n#` | `0/1` | Set pressure |
| `:SX9C,n.n#` | `0/1` | Set humidity |
## Time / Date / Site
| Command | Reply | Description |
| --- | --- | --- |
| `:Ga#` | `HH:MM:SS#` | Local standard time, 12-hour format |
| `:GC#` | `MM/DD/YY#` | Local standard calendar date |
| `:Gc#` | `24#` | Local time format indicator |
| `:GG#` | `sHH:MM#` | UTC offset to add to local time to get UT1 |
| `:Gg#` | `sDDD*MM#` | Current longitude |
| `:GgH#` | `sDDD*MM:SS.SSS#` | Longitude, highest precision |
| `:GL#` | `HH:MM:SS#` | Local standard time, 24-hour format |
| `:GLH#` | `HH:MM:SS.SSSS#` | Local standard time, highest precision |
| `:GM#` | `string#` | Site 1 name |
| `:GN#` | `string#` | Site 2 name |
| `:GO#` | `string#` | Site 3 name |
| `:GP#` | `string#` | Site 4 name |
| `:GS#` | `HH:MM:SS#` | Sidereal time |
| `:GSH#` | `HH:MM:SS.ss#` | Sidereal time, highest precision |
| `:Gt#` | `sDD*MM#` | Current latitude |
| `:GtH#` | `sDD*MM:SS.SSS#` | Latitude, highest precision |
| `:Gv#` | `sn.n#` | Elevation in meters |
| `:GX80#` | `HH:MM:SS.ss#` | UT1 time |
| `:GX81#` | `MM/DD/YY#` | UT1 date |
| `:GX89#` | `0` or `1` | Date/time ready status. `0` means ready, `1` means not ready. |
| `:SCMM/DD/YY#` | `0/1` | Set local date |
| `:SCMM/DD/YYYY#` | `0/1` | Set local date |
| `:SGsHH#` | `0/1` | Set UTC offset |
| `:SGsHH:MM#` | `0/1` | Set UTC offset. Comments indicate `MM` should be `00`, `30`, or `45`. |
| `:Sg(s)DDD*MM#` | `0/1` | Set longitude |
| `:Sg(s)DDD*MM:SS#` | `0/1` | Set longitude |
| `:Sg(s)DDD*MM:SS.SSS#` | `0/1` | Set longitude |
| `:SLHH:MM:SS#` | `0/1` | Set local time |
| `:SLHH:MM:SS.SSS#` | `0/1` | Set local time |
| `:SMname#` | `0/1` | Set site 1 name, max 15 chars |
| `:SNname#` | `0/1` | Set site 2 name, max 15 chars |
| `:SOname#` | `0/1` | Set site 3 name, max 15 chars |
| `:SPname#` | `0/1` | Set site 4 name, max 15 chars |
| `:StsDD*MM#` | `0/1` | Set latitude |
| `:StsDD*MM:SS#` | `0/1` | Set latitude |
| `:StsDD*MM:SS.SSS#` | `0/1` | Set latitude |
| `:SUs.s#` | `0/1` | Set DUT1 correction in seconds, nominally `-0.9` to `+0.9` |
| `:Svsn.n#` | `0/1` | Set elevation in meters |
| `:W0#` .. `:W3#` | none | Select active site slot |
| `:W?#` | `n#` | Query active site slot |
## Mount Position / Tracking / Rates
Available when `MOUNT_PRESENT` is enabled.
| Command | Reply | Description |
| --- | --- | --- |
| `:GA#` | `sDD*MM#` or `sDD*MM'SS#` | Current mount altitude |
| `:GAH#` | `sDD*MM'SS.SSS#` | Current mount altitude, highest precision |
| `:GD#` | `sDD*MM#` or `sDD*MM:SS#` | Current declination |
| `:GDH#` | `sDD*MM:SS.SSS#` | Current declination, highest precision |
| `:GR#` | `HH:MM.T#` or `HH:MM:SS#` | Current right ascension |
| `:GRH#` | `HH:MM:SS.SSSS#` | Current right ascension, highest precision |
| `:GT#` | `n.nnnnn#` or `0#` | Tracking rate in Hz, `0` if not tracking |
| `:GZ#` | `DDD*MM#` or `DDD*MM'SS#` | Current azimuth |
| `:GZH#` | `DDD*MM'SS.SSS#` | Current azimuth, highest precision |
| `:GXTD#` | `n.nnnnnnnn#` | Tracking rate offset, Dec, arcsec per sidereal second |
| `:GXTR#` | `n.nnnnnnnn#` | Tracking rate offset, RA, arcsec per sidereal second |
| `:GX40#` | `DDD*MM:SS#` | Axis1 instrument angle |
| `:GX41#` | `DDD*MM:SS#` | Axis2 instrument angle |
| `:GX42#` | `n.nnnnnn#` | Axis1 instrument angle in decimal degrees |
| `:GX43#` | `n.nnnnnn#` | Axis2 instrument angle in decimal degrees |
| `:GX44#` | `n#` | Axis1 encoder count |
| `:GX45#` | `n#` | Axis2 encoder count |
| `:GXE4#` | `n#` | Axis1 steps per degree |
| `:GXE5#` | `n#` | Axis2 steps per degree |
| `:GXEE#` | `0#`, `1#`, ... | Mount coordinate mode (`MOUNT_COORDS - 1`) |
| `:GXEF#` | `1` or `0` | Axis2 tangent-arm presence flag |
| `:GXEG#` | `1` or `0` | Axis1 sector-gear presence flag |
| `:GXEM#` | `n#` | Current mount type |
| `:GXF3#` | `sn.nnnnnn#` | Axis1 step frequency |
| `:GXF4#` | `sn.nnnnnn#` | Axis2 step frequency |
| `:GXFA#` | `50%#` | Reported workload placeholder |
| `:GXFF#` | `n.nnnnnn#` | Axis1 index position |
| `:GXFG#` | `n.nnnnnn#` | Axis2 index position |
| `:STn.n#` | `0/1` | Set tracking rate in Hz. `0` stops tracking. |
| `:SEO#` | `0/1` | Save absolute encoder origin, or initialize mount coordinate memory at home, when supported |
| `:SX40,n#` | `0/1` | Stage encoder axis1 angle in degrees |
| `:SX41,n#` | `0/1` | Stage encoder axis2 angle in degrees |
| `:SX42,1#` | `0/1` | Sync mount from staged encoder axis values |
| `:SX43,0#` | `0/1` | Allow SWS to control sync mode |
| `:SX44,deg1,deg2[a]#` | `0/1` | Stage and sync both encoder axes, append `a` when both SWS encoder values are absolute and trusted |
| `:SXEM,n#` | `0/1` | Set mount type for next restart |
| `:SXTD,n.n#` | `0/1` | Set Dec tracking rate offset, arcsec per sidereal second |
| `:SXTR,n.n#` | `0/1` | Set RA tracking rate offset, arcsec per sidereal second |
| `:TS#` | none | Solar tracking rate |
| `:TK#` | none | King tracking rate |
| `:TL#` | none | Lunar tracking rate |
| `:TQ#` | none | Sidereal tracking rate |
| `:T+#` | none | Increase master sidereal clock by 0.02 Hz |
| `:T-#` | none | Decrease master sidereal clock by 0.02 Hz |
| `:TR#` | none | Reset master sidereal clock |
| `:Te#` | `0/1` | Enable tracking |
| `:Td#` | `0/1` | Disable tracking |
| `:To#` | `0/1` | Enable full compensation model |
| `:Tr#` | `0/1` | Enable refraction compensation |
| `:Tn#` | `0/1` | Disable compensation |
| `:T1#` | `0/1` | Single-axis tracking mode |
| `:T2#` | `0/1` | Dual-axis tracking mode |
| `:$BDn#` | `0/1` | Set Dec/Alt backlash in arcsec |
| `:$BRn#` | `0/1` | Set RA/Azm backlash in arcsec |
| `:%BD#` | `n#` | Get Dec/Alt backlash in arcsec |
| `:%BR#` | `n#` | Get RA/Azm backlash in arcsec |
### Mount Type Values
Current core constants are:
| Value | Mount type |
| --- | --- |
| `1` | GEM |
| `2` | FORK |
| `3` | ALTAZM |
| `4` | ALTALT |
| `5` | GEM_TA |
| `6` | GEM_TAC |
| `7` | FORK_TA |
| `8` | FORK_TAC |
| `9` | ALTAZM_UNL |
## Goto / Sync / Alignment
| Command | Reply | Description |
| --- | --- | --- |
| `:AW#` | `1` | Write alignment model to NV |
| `:A?#` | `mno#` | Alignment status: max stars, current star, last required star |
| `:A1#` .. `:A9#` | `0/1` | Start manual alignment with that many stars |
| `:A+#` | `0/1` | Accept current align point |
| `:CS#` | none | Sync to current target coordinates |
| `:CM#` | `N/A#` or `E1#`..`E9#` | Sync to current catalog/database object |
| `:D#` | `0x7f#` while moving, otherwise raw `#` | LX200 distance-bar style motion indicator |
| `:Gr#` | `HH:MM.T#` or `HH:MM:SS#` | Get target RA |
| `:GrH#` | `HH:MM:SS.SSSS#` | Get target RA, highest precision |
| `:Gd#` | `sDD*MM#` or `sDD*MM:SS#` | Get target Dec |
| `:GdH#` | `sDD*MM:SS.SSS#` | Get target Dec, highest precision |
| `:Gal#` | `sDD*MM#` or `sDD*MM'SS#` | Get target altitude |
| `:GaH#` | `sDD*MM'SS.SSS#` | Get target altitude, highest precision |
| `:Gz#` | `DDD*MM#` or `DDD*MM'SS#` | Get target azimuth |
| `:GzH#` | `DDD*MM'SS.SSS#` | Get target azimuth, highest precision |
| `:MA#` | `0`..`9` | Goto target Alt/Az |
| `:MD#` | `0`, `1`, or `2` | Destination pier side for current target |
| `:MN#` | `0`..`9` | Goto current position on opposite pier side |
| `:MNe#` | `0`..`9` | Force same-position goto to east pier side |
| `:MNw#` | `0`..`9` | Force same-position goto to west pier side |
| `:MP#` | `0`..`9` | Polar-align goto |
| `:MS#` | `0`..`9` | Goto current target |
| `:SrHH:MM.T#` | `0/1` | Set target RA |
| `:SrHH:MM:SS#` | `0/1` | Set target RA |
| `:SrHH:MM:SS.SSSS#` | `0/1` | Set target RA |
| `:SdsDD*MM#` | `0/1` | Set target Dec |
| `:SdsDD*MM:SS#` | `0/1` | Set target Dec |
| `:SdsDD*MM:SS.SSS#` | `0/1` | Set target Dec |
| `:SasDD*MM#` | `0/1` | Set target altitude |
| `:SasDD*MM'SS#` | `0/1` | Set target altitude |
| `:SasDD*MM'SS.SSS#` | `0/1` | Set target altitude |
| `:SzDDD*MM#` | `0/1` | Set target azimuth |
| `:SzDDD*MM'SS#` | `0/1` | Set target azimuth |
| `:SzDDD*MM'SS.SSS#` | `0/1` | Set target azimuth |
### `:MS#` / `:MA#` / `:MN#` / `:MP#` Return Codes
| Value | Meaning |
| --- | --- |
| `0` | Goto accepted |
| `1` | Below horizon limit |
| `2` | Above overhead limit |
| `3` | Controller in standby |
| `4` | Mount parked |
| `5` | Goto already in progress |
| `6` | Outside limits |
| `7` | Hardware fault |
| `8` | Already in motion |
| `9` | Unspecified error |
### Alignment Model Extended Commands
`ALIGN_MAX_NUM_STARS > 1` builds expose:
| Command | Reply | Description |
| --- | --- | --- |
| `:GX00#` | `n#` | `ax1Cor` in arcsec |
| `:GX01#` | `n#` | `ax2Cor` in arcsec |
| `:GX02#` | `n#` | `altCor` in arcsec |
| `:GX03#` | `n#` | `azmCor` in arcsec |
| `:GX04#` | `n#` | `doCor` in arcsec |
| `:GX05#` | `n#` | `pdCor` in arcsec |
| `:GX06#` | `n#` | `ffCor` for FORK/ALTAZM, else `0` |
| `:GX07#` | `n#` | `dfCor` for GEM-style mounts, else `0` |
| `:GX08#` | `n#` | `tfCor` in arcsec |
| `:GX0a#` | `n#` | `hcp` in degrees |
| `:GX0b#` | `n#` | `hca` in arcsec |
| `:GX0c#` | `n#` | `dcp` in degrees |
| `:GX0d#` | `n#` | `dca` in arcsec |
| `:GX09#` | `n#` | Number of uploaded stars, then resets internal star index |
| `:GX0A#` | `HH:MM:SS#` | Uploaded star actual HA |
| `:GX0B#` | `sDD*MM:SS#` | Uploaded star actual Dec |
| `:GX0C#` | `HH:MM:SS#` | Uploaded star mount HA |
| `:GX0D#` | `sDD*MM:SS#` | Uploaded star mount Dec |
| `:GX0E#` | `n#` | Uploaded star pier side, then advances star index |
| `:SX00,n#` .. `:SX0d,n#` | `0/1` | Set alignment model coefficients listed above |
| `:SX09,0#` | `0/1` | Reset alignment upload state |
| `:SX09,1#` | `0/1` | Build model from uploaded stars |
| `:SX09,2#` | `0/1` | Force model active |
| `:SX0A,HH:MM:SS#` | `0/1` | Upload actual HA for current star |
| `:SX0B,sDD*MM:SS#` | `0/1` | Upload actual Dec for current star |
| `:SX0C,HH:MM:SS#` | `0/1` | Upload mount HA for current star |
| `:SX0D,sDD*MM:SS#` | `0/1` | Upload mount Dec for current star |
| `:SX0E,n#` | `0/1` | Upload pier side and advance to next star |
### Goto Extended Settings
| Command | Reply | Description |
| --- | --- | --- |
| `:GX92#` | `n.nnn#` | Current slew period in us/step |
| `:GX93#` | `n.nnn#` | Base/default slew period in us/step |
| `:GX94#` | `n` plus optional ` N` | Current pier side: `0` none, `1` east, `2` west |
| `:GX95#` | `0` or `1` | Auto meridian flip enabled |
| `:GX96#` | `E`, `W`, `B`, or `A` | Preferred pier side |
| `:GX97#` | `n.n#` | Current step rate in deg/s |
| `:GX99#` | `n.nnn#` | Fastest allowed slew period in us/step |
| `:SX92,n.nnn#` | `0/1` | Set current slew period in us/step |
| `:SX93,[1-5]#` | none | Slew preset: `5`=50%, `4`=66.7%, `3`=100%, `2`=150%, `1`=200% |
| `:SX95,0#` or `:SX95,1#` | `0/1` | Disable/enable automatic meridian flip |
| `:SX96,E#` | `0/1` | Preferred pier side east |
| `:SX96,W#` | `0/1` | Preferred pier side west |
| `:SX96,B#` | `0/1` | Preferred pier side best |
| `:SX96,A#` | `0/1` | Preferred pier side automatic |
| `:SX98,0#` or `:SX98,1#` | `0/1` | Disable/enable pause at home during meridian flip |
| `:SX99,1#` | `0/1` | Continue after pause at home |
## Guide / Manual Motion
| Command | Reply | Description |
| --- | --- | --- |
| `:GX90#` | `n.nn#` | Pulse guide rate |
| `:Mgdn#` | none | Pulse guide for `n` ms in direction `d` where `d` is `w`, `e`, `n`, or `s` |
| `:MGdn#` | `0/1` | Same as `:Mgdn#`, numeric form |
| `:Mw#` | none | Move west at current guide rate |
| `:Me#` | none | Move east at current guide rate |
| `:Mn#` | none | Move north at current guide rate |
| `:Ms#` | none | Move south at current guide rate |
| `:Mp#` | none | Spiral-search motion |
| `:Q#` | none | Stop all slews, abort goto |
| `:Qe#` / `:Qw#` | none | Stop east/west motion |
| `:Qn#` / `:Qs#` | none | Stop north/south motion |
| `:RAn.n#` | none | Set axis1 custom guide rate in deg/s |
| `:REn.n#` | none | Set axis2 custom guide rate in deg/s |
| `:RG#` | none | Guide rate preset 1x |
| `:RC#` | none | Centering rate preset 8x |
| `:RM#` | none | Find rate preset 20x |
| `:RF#` | none | Fast rate preset 48x |
| `:RS#` | none | Slew rate preset, half current goto rate |
| `:R0#` .. `:R9#` | none | Numeric guide-rate preset |
## Park / Home / Limits / Status
### Park
| Command | Reply | Description |
| --- | --- | --- |
| `:hP#` | `0/1` | Park mount |
| `:hQ#` | `0/1` | Set current position as park |
| `:hR#` | `0/1` | Unpark mount |
### Home
| Command | Reply | Description |
| --- | --- | --- |
| `:h?#` | `hasSense,axis1Offset,axis2Offset#` | Home status. Source comment mentions auto-home, but current code returns 3 fields only. |
| `:hA0#` / `:hA1#` | none | Disable/enable automatic home at boot |
| `:hC#` | none | Move to home |
| `:hC1,R#` | none | Toggle axis1 home-sense reversal |
| `:hC1,n#` | none | Set axis1 home offset in arcsec |
| `:hC2,R#` | none | Toggle axis2 home-sense reversal |
| `:hC2,n#` | none | Set axis2 home offset in arcsec |
| `:hF#` | none | Reset mount at home/cold-start position |
### Limits
For a visual explanation of confusing GEM east/west pier-side limit geometry,
see [GOTO_NOTES.md](GOTO_NOTES.md#workflow-4-reachability-and-target-unwinding).
| Command | Reply | Description |
| --- | --- | --- |
| `:Gh#` | `sDD*#` | Horizon limit |
| `:Go#` | `DD*#` | Overhead limit |
| `:GXE9#` | `n#` | East meridian limit in minutes |
| `:GXEA#` | `n#` | West meridian limit in minutes |
| `:GXEe#` | `n#` | Axis1 minimum limit in degrees |
| `:GXEw#` | `n#` | Axis1 maximum limit in degrees |
| `:GXEB#` | `n#` | Axis1 maximum limit in hours |
| `:GXEC#` | `n#` | Axis2 minimum limit in degrees |
| `:GXED#` | `n#` | Axis2 maximum limit in degrees |
| `:ShsDD#` | `0/1` | Set lower altitude limit |
| `:SoDD#` | `0/1` | Set overhead altitude limit |
| `:SXE9,n#` | `0/1` | Set east meridian limit in minutes |
| `:SXEA,n#` | `0/1` | Set west meridian limit in minutes |
### Status
| Command | Reply | Description |
| --- | --- | --- |
| `:Gm#` | `E#`, `W#`, or `N#` | Meridian pier side |
| `:GU#` | status string | Human-readable packed status |
| `:Gu#` | packed bytes | Bit-packed status |
| `:GW#` | 4-char status | Mount type, tracking, parked/home, align-done |
| `:SX97,0#` | `0/1` | Disable buzzer |
| `:SX97,1#` | `0/1` | Enable buzzer |
| `:SX97,2#` | `0/1` | Beep |
| `:SX97,3#` | `0/1` | Alert tone |
| `:SX97,4#` | `0/1` | Click |
#### `:GU#` Status Characters
The reply is an ordered string assembled from active conditions. Characters currently used by the code include:
| Char | Meaning |
| --- | --- |
| `n` | Not tracking |
| `N` | No goto active |
| `p` | Not parked |
| `I` | Parking in progress |
| `P` | Parked |
| `F` | Park failed |
| `e` | Sync-to-encoders-only mode |
| `H` | At home |
| `h` | Homing |
| `B` | Auto-home at boot |
| `S` | PPS synced |
| `G` | Pulse guide active |
| `g` | Guide active |
| `r` | Refraction compensation enabled |
| `s` | Single-axis compensation mode |
| `t` | Full compensation model enabled |
| `(` | Lunar tracking rate selected |
| `O` | Solar tracking rate selected |
| `k` | King tracking rate selected |
| `w` | Meridian flip paused at home |
| `u` | Pause-at-home enabled |
| `z` | Buzzer enabled |
| `a` | Automatic meridian flip enabled |
| `R` | PEC data recorded |
| `/`, `,`, `~`, `;`, `^` | PEC state |
| `E`, `K`, `A`, `L` | GEM, FORK, ALTAZM, ALTALT |
| `o`, `T`, `W` | Pier side none, east, west |
| final digits | pulse-guide rate, guide rate, general error code |
#### `:Gu#` Packed Status Layout
`Gu` is the binary/pseudo-binary status form. The current implementation fills bytes as:
| Byte | Contents |
| --- | --- |
| `0` | tracking/goto/PPS/pulse-guide plus compensation mode |
| `1` | tracking-rate selection plus sync-to-encoders and guide-active |
| `2` | home/homing/auto-home/home-pause/buzzer/auto-flip |
| `3` | mount type plus pier side |
| `4` | PEC state and PEC-recorded flag |
| `5` | park state |
| `6` | pulse-guide selection |
| `7` | guide-rate selection |
| `8` | general limits/error code |
## Object Library
| Command | Reply | Description |
| --- | --- | --- |
| `:LB#` | none | Previous object matching current constraints |
| `:LCn#` | none | Select record number `n` |
| `:LI#` | `name,type#` | Current object name and type |
| `:LIG#` | none | Load current object into goto target |
| `:LR#` | `name,type,ra,dec#` | Current object info, then advance to next record |
| `:LWname,type#` | `0/1` | Write current target RA/Dec to next free record |
| `:LN#` | none | Next object matching current constraints |
| `:L$#` | `1` | Move to catalog name record |
| `:LD#` | none | Clear current record |
| `:LL#` | none | Clear current catalog |
| `:L!#` | none | Clear all catalogs |
| `:L?#` | `n#` | Free records across all catalogs |
| `:Lon#` | `0/1` | Select catalog `0..14` |
Object type codes written/read by library commands are:
`UNK`, `OC`, `GC`, `PN`, `DN`, `SG`, `EG`, `IG`, `KNT`, `SNR`, `GAL`, `CN`, `STR`, `PLA`, `CMT`, `AST`
## PEC
Available when PEC support is enabled for axis 1.
| Command | Reply | Description |
| --- | --- | --- |
| `:GX91#` | `n#` | PEC analog value |
| `:GXE6#` | `n.nnnnnn#` | Steps per sidereal second |
| `:GXE7#` | `n#` | Worm rotation steps from NV |
| `:GXE8#` | `n#` | PEC buffer size in seconds |
| `:SXE7,n#` | `0/1` | Set worm rotation steps |
| `:VH#` | `nnnnn#` | PEC index sense position in sidereal seconds |
| `:VR#` | `snnn,nnn#` | Current PEC segment correction plus segment index |
| `:VRn#` | `snnn#` | PEC correction for segment `n` |
| `:Vrn#` | `x0x1...x9#` | Ten-byte hex frame of PEC data starting at segment `n` |
| `:VS#` | `n.nnnnnn#` | Steps per sidereal second of worm rotation |
| `:VW#` | `nnnnnn#` | Worm rotation steps |
| `:WR+#` | `0/1` | Rotate PEC table forward one second |
| `:WR-#` | `0/1` | Rotate PEC table backward one second |
| `:WRn,sn#` | none | Write PEC correction for segment `n` |
| `:$QZ+#` | none | Enable PEC playback |
| `:$QZ-#` | none | Disable PEC |
| `:$QZ/#` | none | Arm PEC recording |
| `:$QZZ#` | none | Clear PEC buffer |
| `:$QZ!#` | none | Save PEC data to NV |
| `:$QZ?#` | `I#`, `p#`, `P#`, `r#`, `R#`, optionally with `.#` | PEC status |
PEC status characters from `:$QZ?#`:
| Char | Meaning |
| --- | --- |
| `I` | Ignore/off |
| `p` | Ready to play |
| `P` | Playing |
| `r` | Ready to record |
| `R` | Recording |
| `.` | Index detected this second |
### `:GXUa#` Driver Status Flags
Local ASCII replies are comma-separated flag mnemonics:
| Flag | Meaning |
| --- | --- |
| `ST` | Standstill |
| `OA` | Output A open load |
| `OB` | Output B open load |
| `GA` | Output A short to ground |
| `GB` | Output B short to ground |
| `OT` | Over-temperature |
| `PW` | Over-temperature warning |
| `GF` | Driver fault |
## Focuser
Available in focuser-enabled or remote-focuser builds.
Addressing rules:
- `:FA#` returns the currently selected focuser number.
- `:FA1#` .. `:FA6#` selects the active focuser.
- `:F...#` uses the active focuser.
- `:F1...#` .. `:F6...#` directs a command to a specific focuser immediately.
Unit rules for local ASCII focuser commands:
- Uppercase `B`, `D`, `G`, `I`, `M`, `R`, `S` use microns.
- Lowercase `b`, `d`, `g`, `i`, `m`, `r`, `s` use raw steps.
- Other focuser commands are unitless or fixed-unit as noted below.
| Command | Reply | Description |
| --- | --- | --- |
| `:FA#` | `n` | Get active focuser number |
| `:FA1#` .. `:FA6#` | `0/1` | Select active focuser |
| `:hP#` | `0/1` | Park all focusers in standalone/remote focuser builds |
| `:hR#` | `0/1` | Unpark all focusers in standalone/remote focuser builds |
| `:Fa#` | `1` | Primary focuser present/selected |
| `:FT#` | `M1#`, `S3#`, etc. | Focuser status plus goto-rate digit |
| `:Fp#` | `0` or `1` | Mode. Current implementation returns `1` for DC/pseudo-absolute, `0` otherwise. |
| `:FI#` / `:Fi#` | `n#` | Full-in/min position |
| `:FM#` / `:Fm#` | `n#` | Maximum position |
| `:Fe#` | `n.n#` | Temperature delta from TCF baseline |
| `:Ft#` | `n.n#` | Focuser temperature in C |
| `:Fu#` | `n.nnnnn#` | Microns per step |
| `:FB#` / `:Fb#` | `n#` | Backlash |
| `:FBn#` / `:Fbn#` | `0/1` | Set backlash |
| `:FC#` | `n.nnnnn#` | TCF coefficient in microns per C |
| `:FCsn.n#` | `0/1` | Set TCF coefficient |
| `:Fc#` | `0` or `1` | TCF enabled status |
| `:Fc0#` / `:Fc1#` | `0/1` | Disable/enable TCF |
| `:FD#` / `:Fd#` | `n#` | TCF deadband |
| `:FDn#` / `:Fdn#` | `0/1` | Set TCF deadband |
| `:FP#` | `n#` | DC motor power percent |
| `:FPn#` | `0/1` | Set DC motor power percent |
| `:FQ#` | none | Stop focuser |
| `:F1#` .. `:F9#` | none | Set move/goto rate preset |
| `:FW#` | `n#` | Working goto rate in um/s |
| `:F+#` | none | Move inward |
| `:F-#` | none | Move outward |
| `:FG#` / `:Fg#` | `sn#` | Current position |
| `:FRsn#` / `:Frsn#` | none | Relative goto |
| `:FSn#` / `:Fsn#` | `0/1` | Absolute goto |
| `:FZ#` | none | Zero current position |
| `:FH#` | none | Set current position as home |
| `:Fh#` | none | Move to home |
| `:GXU4#` .. `:GXU9#` | flags | Driver status for focuser axes that expose `Axis.command.cpp` |
Rate preset meaning:
| Preset | Meaning |
| --- | --- |
| `1` | 1 um/s move rate |
| `2` | 10 um/s move rate |
| `3` | 100 um/s move rate |
| `4` | 0.5x goto rate, move mode |
| `5` | 0.5x goto rate |
| `6` | 0.66x goto rate |
| `7` | 1x goto rate |
| `8` | 1.5x goto rate |
| `9` | 2x goto rate |
## Rotator
Available in rotator-enabled or remote-rotator builds.
| Command | Reply | Description |
| --- | --- | --- |
| `:rA#` | `0/1` | Rotator active |
| `:hP#` | `0/1` | Park rotator in standalone/remote rotator builds |
| `:hR#` | `0/1` | Unpark rotator in standalone/remote rotator builds |
| `:rT#` | `M1#`, `SD3#`, etc. | Status string plus rate digit |
| `:rI#` | `n#` | Minimum angle in degrees |
| `:rM#` | `n#` | Maximum angle in degrees |
| `:rD#` | `n.n#` | Degrees per step |
| `:rb#` | `n#` | Backlash in steps |
| `:rbn#` | `0/1` | Set backlash |
| `:rQ#` | none | Stop motion |
| `:r1#` .. `:r9#` | none | Set move/goto rate preset |
| `:rW#` | `n.n#` | Working slew rate in deg/s |
| `:rc#` | none | Continuous-move no-op, accepted for compatibility |
| `:r>#` | none | Move clockwise |
| `:r<#` | none | Move counter-clockwise |
| `:rG#` | `sDDD*MM#` | Current angle |
| `:rrsDDD*MM#` | none | Relative goto |
| `:rSsDDD*MM#` | `0/1` | Absolute goto |
| `:rZ#` | none | Zero position |
| `:rF#` | none | Set current position to half travel |
| `:rC#` | none | Move to half-travel / home target |
| `:r+#` | none | Enable derotation |
| `:r-#` | none | Disable derotation |
| `:rP#` | none | Move to parallactic angle |
| `:rR#` | none | Toggle derotator reverse direction |
| `:GX98#` | `D#`, `R#`, or `N#` | Rotator capability: derotate, rotate-only, or none |
| `:GXU3#` | flags | Driver status for rotator axis in standalone/remote builds |
Rotator rate presets:
| Preset | Meaning |
| --- | --- |
| `1` | 0.01 deg/s move rate |
| `2` | 0.1 deg/s move rate |
| `3` | 1.0 deg/s move rate |
| `4` | 0.5x goto rate used as move rate |
| `5` | 0.5x goto rate |
| `6` | 0.66x goto rate |
| `7` | 1x goto rate |
| `8` | 1.5x goto rate |
| `9` | 2x goto rate |
## Auxiliary Features
Available when auxiliary features are enabled.
Feature slots are numbered `1..8`.
### Discovery
| Command | Reply | Description |
| --- | --- | --- |
| `:GXY0#` | `xxxxxxxx#` | Eight-character bitmap of active feature slots, `1` = present |
| `:GXYn#` | `name,purpose#` | Slot name plus purpose code |
### Slot State
| Command | Reply | Description |
| --- | --- | --- |
| `:GXXn#` | purpose-specific payload | Get current state for slot `n` |
| `:SXXn,Vv#` | `0/1` | Generic value set |
| `:SXXn,Zf#` | `0/1` | Dew-heater zero temperature |
| `:SXXn,Sf#` | `0/1` | Dew-heater span temperature |
| `:SXXn,Ef#` | `0/1` | Intervalometer exposure seconds |
| `:SXXn,Df#` | `0/1` | Intervalometer delay seconds |
| `:SXXn,Cf#` | `0/1` | Intervalometer count |
### `:GXXn#` Reply Shapes
The payload depends on the slot purpose:
| Purpose | Reply shape |
| --- | --- |
| Switch / momentary switch / cover switch | `value` plus optional power telemetry |
| Analog output | `value` plus optional power telemetry |
| Dew heater | `enabled,zero,span,deltaT` plus optional power telemetry |
| Intervalometer | `currentCount,exposure,delay,count` |
When power monitoring is compiled in, the local ASCII implementation appends:
`;<volts>,<amps>,<flags>`
Where flags are a five-character string using `P`, `C`, `U`, `V`, `T` or `!`.
## Axis / Motor / Driver Service Commands
Axis service commands are implemented by `Axis.command.cpp`. For the main telescope/mount build these are reachable for axis 1 and axis 2, if present. The rotator exposes axis3, if present. The focuser(s) expose any of axis 4 to axis 9, if present.
| Command | Reply | Description |
| --- | --- | --- |
| `:GXAa,p#` | `value,min,max,type,name#` | Get axis parameter `p` for axis `a` (`1..9`) |
| `:GXAa,M#` | `name#` | Motor/driver name for axis `a` |
| `:GXAa,0#` | `n#` | Parameter count for axis `a` |
| `:GXSa#` | `delta,velocity#` | Servo-only delta and velocity for axis `a` |
| `:GXUa#` | `flags#` | Stepper driver status for axis `a` |
| `:SXAC,0#` | `0/1` | Use runtime NV axis settings |
| `:SXAC,1#` | `0/1` | Use compile-time `Config.h` axis settings |
| `:SXAa,R#` | `0/1` | Revert axis `a` settings to defaults on next boot |
| `:SXAa,p,value#` | `0/1` | Set axis parameter `p` for axis `a` |
### `:GXAa,p#` Reply Format
The reply is:
`value,min,max,type,name#`
Where:
- `value` is the current NV value
- `min` and `max` are the documented range
- `type` is the axis parameter type code returned by firmware
- `name` is the parameter name from the axis parameter table
- some `name` values are locale tokens such as `$1` or `$12` rather than literal English labels
Axis parameter type codes:
| Code | Symbol | Meaning |
| --- | --- | --- |
| `0` | `AXP_INVALID` | Invalid / placeholder entry |
| `1` | `AXP_BOOLEAN` | Boolean value stored in NV and applied on restart/reinit |
| `2` | `AXP_BOOLEAN_IMMEDIATE` | Boolean value applied immediately when set |
| `3` | `AXP_INTEGER` | Integer value stored in NV and applied on restart/reinit |
| `4` | `AXP_INTEGER_IMMEDIATE` | Integer value applied immediately when set |
| `5` | `AXP_FLOAT` | Floating-point value stored in NV and reported as a plain numeric field |
| `6` | `AXP_FLOAT_IMMEDIATE` | Floating-point value applied immediately when set |
| `7` | `AXP_FLOAT_RAD` | Angular float stored internally in radians |
| `8` | `AXP_FLOAT_RAD_INV` | Inverse angular float stored internally with radian/degree conversion |
| `9` | `AXP_POW2` | Power-of-two constrained integer-like value |
| `10` | `AXP_DECAY` | Driver decay-mode selector |
Protocol note:
- `:GXAa,p#` normalizes `AXP_FLOAT_RAD` and `AXP_FLOAT_RAD_INV` to reply type code `5` and converts the value/range to degree-based units for transport.
- Axis parameter values are float-backed in firmware; values are always float even when the logical type is boolean or integer so the UI can show the appropriate controls.
- Boolean parameters: some use logical `0`/`1`, while others use the firmware constants `OFF = -1` and `ON = -2`; so any UI can show 'True'/'False' or 'On'/'Off'.
- For `AXP_DECAY`, the UI shows the matching decay-mode text for the numeric value `1=MIXED`, `2=FAST`, `3=SLOW`, `4=SPREADCYCLE`, `5=STEALTHCHOP`.
Locale-backed axis parameter name tokens currently used by firmware:
| Token | Meaning |
| --- | --- |
| `$1` | Steps/degree |
| `$2` | Min limit, degs |
| `$3` | Max limit, degs |
| `$4` | Steps/um |
| `$5` | Min limit, um |
| `$6` | Max limit, um |
| `$7` | Reverse |
| `$8` | Microsteps |
| `$9` | Microsteps Goto |
| `$10` | Decay mode |
| `$11` | Decay mode Goto |
| `$12` | mA Hold |
| `$13` | mA Run |
| `$14` | mA Goto |
| `$15` | 256x Interpolate |
| `$16` | P tracking |
| `$17` | I tracking |
| `$18` | D tracking |
| `$19` | P slewing |
| `$20` | I slewing |
| `$21` | D slewing |
| `$22` | Rads/count |
| `$23` | Steps/count ratio |
| `$24` | Max accel, %/s/s |
| `$25` | Min power, % |
| `$26` | Max power, % |
## CAN Remote-Node Variants
For architecture, configuration, and current scope, see
[CAN_NOTES.md](CAN_NOTES.md).
The following files implement the same logical command families over packed CAN messages rather than the ASCII LX200-style transport:
- `src/telescope/focuser/local/Focuser.can.command.cpp`
- `src/telescope/rotator/local/Rotator.can.command.cpp`
- `src/telescope/auxiliary/local/Features.can.command.cpp`
These are not separate end-user command names. They are binary transport implementations of the same focuser, rotator, and auxiliary-feature command sets above.
Notable transport differences:
- CAN replies are binary-packed, not ASCII text.
- `:GXY0#` for CAN features returns a single bitmask byte rather than an eight-character ASCII bitmap.
- CAN focuser/rotator driver-status replies are packed bitfields rather than comma-separated text flags.
## Source Coverage
This document was built from the current handlers in:
- `src/telescope/Telescope.command.cpp`
- `src/telescope/mount/Mount.command.cpp`
- `src/telescope/mount/goto/Goto.command.cpp`
- `src/telescope/mount/guide/Guide.command.cpp`
- `src/telescope/mount/home/Home.command.cpp`
- `src/telescope/mount/library/Library.command.cpp`
- `src/telescope/mount/limits/Limits.command.cpp`
- `src/telescope/mount/park/Park.command.cpp`
- `src/telescope/mount/pec/Pec.command.cpp`
- `src/telescope/mount/site/Site.command.cpp`
- `src/telescope/mount/status/Status.command.cpp`
- `src/lib/axis/Axis.command.cpp`
- `src/telescope/focuser/local/Focuser.command.cpp`
- `src/telescope/rotator/local/Rotator.command.cpp`
- `src/telescope/auxiliary/local/Features.command.cpp`
- plus the corresponding CAN transport handlers
- plus `src/libApp/commands/ProcessCmds.cpp`
Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 36 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 49 KiB

+514
View File
@@ -0,0 +1,514 @@
# Goto Notes
## Purpose
These notes describe how goto, sync, orientation choice, and target-limit
planning currently work in OnStepX.
This is a workflow note. It is meant to help explain how the system decides on
a sensible motion plan, not to document every goto command.
## For related topics also see
- [STARTUP_AUTHORITY_NOTES.md](STARTUP_AUTHORITY_NOTES.md)
- [HOMING_NOTES.md](HOMING_NOTES.md)
- [COMMAND_REFERENCE.md](COMMAND_REFERENCE.md)
## Quick Summary
## The cleanest mental model is
1. a user target is turned into mount coordinates
2. the system checks whether that target is reachable in one or more valid
orientations
3. the system chooses a sensible branch and motion plan
4. goto executes that plan, possibly with waypoints or alternate orientation
handling
5. runtime limits continue watching during the motion
## So goto in OnStepX is not just
- convert coordinates
- slew there
It is more like a small decision engine.
## The Main Distinction: Goto vs Sync
`goTo.setTarget(...)` is the common decision point for both goto and sync.
## That means both operations share
- target conversion
- orientation selection
- reachability checks
- axis1 wrap/unwind correction
## Then they diverge
- goto moves the mount to the chosen target
- sync keeps the current physical mount orientation and reassigns coordinates to
match the chosen target
So sync is not a separate simpler target model. It reuses most of the same
target-planning logic, then applies it as a coordinate reassignment instead of
motion.
## What A Goto Request Really Does
## At a high level a goto request goes through these steps
1. make sure goto is allowed right now
2. convert the request into mount coordinates
3. decide which orientation options are valid
4. choose the actual target branch and pier side
5. add a waypoint/home step if needed
6. start the slew
7. continue monitoring limits and refine near the destination
The important thing is that the target may have more than one valid
representation.
## Examples
- east-side vs west-side orientation on a GEM
- axis1 target plus or minus 360 degrees when wrapping/unlimited motion exists
- alternate orientation choices on mounts such as `ALTALT`
## Workflow 1: Entry Conditions
Before goto or sync can proceed, the mount checks a number of ordinary
conditions:
- startup authority must already be trusted
- both axes must be enabled
- the mount must not be parked
- no other goto/guide/motion operation can already be active
- no goto-blocking limit/sense error can already exist
- no motor fault can already exist
For goto specifically, date/time readiness matters through the ordinary mount
and limit logic as well.
In other words, goto is not treated as a way to escape unknown state.
## Workflow 2: Converting The Target
## The incoming target may start life in
- native coordinates
- mount coordinates
- equatorial, horizontal, or `ALTALT` forms depending on mount type
## The goto code converts as needed so the mount can reason about
- target hour angle / declination where applicable
- target altitude for horizon checks
- target instrument coordinates for each orientation choice
This is why the same sky target can still lead to more than one valid motion
plan.
## Workflow 3: Choosing Orientation
This is one of the core pieces.
## OnStepX supports a family of orientation-selection policies
- `PSS_EAST_ONLY`
- `PSS_WEST_ONLY`
- `PSS_EAST`
- `PSS_WEST`
- `PSS_BEST`
- `PSS_AUTO`
- `PSS_SAME_ONLY`
## What these really mean
- some insist on one side only
- some prefer one side but can fall back to the other if needed
- some try to stay on the current side
- some ask the planner to choose what seems best
## `PSS_AUTO`
This was added mainly to support automatic meridian-flip style behavior when the
mount is in the meridian-overlap region and can legitimately continue tracking
on the other side without interruption.
In that sense, `AUTO` is not just "pick something convenient." It is meant to
prefer the side/orientation that keeps the mount on a sensible continuing
tracking path when overlap allows it.
This is still not the same thing on every mount type.
## For ordinary equatorial cases
- it usually picks a preferred side from current hour angle
- in overlap cases, that helps place the target on the side where tracking can
continue unimpeded after the orientation change
## For `ALTAZM` and `ALTALT`
- it falls back to `PSS_BEST`
So `AUTO` is really an automatic orientation policy, not one fixed algorithm.
In practical terms, it is most at home on GEMs, especially imaging setups where
automatic meridian-flip style behavior is desirable. Compared with a fixed
preference such as `PSS_EAST`, `PSS_AUTO` is better at using meridian-overlap
freedom to end up on the side where tracking can keep going cleanly after the
change.
On fork mounts, the usual practical approach is often different. Users commonly
widen the meridian limits to allow much more freedom, then keep a fixed side
preference such as `PSS_EAST` or `PSS_WEST` for normal operation. If they want
the mount to use the other orientation, they typically change that preferred
side. Forks often do not need, and often should not do, automatic flip-style
behavior in the first place. So wide limits help create freedom, but the
selected side policy still drives whether the planner stays put or flips.
## `PSS_BEST`
`BEST` is distance-aware.
It compares the reachable east- and west-orientation targets in instrument
space and may choose the alternate orientation if that target is closer.
## This is why OnStepX can sometimes choose what looks like a shortcut
- through the pole
- through an alternate valid orientation
- through a less-obvious wrapped branch
That behavior can look surprising, but it is intentional.
In practical terms, `PSS_BEST` is often attractive for visual use because it
can reduce unnecessary flips and choose the shorter or less awkward path. That
can make the mount feel nicer at the eyepiece even when it is not the same
choice an imaging workflow would prefer.
## Workflow 4: Reachability And Target Unwinding
After a tentative target exists, `Limits::validateTarget(...)` checks whether
the target is reachable.
## This includes
- altitude min/max
- east-side axis1 window
- west-side axis1 window
- meridian overlap limits for GEMs
- axis2 limits
These sketches help visualize why the same configured GEM limits can look
different depending on which side of the pier the mount is currently using:
![GEM limits example when east of the pier](<GEM LIMITS EXAMPLE EAST OF PIER.jpg>)
When east of the pier, the active limit window is interpreted against the
east-side geometry shown above.
![GEM limits example when west of the pier](<GEM LIMITS EXAMPLE WEST OF PIER.jpg>)
When west of the pier, the same ideas map onto the mirrored west-side geometry.
## But there is another subtle step
- axis1 may be normalized by plus or minus 360 degrees to find a sensible
branch
That means the planner does not necessarily use the raw first axis1 value that
falls out of the transform.
## Instead it may
- keep the current branch if it is already best
- unwind to a nearby branch if that is closer
- shift by `+360` or `-360` to make the target fit the valid motion window
This is why a coordinate that "looks outside range" on first glance may still
be reachable after normalization.
It is also why wrapped or effectively unlimited axes feel smarter than a simple
"move to exactly this number" implementation.
## What `AXIS1_WRAP` Changes
## If `AXIS1_WRAP == ON`
- axis1 is configured with a 360-degree wrap
- its configured range becomes `-360 .. +360`
- sync-threshold style coordinate-jump checks are bypassed
That does not mean the mount ignores all planning.
## It means
- axis1 has a broader wrapped coordinate space to work in
- goto can choose a sensible branch in that larger space
This is most relevant on azimuth-like axes and other mounts where bounded
`-180 .. +180` thinking is too restrictive.
## Workflow 5: Waypoints And Home During Orientation Change
If an equatorial goto changes pier side and `MFLIP_SKIP_HOME == OFF`, OnStepX
does not always go straight to the final destination.
## Instead it may
- insert a waypoint at home
- or insert an avoid waypoint first, then go to home, then continue
## That is why the goto stage machine includes
- `GG_WAYPOINT_AVOID`
- `GG_WAYPOINT_HOME`
- near-destination refine stages
- final destination
So a meridian flip or alternate-orientation goto is often a multi-stage motion,
not one direct straight-line idea.
## Horizon Avoidance
There are two different horizon-avoidance ideas in the goto system.
The first is path-shaping during side/orientation changes.
## When a pier-side change is involved, goto may first route through
- about 4 hours HA
- or about 3 hours HA
before going home and then heading to the final target.
## The reason is practical horizon avoidance
- some otherwise valid geometry would pass too low near the horizon during a
flip or alternate-orientation transition
- low-latitude cases can make that especially awkward
So the planner uses a small detour heuristic rather than pretending all valid
math paths are equally safe in practice.
The second is runtime rate shaping based on distance from the altitude limit.
## There is a runtime slowdown heuristic
- in equatorial mode with `MOUNT_HORIZON_AVOIDANCE == ON`
- the axis frequencies are scaled down near the minimum altitude limit
- the amount of slowdown varies with distance from that limit
- the code decides whether to slow RA-like or Dec-like motion depending on
whether declination is increasing or decreasing
This is best thought of as practical protective behavior, not pure geometry.
## Workflow 6: Near Destination Refinement
Goto does not always drive directly to the literal final target at full intent.
## Depending on encoder/tolerance context, it may
- slew to a near-destination first
- wait to settle
- refine in one or more additional stages
- then finish at the final destination
That final approach is not only about positional refinement. In practice, the
near-destination exit can also be used to normalize backlash on arrival by
finishing with a consistent last-direction approach instead of simply accepting
whatever direction the earlier slew happened to end with.
## This is why the code carries
- `GG_NEAR_DESTINATION_START`
- `GG_NEAR_DESTINATION_WAIT`
- `GG_NEAR_DESTINATION`
- `GG_DESTINATION`
## It is also why encoder presence changes behavior
- with suitable encoder/tolerance support, more refined near-target behavior is
allowed
- during homing/parking or on simpler cases, that refinement can be reduced or
skipped
## Runtime Limits Are Not The Same As Target Validation
This is another important distinction.
## Target validation answers
- "is this planned target/orientation allowed?"
## Runtime limit monitoring answers
- "while the mount is moving or tracking, have we crossed something dangerous?"
## Runtime checks include
- horizon / overhead limits
- meridian east/west limits
- axis min/max limits
- sensed min/max limits
## Those runtime checks can
- stop one axis
- stop the whole mount
- abort goto
- trigger automatic meridian flip in some GEM tracking cases
## So there are really two layers
- planned target acceptance
- live motion policing
## Automatic Meridian Flip
If automatic meridian flip is enabled and the mount is tracking, some runtime
limit crossings do not simply stop motion.
Instead the limit code may request a new goto to the current sky position on
the opposite side:
- east-side request if currently west and beyond the west meridian limit
- west-side request if currently east and beyond the axis1 max side
## So automatic meridian flip is implemented as
- a limit-triggered alternate-orientation goto
not as a separate completely different motion engine.
## How Non-GEM Mounts Differ
For fork and alt/az style mounts, some axis-limit reasoning is based on shaft
angles rather than GEM-style pier-side interpretation.
The limit code therefore sometimes normalizes the current axis1 position back
into a "normal east-like" coordinate form before checking limits.
That is one reason the same target can feel simpler on some mounts and much
more orientation-sensitive on others.
For fork mode specifically, this is why wide meridian limits are often used as
a practical way to increase motion freedom without constantly tripping a
side-change style decision. But wide limits are not the whole story. Orientation
selection still matters. In typical fork use, that usually means keeping
`PSS_EAST` or `PSS_WEST` fixed until the user intentionally changes it to get
the opposite orientation, even though the generous limit window would allow
more than one valid branch.
## `ALTALT` And Other Less Common Modes
`ALTALT` is one of the modes that can seem obscure from the outside.
One useful way to picture it is by re-aiming the primary axis of a familiar
equatorial mount.
- on a GEM, that axis points parallel to Earth's rotation axis
- on an `ALTAZM`, that same idea would point the primary axis at the zenith
- on an `ALTALT`, the primary axis points north on the horizon at `ALT = 0`
That is why `ALTALT` is not just "equatorial with funny numbers." It is a
different mount geometry with its own natural strengths and weak spots.
## In practice this means
- target conversion differs
- `PSS_AUTO` falls back to `PSS_BEST`
- tracking and motion behavior are not identical to GEM or ordinary alt/az
- the mount can move naturally through the zenith and celestial-pole regions
- it is therefore one of the most natural mount geometries for satellite
tracking
- the field will still rotate even if the mount is otherwise tracking the
general sky motion correctly
- the geometry is weakest for targets near due north or due south on the
horizon
So it is better to think of `ALTALT` as another consumer of the same decision
framework, but with a different singularity pattern and a different relationship
between its primary axis and Earth's rotation.
## Special Geometry: Sector Gear And Tangent Arm
Sector gear axis1 and tangent-arm axis2 are special enough that ordinary full
range goto thinking does not always apply.
## For these mounts
- target reachability is influenced by limited physical travel
- some checks are relaxed or specialized
- origin handling can matter more than wide-range coordinate elegance
## So goto on these mounts is partly about
- choosing a useful target in a constrained motion envelope
not simply navigating a wide continuous axis range.
## No-Goto Builds
## If `GOTO_FEATURE == OFF`
- real automatic goto motion does not exist
- sync still reuses the target-selection logic
- the old fake-completion paths for home/park are intentionally gone
## So this mode still benefits from
- coordinate planning
- orientation choice for sync-like operations
But it is not pretending to offer the full automatic motion planner.
## Examples
## Example 1: Ordinary GEM goto
- user asks for a sky target
- planner computes east and west solutions
- both may be reachable
- preferred side or best-distance logic chooses one
- goto may go directly, or through home if the side changes
## Example 2: `PIER_SIDE_BEST`
- both orientations are valid
- alternate orientation is closer in instrument space
- planner chooses the alternate branch
- this can look like a shortcut through the pole or a less-obvious orientation
## Example 3: Wrapped axis1
- raw target axis1 value is not ideal
- planner shifts by `+360` or `-360`
- resulting branch is closer or simply the only valid one inside limits
## Example 4: Horizon-avoidance flip
- side change is needed
- direct route would be too low near the horizon
- goto first detours to an avoid waypoint
- then goes home
- then continues to the final destination
## Good Mental Summary
## The cleanest way to think about goto in OnStepX is
- transforms produce candidate target representations
- limits decide which ones are reachable
- pier-side/orientation policy chooses among them
- wrap normalization may unwind coordinates into better branches
- waypoints and heuristics make the chosen path practical
- runtime limits keep watching after motion begins
## So the goto system is best understood as
- a target-planning and motion-decision engine
not just a coordinate conversion followed by a slew.
+461
View File
@@ -0,0 +1,461 @@
# Homing Notes
## Purpose
These notes describe how mount homing currently works in OnStepX.
This is a workflow note, not a deep explanation of low-level input filtering.
For the shared sensing subsystem itself, see:
- [SENSING_NOTES.md](SENSING_NOTES.md)
## For how homing relates to startup trust/authority, also see
- [STARTUP_AUTHORITY_NOTES.md](STARTUP_AUTHORITY_NOTES.md)
## Quick Summary
## There are three related but different ideas
1. Return to home
Move the mount to the configured home coordinates
2. Sensed home
Use home switches/sensors to find home
3. Reset at home
Rebuild the coordinate basis from the known home position
Those are often used together, but they are not the same operation.
## The Main Entry Points
## The core mount home commands are
- `:hC#`
move to home
- `:hF#`
reset the mount at home / cold-start position
- `:hA0#` / `:hA1#`
disable/enable automatic home at boot
- `:hC1,R#` / `:hC2,R#`
toggle home-sense reversal for axis1/axis2
- `:hC1,n#` / `:hC2,n#`
set home sense offset in arc-seconds
## Status command
- `:h?#`
returns `hasSense,axis1Offset,axis2Offset`
## What "Home" Means
## The configured home position is derived from
- mount type
- configured home defaults
- site latitude where relevant
- optional sense offsets
- special geometry such as meridian-flip handling
That home position is refreshed by `Home::init()` and then returned through
`home.getPosition(...)`.
So "home" is not just a fixed pair of axis numbers. It is computed in context.
## It is also important to separate
- mount orientation
- coordinates assigned to that orientation
Without home switches, "home" is primarily a coordinate definition that the
system returns to or resets against. In that case, home is not independently
observed from hardware. It is whatever mount orientation the current coordinate
basis says corresponds to the home coordinates.
That means the practical truth about what mount orientation counts as "home"
can shift when the coordinate basis shifts.
## Examples
- an authoritative reset at home reassigns the coordinate basis
- sync/model/origin changes can improve accuracy by shifting how the system
maps mount orientation into coordinates
- after those changes, the home coordinates may correspond somewhat differently
to mount orientation than before
With home switches, the home procedure has a stronger mount-orientation anchor
because the system is observing a real sense event during homing.
## So it is best to think of home as
- a reference in coordinate space
that may or may not be strongly anchored to mount orientation depending on
whether home sensing is available.
## The Three Main Workflows
## Workflow 1: Return To Home Without Sensors
This is the simple "move to home coordinates" path.
## It happens when
- `home.request()` is called
- no home switches/sense inputs are configured
## Behavior
- goto must be available
- startup authority must already be trusted
- date and time must be ready
- the mount slews to the computed home coordinates
This is just motion to a known coordinate target. It does not establish truth
from hardware sensing.
## Workflow 2: Sensed Home
This is the switch/sensor-based path.
## It happens when
- `home.request()` is called
- home sense is available
## Behavior
- goto must be available
- if startup authority is not trusted, sensed home is still allowed because it
can establish trust
- the guide subsystem starts a special home-guiding mode
- each axis uses `autoSlewHome()` to find the home switch state
- the axis may first move off the switch or toward it depending on the current
sensed state
- the axis refines through fast/slow/fine homing stages
## If sensing succeeds
- `home.guideDone(true)` runs
- an authoritative reset is performed
- startup authority becomes trusted
## If sensing fails
- `home.guideDone(false)` runs
- a non-authoritative reset/recovery path is attempted
- the home operation is marked failed
## What The Axis Class Actually Does During Sensed Home
The mount-level home request is only part of the story. The detailed switch
search sequence lives down in the axis class.
Each relevant axis uses `Axis::autoSlewHome()`.
## The important sequence is
1. Check the current home-sense state
2. Choose an initial direction
3. Slew until the sense state changes in the expected way
4. Decelerate to a stop
5. Refine through additional slower passes
## More concretely
- if home sense is already ON, the axis first moves forward off the switch
- if home sense is OFF, the axis first moves reverse toward the switch
- when the sense state changes appropriately, the axis stops
- the homing stage advances from `HOME_FAST` to `HOME_SLOW`
- then usually to `HOME_FINE`
## During the refinement sequence
- the slew rate is reduced
- the axis repeats the search with tighter motion
- if the switch state is still not in the expected condition after the slow
pass, an approach correction path is used before the final fine pass
This is why sensed home is more than "drive until switch closes once." It is a
small staged search procedure implemented at the axis level.
## Timeout also matters
- if no explicit timeout is supplied, the axis derives one from the configured
home distance limit and slew rate
- if the search times out, the homing slew aborts
## Motion safety still applies
- motion errors abort homing
- motor faults abort homing
- common min/max sense conflicts can also abort the slew
## So the full sensed-home sequence is
- mount/home layer decides that sensed home should happen
- guide layer starts coordinated home-guiding
- axis layer performs the actual staged switch search
- home layer interprets success/failure and performs reset/recovery
## Workflow 3: Reset At Home
This is the coordinate-basis rebuild step.
## It happens through
- `home.reset(...)`
- `:hF#`
- startup reset logic
- successful sensed-home completion
## Behavior
- tracking is stopped
- tracking-rate offsets are cleared
- goto first-use state is reset
- motor positions are reset to zero where appropriate
- home instrument coordinates are written back
- nominal index positions are captured
- backlash and slow slew defaults are restored
## If the reset is authoritative
- startup trust is granted
## If it is not authoritative
- it does not grant trust by itself
## Authoritative vs Non-Authoritative Reset
This is one of the key distinctions.
## Authoritative reset means
- the software has a good reason to believe the home position being applied is
truly correct
## Examples
- successful sensed home
- startup reset using valid paired absolute authority
- explicit authoritative origin/home workflows
## Non-authoritative reset means
- coordinates are being reassigned to home, but the software is not treating
that as proof of truth
## This distinction matters because
- authoritative reset can establish startup trust
- non-authoritative reset cannot
## How Trust Interacts With Homing
Homing is one of the main bridges between untrusted and trusted state.
## Important rules
- plain return-to-home without sensors requires trust first
- sensed home can be used to regain trust
- authoritative reset grants trust
- non-authoritative reset does not
## There is also one permissive carveout
- in `SA_AUTO` on simple mounts with no absolute encoders and no coordinate
memory, home/reset is allowed to bypass the sync-limit style coordinate jump
restriction
That keeps older/simple mounts practical without weakening the stricter cases
globally.
## Auto Home At Boot
## If `automaticAtBoot` is enabled
- autostart requests home after boot
This shares the same sensed-home or return-home machinery as a normal home
request. It is not a separate home implementation.
## That means
- success behaves like normal homing success
- failure behaves like normal homing failure
- auto-home does not silently pretend success if the sensed-home flow fails
## No-Goto Behavior
## If `GOTO_FEATURE == OFF`
- home request is rejected
- reset/home-with-motion request is rejected
- sensed home through guide-home is also rejected
This is intentional.
## In no-goto builds
- there is no fast automatic slew/home capability
- home/return is not supposed to pretend to exist as a supported motion mode
## How Home Sense Offsets Work
Each mount axis can have a stored sense offset.
## These offsets mean
- the physical home sense event is not necessarily the final logical home
coordinate
## Typical use
- a switch is placed somewhere repeatable but not exactly at the desired final
home location
- the offset defines the difference between switch-detected home and desired
coordinate home
## Commands
- `:hC1,n#`
- `:hC2,n#`
## Examples
- `:hC1,120#`
set axis1 home offset to +120 arcsec
- `:hC2,-300#`
set axis2 home offset to -300 arcsec
## Two Offset Modes
The config option `MOUNT_HOME_AT_OFFSETS` changes how offsets are used.
## When `MOUNT_HOME_AT_OFFSETS == OFF`
- sensed home resets at the switch-derived home first
- then, if offsets are in use, the mount may perform a finishing move toward
the true home coordinates after the authoritative reset
## When `MOUNT_HOME_AT_OFFSETS == ON`
- offsets are folded directly into the computed home position
## So the difference is basically
- separate finishing move
vs
- home already means the offset-adjusted position
## Home Sense Reversal
Each axis can also reverse the meaning of its home sense input.
## Commands
- `:hC1,R#`
- `:hC2,R#`
This is layered on top of the usual home-sense logic and is applied through
`setReversal()`.
Axis1 also has a latitude-related reversal for equatorial mounts in the
southern hemisphere, so axis1 home sense behavior is slightly more subtle than
just a plain stored boolean.
## Examples
## Example 1: Simple mount, no home switches
- user powers on
- mount already has trusted startup authority or permissive `SA_AUTO`
- `:hC#` moves to home coordinates
- `:hF#` can reset at the home position
## Example 2: Mount with home switches
- user or autostart requests home
- guide-home uses switch sensing to find home
- successful sensed home performs authoritative reset
- trust is granted
## Example 3: Switch is repeatable but not exactly at desired home
- home sense is configured
- nonzero offsets are stored
- sensed home finds the switch
- reset establishes truth
- final coordinate home may be offset from the literal switch crossing
## Special Geometry Cases
Sector gear axis1 and tangent-arm axis2 are special.
In those cases, homing and reset do not always follow the plain "reset both
axes to zero and write home coordinates" pattern.
For these geometries, home is not only about returning to a meaningful
coordinate reference. It is also about resetting the mechanism so later gotos
and tracking have useful travel remaining inside the limited range.
## So on a sector gear or tangent-arm mount, homing is often better understood as
- mechanical re-baselining of the constrained axis
- restoring useful travel for later motion
- re-establishing the coordinate-to-mechanism relationship for that limited
range
Because of that, some of the ordinary coordinate-based prechecks are also less
meaningful here. On these mounts the code relaxes or skips parts of the normal
"how far are we from home in coordinates?" logic before sensed homing, because
operation is fundamentally constrained and often more manual.
## Instead
- origin/position handling is adjusted to fit the special axis geometry
- successful sensed home may set origin more directly for the special axis
So if behavior looks a little different on sector gear or tangent-arm mounts,
that is expected.
## Failure Modes
## Homing can fail because of
- goto disabled
- motion already active
- missing date/time for plain return-home
- distance-to-home outside the configured sensed-home search limit
- switch search timeout
- motion error or motor fault during homing
- reset failure after the home-search phase
The code tries to fail conservatively rather than pretending home succeeded.
## Relationship To Sensing
Homing depends heavily on the shared sensing subsystem, but that low-level
behavior is documented separately.
## If you need to understand
- how `HIGH | HYST(20)` is interpreted
- how analog threshold/hysteresis sensing works
- how runtime reversal works
## see
- [SENSING_NOTES.md](SENSING_NOTES.md)
## Good Mental Summary
## The cleanest summary is
- return-to-home is motion to a known coordinate target
- sensed home is a hardware-based search procedure
- reset-at-home rebuilds the coordinate basis
- authoritative homing/reset can establish startup trust
Those are related operations, but they are not interchangeable.
+420
View File
@@ -0,0 +1,420 @@
# PEC Notes
## Purpose
These notes describe how PEC currently works in OnStepX.
## PEC is one of the harder features to reason about because it combines
- persistent state
- a sampled correction table
- worm indexing
- tracking state
- guide interaction
- park/unpark interaction
## The implementation is concentrated mainly in
- `src/telescope/mount/pec/Pec.h`
- `src/telescope/mount/pec/Pec.cpp`
- `src/telescope/mount/pec/Pec.command.cpp`
## Quick Summary
## The clean mental model is
1. PEC stores one correction value per sidereal second of worm rotation
2. a worm index event establishes where the buffer starts
3. playback adds/subtracts a small tracking-rate correction each second
4. recording learns those per-second corrections from accumulated guide action
## So PEC in OnStepX is basically
- a one-second-slot correction table wrapped around the worm rotation
## What PEC Applies To
## Current mount PEC support is for
- axis1 only
Although the implementation and terminology are written around a worm cycle,
the correction model does not technically require a worm. It can also model
other repeatable geared error sources as long as:
- the cycle can be indexed
- the cycle length is stable
- the cycle period fits within the supported PEC limits/buffer size
## If `PEC_BUFFER_SIZE_LIMIT == 0` or `PEC_STEPS_PER_WORM_ROTATION == 0`
- PEC is effectively disabled
## The Main Stored Data
## PEC stores
- whether valid PEC data have been recorded
- current PEC state
- worm rotation length in steps
- the PEC correction buffer itself
The small settings live in normal NV settings storage.
## The correction table itself lives in a dedicated NV partition named
- `PEC`
## Important persistence detail
- changing or recording PEC data in RAM does not automatically write the PEC
table to NV
- writing the PEC table to NV only happens on explicit user command
## This is separate from PEC control state
- arming playback/record or disabling PEC updates the small PEC settings in NV
- but the actual correction table is only written by explicit save command
## That means
- after a recording session, the in-memory PEC table may differ from the
persisted PEC table
- if the user does not explicitly save the new data, a reboot comes back with
whatever PEC table was previously stored
## This is useful because
- a bad recording session can simply be abandoned by not saving it
## The PEC Buffer
The PEC buffer is not stored as one entry per motor step.
## Instead
- one entry represents one sidereal second of worm rotation
## That means
- buffer size in bytes is approximately worm rotation time in seconds
## Example
- if one worm rotation takes 720 sidereal seconds
- the PEC buffer has 720 entries
Each entry is an `int8_t` correction value.
So each second of worm rotation gets a small signed rate correction.
## How Worm Rotation Length Is Used
## The configured worm rotation length is stored as
- `PEC_STEPS_PER_WORM_ROTATION`
## PEC uses that to derive
- seconds per worm rotation
- buffer size
- current worm-rotation position from current axis1 motor steps
## So PEC fundamentally depends on
- knowing how many axis1 motor steps correspond to one worm rotation
## Two Ways PEC Gets Its Index
## PEC can work with
1. real sense input (`PEC_SENSE != OFF`)
2. virtual wraparound indexing (`PEC_SENSE == OFF`)
## With real sense input
- a sense event on `PEC_SENSE_PIN` defines the worm index
- PEC waits for enough worm travel before accepting another index
- this avoids repeated false retriggers too close together
## Without real sense input
- PEC treats worm rotation wraparound as a virtual index
## So
- hardware sense gives a stronger physical anchor
- no-sense PEC is still possible, but indexing is inferred
## How The Index Event Works
## When PEC sense is enabled
- the sense input is read through the shared `Sense` subsystem
- a valid ON transition after enough worm travel is treated as an index event
- the current axis1 motor step position becomes `wormSenseSteps`
- PEC marks that it has a valid worm reference
- playback buffer position can be realigned to that reference
## This is why the sensing note matters here too
- low-level sense filtering decides whether the PEC index input is ON
- PEC then adds its own motion/spacing logic before trusting that event as a
real index
## When PEC Is Active
PEC is only allowed to do real work when the mount is in an appropriate state.
## Main requirements
- the mount must be tracking
- guide state must not exceed pulse-guide style use
- the mount must not be parking or parked
## If those conditions are not true
- PEC disables recording
- PEC pauses playback
## Important distinction
- playback pause is not the same as losing PEC data
## If PEC was playing and the mount becomes ineligible
- state drops back to `PEC_READY_PLAY`
- playback can resume after re-indexing/alignment timing is right again
## The PEC State Machine
## Main states
- `PEC_NONE`
- `PEC_READY_PLAY`
- `PEC_PLAY`
- `PEC_READY_RECORD`
- `PEC_RECORD`
## Meaning
- `PEC_NONE`
PEC inactive
- `PEC_READY_PLAY`
user requested playback; PEC is waiting for the right timing/index position
- `PEC_PLAY`
PEC actively applying corrections
- `PEC_READY_RECORD`
user armed recording; PEC is waiting for the right timing/index position
- `PEC_RECORD`
PEC actively recording guide-derived corrections
## Why "Ready" States Exist
PEC does not jump into play or record at an arbitrary instant.
## Instead, it waits until
- the worm position is aligned to a one-second slot boundary
This makes the table alignment cleaner and keeps the one-second buffer indexing
consistent.
## So "ready" means
- the user has requested the action
- PEC is waiting for the correct phase/alignment to begin
## Playback
## During playback
- PEC advances the buffer index once per sidereal second
- it looks up the correction for the current worm segment
- it applies that as a fractional tracking-rate offset
## One subtle detail
- playback uses the correction from one second earlier than the current segment
The code comments describe this as a rough latency estimate between image
acquisition and response.
So PEC playback is intentionally shifted slightly ahead in effect.
## Recording
## During recording
- guide contribution on axis1 is accumulated
- once per sidereal second, that accumulated correction is quantized into a
small signed step value
- that value becomes the PEC table entry for the current buffer slot
## If this is not the first recording
- new data are blended with existing data using a weighted average
## So PEC recording is not just "write raw guide values directly." It is
- accumulate
- quantize per second
- optionally blend with existing data
## What "First Recording" Changes
## If this is the first time PEC is being recorded
- the new table is taken directly from current recording data
## If PEC data already exist
- new data are blended with the old table
That lets users refine an existing PEC table rather than always replacing it
from scratch.
## Cleanup After Recording
## When recording finishes
- PEC automatically switches to play
- the table is run through a cleanup pass
## Cleanup includes
- a low-pass smoothing pass
- a linear-regression style correction so the total sequence sums close to zero
That last part matters because PEC corrections should not create a long-term
net tracking bias over a whole worm cycle.
## If the cleanup result looks unreasonable
- PEC invalidates the recorded data
- PEC drops back to `PEC_NONE`
## Why The Sum Matters
A PEC table is supposed to redistribute tracking slightly over the worm cycle,
not permanently add or subtract motion over a full cycle.
## So after cleanup
- the total correction sequence should roughly cancel out
That is why PEC does a "reality check" on the residual sum.
## Park / Unpark Interaction
PEC interacts with park in an important way.
## When parking
- PEC is turned off
- the current worm sense position is saved into park settings
## When unparking/restoring
- that saved worm sense position is restored
## If a real `PEC_SENSE` input exists
- worm index truth is also recovered automatically once the worm rotates far
enough to detect the next valid PEC index event
So the restored saved position helps continuity immediately after unpark, while
the physical PEC sense can later re-anchor the index automatically on the next
cycle.
So park/unpark is part of how PEC continuity is maintained across a parked
interval.
This is another reason PEC is harder to reason about than a simple runtime
feature. It is not independent of park state.
## Examples
## Example 1: Playback with real worm index
- PEC data were previously recorded
- user enables PEC playback
- state becomes `PEC_READY_PLAY`
- mount tracks
- PEC waits for the right segment timing
- playback starts
- a later real PEC index event can realign buffer start
## Example 2: Recording new PEC data
- mount is tracking
- user arms PEC recording
- state becomes `PEC_READY_RECORD`
- at the right timing boundary PEC enters `PEC_RECORD`
- guide activity is accumulated into one-second corrections
- after one worm cycle, recording finishes
- cleanup runs
- PEC switches into playback
## Example 3: Mount stops tracking during playback
- PEC was in `PEC_PLAY`
- tracking stops or mount becomes ineligible
- PEC falls back to `PEC_READY_PLAY`
- rate goes to zero
- playback can later resume when conditions are valid again
## Commands
## There are several PEC commands, but the most important control ones are
- `:$QZ+#`
arm/enable playback
- `:$QZ-#`
disable PEC
- `:$QZ/#`
arm recording
- `:$QZZ#`
clear the PEC buffer
- `:$QZ!#`
save PEC data to NV
- `:$QZ?#`
get PEC status
## There are also read/write commands for
- table contents
- worm rotation steps
- buffer size
- current index location
## For the exact command list, see
- [COMMAND_REFERENCE.md](COMMAND_REFERENCE.md)
## Things That Make PEC Hard To Reason About
## PEC combines several different concerns at once
- mount motion state
- tracking state
- guide accumulation
- worm index sensing
- one-second slot timing
- persistent storage
- park/unpark continuity
That is why local code reading can still leave the feature feeling opaque.
## Good Mental Summary
## The most useful summary is
- PEC is a per-second correction table over one worm rotation
- indexing tells PEC where the table starts
- playback applies one correction slot each sidereal second
- recording learns those slots from guide activity
- cleanup makes the finished table smooth and net-neutral over the full cycle
If you keep that model in mind, the rest of the state machine becomes much
easier to follow.
+401
View File
@@ -0,0 +1,401 @@
# Sensing Notes
## Purpose
## These notes describe the shared sensing subsystem used across OnStepX for
- home sense
- limit sense
- park sense
- PEC sense
- some local focuser/button-style inputs
The main reason this deserves its own note is that a "sense input" in OnStepX
is not just a simple digital switch. The same general machinery supports:
- ordinary digital active-high or active-low inputs
- digital inputs with software time filtering
- analog threshold sensing
- analog hysteresis behavior
- runtime inversion of the logical sense state
There is also a related but separate `Button` helper for more button-specific
input behavior, including analog range comparison. That is covered near the end
of this note.
## Quick Summary
## The simplest mental model is
1. raw GPIO or analog input comes in
2. `Sense` turns it into a normalized ON/OFF state
3. higher-level code decides what ON/OFF means operationally
## Examples
- home code asks whether home sense is active/ON according to its configured
`HIGH`/`LOW` meaning
- limit code asks whether the min/max sense is ON
- PEC asks whether the worm index sense is ON
The same low-level sensing code is reused in all of those cases.
## Where The Shared Sense Code Lives
## The main subsystem is
- `src/lib/sense/Sense.h`
- `src/lib/sense/Sense.cpp`
## Main API
- `sense.add(...)`
- `sense.isOn(...)`
- `sense.changed(...)`
- `sense.stableMillis(...)`
- `sense.reverse(...)`
- `sense.poll()`
In most feature code, the higher-level subsystem does not read the GPIO pin
directly. It registers a sense input once and then works with the normalized
result through a sense handle.
## How Sense Configuration Works
## Each sense input is defined by
- a pin
- an init mode such as `INPUT`, `INPUT_PULLUP`, or `INPUT_PULLDOWN`
- a packed trigger value
The packed trigger value normally combines pieces with `|`.
That is the usual configuration pattern.
## Examples
- `HIGH`
- `LOW`
- `HIGH | HYST(20)`
- `LOW | HYST(50)`
- `HIGH | THLD(512)`
- `LOW | THLD(300) | HYST(25)`
Combining flags numerically with `|` is typically the intended style.
## What The Trigger Encodes
## The trigger value carries
- the active state bit: `HIGH` or `LOW`
- an optional analog threshold via `THLD(v)`
- an optional hysteresis via `HYST(v)`
## Important rule
- if the threshold part is zero, the input is treated as digital
- if the threshold part is nonzero, the input is treated as analog
## So
- `HIGH | HYST(20)` is still digital
- `LOW | THLD(400) | HYST(15)` is analog
## Digital Sense
Digital mode is used when there is no threshold component.
## Behavior
- raw input is read with `digitalReadEx(pin)`
- `HYST(n)` is the required stable time in milliseconds before a digital state
change is accepted
- the new digital sample must remain unchanged for that long before the
logical state changes
## So in digital mode, `HYST()` does not mean an analog band. It means
- how long the signal must stay stable before the change is accepted
## Examples
- `HIGH`
active-high digital input, no extra filtering
- `LOW`
active-low digital input, no extra filtering
- `HIGH | HYST(10)`
active-high digital input, require about 10ms of stable state before the
logical result changes
- `LOW | HYST(50)`
active-low digital input with heavier software debounce/noise filtering
## This is useful for
- switch debounce
- modest EMI/RFI filtering
- noisy digital inputs that should not chatter
## Analog Sense
Analog mode is used when a threshold component is present.
## Behavior
- raw input is read with `analogRead(...)`
- on ESP32, `analogReadMilliVolts(...)` is converted back into the common
`ANALOG_READ_RANGE` scale for higher accuracy on this platform
- the threshold and hysteresis act like a software Schmitt trigger
## This means
- if the sample rises above `threshold + hysteresis`, the logical value becomes
`HIGH`
- if the sample falls below `threshold - hysteresis`, the logical value becomes
`LOW`
- inside the band between those two thresholds, the last logical state is
retained
## That band is effectively a deadband zone
- the signal can move around inside it without causing repeated state changes
- a state change only happens after the signal leaves the deadband on one side
or the other
## Examples
- `HIGH | THLD(512)`
active-high analog threshold at mid-scale, no hysteresis band
- `LOW | THLD(300) | HYST(25)`
active-low analog threshold input with a hysteresis band around the threshold
- `HIGH | THLD(800) | HYST(50)`
active-high analog input that must move well above and below the threshold
before changing state
## This is useful when
- a clean digital threshold is not available from hardware
- analog noise would otherwise cause state chatter
## Why Hysteresis Means Two Different Things
This is one of the easiest things to forget.
## In digital mode
- `HYST(n)` means time in milliseconds
## In analog mode
- `HYST(n)` means an analog hysteresis band around the threshold, creating a
deadband zone where the current state is held
That dual meaning is intentional, but it is easy to misread in config.
## What "ON" Means
## The subsystem separates
- the filtered internal logical value (`HIGH` or `LOW`)
- whether that logical value counts as ON for the caller
`sense.isOn(...)` returns true when the filtered value matches the configured
active state.
## So
- active-high means HIGH is considered ON
- active-low means LOW is considered ON
## This lets higher-level code work with
- "is the home sense active?"
- "is the limit sense active?"
without caring whether the hardware is electrically active-high or active-low.
## Runtime Reversal
`sense.reverse(handle, state)` flips the interpretation at runtime.
This is different from the original config.
## Config answers
- what electrical state counts as active
## Runtime reversal answers
- should this sense be interpreted the opposite way right now
## In practice this is used by code such as
- `Axis::setHomeReverse()`
This is useful when the electrical truth stays the same but the motion logic
needs the opposite interpretation.
## Where `Sense` Is Used
## Shared `Sense` users currently include
- axis home sense
- axis min/max limit sense
- park sense
- park signal monitoring
- PEC worm index sense
- local focuser sense inputs
That is why it is better to think of `Sense` as a general-purpose input
normalization subsystem, not just "home switch code."
## Example: Home Sense
Axis home sense is registered in `Axis::init()`.
## Important behavior
- homing first checks whether home sense is already ON
- if it is ON, motion first goes forward off the switch
- if it is OFF, motion first goes reverse toward the switch
So home sense is not just an endpoint detector. It also affects the search
direction and homing flow.
## Typical home examples
- `AXIS1_SENSE_HOME HIGH`
simple active-high home switch
- `AXIS1_SENSE_HOME LOW | HYST(20)`
active-low home switch with digital debounce
- `AXIS1_SENSE_HOME HIGH | THLD(450) | HYST(20)`
analog thresholded home sense with hysteresis
## Example: Limit Sense
Limit sense uses the same subsystem for min/max axis limits.
## Runtime behavior
- `Axis::poll()` updates the sensed limit flags
- `Limits::poll()` reacts and stops the relevant motion direction
## One important special case
- min and max can share the same physical pin
## By default
- the axis notes this as `commonMinMaxSense`
- the higher-level limit logic avoids treating one shared input as two separate
independent events
## Config option
- `LIMIT_SENSE_STRICT == ON` disables that relaxation and treats shared min/max
more strictly
## Typical limit examples
- `LIMIT_SENSE LOW`
common active-low limit input
- `LIMIT_SENSE LOW | HYST(10)`
common active-low limit input with digital filtering
## Example: Park Sense
## Parking uses the same sensing framework for
- `PARK_SENSE`
- `PARK_SIGNAL`
Those are not special sensing implementations. They are just more clients of
the shared normalized ON/OFF sensing subsystem.
## Example: PEC Sense
PEC can also use the same shared `Sense` subsystem.
## That means the PEC index input can also be
- digital
- analog thresholded
- analog with hysteresis
Then PEC adds its own higher-level logic on top, such as only accepting a new
index event after enough motion has occurred.
## So
- `Sense` decides whether the input is ON
- PEC decides whether that ON transition counts as a valid worm index event
## What `Sense` Does Not Do
The shared `Sense` subsystem does not implement every kind of analog input
pattern.
## In particular, it does not implement
- "pressed when analog value lies within a range"
## It is focused on
- digital filtered ON/OFF sensing
- analog threshold-plus-hysteresis ON/OFF sensing
## Related But Separate: `Button`
## There is a related helper in
- `src/lib/pushButton/PushButton.h`
- `src/lib/pushButton/PushButton.cpp`
## That helper is more button-focused and adds behavior such as
- press/release semantics
- click and double-click detection
- tone/frequency detection
- analog threshold mode
- analog range/value mode
That analog value/range mode is the "pseudo-digital using analog sampling and
range comparison" behavior.
## So if someone is looking for
- analog value-in-range detection
- button semantics
- tone-style input behavior
they should usually look at `Button`, not `Sense`.
## Practical Rules Of Thumb
## If the input is a normal switch
- start with plain `HIGH` or `LOW`
## If the switch chatters or is noisy
- add `HYST(n)` and remember that in digital mode it means milliseconds
## If the input is fundamentally analog
- use `THLD(...)`
- add `HYST(...)` if you want Schmitt-trigger-like stability
## If the meaning of the signal must flip at runtime
- use runtime reversal rather than redefining the electrical config
## Good Mental Summary
## The cleanest way to think about sensing in OnStepX is
- config defines how raw input should be interpreted
- `Sense` turns that raw input into a stable ON/OFF result
- higher-level features decide what ON/OFF means operationally
That separation is why the same low-level sensing subsystem can be reused for
home, limits, park, PEC, and other features without each subsystem reinventing
analog/digital input conditioning.
+314
View File
@@ -0,0 +1,314 @@
# Serial Notes
## Purpose
These notes explain how serial interfaces are used in OnStepX and why serial
configuration can be confusing across platforms.
## The short version is
- a platform may support several kinds of serial interfaces
- a pinmap chooses which ones are exposed for a given board
- a feature may or may not be well suited to the chosen serial transport
## So "serial is supported" does not always mean
- easy to configure
- portable to another board
- good for real-time runtime use
## Quick Summary
## Think about serial in three layers
1. Platform:
What the MCU/core can do
2. Pinmap:
Which serial roles are exposed on this board
3. Feature:
Whether the transport is actually a good fit for the workload
## Examples
- GPS over `SoftSerial` can be fine
- TMC2209 over `SoftSerial` may compile but still be a poor runtime fit
- Teensy can expose extra USB virtual serial ports
- ESP32 can often move hardware UARTs to different pins
## The Main Serial Roles
OnStepX uses generic serial role names instead of hard-coding one board's port
names everywhere.
## Common roles include
- `SERIAL_A`
- `SERIAL_B`
- `SERIAL_C`
- `SERIAL_D`
- `SERIAL_E`
- `SERIAL_GPS`
- `SERIAL_TMC`
- `SERIAL_DEBUG`
These are best thought of as roles, not fixed physical ports.
## One board might make
- `SERIAL_B = Serial2`
## Another board might make
- `SERIAL_B = HardSerial` with configured RX/TX pins
Another board might not expose `SERIAL_B` at all.
## The Main Serial Types
## In practice, OnStepX may use
- built-in hardware serial ports such as `Serial1`, `Serial2`, etc.
- created hardware serial objects using chosen RX/TX pins
- `SoftwareSerial`
- USB virtual serial ports
- internal pseudo-serial helpers such as `SERIAL_LOCAL`
All of these may look stream-like in code, but they are not equally suitable
for all jobs.
## Platform Differences
This is where a lot of confusion starts.
## Teensy
- often has multiple hardware UARTs
- can also expose extra USB virtual serial ports depending on USB mode
- some pinmaps use that to expose `SERIAL_D = SerialUSB1` and
`SERIAL_E = SerialUSB2`
## ESP32
- usually has flexible hardware UART routing
- can often place UART RX/TX on non-default pins
- that makes created hardware serial or remapped UART use more practical than
on some other Arduino-class targets
- also has optional Bluetooth serial support in the HAL
## STM32
- often supports created/remapped hardware serial well
- also pulls in `SoftwareSerial` support early in the HAL because library/core
behavior can otherwise get awkward
## Why ESP32 Is Worth Calling Out
ESP32 is a good example of why "hardware serial" does not always mean
"hard-wired fixed pins."
## In OnStepX, some ESP32 pinmaps define roles like
- `SERIAL_B = Serial2`
- `SERIAL_TMC = Serial1`
## and then separately define
- `SERIAL_B_RX`
- `SERIAL_B_TX`
- `SERIAL_TMC_RX`
- `SERIAL_TMC_TX`
That means the feature gets a real hardware UART, but the board still has some
freedom to place it where it makes sense.
## This is one reason ESP32 can be a nice middle ground
- better than `SoftSerial` for runtime work
- more flexible than boards with only fixed UART pin assignments
## Pinmaps Decide What Exists
The pinmap layer is where generic serial roles become concrete.
## This means
- a feature may request `SERIAL_GPS`
- but whether that becomes `SoftSerial`, `HardSerial`, `Serial1`, or something
else depends on the pinmap and platform
## Compile-time validation catches some problems, for example
- a baud rate is enabled for a serial role that the pinmap did not define
- a TMC UART driver is enabled but `SERIAL_TMC` is missing
## What validation does not prove
- that the chosen serial transport is a good runtime fit
- that it is non-blocking enough
- that the underlying library behaves well on that platform
## Best Uses For Each Type
## Built-in or created hardware serial
## Usually best for
- continuous runtime traffic
- higher baud rates
- frequent bidirectional communication
- motion-control related serial work
## Examples
- shared TMC2209 UART on boards designed for it
- a secondary MCU link
- frequent device polling
## `SoftwareSerial`
## Usually best for
- one-time configuration at boot
- low-rate telemetry
- devices that become less important once startup finishes
## Examples
- GPS
- boot-time driver setup in some constrained builds
## USB virtual serial
## Usually best for
- extra host-side channels
- debug, tooling, or auxiliary control on supported platforms
## Examples
- Teensy `SerialUSB1`
- Teensy `SerialUSB2`
## Why `SoftwareSerial` Is Tricky
`SoftwareSerial` is often the most confusing case because it is sometimes very
useful and sometimes a terrible fit.
## General concerns
- it is often blocking or close enough to blocking to matter
- support quality varies by platform
- timing behavior varies by core and library
- library code sitting on top of it may own the actual read/write behavior
So if a feature "supports `SoftSerial`", that should not automatically be read
as:
- well tested
- non-blocking
- appropriate for real-time runtime use
## Example: GPS
GPS is one of the better cases for less-than-perfect serial.
## Why
- relatively low-rate
- mostly an input stream
- used to establish time/location
- OnStepX may close the GPS serial port once current time has been acquired
So GPS over `SoftSerial` can be a reasonable trade on many builds.
That does not make `SoftSerial` universally good. It just means GPS is a
feature that can often tolerate it.
## Example: TMC2209 UART
TMC2209 is the opposite kind of example.
## Why it is harder
- runtime UART interaction can matter
- mode changes may happen during operation
- status/config traffic may be needed while the rest of the mount is busy
- blocking behavior is much more painful in a real-time motion system
## So for TMC2209
- `SoftSerial` may be acceptable for one-time setup at boot
- `SoftSerial` is much less attractive for active runtime interaction
That does not mean `SoftSerial` is useless here. It means the use case matters.
## Example: More Than Four TMC2209s
## There is one place where `SoftSerial` can still be attractive for TMC2209
- per-device links can make scaling easier when a shared hardware UART bus gets
awkward
## So there is a real trade
- shared hardware UART is usually better for runtime quality
- per-device `SoftSerial` may make some larger or stranger topologies possible
## This is why the answer is not simply
- "never use `SoftSerial`"
## It is more like
- use it carefully
- prefer it for boot/setup or unusual topologies
- do not assume it is ideal for active runtime control
## Library Ownership Matters
## Another subtle point
OnStepX may define the transport, but the feature library often performs the
real reads and writes.
## That means serial behavior depends on
- the platform core
- the chosen transport
- the feature library
## This is especially relevant for
- TMC driver libraries
- any feature with frequent serial traffic
So a configuration can be theoretically valid while still being lightly tested
or operationally uncertain.
## Practical Rules Of Thumb
## If the serial link is mostly needed at boot
- `SoftSerial` may be acceptable
## If the serial link is needed continuously during runtime
- prefer hardware UART where possible
## If the board/platform offers extra USB serial channels
- treat that as a platform-specific bonus, not a general Arduino assumption
## If a user is choosing between "works in theory" and "works robustly"
- favor the more boring hardware-UART option
## Good Mental Summary
## The simplest reliable way to think about serial in OnStepX is
- HAL defines what the platform can plausibly do
- the pinmap assigns generic serial roles to actual transports
- the feature decides whether that transport is really suitable
That last step is where most serial surprises come from.
+496
View File
@@ -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"
+366
View File
@@ -0,0 +1,366 @@
# Startup Authority And Coordinate Trust Notes
## Purpose
These notes describe how startup authority and coordinate trust currently work
for the mount, and how that affects automatic motion such as goto, sync,
park/unpark, and home/return.
## Core idea
The mount tracks a runtime trust state whose only question is:
"Do we trust the current coordinate basis enough for coordinate-based
automatic motion?"
If trust is true:
- coordinate-based automatic operations are allowed
If trust is false:
- coordinate-based automatic operations are blocked
- manual guide recovery is still allowed
- plain sidereal tracking is not gated by startup authority itself, but it may
still be blocked by other safety policy
## Two useful distinctions
1. Immediate startup authority
- trust is available immediately at boot from an already-available authority
source
2. Deferred startup authority
- boot starts untrusted
- an authoritative startup-time action later establishes trust
Date/time readiness is separate from both of the above.
Limit enforcement is related but separate too:
- startup authority answers whether the coordinate basis is trusted
- date/time readiness answers whether sky-referenced operation is ready
- limit enforcement can become active as soon as both are available
## What currently establishes trust
Trust can currently come from either immediate startup authority sources or
later authoritative actions.
Immediate startup authority sources:
- paired mount-axis absolute position sources at boot, with origin(s)
established
- trusted mount coordinate memory restore
Boot policy is selected by MOUNT_STARTUP_MODE.
Default:
- SA_AUTO
Modes:
- SA_STRICT:
boot stays untrusted unless an immediate startup authority source succeeds
- SA_AUTO:
if neither mount axis has an absolute position source and mount coordinate
memory is OFF, boot grants legacy session trust automatically
- SA_PERMISSIVE:
boot grants session trust automatically even when stricter authority sources
exist
Later authoritative actions:
- authoritative set-origin at a known home position
- authoritative reset at a known home position
- successful switch-based home
- SWS v2.10d or later hosting absolute encoders (for pointing correction)
Ordinary sync is not used to restore trust.
## What currently revokes trust
Trust is revoked conservatively when the system can no longer honestly assume
the coordinate basis is valid.
Currently implemented:
- motor/encoder fault
- NV fault (default behavior, because NV_INIT_ERROR_REVOKES_AUTHORITY defaults to ON)
Important non-revocation note:
- a motion stop caused by limits or StallGuard is not, by itself, a trust
revocation event
## What is blocked while untrusted
Blocked:
- goto
- set park
- park
- unpark
- normal sync
- home/return unless switch-based home is available
Allowed:
- manual guide
- plain sidereal tracking, subject to the normal tracking safety policy
Important tracking note:
- startup authority does not itself gate plain sidereal tracking
- however, tracking is still subject to other conditions such as parked state,
date/time-dependent enable rules, and limit policy
- by default, tracking is disallowed when limits are not enforced
## Parking workflow
Parking is part of the same trust model because park/set-park/unpark all depend
on the mount coordinate basis being believable.
While untrusted:
- set park is blocked
- park is blocked
- unpark/restore is blocked
Why:
- set park stores a coordinate-based reference that should not be accepted if
the current coordinate basis is already in doubt
- park and unpark are automatic coordinate-based motions, so they should follow
the same trust rules as goto
Operationally this means:
- a parked state is only useful if it was established from a trusted coordinate
basis
- unpark/restore is allowed when resuming from previously trusted parked state
- unpark/restore should not be thought of as a way to recover trust from unknown
state
- the legacy "unpark from home" exception is only allowed on simpler mounts; it
is disabled for SA_STRICT, for mounts using coordinate memory, and for mounts
with absolute position sources
## Workflow 1: Boot With Immediate Startup Authority
This is the cleanest startup path.
On these mounts, trust can be granted automatically at boot because the mount
already has an authoritative coordinate basis before any manual recovery is
needed.
Current immediate startup authority sources are:
- paired mount-axis absolute position sources
- trusted mount coordinate memory
## Workflow 1a: Boot With Paired Mount-Axis Absolute Coordinate Authority
This applies when:
- both mount axes report absolute position at startup
- the required encoder origin(s) are already established
- startup reset is therefore allowed to treat the mount-axis absolute readings
as authoritative for the initial coordinate basis
This is intentionally stricter than "one axis happens to be absolute."
For the mount axes, absolute coordinate authority is only valid as a paired
startup basis.
In practice this covers the supported mount-axis absolute-authority cases,
including:
- paired servo absolute encoders
- paired ODrive absolute-authority configuration
For runtime/NV origin storage:
- UINT32_MAX is used as the "origin not established" sentinel
Compile-time configured nonzero AXIS*_ENCODER_ORIGIN values are treated as
already established by configuration.
## Workflow 1b: Boot With Trusted Mount Coordinate Memory
Mount coordinate memory acts much like an "effective absolute startup source"
in the trust model:
- it can re-establish a coordinate basis at boot
- but only if the saved record is marked trusted
Important assumption:
- this depends on the mount being moved only by the drive system
- if clutches are present, they must not slip and must not be disengaged while
coordinate memory is being relied on as a startup authority source
Mount coordinate memory already uses:
- alternating A/B records
- CRC validation
It now also uses a trust bit:
- trusted records may restore authority
- untrusted records do not restore authority
This separates:
- storage validity
- semantic trust
So coordinate memory is not just "last known position storage." It is also a
startup authority source when, and only when, the saved record is trusted.
## Workflow 2: Boot Without Immediate Startup Authority
What happens here depends on MOUNT_STARTUP_MODE.
In SA_STRICT:
- if the mount has neither:
- paired mount-axis absolute position sources
- trusted mount coordinate memory
- trust is not granted automatically at startup
In SA_AUTO:
- if the mount has neither:
- paired mount-axis absolute position sources
- mount coordinate memory enabled
- boot grants legacy session trust automatically
- this preserves the long-standing "power up and goto" workflow on simpler
mounts
If mount coordinate memory is configured but the saved record is missing or
untrusted, SA_AUTO does not silently fall back to permissive trust. In that
case the system stays untrusted until an authoritative action succeeds.
In SA_PERMISSIVE:
- boot grants session trust automatically regardless of startup authority
sources
Current recovery model:
1. user manually guides to a known place if needed
2. user performs an authoritative action:
- set origin
- authoritative reset at a known home position
- successful switch-based home
- reboot with a valid startup authority source
3. trust becomes true again
Important practical consequence:
- the default SA_AUTO mode preserves permissive startup for simple mounts with
neither paired absolute position sources nor coordinate memory enabled
- SA_STRICT remains available for observatory and interlock-sensitive installs
## Workflow 3: Boot Untrusted, Then Establish Trust With Auto-Home
Auto-home with switches is best thought of as deferred startup authority.
It is not an immediate startup authority source.
Instead:
- boot begins untrusted
- switch-based home runs
- if successful, trust is established afterward
Switch-based home and auto-home-at-boot share the same sensed-home path.
Success:
- successful sensed home leads to authoritative reset
- trust is restored
Failure:
- coordinates are still reset for consistency
- failure is latched
- trust is not restored
- auto-home at boot does not continue as if homing succeeded
This behavior is intentionally consistent with normal switch-based return/home,
not just boot homing.
## Coordinate memory during homing
Important edge case:
when switch-based homing is in progress, mount coordinates are effectively
arbitrary relative to physical truth.
To prevent a power loss during homing from producing a misleading trusted
restore candidate:
- coordinate memory is marked untrusted as soon as switch-based homing starts
- periodic saves during HS_HOMING remain untrusted
- after successful authoritative homing, trust is restored normally
So if power is lost mid-home:
- the mount will come up with coordinate memory present but untrusted
- automatic coordinate-based motion will remain blocked
- the user can home/reset again, regain trust, and continue
## Workflow 4: Date/Time Not Ready
Date/time readiness and startup trust are related but not the same thing.
Trust answers:
- "Do we believe the coordinate basis is valid?"
Date/time answers:
- "Can we safely/usefully perform sky-referenced operations right now?"
So a mount may have trust while date/time is still not ready.
In that state:
- the coordinate basis may still be considered authoritative
- but some operations may remain postponed or blocked until date/time is ready
For mounts using trusted coordinate memory restore or trusted paired absolute
startup position:
- once date/time becomes ready, limit enforcement can be enabled immediately
- this does not require a later goto, reset/home, or unpark just to make
limits active
- that in turn allows tracking requests to succeed normally under the usual
limit-safety policy
Example:
- unpark recovery may wait for the normal site/time flow even when trust is
already valid
## Workflow 5: Losing Trust During Runtime
If trust is lost after startup:
- coordinate-based automatic motion stops being allowed
- manual guide recovery remains available
- sidereal tracking is still not gated by startup authority itself, but it
remains subject to the normal tracking safety policy
The guiding rule is:
- if the system knows where it is, coordinate-based automatic motion is allowed
- if it does not know where it is, coordinate-based automatic motion is blocked
- guide-based manual recovery remains available
## Important startup workflows to remember
1. Basic mount with clutches, no absolute encoders, no coordinate memory:
- common user workflow is manually place at home, power on, then goto/sync
- SA_AUTO preserves this by granting session trust at boot
- SA_STRICT intentionally blocks this until an authoritative action succeeds
2. Mount without coordinate memory and without clutches:
- mount may power up far from home
- user must guide back to home
- then perform an authoritative home/reset action
- then begin normal operation
- current model fits this workflow well
3. User wants only sidereal tracking at startup:
- trust does not gate sidereal tracking by itself
- but default safety behavior still disallows tracking when limits are not
enforced
- this is intentional and should remain so
## NV policy
The compile-time switch:
- NV_INIT_ERROR_REVOKES_AUTHORITY
Default:
- ON
Meaning:
- if NV reports an init/read fault that may undermine coordinate or motion
confidence, trust is not granted or is revoked
This is intentionally strict, but it has an escape hatch for expert use.
## Status exposure
The trust state is exposed in :Gu# so clients can detect it without extra
status calls.
Longer term, a small circular event log is probably a better place to record
why trust changed than trying to pack too much into live status.
## Open future work
- circular timestamped event log for trust loss/recovery reasons
- possibly record a simple trust-loss reason code
- maybe future fault-tolerant KV/partition design
- refine the basic clutch/manual-home startup case so normal users are not
surprised while still preserving the stricter safety model for systems with
stronger authority sources