# 2026dts/oil_rig architecture

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

- Interactive diagram: https://gitdiagram.com/2026dts/oil_rig
- Repository: https://github.com/2026dts/oil_rig

## Overview

The repository contains two Python monitoring products: a Modbus-to-ThingsBoard bridge and a local Flask dashboard, plus a standalone read-only register diagnostic. The primary workflow polls PLC registers, derives telemetry and runtime values, then publishes them or presents them locally; motor commands can return to the PLC. The HTTP application excerpt also shows database-backed readings, alerts, and dashboard/API behavior. Unsampled routes and the ESP sketch are not expanded; edges reflect only the README or shown source excerpts.

Main entry points: [`oil_rig.py`](https://github.com/2026dts/oil_rig/blob/main/oil_rig.py) (Telemetry bridge), [`Oil_Rig_HTTP/oil_rig.py`](https://github.com/2026dts/oil_rig/blob/main/Oil_Rig_HTTP/oil_rig.py) (Flask dashboard), [`wind_speed.py`](https://github.com/2026dts/oil_rig/blob/main/wind_speed.py) (Register diagnostic), [`motor_runtime_state.json`](https://github.com/2026dts/oil_rig/blob/main/motor_runtime_state.json) (Runtime state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_field["Rig hardware"]
  node_sensors(("Rig sensors"))
  node_plc["Delta PLC"]
  node_gateway["USR-W630"]
end

subgraph group_bridge["Cloud bridge"]
  node_bridge_app["Telemetry bridge<br/>[oil_rig.py]"]
  node_register_read["Register polling<br/>[oil_rig.py]"]
  node_derived_data["Scaled telemetry<br/>[oil_rig.py]"]
  node_runtime["Motor runtime<br/>[oil_rig.py]"]
  node_runtime_file["Runtime state"]
  node_thingsboard["ThingsBoard"]
end

subgraph group_dashboard["Local dashboard"]
  node_http_app["Flask dashboard<br/>[oil_rig.py]"]
  node_http_polling["PLC polling<br/>[oil_rig.py]"]
  node_dashboard_api["Dashboard API<br/>[oil_rig.py]"]
  node_web_views["Dashboard views<br/>[oil_rig.py]"]
  node_history_store[("SQLite history<br/>[oil_rig.py]")]
  node_alerting["Wind alerts<br/>[oil_rig.py]"]
end

subgraph group_diagnostics["Diagnostics"]
  node_diagnostic["Register diagnostic<br/>[wind_speed.py]"]
  node_raw_log["Raw register log"]
end

node_operator(("Operator"))

node_sensors -->|"feed readings"| node_plc
node_plc -->|"serial link"| node_gateway
node_gateway -->|"Modbus TCP"| node_bridge_app
node_bridge_app -->|"polls registers"| node_register_read
node_register_read -->|"scales values"| node_derived_data
node_derived_data -->|"updates counters"| node_runtime
node_runtime -->|"persists state"| node_runtime_file
node_bridge_app -->|"publishes telemetry"| node_thingsboard
node_thingsboard -->|"sends RPC"| node_bridge_app
node_bridge_app -->|"writes motor state"| node_plc
node_gateway -.->|"Modbus TCP"| node_http_app
node_http_app -->|"reads PLC"| node_http_polling
node_http_app -->|"initializes tables"| node_history_store
node_http_app -->|"checks wind"| node_alerting
node_operator -.->|"opens dashboard"| node_web_views
node_web_views -->|"requests data"| node_dashboard_api
node_diagnostic -->|"reads registers"| node_gateway
node_diagnostic -->|"logs readings"| node_raw_log

click node_bridge_app "https://github.com/2026dts/oil_rig/blob/main/oil_rig.py"
click node_register_read "https://github.com/2026dts/oil_rig/blob/main/oil_rig.py"
click node_derived_data "https://github.com/2026dts/oil_rig/blob/main/oil_rig.py"
click node_runtime "https://github.com/2026dts/oil_rig/blob/main/oil_rig.py"
click node_runtime_file "https://github.com/2026dts/oil_rig/blob/main/motor_runtime_state.json"
click node_http_app "https://github.com/2026dts/oil_rig/blob/main/Oil_Rig_HTTP/oil_rig.py"
click node_http_polling "https://github.com/2026dts/oil_rig/blob/main/Oil_Rig_HTTP/oil_rig.py"
click node_dashboard_api "https://github.com/2026dts/oil_rig/blob/main/Oil_Rig_HTTP/oil_rig.py"
click node_web_views "https://github.com/2026dts/oil_rig/blob/main/Oil_Rig_HTTP/oil_rig.py"
click node_history_store "https://github.com/2026dts/oil_rig/blob/main/Oil_Rig_HTTP/oil_rig.py"
click node_alerting "https://github.com/2026dts/oil_rig/blob/main/Oil_Rig_HTTP/oil_rig.py"
click node_diagnostic "https://github.com/2026dts/oil_rig/blob/main/wind_speed.py"
click node_raw_log "https://github.com/2026dts/oil_rig/blob/main/wind_speed_diagnostic_log.csv"

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_sensors,node_plc,node_gateway toneBlue
class node_bridge_app,node_register_read,node_derived_data,node_runtime,node_runtime_file,node_thingsboard toneAmber
class node_http_app,node_http_polling,node_dashboard_api,node_web_views,node_history_store,node_alerting toneMint
class node_diagnostic,node_raw_log toneRose
class node_operator toneIndigo
```

## Components

### Rig hardware

- **Rig sensors**
- **Delta PLC**
- **USR-W630**

### Cloud bridge

- [Telemetry bridge](https://github.com/2026dts/oil_rig/blob/main/oil_rig.py): `oil_rig.py`
- [Register polling](https://github.com/2026dts/oil_rig/blob/main/oil_rig.py): `oil_rig.py`
- [Scaled telemetry](https://github.com/2026dts/oil_rig/blob/main/oil_rig.py): `oil_rig.py`
- [Motor runtime](https://github.com/2026dts/oil_rig/blob/main/oil_rig.py): `oil_rig.py`
- [Runtime state](https://github.com/2026dts/oil_rig/blob/main/motor_runtime_state.json): `motor_runtime_state.json`
- **ThingsBoard**

### Local dashboard

- [Flask dashboard](https://github.com/2026dts/oil_rig/blob/main/Oil_Rig_HTTP/oil_rig.py): `Oil_Rig_HTTP/oil_rig.py`
- [PLC polling](https://github.com/2026dts/oil_rig/blob/main/Oil_Rig_HTTP/oil_rig.py): `Oil_Rig_HTTP/oil_rig.py`
- [Dashboard API](https://github.com/2026dts/oil_rig/blob/main/Oil_Rig_HTTP/oil_rig.py): `Oil_Rig_HTTP/oil_rig.py`
- [Dashboard views](https://github.com/2026dts/oil_rig/blob/main/Oil_Rig_HTTP/oil_rig.py): `Oil_Rig_HTTP/oil_rig.py`
- [SQLite history](https://github.com/2026dts/oil_rig/blob/main/Oil_Rig_HTTP/oil_rig.py): `Oil_Rig_HTTP/oil_rig.py`
- [Wind alerts](https://github.com/2026dts/oil_rig/blob/main/Oil_Rig_HTTP/oil_rig.py): `Oil_Rig_HTTP/oil_rig.py`

### Diagnostics

- [Register diagnostic](https://github.com/2026dts/oil_rig/blob/main/wind_speed.py): `wind_speed.py`
- [Raw register log](https://github.com/2026dts/oil_rig/blob/main/wind_speed_diagnostic_log.csv): `wind_speed_diagnostic_log.csv`

### Other components

- **Operator**

## Connections

- Rig sensors → Delta PLC: feed readings (evidence: `README.md`)
- Delta PLC → USR-W630: serial link (evidence: `README.md`)
- USR-W630 → Telemetry bridge: Modbus TCP (evidence: `README.md`)
- Telemetry bridge → Register polling: polls registers (evidence: `oil_rig.py`)
- Register polling → Scaled telemetry: scales values (evidence: `oil_rig.py`)
- Scaled telemetry → Motor runtime: updates counters (evidence: `oil_rig.py`)
- Motor runtime → Runtime state: persists state (evidence: `oil_rig.py`)
- Telemetry bridge → ThingsBoard: publishes telemetry (evidence: `README.md`)
- ThingsBoard → Telemetry bridge: sends RPC (evidence: `README.md`)
- Telemetry bridge → Delta PLC: writes motor state (evidence: `README.md`)
- USR-W630 → Flask dashboard: Modbus TCP
- Flask dashboard → PLC polling: reads PLC (evidence: `Oil_Rig_HTTP/oil_rig.py`)
- Flask dashboard → SQLite history: initializes tables (evidence: `Oil_Rig_HTTP/oil_rig.py`)
- Flask dashboard → Wind alerts: checks wind (evidence: `Oil_Rig_HTTP/oil_rig.py`)
- Operator → Dashboard views: opens dashboard
- Dashboard views → Dashboard API: requests data (evidence: `Oil_Rig_HTTP/oil_rig.py`)
- Register diagnostic → USR-W630: reads registers (evidence: `wind_speed.py`)
- Register diagnostic → Raw register log: logs readings (evidence: `wind_speed.py`)
