e-foc System Architecture

Note — Architecture-level document: This document describes what the system is and why it is structured this way. Code must follow the architecture, not the opposite. Logical component and interface names are the vocabulary of architecture and belong here. What must be avoided: source file paths, implementation class names (e.g. FooImpl), and code-level algorithmic details.

Diagrams: All visuals must be either a Mermaid fenced code block or ASCII art inline in the document. External image references (![alt](/home/runner/work/e-foc/e-foc/documentation/architecture/path)) are not allowed.

Sequence diagrams, block diagrams, component diagrams, and state machines (Mermaid syntax) are allowed and encouraged.

Assumptions & Constraints

• Constraint: No dynamic memory allocation on the embedded target. All objects are stack- or statically-allocated for deterministic, bounded memory footprint.
• Constraint: The core FOC loop executes in an interrupt service routine at 20 kHz. The complete control cycle must not exceed 75 percent of the available CPU time per control period (<= 4500 cycles at 120 MHz / 20 kHz) to guarantee real-time deadlines.
• Constraint: No recursion in control-loop or ISR-reachable paths. Stack usage must be statically predictable.
• Constraint: No C++ exceptions. Error signalling uses status return values, std::optional, or asynchronous callbacks.
• Constraint: The system targets 32-bit ARM Cortex-M microcontrollers (STM32 and TI Tiva families). Host builds are supported for unit testing and simulation only.
• Assumption: A single motor is controlled per instantiation. Multi-motor configurations require multiple independent instantiations.
• Assumption: The motor is a BLDC or PMSM (surface or interior permanent magnet) with a sinusoidal back-EMF profile suitable for FOC.
• Assumption: Rotor position is measured by a quadrature encoder. Hall-sensor support is defined in the driver interface but is a secondary configuration.
• Assumption: All motor electrical and mechanical parameters (resistance, inductance, pole pairs, inertia, friction) can be identified at startup or loaded from non-volatile storage.
• Constraint: The build system produces a single unified binary (e_foc.sync_foc_sensored.main) that contains all three control modes. The active mode can be selected at runtime via CAN command (SelectControlMode) and persisted to NVM so it survives a power cycle. The CLI command active_mode reports the currently active mode. No mode switch is permitted while the motor is enabled.

System Overview

e-foc is a Field-Oriented Control (FOC) firmware for BLDC and PMSM motors. Its purpose is to transform three-phase stator currents into a rotating reference frame so that torque and flux can be regulated independently with standard linear PIDs, then synthesise the three-phase PWM voltages via Space Vector Modulation.

The system is structured in four tiers:

1. Infrastructure tier — external repositories providing general-purpose utilities, numerical algorithms, and vendor HAL drivers. These are consumed as submodules and are never modified by this project.
2. Core / Library tier — the FOC algorithm library (core/foc/), service library (core/services/), and the Platform Abstraction Layer interface (core/platform_abstraction/). These are pure, portable libraries with no target-specific knowledge.
3. Targets tier — target-specific code that is NOT reusable across all environments: platform implementations (concrete PlatformFactory for TI, ST, and Host) and application entry points (hardware_test, sync_foc_sensored). Lives under targets/.
4. Tools tier — host-only desktop tools (simulator, CAN commander) that run on development machines only. Lives under tools/.

The simulator implements the same PAL contracts as real hardware. Control logic never needs to distinguish between running on a microcontroller or on the host; this enables full-fidelity closed-loop validation without hardware.

Component Decomposition

1. FOC Core

The heart of the system. Decomposed into sub-layers following a strict separation of vocabulary, generic numerics, transform algorithms, orchestration, and wiring. Dependencies flow in one direction only — from wiring down towards vocabulary; no lower layer may depend on a higher one:

Because Interfaces, Math, and Transforms carry no dependency on the control cascade, the identification, alignment, and simulation components consume them directly without pulling in the control loops.

The three control modes are available in the same binary and are selected at runtime through ControlModeStateMachine. Only one mode is active at a time; switching is only permitted from Idle or Ready state and persists the new choice to NVM via defaultControlMode:

• Torque control — innermost loop: regulates phase currents to produce a commanded torque (specified as Id/Iq current setpoints).
• Speed control — outer loop on top of torque control: a PID regulates rotor angular velocity by commanding Id/Iq setpoints to the inner loop. The outer loop runs at a lower priority interrupt (typically 1 kHz) while the inner loop still runs at 20 kHz.
• Position control — outermost cascade: a PID regulates rotor position by commanding a speed setpoint to the speed loop. Builds on speed control.

Interrupt Priority Plan

On Cortex-M, equal priority means no preemption: a handler at the same level as the FOC ISR cannot be interrupted by it, so the FOC loop’s worst-case latency is the duration of the longest other handler at or above its level. Leaving every source at the default therefore leaves the 20 kHz deadline hostage to a CAN receive or a UART DMA completion.

The TI target assigns priorities explicitly in application::InterruptPriorities:

The outer loop runs on PendSV at the lowest configurable priority. It carries a 20 000-cycle budget against the inner loop’s 4 500, so running it above the current loop would insert up to a full outer-loop execution of duty-update jitter once per millisecond.

The Runner is the only component that interacts with the PAL inverter and encoder at interrupt time. It registers the ADC-sampling callback and drives the Calculate() dispatch into the active control-mode implementation.

The dispatch carries no validation of the sample. Nothing in the 20 kHz path inspects the phase currents for plausibility or for finiteness: at 4500 cycles a frame the budget is spent on the control law, and a failed shunt or ADC channel is the hardware’s fault detection to catch, not the control loop’s. foc::ToDutyCycles clamps each modulator output into [0, 1] and converts to percent, and does nothing else.

foc::IsFiniteValue survives for the places where validation is affordable and worth having — CurrentPlantModel::IsUsable when the plant is configured, and the plausibility band the mechanical estimator applies before publishing. Both run outside the hot path. It tests the float’s exponent bits rather than calling std::isnan, which -ffinite-math-only licenses the compiler to fold to a constant; the embedded builds keep -fno-finite-math-only, but the check does not depend on it.

2. Services

Higher-level, non-real-time services that support commissioning and runtime operation. Each service is independently usable:

3. CAN Service

The CAN service layer (core/can/) provides the FOC motor CAN category as a server/client pair and the bridge that connects the server to the ControlModeStateMachine. It is split into two halves:

Server half (runs on the embedded target): - FocMotorCategoryServer — a CanCategoryServer subclass. Decodes incoming CAN frames into typed observer callbacks. Encodes typed results back into response frames. Wire scaling (int16 ↔︎ physical unit) is contained entirely here. - FocMotorCanBridge — implements the server observer interface. Translates CAN motor commands (Start, Stop, SelectControlMode, SetTorqueSetpoint, SetSpeedSetpoint, SetPositionSetpoint, ClearFault, EmergencyStop) into the corresponding ControlModeStateMachine calls. It also implements the PID bandwidth, identification, telemetry, and encoder-resolution commands (OnIdentifyElectrical, OnIdentifyMechanical, OnRequestTelemetry, OnSetEncoderResolution, OnConfigureTelemetryRate), each reporting success or a specific FocMotorCategoryError on the response frame.

Client half (runs on the desktop host — CAN Commander, SIL tests): - FocMotorCategoryClient — a CanCategoryClient subclass. Encodes typed setpoints into CAN frames and decodes response frames into typed callbacks. - FocMotorCanClient — user-facing API that composes CanFrameTransport, CanProtocolClient, and FocMotorCategoryClient internally. Takes a hal::Can& and a node ID; exposes Start, Stop, SetTorque, SetSpeed, and SetPosition methods.

Tracing is applied at every layer boundary via the can-lite tracing decorators (TracingCan, TracingCanProtocolServerObserver, TracingCanProtocolClientObserver).

Services communicate via asynchronous callbacks (zero-allocation closures from embedded-infra-lib), not return values. This allows long-running operations (identification, alignment) to yield the CPU and complete asynchronously without blocking.

3. Platform Abstraction Layer

The PAL provides a single platform-facing abstraction that groups creation and access to the hardware services needed by the control system:

Concrete implementations exist for: - TI Tiva (EK-TM4C1294XL, EK-TM4C123GXL): platform-specific peripheral adapters under targets/platform_implementations/ti/. - ST STM32 (STM32F407G-DISC1, NUCLEO-H563ZI): platform-specific peripheral adapters under targets/platform_implementations/st/. - Host / Simulator: a software-backed platform implementation that emulates the motor-control I/O needed to run the closed-loop algorithm on a development machine, located under targets/platform_implementations/host/.

4. Application / Instantiation (was §3)

The wiring layer. Assembles the concrete PAL implementation, the selected FOC mode(s), and the services into a runnable system. This is the only layer that is aware of the specific combination in use — all other layers depend only on abstractions.

The FocStateMachine is the central lifecycle authority. It owns the full motor commissioning and operation lifecycle: it enforces a formal five-state machine (Idle → Calibrating → Ready ⇄ Enabled, Fault), orchestrates the sequential calibration chain (electrical identification, alignment, and mechanical identification for speed/position modes), and responds to hardware fault notifications by immediately stopping the inverter and entering the Fault state. Only after FocStateMachine has reached Ready can the motor be enabled.

In CLI mode, ControlModeStateMachine registers the lifecycle commands calibrate, enable, disable, clear_fault, clear_cal, apply_estimates, and active_mode on the terminal. These commands delegate to the currently active state machine. The TerminalFocBaseInteractor (and its control-mode subclasses) register PID tuning and setpoint commands on the same terminal.

5. Tools (was §4)

Host-only tools that do not run on the embedded target:

6. Infrastructure (was §5)

External repositories consumed as Git submodules. This project does not modify them.

Upstream dependencies of the position state feedback laws

Because submodules are never patched locally, an upstream defect has to be carried here as a workaround until the fix lands. Two such defects shaped the position loop and are now resolved on numerical-toolbox main, which is what the submodule tracks:

Should a comparable defect appear again, record it in this table with the workaround and the condition for retiring it, so a workaround does not quietly become permanent.

7. Vendor HAL (was §6)

Vendor-provided hardware abstraction libraries consumed as Git submodules. They supply the low-level peripheral register access and interrupt management that the PAL concrete implementations use.

These are never used directly by the FOC core or services — only by the PAL concrete implementations.

Interfaces & Contracts

Provided Interfaces (exported by this system)

Required Interfaces (consumed from the PAL)

SOLID Principles Applied

The interface design reflects explicit SOLID choices:

• Single Responsibility: Each interface (FocTorque, FocSpeed, FocPosition, ThreePhaseInverter, Encoder, NonVolatileMemory, …) is narrowly scoped to one concern. No interface carries unrelated responsibilities.
• Open/Closed: New control modes are added by implementing a new derived control interface, not by modifying existing implementations. The PAL is similarly extended by creating a new platform factory implementation for a new board without touching the core.
• Liskov Substitution: Every FOC controller instantiation (torque, speed, position) is fully substitutable wherever the base control interface is expected. The simulator’s motor model is fully substitutable for the real PAL hardware.
• Interface Segregation: FocBase carries only the minimal common contract. Callers that need only torque control depend on FocTorque, not on FocSpeed or FocPosition. The PAL is similarly split — callers that only need an encoder do not depend on the PWM interface.
• Dependency Inversion: The FOC core and all services depend exclusively on abstract interfaces. Concrete implementations are injected at application wiring time via the platform factory and constructor arguments. No global variables; no direct peripheral access from the control layer.

Data Flow

The primary data flow during closed-loop motor control is the 20 kHz FOC interrupt cycle:

The commissioning data flow (run once at startup or on command):

Observer and Callback Patterns

The system uses two complementary asynchronous communication patterns, both supplied by infra/embedded-infra-lib:

• Zero-allocation closures (from embedded-infra-lib) — used for one-shot or single-subscriber callbacks. All service operations (NVM, identification, alignment) deliver their results through this mechanism.
• Observer/Subject pattern (from embedded-infra-lib) — a type-safe, heap-free mechanism where a subject notifies multiple observers. The simulator’s motor model is a subject; views and loggers attach as observers. No raw event buses or dynamic dispatch lists are used.

These patterns eliminate polling, decouple producers from consumers, and allow the application to remain single-threaded and non-blocking.

Cross-Cutting Concerns

Open Questions & Decisions

Integration Testing

Integration testing drives the real firmware as a black box over the product’s own CAN command set. Nothing inside the firmware is mocked or reached into; the suite starts a target, sends commands, and asserts on telemetry and traces.

Two targets implement scenarios, selected by tag:

1. Software-in-the-loop — the firmware built for an emulated Cortex-M4, running under an emulator against a simulated three-phase motor the firmware itself owns. Only the motor, the power stage and the board protection are simulated, because there is no hardware. The motor is described per scenario and handed to the firmware at boot, and non-volatile memory is pre-seeded so a scenario starts from a chosen calibration and configuration.
2. Hardware-in-the-loop — the same firmware on a real board, reached through the hardware bridge over serial and CAN.

Design detail: documentation/design/integration-testing.md for the shared structure, and documentation/design/software-in-the-loop.md for the simulated target.

Integration Boundaries

Requirements Traceability

Each scenario carries the requirement identifiers it verifies as tags, alongside the tag naming the target that implements it. The traceability matrix is generated from those tags at release time by reading the feature directory, so the mapping lives with the scenarios rather than in a table here that would drift away from them.

Requirements with no scenario are verified by unit tests under the owning library, or are structural constraints discharged by design review; the generated matrix reports both.