# sverdfisk/wind-turbine-rpm-estimation-software architecture

> Architecture diagram of the GitHub repository sverdfisk/wind-turbine-rpm-estimation-software, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sverdfisk/wind-turbine-rpm-estimation-software
- Repository: https://github.com/sverdfisk/wind-turbine-rpm-estimation-software

## Overview

#### Purpose and System Boundary
This repository is a wind-turbine RPM monitoring prototype built around a Sony IMX385LQR image sensor, a custom Raspberry Pi 5 carrier PCB, Linux sensor integration, and Python video analysis. Its three usable subsystems are intentionally separable: hardware design, Pi-side sensor driver/control, and RPM estimation software.

#### Hardware Design
The custom four-layer IMX385 board provides sensor interfacing, power regulation, analog/digital circuitry, and output connectivity for a Raspberry Pi 5 installation.
- Altium project and PCB layout: `altium_files/IMX385/IMX385_Final.PrjPcb`, `altium_files/IMX385/IMX_PCB.PcbDoc`
- Power domains and sequencing-related schematics: `altium_files/IMX385/IMX_Power Regulation.SchDoc`, `altium_files/IMX385/IMX_1.2V Digital Power Supply.SchDoc`, `altium_files/IMX385/IMX_3.3 V Analog Power Supply.SchDoc`
- Interface and sensor-support circuits: `altium_files/IMX385/IMX_Digital Interface Circuit.SchDoc`, `altium_files/IMX385/IMX_Analog Interface Circuit.SchDoc`, `altium_files/IMX385/IMX_Supporting Circuits.SchDoc`

Manufacturing outputs, including BOM, placement data, DRC report, Gerbers, and ODB package, are under `altium_files/IMX385/Project Outputs for IMX385_Final/`.

#### Raspberry Pi Sensor Enablement
The `driver/` subsystem targets Raspberry Pi 5/Linux and bridges the custom IMX385 hardware into the platform’s camera stack.
- Kernel sensor driver: `driver/imx385.c`
- Device-tree overlay defining hardware integration: `driver/imx385-overlay.dts`
- Build/load support and boot configuration: `driver/compile.sh`, `driver/Makefile`, `driver/config.txt`

The V4L2 capture pipeline is an explicit external boundary: this repository does not fully configure frame acquisition or encoding. It supplies the driver pieces so sensor pixel data can reach the Pi, while deployment must establish an appropriate capture/format pipeline.

#### Hardware Control and Image Path
GPIO scripts implement strict sensor power/enable sequencing and peripheral image controls:
- Sensor startup/shutdown: `driver/imx-on.py`, `driver/imx-off.py`
- IR-cut filter control: `driver/filter-on.py`, `driver/filter-off.py`
- Sensor configuration: `driver/imxconfig.sh`

A physical sequencing connection from the PCB `SEQ` test point to a Pi GPIO is required; default assumptions are embedded in `driver/imx-on.py`. Once enabled and captured through V4L2 or another source, frames become the input boundary for the Python RPM software.

#### RPM Application Entry Points
The Python application accepts either a camera/video feed and a generated JSON configuration.
- Main operational entry point: `software/main.py`
- Interactive configuration producer: `software/config_generator.py`
- Configuration template: `software/config/config_template.json`

Testing mode displays/prints detection output; deployment mode continuously processes the feed and appends newly computed estimates to `runs/out.csv`. The feed location is provided by the config’s target field rather than hardwired to the custom sensor.

#### Vision-to-RPM Processing
RPM estimation is organized under `software/rpm/`:
- Optical-flow motion extraction: `software/rpm/opticalflow.py`
- BPM/RPM cascade and calculation: `software/rpm/bpm_cascade.py`, `software/rpm/calculate_rpm.py`
- Feed abstraction: `software/rpm/feed/feed.py`

Control flow is: config → open target video/camera feed → frame-by-frame vision processing → motion/BPM inference → RPM calculation → console visualization or deployment CSV output. `software/rpm/utils.py` supports the processing pipeline.

#### Runtime and Dependencies
The application is Python-based and uses Conda environment definitions at `software/environment.yml` and root `environment.yml`. Hardware operation requires Raspberry Pi 5, Linux kernel/module and device-tree support, GPIO access, the custom IMX385 PCB, and a separately configured V4L2-compatible capture path.

Main entry points: [`altium_files/IMX385/IMX385_Final.PrjPcb`](https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/altium_files/IMX385/IMX385_Final.PrjPcb) (Altium PCB project), [`driver/imx385.c`](https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/driver/imx385.c) (IMX385 kernel driver), [`software/main.py`](https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/software/main.py) (RPM application), [`software/rpm/feed/feed.py`](https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/software/rpm/feed/feed.py) (Video/camera feed)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hardware["Custom IMX385 Hardware"]
  node_pcb_project["Altium PCB project<br/>hardware design"]
  node_pcb_layout["Four-layer PCB layout<br/>[IMX_PCB.PcbDoc]"]
  node_power_sequence["Power domains &amp; sequencing<br/>schematics"]
  node_sensor_interfaces["Sensor interface circuits<br/>schematics"]
  node_imx385_board{{"IMX385 carrier board<br/>physical hardware"}}
  node_manufacturing["Manufacturing outputs<br/>fabrication package"]
end

subgraph group_pi["Pi Sensor Enablement"]
  node_device_overlay["Device-tree overlay<br/>Linux hardware binding<br/>[imx385-overlay.dts]"]
  node_kernel_driver["IMX385 kernel driver<br/>V4L2 sensor driver<br/>[imx385.c]"]
  node_driver_build["Driver build &amp; boot setup<br/>deployment support<br/>[compile.sh]"]
  node_gpio_controls["GPIO sensor controls<br/>power and image control<br/>[imx-on.py]"]
  node_v4l2_boundary["V4L2 capture pipeline<br/>external boundary"]
end

subgraph group_rpm["RPM Application"]
  node_config_generator["Config generator<br/>interactive CLI"]
  node_config_template["Config template<br/>JSON configuration"]
  node_main_app["RPM application<br/>Python entry point<br/>[main.py]"]
  node_feed["Video/camera feed<br/>feed abstraction<br/>[feed.py]"]
  node_optical_flow["Optical-flow extraction<br/>vision processing<br/>[opticalflow.py]"]
  node_bpm_cascade["Motion/BPM inference<br/>signal inference<br/>[bpm_cascade.py]"]
  node_rpm_calculation["RPM calculation<br/>estimation<br/>[calculate_rpm.py]"]
  node_outputs["Console or CSV output<br/>runtime output"]
  node_conda_env["Conda environment<br/>Python dependencies<br/>[environment.yml]"]
end

node_pcb_project -->|"contains layout"| node_pcb_layout
node_pcb_project -->|"includes"| node_power_sequence
node_pcb_project -->|"includes"| node_sensor_interfaces
node_pcb_project -->|"produces"| node_manufacturing
node_pcb_layout -->|"implements"| node_imx385_board
node_power_sequence -->|"powers and sequences"| node_imx385_board
node_sensor_interfaces -->|"interfaces"| node_imx385_board
node_imx385_board -->|"hardware described by"| node_device_overlay
node_imx385_board -->|"SEQ GPIO and controls"| node_gpio_controls
node_device_overlay -->|"binds"| node_kernel_driver
node_driver_build -->|"builds and loads"| node_kernel_driver
node_gpio_controls -->|"enables sensor before capture"| node_kernel_driver
node_kernel_driver -->|"exposes pixel data"| node_v4l2_boundary
node_config_template -->|"seeds"| node_config_generator
node_config_generator -->|"generates config for"| node_main_app
node_conda_env -.->|"provides dependencies"| node_main_app
node_v4l2_boundary -.->|"captured frames"| node_feed
node_main_app -->|"opens configured target"| node_feed
node_feed -->|"frames"| node_optical_flow
node_optical_flow -->|"motion signal"| node_bpm_cascade
node_bpm_cascade -->|"BPM estimate"| node_rpm_calculation
node_rpm_calculation -->|"estimate"| node_outputs

click node_pcb_project "https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/altium_files/IMX385/IMX385_Final.PrjPcb"
click node_pcb_layout "https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/altium_files/IMX385/IMX_PCB.PcbDoc"
click node_power_sequence "https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/altium_files/IMX385/IMX_Power%20Regulation.SchDoc"
click node_sensor_interfaces "https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/altium_files/IMX385/IMX_Digital%20Interface%20Circuit.SchDoc"
click node_device_overlay "https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/driver/imx385-overlay.dts"
click node_kernel_driver "https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/driver/imx385.c"
click node_driver_build "https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/driver/compile.sh"
click node_gpio_controls "https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/driver/imx-on.py"
click node_config_generator "https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/software/config_generator.py"
click node_config_template "https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/software/config/config_template.json"
click node_main_app "https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/software/main.py"
click node_feed "https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/software/rpm/feed/feed.py"
click node_optical_flow "https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/software/rpm/opticalflow.py"
click node_bpm_cascade "https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/software/rpm/bpm_cascade.py"
click node_rpm_calculation "https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/software/rpm/calculate_rpm.py"
click node_conda_env "https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/software/environment.yml"

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_pcb_project,node_pcb_layout,node_power_sequence,node_sensor_interfaces,node_imx385_board,node_manufacturing toneBlue
class node_device_overlay,node_kernel_driver,node_driver_build,node_gpio_controls,node_v4l2_boundary toneAmber
class node_config_generator,node_config_template,node_main_app,node_feed,node_optical_flow,node_bpm_cascade,node_rpm_calculation,node_outputs,node_conda_env toneMint
```

## Components

### Custom IMX385 Hardware

Four-layer Raspberry Pi 5 carrier and sensor board.

- [Altium PCB project](https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/altium_files/IMX385/IMX385_Final.PrjPcb): hardware design · `altium_files/IMX385/IMX385_Final.PrjPcb`
- [Four-layer PCB layout](https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/altium_files/IMX385/IMX_PCB.PcbDoc): PCB layout · `altium_files/IMX385/IMX_PCB.PcbDoc`
- [Power domains & sequencing](https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/altium_files/IMX385/IMX_Power%20Regulation.SchDoc): schematics · Regulation, digital, and analog supply circuits. · `altium_files/IMX385/IMX_Power Regulation.SchDoc`
- [Sensor interface circuits](https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/altium_files/IMX385/IMX_Digital%20Interface%20Circuit.SchDoc): schematics · Analog, digital, and support circuitry for the IMX385. · `altium_files/IMX385/IMX_Digital Interface Circuit.SchDoc`
- **IMX385 carrier board**: physical hardware · Connects the IMX385 sensor and sequencing signal to the Pi.
- **Manufacturing outputs**: fabrication package · BOM, placement, DRC, Gerbers, and ODB outputs.

### Pi Sensor Enablement

Linux integration and GPIO control on Raspberry Pi 5.

- [Device-tree overlay](https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/driver/imx385-overlay.dts): Linux hardware binding · `driver/imx385-overlay.dts`
- [IMX385 kernel driver](https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/driver/imx385.c): V4L2 sensor driver · `driver/imx385.c`
- [Driver build & boot setup](https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/driver/compile.sh): deployment support · Builds and loads the module and supplies boot configuration. · `driver/compile.sh`
- [GPIO sensor controls](https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/driver/imx-on.py): power and image control · Startup/shutdown, IR-cut filter, and sensor configuration scripts. · `driver/imx-on.py`
- **V4L2 capture pipeline**: external boundary · Deployment supplies capture, format, and encoding setup.

### RPM Application

Python configuration and video-based RPM estimation.

- [Config generator](https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/software/config_generator.py): interactive CLI · `software/config_generator.py`
- [Config template](https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/software/config/config_template.json): JSON configuration · `software/config/config_template.json`
- [RPM application](https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/software/main.py): Python entry point · Runs testing display or continuous deployment processing. · `software/main.py`
- [Video/camera feed](https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/software/rpm/feed/feed.py): feed abstraction · Opens the target configured by the JSON input. · `software/rpm/feed/feed.py`
- [Optical-flow extraction](https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/software/rpm/opticalflow.py): vision processing · `software/rpm/opticalflow.py`
- [Motion/BPM inference](https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/software/rpm/bpm_cascade.py): signal inference · `software/rpm/bpm_cascade.py`
- [RPM calculation](https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/software/rpm/calculate_rpm.py): estimation · `software/rpm/calculate_rpm.py`
- **Console or CSV output**: runtime output · Deployment appends new estimates to runs/out.csv.
- [Conda environment](https://github.com/sverdfisk/wind-turbine-rpm-estimation-software/blob/main/software/environment.yml): Python dependencies · `software/environment.yml`

## Connections

- Altium PCB project → Four-layer PCB layout: contains layout
- Altium PCB project → Power domains & sequencing: includes
- Altium PCB project → Sensor interface circuits: includes
- Altium PCB project → Manufacturing outputs: produces
- Four-layer PCB layout → IMX385 carrier board: implements
- Power domains & sequencing → IMX385 carrier board: powers and sequences
- Sensor interface circuits → IMX385 carrier board: interfaces
- IMX385 carrier board → Device-tree overlay: hardware described by
- IMX385 carrier board → GPIO sensor controls: SEQ GPIO and controls
- Device-tree overlay → IMX385 kernel driver: binds
- Driver build & boot setup → IMX385 kernel driver: builds and loads
- GPIO sensor controls → IMX385 kernel driver: enables sensor before capture
- IMX385 kernel driver → V4L2 capture pipeline: exposes pixel data
- Config template → Config generator: seeds
- Config generator → RPM application: generates config for
- Conda environment → RPM application: provides dependencies
- V4L2 capture pipeline → Video/camera feed: captured frames
- RPM application → Video/camera feed: opens configured target
- Video/camera feed → Optical-flow extraction: frames
- Optical-flow extraction → Motion/BPM inference: motion signal
- Motion/BPM inference → RPM calculation: BPM estimate
- RPM calculation → Console or CSV output: estimate
