init
This commit is contained in:
Executable
+437
@@ -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.
|
||||
Executable
+861
@@ -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`
|
||||
Executable
BIN
Binary file not shown.
|
After Width: | Height: | Size: 48 KiB |
Executable
BIN
Binary file not shown.
|
After Width: | Height: | Size: 36 KiB |
Executable
BIN
Binary file not shown.
|
After Width: | Height: | Size: 49 KiB |
Executable
+514
@@ -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:
|
||||
|
||||

|
||||
|
||||
When east of the pier, the active limit window is interpreted against the
|
||||
east-side geometry shown above.
|
||||
|
||||

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