# hjd1964/onstepx architecture

> Architecture diagram of the GitHub repository hjd1964/onstepx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hjd1964/onstepx
- Repository: https://github.com/hjd1964/onstepx

## Overview

##### Project Type and Purpose
- This is an embedded firmware project (OnStep) for controlling telescope mounts and accessories.
- It provides a hardware-agnostic control core with support for multiple MCUs (Arduino M0, Mega2560/328, ESP32/8266, STM32, Teensy, RP2040, etc.).
- Key features include motion control (axes, motors, step/servo), mount functions (goto, guide, park, PEC), auxiliary devices (dew heater, intervalometer), communications (serial, Ethernet, Wi-Fi, Bluetooth, CAN), and plugin extensibility.

##### File Structure and Architectural Layers
– Top Level
- OnStepX.ino, Config.h, Extended.config.h: sketch entry points and configuration overrides.
- src/ folder: all source code.
– HAL Layer (src/HAL)
- Common HAL interface (HAL.h) and per-MCU header implementations.
- Abstracts timers, GPIO, serial, I²C, SPI, PWM, interrupts.
– Core Libraries (src/lib)
- Drivers for encoders, motors (stepDir, servo), 1-wire, CAN, calendars, tasks scheduler (OnTask), watchdog, NV storage, etc.
- Communications sub-modules: serial (local, IP over Ethernet/Wi-Fi), web/cmd servers, Bluetooth.
– Application Layer (src/libApp, src/telescope)
- libApp: high-level command processing, temperature & weather modules.
- telescope: mount, focuser, rotator, auxiliary feature implementations with command handlers.
– Configuration & Pinmaps (src/pinmaps)
- MCU/board-specific pin definitions.
– Plugins (src/plugins)
- Sample plugin interface and stub for third-party feature extensions.

##### Architectural Patterns and Key Components
- Layered architecture:
– Hardware Abstraction Layer → Core Drivers & Services → Application Modules → Plugins
- Modular motor control: axis library uses pluggable motor drivers (oDrive, kTech, DC, TMC SPI/UART).
- Task scheduler (OnTask) creates pseudo-RTOS for timed operations.
- Communication stack: uniform “Serial” API multiplexed over physical UART, Ethernet, Wi-Fi or Bluetooth.

a. Main Components
– Hardware: MCU (choose one), power, sensors, actuators, communications peripherals.
– HAL Module: timer, GPIO, serial, I²C, SPI, PWM interfaces.
– Core Services: OnTask scheduler, NV storage, watchdog, debug/log.
– Driver Libraries: motor drivers, encoder interfaces, temperature/clock modules, CAN, calendars.
– Application Modules: mount controller, focuser, rotator, auxiliary (dew heater, intervalometer), command processor.
– Communication Interfaces: Serial, Ethernet, Wi-Fi, Bluetooth, Web/CMD servers.
– Plugin Layer.
b. Relationships & Data Flow
- MCU peripherals → HAL layer → core services & drivers → application modules → external devices (motors, encoders, heaters).
- Command inputs (serial, network) → command processor → application modules → driver APIs → actuators.
- Sensor data (temperature, encoders) → driver libraries → application logic → telemetry over comms.
c. Patterns
- Layer separation: physical vs. HAL vs. services vs. logic.
- Pluggable drivers and plugins.
- Single scheduler coordinating tasks.
d. Technologies
- C++ classes for HAL, drivers, modules.
- OnTask scheduler.
- Network stacks (EthernetManager, WifiManager).
- Motor protocols (StepDir, servo, TMC, oDrive).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Level
    Sketch["Sketch Entry & Config\nOnStepX.ino, Config.h, Extended.config.h"]:::top

    %% Hardware & HAL Layer
    subgraph "Hardware & HAL" 
        direction TB
        MCU["MCU & Peripherals"]:::hardware
        HAL["HAL Layer\n(src/HAL/HAL.h + implementations)"]:::hardware
    end

    %% Core Services & Drivers
    subgraph "Core Services & Drivers"
        direction TB
        OnTask["Task Scheduler\nOnTask.h/.cpp"]:::core
        NV["Non-Volatile Storage\nNv.h/.cpp + subfolders"]:::core
        Watchdog["Watchdog Service\nWatchdog.h/.cpp"]:::core
        Debug["Debug/Logging Service\nDebug.h/.cpp"]:::core
        Calendar["Calendar/Timekeeping\nCalendars.h/.cpp"]:::core
        Axis["Axis Abstraction\nAxis.h/.cpp"]:::core
        Enc["Encoder Libraries\nEncoderBase.h/.cpp"]:::core
        OneWire["1-Wire Driver\n1Wire.h/.cpp"]:::core
        CAN["CAN Bus\nCanPlus.h/.cpp"]:::core
        GPIOEx["GPIO Expanders\nGpioEx.h/.cpp"]:::core
        SoftSPI["Soft SPI/I²C\nSoftSpi.h/.cpp"]:::core
        Sound["Sound Output\nSound.h/.cpp"]:::core
        Motors["Motor Drivers\nStepDir, Servo, ODrive, kTech"]:::core
    end

    %% Application & Plugins
    subgraph "Application Logic & Plugins"
        direction TB
        CmdProc["Command Processor\nProcessCmds.h/.cpp"]:::app
        Temp["Temp & Weather\nTemperature.h/.cpp, Weather.h/.cpp"]:::app
        Telescope["Telescope Mount Core\nTelescope.h/.cpp"]:::app
        Focuser["Focuser\nFocuser.h/.cpp"]:::app
        Rotator["Rotator\nRotator.h/.cpp"]:::app
        Aux["Auxiliary Devices\nDewHeater, Intervalometer"]:::app
        Flasher["Addon Flasher\nAddonFlasher.h/.cpp"]:::app
        Plugins["Plugin Interface\nPlugins.config.h, Sample"]:::app
    end

    %% Communication Stack
    subgraph "Communication Stack"
        direction TB
        Serial["Serial Comm\nSerial_Local.h/.cpp, IP over Ethernet/Wi-Fi"]:::comm
        Ethernet["Ethernet Manager & Servers\nEthernetManager, CmdServer, WebServer"]:::comm
        Wifi["Wi-Fi Manager & Servers\nWifiManager, CmdServer, WebServer"]:::comm
        Bluetooth["Bluetooth Manager\nBluetoothManager.h/.cpp"]:::comm
    end

    %% Connections
    Sketch --> HAL
    HAL --> OnTask
    HAL --> Motors
    HAL --> Enc
    HAL --> OneWire
    HAL --> CAN
    HAL --> GPIOEx
    HAL --> SoftSPI

    OnTask --> CmdProc
    NV --> CmdProc
    Watchdog --> OnTask
    Debug --> CmdProc
    Calendar --> Temp

    Enc --> Telescope
    Motors --> Telescope
    OneWire --> Temp
    CAN --> Telescope
    GPIOEx --> Telescope
    SoftSPI --> Telescope
    Sound --> Aux

    Serial --> CmdProc
    Ethernet --> Serial
    Wifi --> Serial
    Bluetooth --> Serial

    CmdProc --> Telescope
    Telescope --> Focuser
    Telescope --> Rotator
    Telescope --> Aux
    Telescope --> Flasher
    Plugins --> Telescope

    %% Click Events
    click HAL "https://github.com/hjd1964/onstepx/blob/main/src/HAL/HAL.h"
    click OnTask "https://github.com/hjd1964/onstepx/blob/main/src/lib/tasks/OnTask.h"
    click NV "https://github.com/hjd1964/onstepx/blob/main/src/lib/nv/Nv.h"
    click Watchdog "https://github.com/hjd1964/onstepx/blob/main/src/lib/watchdog/Watchdog.h"
    click Debug "https://github.com/hjd1964/onstepx/blob/main/src/lib/debug/Debug.h"
    click Calendar "https://github.com/hjd1964/onstepx/blob/main/src/lib/calendars/Calendars.h"
    click Axis "https://github.com/hjd1964/onstepx/blob/main/src/lib/axis/Axis.h"
    click Enc "https://github.com/hjd1964/onstepx/blob/main/src/lib/encoder/EncoderBase.h"
    click OneWire "https://github.com/hjd1964/onstepx/blob/main/src/lib/1wire/1Wire.h"
    click CAN "https://github.com/hjd1964/onstepx/blob/main/src/lib/canPlus/CanPlus.h"
    click GPIOEx "https://github.com/hjd1964/onstepx/blob/main/src/lib/gpioEx/GpioEx.h"
    click SoftSPI "https://github.com/hjd1964/onstepx/blob/main/src/lib/softSpi/SoftSpi.h"
    click Sound "https://github.com/hjd1964/onstepx/blob/main/src/lib/sound/Sound.h"
    click CmdProc "https://github.com/hjd1964/onstepx/blob/main/src/libApp/commands/ProcessCmds.h"
    click Temp "https://github.com/hjd1964/onstepx/blob/main/src/libApp/temperature/Temperature.h"
    click Telescope "https://github.com/hjd1964/onstepx/blob/main/src/telescope/Telescope.h"
    click Focuser "https://github.com/hjd1964/onstepx/blob/main/src/telescope/focuser/Focuser.h"
    click Rotator "https://github.com/hjd1964/onstepx/blob/main/src/telescope/rotator/Rotator.h"
    click Plugins "https://github.com/hjd1964/onstepx/blob/main/src/plugins/Plugins.config.h"
    click Serial "https://github.com/hjd1964/onstepx/blob/main/src/lib/serial/Serial_Local.h"
    click Ethernet "https://github.com/hjd1964/onstepx/blob/main/src/lib/ethernet/EthernetManager.h"
    click Wifi "https://github.com/hjd1964/onstepx/blob/main/src/lib/wifi/WifiManager.h"
    click Bluetooth "https://github.com/hjd1964/onstepx/blob/main/src/lib/bluetooth/BluetoothManager.h"

    %% Styles
    classDef top fill:#f9f,stroke:#333,stroke-width:1px;
    classDef hardware fill:#bbdefb,stroke:#1e88e5,stroke-width:1px;
    classDef core fill:#c8e6c9,stroke:#43a047,stroke-width:1px;
    classDef app fill:#ffe0b2,stroke:#fb8c00,stroke-width:1px;
    classDef comm fill:#e1bee7,stroke:#8e24aa,stroke-width:1px;
```
