# jrbynum/rpm_ac_motor_controller architecture

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

- Interactive diagram: https://gitdiagram.com/jrbynum/rpm_ac_motor_controller
- Repository: https://github.com/jrbynum/rpm_ac_motor_controller

## Overview

1. This repository is an embedded motor-controller project, not a typical software app. The core runtime is Arduino-style C++ firmware for an AC motor control system, with a separate Eagle schematic/board layout for the supporting shield hardware.

2. The main control problem is a closed loop: a reflective optical sensor measures motor RPM, an LM135 measures temperature, and the firmware uses PID-based feedback to regulate motor speed. The system also displays RPM and temperature on an LCD for local monitoring.

3. The actuation path is hardware-driven. A zero-crossing circuit plus a triac control AC power to the motor. The target speed comes either from a 10K potentiometer on the shield or from an external PWM input, which the readme notes could come from Mach3. That makes the controller compatible with both manual and external machine-control sources.

4. The firmware is organized into a small set of focused source files under `RPM_TEST/source`:
   - `RPM_TEST_main.cpp` is the application entry point and top-level orchestration.
   - `startup.cpp` likely handles initialization of pins, timers, peripherals, and interrupt setup.
   - `isrs.cpp` isolates interrupt service routines for sensor timing, zero-crossing events, or other real-time signals.
   - `calculations.cpp` contains the measurement and control math, such as RPM computation, temperature conversion, and PID-related logic.
   - `diagnostics.cpp` likely handles LCD output and any status/debug reporting.
   - `rpm_test_main.h` ties the modules together through shared declarations and configuration.

5. The important data flow is sensor-to-control-to-actuator:
   - optical sensor pulse timing becomes RPM,
   - temperature sensor voltage becomes temperature,
   - setpoint comes from pot or PWM input,
   - control logic computes the output command,
   - zero-cross/triac circuitry applies that command to motor power,
   - LCD reports the current state.

6. Interrupts are a key architectural boundary. Because RPM and AC phase timing are time-sensitive, the system likely relies on ISRs for accurate edge/crossing capture rather than polling. That means `isrs.cpp` is part of the real-time layer, while `calculations.cpp` and `diagnostics.cpp` run in the less time-critical foreground loop.

7. The project has both firmware and hardware design artifacts. The `Schematic/` folder contains an Eagle board and schematic named `AC Motor Control Shield`, indicating the electronics are intended as an Arduino shield. This matters architecturally because the firmware assumptions are tightly coupled to the shield’s pinout and signal conditioning circuits.

8. The system boundary is mostly local and embedded: no network stack, database, or cloud service is present. External dependencies are limited to the Arduino runtime environment and the PID library mentioned in the readme.

9. From a diagramming perspective, the major blocks to draw are:
   - human/operator inputs: pot and optional PWM source,
   - sensing inputs: optical RPM sensor and LM135 temperature sensor,
   - embedded controller: Arduino firmware with interrupts, calculation, diagnostics, and PID,
   - power stage: zero-cross circuit and triac,
   - outputs: motor speed and LCD status display.

10. The repository is also historical and development-oriented: the readme says the Eagle shield layout was added for development in 2013. So the hardware design files are not just documentation; they are part of the implementation boundary for the controller.

Main entry points: [`Schematic/AC Motor Control Shield.sch`](https://github.com/jrbynum/rpm_ac_motor_controller/blob/HEAD/Schematic/AC%20Motor%20Control%20Shield.sch) (Shield PCB), [`RPM_TEST/source/RPM_TEST_main.cpp`](https://github.com/jrbynum/rpm_ac_motor_controller/blob/master/RPM_TEST/source/RPM_TEST_main.cpp) (Main), [`RPM_TEST/source/calculations.cpp`](https://github.com/jrbynum/rpm_ac_motor_controller/blob/master/RPM_TEST/source/calculations.cpp) (Math), [`RPM_TEST/source/startup.cpp`](https://github.com/jrbynum/rpm_ac_motor_controller/blob/master/RPM_TEST/source/startup.cpp) (Startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["Firmware"]
  node_main["Main<br/>firmware entry<br/>[RPM_TEST_main.cpp]"]
  node_startup["Startup<br/>init<br/>[startup.cpp]"]
  node_isrs["ISRs<br/>real-time<br/>[isrs.cpp]"]
  node_calc["Math<br/>[calculations.cpp]"]
  node_diag["Display<br/>status output<br/>[diagnostics.cpp]"]
  node_header["Shared API<br/>declarations<br/>[rpm_test_main.h]"]
  node_pidlib{{"PID lib<br/>external dependency"}}
end

subgraph group_hardware["Hardware"]
  node_pot(("Pot Input<br/>setpoint source"))
  node_pwm(("PWM Input<br/>setpoint source"))
  node_sensor(("RPM Sensor<br/>optical sensor"))
  node_temp(("Temp Sensor<br/>LM135"))
  node_lcd["LCD<br/>display"]
  node_zc(("Zero Cross<br/>power timing"))
  node_triac{{"Triac Stage<br/>power output"}}
  node_motor(("Motor<br/>load"))
  node_shield["Shield PCB<br/>eagle hardware"]
end

node_pot -->|"setpoint"| node_main
node_pwm -->|"setpoint"| node_main
node_sensor -->|"pulses"| node_isrs
node_temp -->|"reading"| node_calc
node_isrs -->|"timing data"| node_calc
node_calc -->|"feedback"| node_main
node_main -->|"drive"| node_triac
node_zc -->|"crossings"| node_isrs
node_triac -->|"power"| node_motor
node_calc -->|"status"| node_lcd
node_main -->|"reporting"| node_diag
node_startup -->|"configures"| node_isrs
node_startup -->|"enables"| node_zc
node_startup -->|"enables"| node_sensor
node_startup -->|"enables"| node_temp
node_header -->|"declares"| node_main
node_pidlib -->|"control law"| node_calc
node_shield -->|"contains"| node_pot
node_shield -->|"supports"| node_pwm
node_shield -->|"routes"| node_sensor
node_shield -->|"routes"| node_temp
node_shield -->|"routes"| node_zc
node_shield -->|"hosts"| node_triac
node_shield -->|"supports"| node_lcd

click node_main "https://github.com/jrbynum/rpm_ac_motor_controller/blob/master/RPM_TEST/source/RPM_TEST_main.cpp"
click node_startup "https://github.com/jrbynum/rpm_ac_motor_controller/blob/master/RPM_TEST/source/startup.cpp"
click node_isrs "https://github.com/jrbynum/rpm_ac_motor_controller/blob/master/RPM_TEST/source/isrs.cpp"
click node_calc "https://github.com/jrbynum/rpm_ac_motor_controller/blob/master/RPM_TEST/source/calculations.cpp"
click node_diag "https://github.com/jrbynum/rpm_ac_motor_controller/blob/master/RPM_TEST/source/diagnostics.cpp"
click node_header "https://github.com/jrbynum/rpm_ac_motor_controller/blob/master/RPM_TEST/source/rpm_test_main.h"
click node_shield "https://github.com/jrbynum/rpm_ac_motor_controller/blob/master/Schematic/AC Motor Control Shield.sch"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_startup,node_isrs,node_calc,node_diag,node_header,node_pidlib toneBlue
class node_pot,node_pwm,node_sensor,node_temp,node_lcd,node_zc,node_triac,node_motor,node_shield toneAmber
```

## Components

### Firmware

Arduino-style motor-control runtime

- [Main](https://github.com/jrbynum/rpm_ac_motor_controller/blob/master/RPM_TEST/source/RPM_TEST_main.cpp): firmware entry · Top-level orchestration and control loop · `RPM_TEST/source/RPM_TEST_main.cpp`
- [Startup](https://github.com/jrbynum/rpm_ac_motor_controller/blob/master/RPM_TEST/source/startup.cpp): init · Pins, timers, peripherals, and interrupts setup · `RPM_TEST/source/startup.cpp`
- [ISRs](https://github.com/jrbynum/rpm_ac_motor_controller/blob/master/RPM_TEST/source/isrs.cpp): real-time · Interrupt handlers for RPM and AC timing events · `RPM_TEST/source/isrs.cpp`
- [Math](https://github.com/jrbynum/rpm_ac_motor_controller/blob/master/RPM_TEST/source/calculations.cpp): control math · RPM, temperature, and PID-related calculations · `RPM_TEST/source/calculations.cpp`
- [Display](https://github.com/jrbynum/rpm_ac_motor_controller/blob/master/RPM_TEST/source/diagnostics.cpp): status output · LCD output and diagnostic reporting · `RPM_TEST/source/diagnostics.cpp`
- [Shared API](https://github.com/jrbynum/rpm_ac_motor_controller/blob/master/RPM_TEST/source/rpm_test_main.h): declarations · Shared declarations and configuration across modules · `RPM_TEST/source/rpm_test_main.h`
- **PID lib**: external dependency · PID control library used by the firmware

### Hardware

Shield schematic and power/sensing circuits

- **Pot Input**: setpoint source · 10K potentiometer target-speed input
- **PWM Input**: setpoint source · Optional external PWM setpoint source, e.g. Mach3
- **RPM Sensor**: optical sensor · Reflective optical sensor for motor speed feedback
- **Temp Sensor**: LM135 · Temperature measurement for thermal feedback
- **LCD**: display · Local display for RPM and temperature
- **Zero Cross**: power timing · Zero-crossing detection for AC phase control
- **Triac Stage**: power output · AC power switching stage driving the motor
- **Motor**: load · AC motor being regulated
- [Shield PCB](https://github.com/jrbynum/rpm_ac_motor_controller/blob/HEAD/Schematic/AC%20Motor%20Control%20Shield.sch): eagle hardware · Arduino shield schematic and board layout · `Schematic/AC Motor Control Shield.sch`

## Connections

- Pot Input → Main: setpoint · Manual speed command
- PWM Input → Main: setpoint · External speed command
- RPM Sensor → ISRs: pulses · Speed feedback timing edges
- Temp Sensor → Math: reading · Temperature measurement input
- ISRs → Math: timing data · Captured pulse and phase timing data
- Math → Main: feedback · Computed RPM, temperature, and control output
- Main → Triac Stage: drive · Actuation command to power stage
- Zero Cross → ISRs: crossings · AC phase reference events
- Triac Stage → Motor: power · Controlled AC delivery to the motor
- Math → LCD: status · Current RPM and temperature display values
- Main → Display: reporting · Foreground diagnostics and UI updates
- Startup → ISRs: configures · Interrupt and timing setup
- Startup → Zero Cross: enables · Zero-cross sensing initialization
- Startup → RPM Sensor: enables · RPM sensor initialization
- Startup → Temp Sensor: enables · Temperature input initialization
- Shared API → Main: declares · Shared interfaces for the application
- PID lib → Math: control law · PID logic used in calculations
- Shield PCB → Pot Input: contains · Shield hardware includes the potentiometer input
- Shield PCB → PWM Input: supports · Shield/interface accommodates external PWM input
- Shield PCB → RPM Sensor: routes · Sensor interface and conditioning on the shield
- Shield PCB → Temp Sensor: routes · LM135 conditioning on the shield
- Shield PCB → Zero Cross: routes · Zero-cross detection circuitry on the shield
- Shield PCB → Triac Stage: hosts · Triac power-control circuitry on the shield
- Shield PCB → LCD: supports · Local display interfacing