Architecture¶
Detailed-design specifications. Pages under this section follow the
arc42 template (12 sections) encoded with sphinx-needs using the
useblocks “x-as-code” arc42 directive types — arch-decision,
building-block, architecture, constraint, quality-goal,
risk, glossary. Legacy spec directives may also appear for
detailed-design notes that predate the arc42 adoption.
- Connector framework — architecture (arc42)
- 1. Introduction and goals
- 2. Constraints
- 3. Context and scope
- 4. Solution strategy
- 5. Building block view
- 6. Runtime view
- 7. Deployment view
- 8. Crosscutting concepts
- 9. Architecture decisions
- 10. Quality requirements
- 11. Risks and technical debt
- 12. Glossary
- 13. Implementations
- Cross-cutting traceability
- PLC runtime — architecture
- Bounded global allocator — architecture
- Device-driver codegen — architecture (arc42)
- CANopen device-driver codegen — architecture (arc42)
- Safety architecture decisions
Building blocks¶
ID |
Title |
Status |
Implements |
|---|---|---|---|
taktora-connector-core |
open |
||
taktora-connector-transport-iox |
open |
||
taktora-connector-codec |
open |
||
taktora-connector-mqtt |
open |
||
taktora-connector-host |
open |
||
ConnectorEnvelope (sub-block of BB_0002) |
open |
||
ServiceFactory (sub-block of BB_0002) |
open |
||
MqttConnector (sub-block of BB_0004, plugin side) |
open |
||
MqttGateway (sub-block of BB_0004, gateway side) |
open |
||
Tokio bridge (sub-block of BB_0021) |
open |
||
Dispatch scratch (pre-allocated) |
open |
||
taktora-bounded-alloc crate |
open |
||
taktora-connector-ethercat |
open |
||
EthercatConnector (sub-block of BB_0030, plugin side) |
open |
||
EthercatGateway (sub-block of BB_0030, gateway side) |
open |
||
PDO mapping (sub-block of BB_0030) |
open |
||
Tokio bridge for ethercrab (sub-block of BB_0030) |
open |
||
taktora-connector-zenoh |
open |
||
ZenohConnector (sub-block of BB_0040, plugin side) |
open |
||
ZenohGateway (sub-block of BB_0040, gateway side) |
open |
||
Zenoh query handles (sub-block of BB_0041) |
open |
||
Tokio bridge for zenoh (sub-block of BB_0042) |
open |
||
Per-task cycle statistics |
open |
||
Statistics snapshot view |
open |
||
xtask-preempt-rt harness |
open |
||
ethercat-esi (parser crate) |
open |
||
ethercat-esi-codegen (IR + backend trait) |
open |
||
ethercat-esi-codegen-ethercrab (concrete backend) |
open |
||
ethercat-esi-rt (runtime trait crate) |
open |
||
ethercat-esi-build (build.rs glue) |
open |
||
ethercat-esi-cli (cargo subcommand) |
open |
||
ethercat-esi-verify (EEPROM diff tool) |
open |
||
taktora-connector-ethercat EsiDevice adapter |
open |
||
taktora-connector-can crate |
open |
||
CanConnector (sub-block of BB_0070, plugin side) |
open |
||
CanGateway (sub-block of BB_0070, gateway side) |
open |
REQ_0613; REQ_0614; REQ_0620; REQ_0624; REQ_0625; REQ_0630; REQ_0631 |
|
Tokio bridge for CAN (sub-block of BB_0072) |
open |
||
Per-iface filter compiler (sub-block of BB_0072) |
open |
||
MockCanInterface (sub-block of BB_0070) |
open |
||
fieldbus-od-core |
open |
||
canopen-eds parser crate |
open |
||
canopen-eds-codegen |
open |
||
canopen-eds-codegen-taktora |
open |
||
canopen-eds-rt |
open |
||
canopen-eds-build |
open |
||
canopen-eds-cli |
open |
||
canopen-eds-verify |
open |
||
taktora-connector-can adapter (follow-on) |
open |
Architecture views (context, runtime, deployment, crosscutting)¶
ID |
Title |
Status |
Refines |
|---|---|---|---|
System context |
open |
||
Level-1 building block decomposition |
open |
BB_0001; BB_0002; BB_0003; BB_0004; BB_0005; BB_0030; BB_0040 |
|
Send path (app → broker) |
open |
||
Receive path (broker → app) |
open |
||
Health and reconnect lifecycle |
open |
||
Shutdown coordination |
open |
||
In-process gateway deployment |
open |
||
Separate-process gateway deployment |
open |
||
Codec — compile-time generic |
open |
||
Error handling — single error type, explicit origins |
open |
||
Observability — Observer + ExecutionMonitor adapter |
open |
||
Back-pressure — explicit at every bounded buffer |
open |
||
EtherCAT bus bring-up sequence |
open |
||
Cyclic process-data exchange and working-counter health |
open |
||
Optional Distributed Clocks bring-up |
open |
||
Toolchain layering (crate dependency graph) |
open |
||
Build-time vs runtime separation |
open |
||
Build-time generation flow |
open |
||
Preop bring-up flow (per device) |
open |
||
Toolchain crate placement in workspace |
open |
||
CAN frame send path (app → bus) |
open |
||
CAN receive path with multi-iface demux |
open |
||
CAN bus health and bus-off recovery |
open |
||
Toolchain layering (crate dependency graph) |
open |
||
Build-time vs runtime separation |
open |
Architecture decisions¶
ID |
Title |
Status |
Refines |
|---|---|---|---|
Spec scope — framework core + MQTT reference |
open |
||
Umbrella feature is a peer of FEAT_0010 |
open |
||
Both deployment shapes supported |
open |
||
Per-channel envelope size, declared in descriptor |
open |
||
Codec is a generic parameter on the connector |
open |
||
Explicit-builder plugin discovery |
open |
||
Plugin and gateway are both taktora-executor consumers |
open |
||
Routing carried as a typed struct |
open |
||
Lifecycle = ReconnectPolicy + ConnectorHealth |
open |
||
MQTT scope — realistic but bounded |
open |
||
Pre-allocate dispatch scratch at Executor::build time |
open |
||
Compile-time caps + hand-rolled fixed-block bitmap |
open |
||
ethercrab as the EtherCAT MainDevice library |
open |
||
Single MainDevice per gateway |
open |
||
Static PDO mapping declared at build time |
open |
||
Distributed Clocks bring-up is opt-in |
open |
||
Linux raw socket only in first cut |
open |
||
``taktora-connector-ethercat`` module decomposition |
open |
||
Tokio runtime owned by ``EthercatGateway``, joined on Drop |
open |
||
``EthercatConnectorOptions`` is a typed builder; PDO map declared as ``&'static [SubDeviceMap]`` |
open |
||
Verification harness — pure-logic unit tests + env-gated bus tests |
open |
||
Zenoh queries live on a concrete handle type, not the Connector trait |
open |
||
Stack-internal reconnect for Zenoh — no ReconnectPolicy |
open |
||
One ZenohRouting struct carries pub/sub QoS; query knobs on options |
open |
||
Reply framing uses a Zenoh-private 1-byte payload prefix |
open |
||
Process boundary as spatial isolation context |
open |
||
Bounded allocator as spatial-determinism anchor |
open |
||
Fixed-bucket histogram for percentile estimation |
open |
||
Harness as xtask, not CI gate |
open |
||
Parser separated from codegen (strict layering) |
open |
||
Two-trait runtime split (EsiDevice + EsiConfigurable) |
open |
||
PDO assignment alternatives as sum types |
open |
||
Future CANopen support via shared OD IR |
accepted |
||
Vendor extensions captured as opaque blobs |
open |
||
Object dictionary as static table, feature-gated |
open |
||
Use prettyplease, not rustfmt, for emit formatting |
open |
||
cargo subcommand for inspection, not proc-macro |
open |
||
Lift OD IR to fieldbus-od-core now |
open |
||
fieldbus-od-core stays data-only |
open |
||
Re-export from ethercat-esi, do not break it |
open |
||
INI backend choice — serde-derive façade |
open |
||
PDO entry dedup is structural, name-blind |
open |
||
Dummy entries skip into bit offsets, not padding fields |
open |
||
heapless::Vec<u8, 8> for PdoOut payload |
open |
||
Async only on configure, sync on frame path |
open |
||
JSON SDO-dump format with versioned schema |
open |
Quality goals and constraints¶
ID |
Title |
Status |
Refines |
|---|---|---|---|
Fault isolation between protocol stack and app |
open |
||
Compile-time type safety end-to-end |
open |
||
Zero-copy data flow on the publish path |
open |
||
Uniform observable health across connectors |
open |
||
Build-time determinism (same ESI in → same code out) |
open |
||
Layering integrity (strict left-to-right deps) |
open |
||
Zero runtime cost of codegen presence |
open |
||
Trait stability for ecosystem adoption |
open |
||
Build-time determinism (same EDS in → same code out) |
open |
||
Layering integrity (strict left-to-right deps) |
open |
||
Zero runtime cost of codegen presence |
open |
||
Trait stability for ecosystem adoption |
open |
ID |
Title |
Status |
Refines |
|---|---|---|---|
Built on taktora-executor's WaitSet |
open |
||
iceoryx2 0.8.x as the IPC layer |
open |
||
Rust 2024 edition / MSRV 1.85 |
open |
||
Single-threaded test discipline |
open |
||
Tokio sidecar contained per connector crate |
open |
||
cargo build-script semantics |
open |
||
ethercrab API surface as upstream |
open |
||
bitvec for process-image access |
open |
||
no_std + alloc baseline for parser and runtime trait |
open |
||
ETG owns the ESI XML schema |
open |
||
cargo build-script semantics |
open |
||
CiA 301 / 306 own the EDS schema |
open |
||
no_std + alloc baseline for OD core, parser, runtime |
open |
||
heapless 0.8 surface for fixed-capacity buffers |
open |
Risks¶
ID |
Title |
Status |
Links |
|---|---|---|---|
rumqttc API stability before 1.0 |
open |
||
iceoryx2 0.8 pre-1.0 churn |
open |
||
Const-generic monomorphisation cost |
open |
||
Tokio bridge latency |
open |
||
Wildcard demux pathological topic patterns |
open |
||
OD table size blow-up on coupling modules |
open |
||
Beckhoff vendor extensions churn the IR |
open |
||
ethercrab API churn breaking the backend |
open |
||
ESI XML schema drift across vendors |
open |
||
Generated code becomes load-bearing without migration path |
open |
||
EDS files in the wild are inconsistent |
open |
||
serde-ini ecosystem thinness |
open |
||
CiA 301 OD blow-up on profile-rich devices |
open |
||
COB-ID base assumptions in generated code |
open |
Glossary¶
ID |
Title |
Status |
|---|---|---|
Connector |
open |
|
Plugin |
open |
|
Gateway |
open |
|
ConnectorEnvelope |
open |
|
Codec |
open |
|
Routing |
open |
|
Bridge |
open |
|
Health |
open |
|
Reconnect policy |
open |
|
Channel |
open |
|
ASIL |
open |
|
ESI |
open |
|
SII |
open |
|
PDO |
open |
|
CoE |
open |
|
OD (Object Dictionary) |
open |
|
InitCmd |
open |
Legacy detailed-design specifications¶
No needs passed the filters