# tdenkov123/bolt architecture

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

- Interactive diagram: https://gitdiagram.com/tdenkov123/bolt
- Repository: https://github.com/tdenkov123/bolt

## Overview

#### Purpose and entry points
BOLT is an IEC 61499-inspired Python runtime: applications compose Function Blocks (FBs), connect event/data ports, and execute event chains. The host example starts at `main.py`; runtime primitives live under `core/`. An ESP32 MicroPython peer receives engine commands and publishes acknowledgements via MQTT from `BOLT_mp/BOLT_mp/main.py`.

#### Host runtime model
`core/BaseDevice.py` represents a device-level container for resources. `core/BaseResource.py` owns FB instances and their execution context; `core/BaseFunctionBlock.py` defines FB lifecycle, interfaces, state, and event handling. `core/FunctionBlockLoader.py` resolves/load built-in FB implementations, allowing the application to construct a resource graph from FB types.

#### Event and data graph execution
FB interfaces and execution states are modeled in `core/FBInterface.py` and `core/FBStates.py`. Connections are explicit graph edges: `core/connections/EventConnection.py` propagates control/events, while `core/connections/DataConnection.py` transfers values between FB variables. Event propagation is the main control flow; the README notes one thread is used per event chain on CPython.

#### Function-block library
Built-in blocks in `core/FBs/` implement application behavior. `core/FBs/START.py` initiates a graph at resource startup, `core/FBs/E_CYCLE.py` generates periodic events, and `core/FBs/MQTT_PUBLISH.py` / `core/FBs/MQTT_SUBSCRIBE.py` bridge the graph to MQTT. The example’s cyclic path publishes `ENGINE_DEGREES` every 500 ms and receives `ENGINE_STATUS` acknowledgements.

#### Data typing boundary
IEC-style values and casting are centralized in `core/datatypes/`, including `core/datatypes/IEC_INT.py`, `core/datatypes/IEC_STRING.py`, and `core/datatypes/Cast.py`. This separates typed FB input/output data semantics from Python transport and scheduling concerns.

#### MQTT and infrastructure boundary
The host MQTT adapter is `core/MQTTClient.py`; host broker endpoint settings are in `config.py`. MQTT is the process/network boundary between the Python FB engine and embedded devices. Local infrastructure is Docker Compose-backed Mosquitto via `docker-compose.yml` and `docker/mosquitto.conf`; optional Avahi service files under `docker/` advertise broker discovery as `mqtt.local`.

#### ESP32 MicroPython peer
ESP firmware bootstraps networking in `BOLT_mp/BOLT_mp/boot.py`, then runs its MQTT command/acknowledgement loop in `BOLT_mp/BOLT_mp/main.py` using `BOLT_mp/BOLT_mp/mqtt_client.py`. `BOLT_mp/BOLT_mp/bolt_net.py` initializes Wi-Fi and resolves the broker. `BOLT_mp/BOLT_mp/mdns_discovery.py` provides a fast configured-IP probe plus optional mDNS lookup/fallback, controlled by `BOLT_mp/BOLT_mp/config.py`.

Main entry points: [`core/FBs/MQTT_PUBLISH.py`](https://github.com/tdenkov123/bolt/blob/master/core/FBs/MQTT_PUBLISH.py) (MQTT publish / subscribe), [`core/BaseResource.py`](https://github.com/tdenkov123/bolt/blob/master/core/BaseResource.py) (Resource executor), [`core/BaseFunctionBlock.py`](https://github.com/tdenkov123/bolt/blob/master/core/BaseFunctionBlock.py) (Function block base), [`core/connections/EventConnection.py`](https://github.com/tdenkov123/bolt/blob/master/core/connections/EventConnection.py) (Event connections)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host runtime"]
  node_host_entry["Host example<br/>entry point<br/>[main.py]"]
  node_device["Device container<br/>runtime container<br/>[BaseDevice.py]"]
  node_resource["Resource executor<br/>execution context<br/>[BaseResource.py]"]
  node_function_block["Function block base<br/>FB runtime"]
  node_fb_loader["FB loader<br/>implementation loader"]
  node_fb_model["Interfaces and states<br/>FB model<br/>[FBInterface.py]"]
  node_event_connection["Event connections<br/>control graph<br/>[EventConnection.py]"]
  node_data_connection["Data connections<br/>data graph<br/>[DataConnection.py]"]
  node_datatypes["IEC data types<br/>typing boundary<br/>[Cast.py]"]
  node_mqtt_client{{"Host MQTT adapter<br/>MQTT client<br/>[MQTTClient.py]"}}
end

subgraph group_blocks["Function-block library"]
  node_start["START<br/>built-in FB<br/>[START.py]"]
  node_cycle["E_CYCLE<br/>built-in FB<br/>[E_CYCLE.py]"]
  node_mqtt_blocks["MQTT publish / subscribe<br/>built-in FBs<br/>[MQTT_PUBLISH.py]"]
end

subgraph group_infra["MQTT infrastructure"]
  node_broker{{"Mosquitto broker<br/>MQTT broker<br/>[docker-compose.yml]"}}
end

subgraph group_peer["ESP32 peer"]
  node_esp_boot["ESP boot<br/>firmware bootstrap<br/>[boot.py]"]
  node_esp_main["ESP command loop<br/>firmware entry point<br/>[main.py]"]
  node_esp_mqtt{{"ESP MQTT client<br/>[mqtt_client.py]"}}
  node_network_discovery["Wi-Fi and broker discovery<br/>network setup<br/>[bolt_net.py]"]
end

node_host_entry -->|"builds"| node_device
node_device -->|"contains"| node_resource
node_resource -->|"loads FB types"| node_fb_loader
node_fb_loader -->|"instantiates"| node_function_block
node_function_block -->|"uses"| node_fb_model
node_function_block -->|"typed I/O"| node_datatypes
node_resource -->|"executes"| node_event_connection
node_event_connection -->|"drives data flow"| node_data_connection
node_start -->|"startup event"| node_cycle
node_cycle -->|"periodic event"| node_mqtt_blocks
node_mqtt_blocks -->|"uses"| node_mqtt_client
node_mqtt_client -->|"publish / subscribe"| node_broker
node_esp_boot -->|"initializes"| node_network_discovery
node_network_discovery -->|"broker ready"| node_esp_main
node_esp_main -->|"uses"| node_esp_mqtt
node_esp_mqtt -->|"commands / acknowledgements"| node_broker
node_mqtt_blocks -.->|"FB event endpoints"| node_event_connection
node_mqtt_blocks -.->|"FB data endpoints"| node_data_connection

click node_host_entry "https://github.com/tdenkov123/bolt/blob/master/main.py"
click node_device "https://github.com/tdenkov123/bolt/blob/master/core/BaseDevice.py"
click node_resource "https://github.com/tdenkov123/bolt/blob/master/core/BaseResource.py"
click node_function_block "https://github.com/tdenkov123/bolt/blob/master/core/BaseFunctionBlock.py"
click node_fb_loader "https://github.com/tdenkov123/bolt/blob/master/core/FunctionBlockLoader.py"
click node_fb_model "https://github.com/tdenkov123/bolt/blob/master/core/FBInterface.py"
click node_event_connection "https://github.com/tdenkov123/bolt/blob/master/core/connections/EventConnection.py"
click node_data_connection "https://github.com/tdenkov123/bolt/blob/master/core/connections/DataConnection.py"
click node_datatypes "https://github.com/tdenkov123/bolt/blob/master/core/datatypes/Cast.py"
click node_mqtt_client "https://github.com/tdenkov123/bolt/blob/master/core/MQTTClient.py"
click node_start "https://github.com/tdenkov123/bolt/blob/master/core/FBs/START.py"
click node_cycle "https://github.com/tdenkov123/bolt/blob/master/core/FBs/E_CYCLE.py"
click node_mqtt_blocks "https://github.com/tdenkov123/bolt/blob/master/core/FBs/MQTT_PUBLISH.py"
click node_broker "https://github.com/tdenkov123/bolt/blob/master/docker-compose.yml"
click node_esp_boot "https://github.com/tdenkov123/bolt/blob/master/BOLT_mp/BOLT_mp/boot.py"
click node_esp_main "https://github.com/tdenkov123/bolt/blob/master/BOLT_mp/BOLT_mp/main.py"
click node_esp_mqtt "https://github.com/tdenkov123/bolt/blob/master/BOLT_mp/BOLT_mp/mqtt_client.py"
click node_network_discovery "https://github.com/tdenkov123/bolt/blob/master/BOLT_mp/BOLT_mp/bolt_net.py"

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_host_entry,node_device,node_resource,node_function_block,node_fb_loader,node_fb_model,node_event_connection,node_data_connection,node_datatypes,node_mqtt_client toneBlue
class node_start,node_cycle,node_mqtt_blocks toneAmber
class node_broker toneMint
class node_esp_boot,node_esp_main,node_esp_mqtt,node_network_discovery toneRose
```

## Components

### Host runtime

Python IEC 61499-style execution engine.

- [Host example](https://github.com/tdenkov123/bolt/blob/master/main.py): entry point · `main.py`
- [Device container](https://github.com/tdenkov123/bolt/blob/master/core/BaseDevice.py): runtime container · `core/BaseDevice.py`
- [Resource executor](https://github.com/tdenkov123/bolt/blob/master/core/BaseResource.py): execution context · Owns FB instances and event-chain execution. · `core/BaseResource.py`
- [Function block base](https://github.com/tdenkov123/bolt/blob/master/core/BaseFunctionBlock.py): FB runtime · Defines lifecycle, interfaces, state, and event handling. · `core/BaseFunctionBlock.py`
- [FB loader](https://github.com/tdenkov123/bolt/blob/master/core/FunctionBlockLoader.py): implementation loader · `core/FunctionBlockLoader.py`
- [Interfaces and states](https://github.com/tdenkov123/bolt/blob/master/core/FBInterface.py): FB model · `core/FBInterface.py`
- [Event connections](https://github.com/tdenkov123/bolt/blob/master/core/connections/EventConnection.py): control graph · Propagates events through FB chains. · `core/connections/EventConnection.py`
- [Data connections](https://github.com/tdenkov123/bolt/blob/master/core/connections/DataConnection.py): data graph · Transfers values between FB variables. · `core/connections/DataConnection.py`
- [IEC data types](https://github.com/tdenkov123/bolt/blob/master/core/datatypes/Cast.py): typing boundary · Centralizes IEC values and casting. · `core/datatypes/Cast.py`
- [Host MQTT adapter](https://github.com/tdenkov123/bolt/blob/master/core/MQTTClient.py): MQTT client · `core/MQTTClient.py`

### Function-block library

- [START](https://github.com/tdenkov123/bolt/blob/master/core/FBs/START.py): built-in FB · Initiates the graph at resource startup. · `core/FBs/START.py`
- [E_CYCLE](https://github.com/tdenkov123/bolt/blob/master/core/FBs/E_CYCLE.py): built-in FB · Generates periodic events. · `core/FBs/E_CYCLE.py`
- [MQTT publish / subscribe](https://github.com/tdenkov123/bolt/blob/master/core/FBs/MQTT_PUBLISH.py): built-in FBs · Bridges FB events and data to MQTT topics. · `core/FBs/MQTT_PUBLISH.py`

### MQTT infrastructure

- [Mosquitto broker](https://github.com/tdenkov123/bolt/blob/master/docker-compose.yml): MQTT broker · Process and network boundary for engine and device. · `docker-compose.yml`

### ESP32 peer

MicroPython command and acknowledgement runtime.

- [ESP boot](https://github.com/tdenkov123/bolt/blob/master/BOLT_mp/BOLT_mp/boot.py): firmware bootstrap · Starts networking before the command loop. · `BOLT_mp/BOLT_mp/boot.py`
- [ESP command loop](https://github.com/tdenkov123/bolt/blob/master/BOLT_mp/BOLT_mp/main.py): firmware entry point · Receives engine commands and publishes acknowledgements. · `BOLT_mp/BOLT_mp/main.py`
- [ESP MQTT client](https://github.com/tdenkov123/bolt/blob/master/BOLT_mp/BOLT_mp/mqtt_client.py): MQTT client · `BOLT_mp/BOLT_mp/mqtt_client.py`
- [Wi-Fi and broker discovery](https://github.com/tdenkov123/bolt/blob/master/BOLT_mp/BOLT_mp/bolt_net.py): network setup · Initializes Wi-Fi and resolves configured or mDNS broker. · `BOLT_mp/BOLT_mp/bolt_net.py`

## Connections

- Host example → Device container: builds
- Device container → Resource executor: contains
- Resource executor → FB loader: loads FB types
- FB loader → Function block base: instantiates
- Function block base → Interfaces and states: uses
- Function block base → IEC data types: typed I/O
- Resource executor → Event connections: executes
- Event connections → Data connections: drives data flow
- START → E_CYCLE: startup event
- E_CYCLE → MQTT publish / subscribe: periodic event · Publishes ENGINE_DEGREES every 500 ms in the example.
- MQTT publish / subscribe → Host MQTT adapter: uses
- Host MQTT adapter → Mosquitto broker: publish / subscribe
- ESP boot → Wi-Fi and broker discovery: initializes
- Wi-Fi and broker discovery → ESP command loop: broker ready
- ESP command loop → ESP MQTT client: uses
- ESP MQTT client → Mosquitto broker: commands / acknowledgements · Receives ENGINE_DEGREES commands and publishes ENGINE_STATUS.
- MQTT publish / subscribe → Event connections: FB event endpoints
- MQTT publish / subscribe → Data connections: FB data endpoints