NeoECU-Firmware/docs/ARCHITECTURE.md

NeoECU Target Architecture

NeoECU uses an AMP layout. The CM7 side owns deterministic engine control; the secondary core is reserved for non-critical work and is outside the scope of this document.

This document describes the target CM7 architecture. Current development-board details and temporary implementation notes live in DEVELOPMENT_SETUP.md.

CM7 Role

CM7 is responsible for:

• capturing crank and cam timing edges with low jitter
• maintaining engine phase synchronization
• deriving the current four-stroke cycle position
• scheduling time-critical spark and injection transitions
• keeping interrupt paths short and deterministic

The engine-control path should stay small, explicit, and timer-driven.

Runtime Flow

The target runtime model is:

1. A hardware timer captures crank and cam edges.
2. The input-capture callback stores each timestamp.
3. The callback wakes the task that owns that signal.
4. The task validates the event, updates engine state, and computes future actions.
5. Output-compare events apply scheduled actuator transitions.

Interrupt context owns timestamp capture and exact compare-time transitions. Task context owns filtering, state progression, synchronization, and scheduling decisions.

Sensors

Crank

The crank signal is the primary timing source.

• One crank pulse represents 180 engine degrees.
• Consecutive crank intervals estimate current engine speed.
• Crank timing drives phase progression and scheduled outputs.

Cam

The cam signal is the phase reference.

• One cam pulse represents the 720 degree four-stroke cycle.
• Cam timing is used to establish and recover cycle synchronization.
• Unexpected or missing cam events reduce or clear phase confidence.

Shared State

The target model uses one compact shared engine state object. It contains:

• synchronization state
• crank cycle state
• cam event state
• cam miss tolerance
• recent crank and cam timestamp history
• scheduled spark state

State shared between ISR and task context must be explicit. If a value crosses that boundary, its ownership and meaning should be clear from the surrounding code.

Synchronization

Synchronization has three states:

• SYNC_NOT_OK: phase is not trusted
• SYNC_PENDING: cam has been observed, but phase is not confirmed
• SYNC_OK: crank/cam relationship is trusted

Target progression:

1. Boot starts unsynchronized.
2. A cam event moves the system to pending sync.
3. The expected crank/cam phase relationship promotes sync to OK.
4. Missing or unexpected cam behavior drops sync back toward unknown phase.

When synchronized, crank pulses advance through:

1. CYCLE_COMBUSTION
2. CYCLE_EXHAUST
3. CYCLE_INTAKE
4. CYCLE_COMPRESSION

When unsynchronized, the crank state remains unknown until cam-assisted phase alignment restores confidence.

Timing and Scheduling

Scheduled outputs are derived from recent crank timing.

The target scheduler should:

• compute future compare times from measured crank intervals
• arm hardware compare events instead of busy waiting
• keep actuator transitions in compare callbacks short and deterministic
• keep scheduling decisions near the sensor logic that drives them

Spark and injection should both follow this pattern:

1. The crank task computes the next transition time.
2. The timer compare channel is armed.
3. The compare callback applies the transition.
4. Follow-up transitions are scheduled by task logic.

Core Modules

The intended CM7 module boundaries are:

• main.c: boot, peripheral initialization, HAL callbacks, task creation
• tasks/crank.c: crank validation, cycle progression, output scheduling
• tasks/cam.c: cam validation and sync promotion
• global_state.h: shared state, enums, timing constants
• ring_buffer.*: timestamp history

Open Target Work

The current target architecture still needs final decisions or validation for:

• complete injection scheduling
• final spark dwell-time handling
• production crank/cam phase validation
• sync-loss and recovery thresholds
• final hardware pin and timer routing