Files
2026-05-20 21:48:13 +02:00

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.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 — 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:

  1. 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/): Pins.*.h per board. The user picks one via #define PINMAP <board> in Config.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/): 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/): commands/ (the ProcessCmds command channel processor and CommandBroker for cross-channel request/reply), weather/, temperature/.
  5. Telescope domain (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 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) → 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.

The docs/ directory holds the design notes that aren't otherwise discoverable from the code:

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).