This commit is contained in:
sagiferi
2026-05-20 21:48:13 +02:00
parent a907d8ba74
commit d3c13f997e
446 changed files with 70716 additions and 0 deletions
+67
View File
@@ -0,0 +1,67 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project type
OnStepX is an Arduino sketch ([OnStepX.ino](OnStepX.ino)) — not a CMake / PlatformIO / Makefile project. There is no `platformio.ini`. Builds happen in the Arduino IDE or via `arduino-cli`. The MCU target is selected by which board the user picks in their IDE; the code adapts via the HAL.
There is no test suite, no linter config, and no CI. "Build" means "compile this sketch for the target board." When asked to verify a change, the realistic checks are:
- Read the relevant `Config.defaults.h` and `Validate.h` sections to confirm the change passes preprocessor validation.
- For deeper checks, run `arduino-cli compile --fqbn <fqbn> .` from the repo root if `arduino-cli` is available.
## Configuration is preprocessor-driven
User-editable controller configuration lives in three header files at the project root or in `src/plugins/`:
- [Config.h](Config.h) — the main per-installation config: pinmap, mount type, axis drivers, steps/degree, serial baud, WiFi/BT, etc. This file *will* differ between installations and is edited by the end user. Do not "tidy" it.
- [Extended.config.h](Extended.config.h) — debug/NV-wipe and other infrequently-changed knobs.
- [src/plugins/Plugins.config.h](src/plugins/Plugins.config.h) — enables PLUGIN1..PLUGIN8.
Defaults live in [src/Config.defaults.h](src/Config.defaults.h); every option `Config.h` does not set is filled in there. Validation rules live in [src/Validate.h](src/Validate.h) — `#error` and `#warning` directives there are the closest thing to a type system this codebase has. When adding a new config option, add the default AND a validation rule.
`#define FirmwareVersionConfig` in `OnStepX.ino` is bumped whenever `Config.h`'s structure changes; mismatches trigger a `#error` in `Validate.h`.
`src/plugins/*` is gitignored (except the `sample/` dir). Plugin code is expected to be dropped into that directory by the user.
## Big picture: HAL → pinmap → Telescope → subsystems
`OnStepX.ino` is intentionally tiny. It calls `HAL_INIT()`, brings up NV, starts the cooperative task scheduler, instantiates one global `Telescope telescope;`, and registers command channels. Everything else is driven from there.
Layers, from bottom up:
1. **HAL** ([src/HAL/](src/HAL/)): one subdirectory per MCU family (`atmel`, `esp`, `stm32`, `teensy`, `mbed`, `arduinoM0`, `default`). `HAL.h` does compile-time `#if defined(__AVR_…)` / `defined(ESP32)` / etc. selection and pulls in the right per-MCU header, which provides `HAL_INIT()`, `HAL_TEMP()`, fast-tick macros, and analog wrappers. Adding a new MCU means adding a HAL subfolder and a branch in `src/HAL/HAL.h`.
2. **Pinmap** ([src/pinmaps/](src/pinmaps/)): `Pins.*.h` per board. The user picks one via `#define PINMAP <board>` in `Config.h`; [src/pinmaps/Models.h](src/pinmaps/Models.h) maps that to the include. `Pins.defaults.h` fills in anything the chosen pinmap omits. If `PINMAP == OFF`, the user is expected to define `AXIS*_STEP_PIN` etc. directly in `Config.h` (see the user's current config for an example).
3. **Generic libraries** ([src/lib/](src/lib/)): hardware-independent building blocks — `tasks/` (cooperative scheduler, see below), `axis/` (motion control, motor abstraction), `nv/` (non-volatile storage over EEPROM/FRAM/Flash), `commands/` (parser + buffer), plus transports: `serial/`, `bluetooth/`, `wifi/`, `ethernet/`, `canPlus/`, `canTransport/`, and peripherals: `analog/`, `sense/`, `gpioEx/`, `tls/` (time/location source), `encoder/`, `softSpi/`, `convert/`, `math/`, `calendars/`.
4. **App-level shared services** ([src/libApp/](src/libApp/)): `commands/` (the `ProcessCmds` command channel processor and `CommandBroker` for cross-channel request/reply), `weather/`, `temperature/`.
5. **Telescope domain** ([src/telescope/](src/telescope/)): `Telescope.cpp` owns the global object; subdirs implement the four optional subsystems: `mount/`, `rotator/`, `focuser/`, `auxiliary/`. Whether each is compiled in is controlled by `*_PRESENT` macros derived in [src/Common.h](src/Common.h) from the driver-model and feature-purpose settings in `Config.h`.
A request typically flows: serial/IP byte stream → `CommandProcessor::poll()` ([src/libApp/commands/ProcessCmds.cpp](src/libApp/commands/ProcessCmds.cpp)) → `telescope.command(...)` → subsystem `*.command.cpp` files. Each subsystem has its own `Foo.command.cpp` that handles its slice of the LX200-style protocol; that's where to look when implementing or modifying a `:XX...#` command.
## Cooperative scheduler (OnTask)
There is no RTOS abstraction layer above this — everything that isn't an ISR runs through `tasks` from [src/lib/tasks/OnTask.h](src/lib/tasks/OnTask.h). New periodic work is added with `tasks.add(periodMs, durationMs, repeat, priority, function, name)`. Long-running code inside a task must call `tasks.yield()` (or the `Y;` macro) so the scheduler can run higher-priority work — including the step-pulse generator. This is critical: blocking inside a task starves stepper output.
The main `loop()` is just `tasks.yield();`.
## Command protocol
The canonical reference for the wire protocol is [docs/COMMAND_REFERENCE.md](docs/COMMAND_REFERENCE.md), and it's explicitly derived from the current `*.command.cpp` files — if behavior and the older OnStep wiki disagree, the code wins. Frame format: `:CC...#` (plain) or `;CC...CCS#` (with checksum). Error codes returned by `:GE#` are listed in that doc.
Many commands are compile-time-gated by feature defines. Code under `#ifdef MOUNT_PRESENT`, `#ifdef FOCUSER_PRESENT`, etc. only exists when the corresponding axes/drivers are configured.
## Subsystem docs (read these before changing related code)
The `docs/` directory holds the design notes that aren't otherwise discoverable from the code:
- [COMMAND_REFERENCE.md](docs/COMMAND_REFERENCE.md) — wire protocol.
- [STARTUP_AUTHORITY_NOTES.md](docs/STARTUP_AUTHORITY_NOTES.md) — when the mount trusts its coordinate basis enough to allow goto/sync/park. Important: gating logic here affects nearly every motion command.
- [GOTO_NOTES.md](docs/GOTO_NOTES.md), [HOMING_NOTES.md](docs/HOMING_NOTES.md), [PEC_NOTES.md](docs/PEC_NOTES.md), [SENSING_NOTES.md](docs/SENSING_NOTES.md) — subsystem-specific design notes.
- [SERIAL_NOTES.md](docs/SERIAL_NOTES.md) — three-layer model (platform / pinmap / feature) for understanding why a serial transport may "exist but not work" on a given board.
- [SERVO_SETUP.md](docs/SERVO_SETUP.md), [CAN_NOTES.md](docs/CAN_NOTES.md) — motor and transport specifics.
## Conventions
- Each subsystem follows the pattern `Foo.h` / `Foo.cpp` for state, `Foo.command.cpp` for the command handler, optionally `Foo.can.command.cpp` / `Foo.can.encode.cpp` / `Foo.can.decode.cpp` for the CAN-bus remote-control variant of the same surface.
- Logging uses the `V…` / `D…` macros from `src/lib/debug/Debug.h` (e.g. `VLF`, `VF`, `DLF`). Output is gated by the `DEBUG` setting in `Extended.config.h` and goes to `SERIAL_DEBUG`. Don't add raw `Serial.print` — use the macros so debug output can be compiled out.
- Commit messages follow the brief, lowercase-prefixed style shown by `git log --date=short --pretty=format:"%h %ad %<(20)%an %<(150,trunc)%s"` (per [README.md](README.md)).