README- Vversion
MoonECAT
A modular EtherCAT master library written in MoonBit
ethercat
industrial
fieldbus
#MoonECAT
A modular EtherCAT master library written in MoonBit, targeting ETG.1500 Class B.
#Package Structure
| Package | Layer | Description |
|---|---|---|
| hal/ | Platform HAL | Network send/recv, timing, scheduling traits; FramePool/ZeroCopyNic |
| hal/mock/ | Platform HAL | Mock loopback, VirtualBus, RecordingNic, ReplayNic, FaultNic |
| hal/mcu/ | Platform HAL | MCU bare-metal HAL stubs (RZ/N2L, HPM6E00) |
| protocol/ | Protocol Core | Frame/PDU codec, ESM, PDO, zero-copy codec, addressing |
| mailbox/ | Mailbox & Config | CoE/SDO, SII/ESI parsing, FMMU/SM, RMSM, Emergency |
| runtime/ | Runtime | Scheduler, PDO loop, telemetry, monitors, verdicts, analysis engine |
| cmd/main/ | CLI | moonecat command-line interface |
| cmd/eni_json/ | Tool | ENI/ESI XML→JSON converter |
| plugin/extism/ | Plugin | Extism Wasm plugin skeleton |
| fixtures/ | Test Data | Shared test fixtures and sample frames |
#Quick Start
moon run cmd/main # Show CLI help
moon test # Run all tests
moon test hal/mock # Run mock HAL tests only
moon build --target native # Build native binaryMoonECAT no longer ships a native FFI backend package. --backend native*
commands now produce provider-harness pending output; live NIC access is owned
by the Isochronon fieldbus_core/moonecat_master_harness delivery path on top
of Lockwire native sessions.
#CLI Commands
MoonBit CLI flags belong to moon run, so MoonECAT parameters must be placed
after --, otherwise flags like --backend and --if will be consumed by
moon itself.
--backend native resolves to Windows Npcap when available, otherwise Linux Raw
Socket. Use native-windows-npcap or native-linux-raw for explicit control.
#Discovery
# Enumerate available network interfaces
moon run cmd/main list-if -- --backend native --json
# Force Windows Npcap / Linux Raw Socket enumeration
moon run cmd/main list-if -- --backend native-windows-npcap --json
moon run cmd/main list-if -- --backend native-linux-raw --json
# Scan slave topology
moon run cmd/main scan -- --backend native --if <interface>
moon run cmd/main scan -- --backend native --if <interface> --json#Configuration
# Validate online vs offline configuration
moon run cmd/main validate -- --backend native --if <interface> --eni-json config.json --json
# ESI XML→SII JSON projection
moon run cmd/main esi-sii -- --esi-json sample.esi.json --device-index 0 --json#Diagnostics
# Read slave SII/EEPROM
moon run cmd/main read-sii -- --backend native --if <interface> --position 0 --json
# Unified diagnostic surface
moon run cmd/main diagnosis -- --backend native --if <interface> --station 4097 --json
# Object dictionary browse (slave)
moon run cmd/main od -- --backend native --if <interface> --station 4097 --json
moon run cmd/main od -- --backend native --if <interface> --station 4097 --index 7187
moon run cmd/main od -- --backend native --if <interface> --station 4097 --index 6656 --subindex 1
# Master object dictionary
moon run cmd/main master-od -- --backend native --if <interface> --json
# ESC register dump
moon run cmd/main esc-regs -- --backend native --if <interface> --station 4097 --json
# Expected vs actual register comparison
moon run cmd/main expected-regs -- --backend native --if <interface> --station 4097 --json#Operation
# ESM state transition (bus-wide broadcast)
moon run cmd/main state -- --backend native --if <interface> --state safeop
# Per-slave confirmed state transition with stepwise path
moon run cmd/main state -- --backend native --if <interface> --state op --station 4097 --path
# Cyclic PDO exchange
moon run cmd/main run -- --backend native --if <interface> --cycles 1000
moon run cmd/main run -- --backend native --if <interface> --startup-state safeop --shutdown-state none
moon run cmd/main run -- --backend native --if <interface> --until-fault --json --progress-ndjson --output-period-ms 1000
# Zero-copy PDO exchange (FramePool + MutableProcessImage)
moon run cmd/main run-zc -- --backend mock --cycles 1000 --json
moon run cmd/main run-zc -- --backend native --if <interface> --cycles 1000 --pool-capacity 32 --json
# Virtual slave bus from ESI JSON (offline simulation)
moon run cmd/main run-virtual -- --esi-json sample.esi.json --cycles 1000 --json
# Startup sequence tracing
moon run cmd/main startup-trace -- --backend native --if <interface> --station 4097 --esi-json sample.esi.json --device-index 0 --json
# Startup diff analysis
moon run cmd/main startup-diff -- --backend native --if <interface> --station 4097 --esi-json sample.esi.json --device-index 0 --json
# Mailbox resilient layer validation
moon run cmd/main mailbox-readback -- --backend native --if <interface> --station 4097 --esi-json sample.esi.json --device-index 0 --json#Verification
# Replay from NDJSON trace file and output verdict
moon run cmd/main replay -- --trace session.ndjson --json
# Execute composite verification scenario
moon run cmd/main scenario -- --scenario basic-timeout --cycles 200 --json#Analysis Engine
# DC jitter profiling
moon run cmd/main jitter-profile -- --trace session.ndjson --period-ns 1000000 --json
# PDO auto-tuning (online parameter identification)
moon run cmd/main auto-tune -- --strategy balanced --json
# Topology health analysis
moon run cmd/main topo-health -- --trace session.ndjson --json
# Cycle performance statistics
moon run cmd/main cycle-perf -- --trace session.ndjson --period-ns 1000000 --json
# Communication quality scoring
moon run cmd/main comm-quality -- --trace session.ndjson --json#ENI/ESI XML Converter
# Convert ENI XML to JSON
moon run cmd/eni_json -- --input config.xml --output config.json
# Convert ESI XML to JSON
moon run cmd/eni_json -- --input References/sample.xml --kind esi --output sample.esi.json#Common Parameters
| Parameter | Description | Applies to |
|---|---|---|
| --backend <name> | mock, native, native-windows-npcap, native-linux-raw | All |
| --if <interface> | Network interface name | Native commands |
| --json | Structured JSON output | All |
| --timeout-ms <n> | Command timeout in milliseconds | All |
| --station <addr> | Target slave configured address | Per-slave commands |
| --position <n> | Target slave link position (0-based) | read-sii |
| --cycles <n> | PDO cycle count | run, run-zc, scenario |
| --until-fault | Run until fault detected | run |
| --progress-ndjson | Stream NDJSON progress events | run |
| --startup-state <s> | Startup target ESM state | run, run-zc, replay |
| --shutdown-state <s> | Shutdown target or none | run, run-zc, replay |
| --cycle-period-us <n> | Override cycle period (microseconds) | run |
| --output-period-ms <n> | NDJSON progress output interval | run |
| --pool-capacity <n> | Zero-copy frame pool capacity | run-zc |
| --trace <path> | NDJSON trace file path | replay, jitter-profile, topo-health, cycle-perf, comm-quality |
| --scenario <name> | Scenario name | scenario |
| --strategy <name> | balanced, conservative, aggressive | auto-tune |
| --period-ns <n> | Analysis period (nanoseconds) | jitter-profile, cycle-perf |
| --esi-json <path> | ESI JSON file for enrichment | state, run, startup-*, mailbox-readback |
| --path | Use stepwise state transition path | state |
#Key Features
- Multi-backend architecture: Mock loopback, Windows Npcap, Linux Raw Socket
- Full ESM lifecycle: Init → PreOp → SafeOp → Op with per-slave confirmed transitions
- CoE/SDO: Upload/download, segmented transfer, complete access, SDO Info Service
- SII/EEPROM: Full ETG.2010 category deep-read framework
- Zero-copy PDO: FramePool + MutableProcessImage for hot-path allocation elimination
- Event sourcing: RecordingNic → ReplayNic deterministic replay
- Fault injection: 7 fault types × 5 schedules via FaultNic
- Monitor/Verdict: Pass/Warn/Fail/Block verdicts with composable monitor registry
- Analysis engine: DC jitter profiling, PDO auto-tuning, topology health, cycle perf, comm quality scoring
- Distributed Clock: SYNC0 configuration + FRMW drift compensation + propagation delay
- ENI/ESI tooling: XML→JSON converter with unified configuration model
- VirtualBus: Multi-slave protocol-level simulation with SDO/Emergency emulation
- VirtualSlaveTemplate: ESI JSON → synthesized EEPROM → VirtualSlave pipeline
#Documentation
| Document | Description |
|---|---|
| docs/ARCHITECTURE.md | Architecture guide, data flow, testing strategy |
| docs/BACKEND_RELEASE_MATRIX.md | Release boundaries + environment requirements |
| docs/NATIVE_FFI_SAFETY.md | FFI handle lifetime + sanitizer guidance |
| docs/NATIVE_REAL_STATE_TRANSITION_DESIGN.md | Npcap ESM transition design |
| docs/ZERO_COPY_HAL_DESIGN.md | Zero-copy FramePool + ZeroCopyNic design |
| docs/SII_FULL_READ_DESIGN.md | SII deep-read category framework |
| docs/EXTISM_HOST_BOUNDARY.md | Extism plugin host boundary |
| project_workflow/ | Integrated roadmap + backlog (L1-L4, P0-P2) |
LGPL-3.0
Updated 3 months ago
64 downloads