7.2 KiB
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) — 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.handValidate.hsections to confirm the change passes preprocessor validation. - For deeper checks, run
arduino-cli compile --fqbn <fqbn> .from the repo root ifarduino-cliis available.
Configuration is preprocessor-driven
User-editable controller configuration lives in three header files at the project root or in src/plugins/:
- 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 — debug/NV-wipe and other infrequently-changed knobs.
- src/plugins/Plugins.config.h — enables PLUGIN1..PLUGIN8.
Defaults live in src/Config.defaults.h; every option Config.h does not set is filled in there. Validation rules live in 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:
- HAL (src/HAL/): one subdirectory per MCU family (
atmel,esp,stm32,teensy,mbed,arduinoM0,default).HAL.hdoes compile-time#if defined(__AVR_…)/defined(ESP32)/ etc. selection and pulls in the right per-MCU header, which providesHAL_INIT(),HAL_TEMP(), fast-tick macros, and analog wrappers. Adding a new MCU means adding a HAL subfolder and a branch insrc/HAL/HAL.h. - Pinmap (src/pinmaps/):
Pins.*.hper board. The user picks one via#define PINMAP <board>inConfig.h; src/pinmaps/Models.h maps that to the include.Pins.defaults.hfills in anything the chosen pinmap omits. IfPINMAP == OFF, the user is expected to defineAXIS*_STEP_PINetc. directly inConfig.h(see the user's current config for an example). - Generic libraries (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/. - App-level shared services (src/libApp/):
commands/(theProcessCmdscommand channel processor andCommandBrokerfor cross-channel request/reply),weather/,temperature/. - Telescope domain (src/telescope/):
Telescope.cppowns the global object; subdirs implement the four optional subsystems:mount/,rotator/,focuser/,auxiliary/. Whether each is compiled in is controlled by*_PRESENTmacros derived in src/Common.h from the driver-model and feature-purpose settings inConfig.h.
A request typically flows: serial/IP byte stream → CommandProcessor::poll() (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. 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, 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 — wire protocol.
- 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, HOMING_NOTES.md, PEC_NOTES.md, SENSING_NOTES.md — subsystem-specific design notes.
- 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, CAN_NOTES.md — motor and transport specifics.
Conventions
- Each subsystem follows the pattern
Foo.h/Foo.cppfor state,Foo.command.cppfor the command handler, optionallyFoo.can.command.cpp/Foo.can.encode.cpp/Foo.can.decode.cppfor the CAN-bus remote-control variant of the same surface. - Logging uses the
V…/D…macros fromsrc/lib/debug/Debug.h(e.g.VLF,VF,DLF). Output is gated by theDEBUGsetting inExtended.config.hand goes toSERIAL_DEBUG. Don't add rawSerial.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).