Embedded Real-Time Motion Controller

Software-first embedded real-time motion controller for an industrial automation portfolio. The project demonstrates deterministic cyclic control, CiA 402-style drive handling, injectable bus backends, watchdog supervision, fault injection, telemetry, diagnostics, and validation reporting.

This repository does not claim certified SIL/PL safety and does not claim real EtherCAT/CANopen hardware validation. The current scope includes a safety-oriented deterministic software bench, dependency-backed SOEM v2, Linux SocketCAN/CANopen, a pinned FreeRTOS cyclic-task port, and a wall-clock host timing probe. Both fieldbus backends remain physically uncommissioned.

Current release: v0.3.0-software-ready, the machine-gated completion of all defined non-hardware work. The historical v0.2.0-simulation-complete baseline remains enforced.

Portfolio-Ready Status

Yes: the non-hardware scope is complete and publishable as a software-ready project. The repo can be presented as deterministic motion-control software with simulation, replay, host timing evidence, adapter contracts, documentation, and portfolio packaging complete.

Do not present it as commissioned industrial hardware. The honest boundary is that physical drive selection, device-specific PDO/OD mapping, target timing capture, real encoder measurements, physical stop-path testing, and certified safety validation remain Phase 2.

Key public evidence:

• v0.3.0-software-ready release gate.
• 45 C++ checks and 21/21 deterministic scenarios.
• 1 ms nominal loop benchmark with injected missed-cycle and deadline-overrun evidence.
• Fault recovery evidence with 0-cycle detection latency and 7-cycle recovery to operation re-enabled.
• Motion metrics: 0.0 overshoot, 0.8 s settling time, two-axis acceptance pass.
• Portfolio bundle generation through scripts/package_portfolio.ps1.

Visual Evidence

Overview	Control Architecture	Validation Dashboard

Graph-first engineering evidence is also committed under reports/: jitter histogram, scenario pass/fail matrix, control response, two-axis path, two-axis acceptance, recovery comparison, and timing PDF.

What Is Included

• C++17 controller core with a 1 ms default cyclic loop model.
• CiA 402-style axis state machine.
• Profile position, profile velocity, and cyclic synchronous mode abstractions.
• EtherCAT/CANopen-ready bus abstraction with a deterministic simulated backend.
• Replay-backed adapter harness for recorded nominal, stale-data, bus, heartbeat, invalid-response, and recovery exchanges.
• Pinned SOEM v2 compile path with guarded NIC/slave configuration, CiA 402 PDO byte exchange, working-counter supervision, and controller backend injection.
• Linux SocketCAN/CANopen backend with NMT, split RPDO/TPDO exchange, heartbeat supervision, transport diagnostics, and injectable transport tests.
• Strict JSON scenario and runtime adapter configuration loading with hardware-free CLI validation.
• Pinned FreeRTOS V11.3.0 periodic-task port with Windows simulator and Linux POSIX smoke execution.
• Absolute-deadline host timing probe with CPU stress and Linux FIFO/memory-lock capability reporting.
• Watchdogs for loop timing, heartbeat, bus health, following error, and encoder feedback loss.
• Fault injector for missed cycle, CPU spike, heartbeat timeout, bus dropout, packet loss, invalid transition, encoder loss, sensor noise, following error, drive fault, watchdog timeout, and command abuse.
• Timestamped telemetry, CSV trace, JSON metrics, persistent fault log, and Markdown validation report export.
• No-dependency C++ test runner and CMake build.
• Deterministic Python sample report generator for review workstations without a native compiler.

Repository Layout

apps/                 Simulator, benchmark, timing probe, and diagnostic CLI entry points
config/adapters/       Versioned SOEM and SocketCAN/CANopen runtime examples
config/capture_profiles/ Hardware-facing simulation and future bench capture profiles
config/hardware_targets/ Vendor-neutral future hardware target planning profiles
docs/                 Architecture, timing, safety-oriented design, tests, reports
examples/scenarios/   Deterministic controller scenario definitions
examples/replay/      Recorded process-image exchange fixtures
include/emrtc/        Public C++ interfaces
reports/              Sample generated validation artifacts
ports/freertos/       FreeRTOS cyclic-task integration and configuration
scripts/              Build, test, benchmark, and report generation helpers
src/                  C++ implementation
tests/                No-dependency unit/integration test runner

Build And Test

Requires CMake 3.20+ and a C++17 compiler.

scripts/build.ps1
scripts/test.ps1
scripts/benchmark.ps1 -Cycles 10000

Optional hardware-adapter integration flags are available for bench work:

cmake -S . -B build-soem -DEMRTC_ENABLE_SOEM=ON -DEMRTC_REQUIRE_SOEM=ON
cmake -S . -B build-etherlab -DEMRTC_ENABLE_ETHERLAB=ON
cmake -S . -B build-socketcan -DEMRTC_ENABLE_SOCKETCAN=ON
cmake -S . -B build-canopennode -DEMRTC_ENABLE_CANOPENNODE=ON

The SOEM path becomes dependency-backed when SOEM v2 is discoverable. The SocketCAN path uses Linux raw CAN sockets when Linux CAN headers are present. CI compiles both, tests SOEM against a pinned upstream commit, and exercises SocketCAN through an injectable transport. EtherLab and CANopenNode remain optional alternative integration points outside the required software-ready scope. None of these flags claim commissioned hardware behavior.

If Windows blocks local PowerShell scripts, run the same commands through a process-local bypass:

powershell -ExecutionPolicy Bypass -File scripts/build.ps1

One-command native validation:

scripts/run_all.ps1

Pinned portable Windows toolchain and validation:

scripts/install_portable_toolchain.ps1
scripts/run_all_portable.ps1

Portfolio demo walkthrough:

scripts/demo_portfolio.ps1 -BuildDir build -OutDir reports/generated/demo

Portfolio evidence bundle:

scripts/package_portfolio.ps1 -OutDir reports/generated/portfolio_bundle

Release gates:

python scripts/check_simulation_milestone.py
python scripts/check_software_ready_milestone.py

Evidence archive integrity check:

python scripts/validate_evidence_archive.py reports/generated/hardware/<run-directory> --require-complete

If CMake or a compiler is missing, use the pinned portable installer above or install a C++17 toolchain such as MSVC Build Tools, LLVM/Clang, or GCC/MinGW.

Use the local toolchain checker before a native build:

scripts/check_toolchain.ps1 -RequireCMake -RequireCompiler

Simulation And CLI

After building:

build\emrtc_sim.exe --cycles 2500 --out reports/generated
build\emrtc_benchmark.exe --cycles 10000 --out reports/generated
build\emrtc_cli.exe show status
build\emrtc_cli.exe show adapters
build\emrtc_cli.exe validate adapter-config config/adapters/soem_single_axis.example.json
build\emrtc_cli.exe validate adapter-config config/adapters/socketcan_canopen_single_axis.example.json
build\emrtc_cli.exe run scenario
build\emrtc_cli.exe run replay examples/replay/fault_recovery_exchange.csv
build\emrtc_cli.exe inject fault heartbeat_timeout
build\emrtc_cli.exe export report reports/generated

Sample Reports Without Native Toolchain

For review machines that do not yet have CMake/C++ installed:

python scripts/generate_report.py --out reports/generated
python scripts/generate_capture_manifest.py --profiles config/capture_profiles --out reports

The committed files under reports/ are deterministic sample artifacts. Native C++ validation should be rerun after installing the toolchain.

Key committed visuals include jitter, scenario matrix, control response, two-axis path/acceptance, and recovery-comparison plots under reports/.

Documentation Index

• Project Status
• Hardware Commissioning Remaining
• Software-Ready Milestone
• Portfolio Alignment
• Website Project Entry
• Recruiter One-Pager
• Portfolio Demo Walkthrough
• Graph-First Technical Article
• Preliminary BOM
• Commissioning Logbook Template
• Hardware Checkout Checklist
• Data Capture Profiles
• Hardware Target Profiles
• Hardware Evidence Archive
• Local Toolchain Setup
• Local Windows Validation
• Simulation-Complete Milestone
• Release Notes Template
• Changelog
• Bench Run Playbook
• Hardware Runbooks
• Hardware Adapter Integration Notes
• SOEM EtherCAT Backend
• Architecture Overview
• Timing Budget
• Control Loop Architecture
• Bus Map
• Drive State Machine
• Watchdog Design
• Fault Handling Matrix
• Test Plan
• Validation Report
• Benchmark Appendix
• Design Tradeoffs
• Hardware Integration Plan
• Final Software-Complete Report
• Demo Narratives