NeoECU-Hardware/Architecture/IO_ARCHITECTURE.md

# NeoECU V1 Initial Functional I/O Architecture

## Purpose

This document records the initial functional I/O architecture for NeoECU V1.
It builds on [the power architecture](POWER_ARCHITECTURE.md) and defines the
required interface classes, analogue-channel allocation, and intended signal
conditioning. It is not a schematic or component-selection document; exact
parts, resistor values, pin assignments, connector allocation, and final I/O
quantities remain to be confirmed.

The initial ECU controls a single-cylinder four-stroke engine with one
injector, one dual-ended dumb ignition coil, crank and cam Hall sensors,
temperature and pressure sensors, and an external starter switch.

## I/O Summary

| Interface | V1 allocation | Functional intent |
| --- | ---: | --- |
| Crank trigger input | 1 | 12 V active-low Hall, timer capture |
| Cam trigger input | 1 | 12 V active-low Hall, timer capture |
| Deadman inputs | 2 | Dedicated, independent 5 V vehicle-logic engine-permit inputs |
| Thermistor inputs | 4 | Air, oil, water, and one spare temperature input |
| General analogue inputs | 9 | Protected 0-5 V sensor channels |
| ADC rail-monitor channels | 3 | `VBAT_PROT`, `+5V_SENS`, and `+12V_SENS` |
| Ignition output | 1 | Dedicated coil low-side driver |
| Injector output | 1 | Dedicated injector low-side driver |
| Generic digital inputs | Provisionally 6 | Protected 5 V / 12 V compatible inputs |
| Generic logic outputs | Provisionally 4 | Protected 5 V logic outputs |
| Generic sink outputs | Provisionally 4 | Protected low-side outputs |
| Analogue outputs | Reserve 2 MCU/output paths | Future 0-5 V output capability; not a V1 requirement |

The provisional generic digital I/O counts are planning values, not a frozen
connector or pin budget. CAN and its physical layer are intentionally outside
the scope of this document.

## Power-Domain Rules

- `+5V_MAIN` is the primary internal regulated 5 V rail. It supplies internal
  5 V circuitry and is the upstream rail for `+5V_AUX` and `+5V_SENS`; it is
  not connected directly to external harness loads.
- `+5V_SENS` is exclusively for sensor excitation and thermistor pull-ups.
  It is never used to power generic peripherals or output loads.
- `+5V_AUX` powers external 5 V logic-level output circuitry. It is separately
  protected so an external fault cannot disturb sensor excitation.
- `+12V_SENS` is the regulated buck-boost Hall/12 V sensor supply. It is kept
  separate from arbitrary digital output loads.
- `VBAT_PROT` supplies the ignition, injector, and protected low-side output
  branches. It is the 12 V-class source for general load-driving interfaces.
- High-current ignition, injector, and load-driver returns remain separate
  from the sensor and MCU returns until their deliberate join at the power
  entry region.

## Engine-Position Inputs

Crank and cam are dedicated timer-capture inputs, not generic digital inputs.
The V1 timing pattern remains two crank pulses per revolution and one cam pulse
per 720-degree cycle. Their interface, harness/shield termination, protection,
conditioning, and hardware/firmware glitch-rejection requirements are defined
in [ENGINE_POSITION_INPUTS.md](IO_MODULES/ENGINE_POSITION_INPUTS.md).

## Analogue Inputs

### ADC allocation

The STM32H747 provides three ADC peripherals. ADC1 and ADC2 share most of the
external analogue-pin pool, so they increase concurrent conversion capacity
rather than doubling the number of physical sensor pins. The proposed V1
allocation occupies 16 conditioned ADC channels:

```text
4 thermistor inputs
9 general 0-5 V inputs
1 VBAT_PROT sense input
1 +5V_SENS sense input
1 +12V_SENS sense input
```

This leaves meaningful MCU ADC and pin margin, but the final STM32 package and
pin assignment must reserve all analogue pins alongside timer, CAN, debug,
I2C, and optional DAC requirements. In particular, PA4 and PA5 should remain
available if the two internal DAC outputs are to be retained for future
analogue outputs.

### Thermistor channels

Each thermistor channel is excited from `+5V_SENS` using a precision pull-up.
The input is attenuated and filtered before the ADC; this remains required
because an open thermistor drives the node towards 5 V. Firmware calculates the
thermistor resistance from the ratio of its ADC result to the `+5V_SENS` ADC
result, then applies the calibration map for the selected sensor.

```text
+5V_SENS -- precision pull-up --+-- thermistor -- sensor ground
                                 |
                              attenuation/filter --> ADC
```

The pull-up value is selected from the actual NTC curve and required
temperature range, balancing resolution against self-heating. The attenuation
network should be high impedance enough that it does not materially load the
thermistor divider; the ADC sample time and local input capacitor must then be
chosen to achieve settling. The initial Bosch 2.5 kOhm NTC population is a
3.01 kOhm precision pull-up; 10.0 kOhm and 30.1 kOhm alternatives are reserved
only for confirmed sensor curves. See
[ANALOG_INPUTS.md](IO_MODULES/ANALOG_INPUTS.md) for the detailed architecture.

### General 0-5 V channels

General analogue inputs support conventional 0.5-4.5 V and 0-5 V automotive
sensors. Each includes connector protection, attenuation, and an ADC-local
filter capacitor. A nominal attenuation ratio near 0.55 maps a 5.25 V sensor
signal to about 2.9 V at an ADC referenced by `+3V3_ANA`.

General analogue inputs are passive. Their dividers, filter capacitors, and ADC
acquisition time must be selected together to meet source-impedance and
settling requirements. A genuinely high-impedance or special-purpose sensor
requires a dedicated front end rather than altering the generic channel.

`+5V_SENS` is measured through an equivalent matched divider/filter path and
sampled near each ratiometric sensor channel. Firmware uses the ratio of the
sensor and supply readings to cancel sensor-supply and ADC-reference variation.

## Battery and Rail Measurements

`VBAT_PROT` is measured by a protected, scaled direct ADC channel. This is the
deterministic engine-control measurement used for battery-voltage dwell and
injector compensation. The M7 should receive a DMA-updated, filtered value and
snapshot it immediately before scheduling a dwell event.

Voltage/current monitor ICs may monitor the regulated rails for telemetry and
diagnostics. They are not the sole engine-control voltage source. In
particular, no whole-ECU current shunt is placed in series with `VBAT_PROT`;
coil and injector pulse currents would waste power and make that measurement
less useful. Upstream protection is provided by the input fuse/e-fuse and
local protection is provided by the ignition and injector driver stages.

## Generic Digital Inputs

Generic digital inputs accept externally driven 5 V through `VBAT_PROT`
active-high signals, with software-configurable reported polarity. They are
not intended for crank or cam capture. The detailed interface, including
fail-safe ECU-off behavior, external hysteresis, optional wetting/pull-down
footprints, and harness protection, is defined in
[DIGITAL_INPUTS.md](IO_MODULES/DIGITAL_INPUTS.md).

The generic input front end uses fail-safe, 40 V-capable open-drain
comparators powered by `+3V3_MAIN`, with thresholds derived from `+5V_MAIN`.
The input is protected at the connector and cannot back-power the ECU when an
external source drives it while the ECU is unpowered. The final transient
protection, threshold, hysteresis, filter, and bias values remain pending the
actual harness and input-function requirements.

## Deadman Engine-Permit Interlock

The deadman uses two dedicated 5 V vehicle-logic inputs, not generic digital
inputs. The steering-wheel switch provides two electrically independent,
normally-open contacts. Each contact has its own connector pin, protection,
filtering, default-low bias, and conditioned logic path. This makes an open
circuit or a short to the 5 V source on one signal path non-permissive.

The resulting 5 V `DEADMAN_OK` signal is high only when channel A reports
held and the independently conditioned, inverted channel B reports not
released. It has two independent destinations:

- `DEADMAN_A_STATUS` and `DEADMAN_B_STATUS` enter MCU digital inputs so
  firmware can observe each contact, detect disagreement, disable scheduling,
  and report the state.
- `DEADMAN_OK` is combined in hardware with the MCU's `MCU_RUN_PERMIT` output
  to produce `ENGINE_PERMIT`.

```text
deadman contact A --> protected input --> DEADMAN_A_HELD --------+
                                                                  +--> valid-state logic --> DEADMAN_OK --+
deadman contact B --> protected input --> inverted --> DEADMAN_B_RELEASED -+                              |
                                                                                                            AND --> ENGINE_PERMIT
MCU_RUN_PERMIT ----------------------------------------------------------------------------------------------+
```

`ENGINE_PERMIT` controls the enable inputs of the injector and ignition drivers
where those inputs are provided. If a selected driver has no suitable enable
input, `ENGINE_PERMIT` is ANDed with that driver's MCU command signal using
logic that defaults to the disabled state on power-up or loss of power.

This hardware path ensures that releasing the deadman, an open circuit, or a
single signal-path short to the 5 V source stops injector and ignition commands
even if firmware or a timer output fails to respond. It does not claim to cover
a common-mode fault that energises both paths. Firmware must clear/disable
pending injection and dwell schedules whenever `DEADMAN_OK` becomes invalid or
the two MCU status inputs disagree. A firmware test mode may assert
`MCU_RUN_PERMIT`, but it does not override the physical deadman inputs; bench
operation requires a deliberate external test arrangement that presents the
valid two-channel held state. The detailed signal and fault model is defined in
[DEAD_MAN.md](IO_MODULES/DEAD_MAN.md).

## Outputs

### Ignition and injector

The ignition coil is supplied from `VBAT_PROT` and switched with a dedicated
automotive ignition driver or smart ignition IGBT. It requires controlled
primary flyback clamping, over-current and thermal protection, and fault
reporting. Firmware applies battery-voltage dwell compensation using the direct
`VBAT_PROT` ADC measurement; driver current limiting remains the safety
backstop.

The injector is supplied from `VBAT_PROT` and switched by a dedicated
automotive smart low-side driver. It requires inductive-load capability,
controlled turn-off clamping, current/thermal protection, and MCU-readable
open-load and short-circuit diagnostics. This assumes a conventional
high-impedance/saturated injector; a low-impedance injector requires a
peak-and-hold architecture.

### Generic digital outputs

All non-engine digital output connector functions are labelled generically and
assigned their vehicle role in firmware. For example, the starter-enable
function is mapped to a compatible generic output rather than having a
dedicated connector-only electrical architecture.

Two hardware classes remain necessary. Their selected architecture, default
state, diagnostic intent, connector protection, and remaining validation are
defined in [DIGITAL_OUTPUTS.md](IO_MODULES/DIGITAL_OUTPUTS.md).

- Generic logic outputs use `+5V_AUX`-supplied `TPS4H000-Q1` protected
  high-side channels with a local output pull-down. They command external
  electronic-control inputs and are limited to 100 mA per channel.
- Generic sink outputs use `VBAT_PROT`-supplied `TLE9104SH` protected low-side
  channels. They command relays, solenoids, and external modules that provide
  a pull-up.

Firmware configuration selects the output's vehicle role and active polarity,
but cannot make one electrical driver class behave as the other. A starter
enable can therefore use either a generic logic output or a generic sink output
only when the selected external starter switch accepts that interface.

### Analogue-output provision

Analogue output is not a V1 functional requirement. Reserve two MCU pins and
board footprints for future 0-5 V outputs. The intended future path is:

```text
DAC --> rail-to-rail buffer --> protection / series impedance --> connector
```

A true calibrated 0-5 V output may require an external 5 V-referenced DAC or
a suitably characterised buffer stage. A general 0-12 V analogue output is not
included unless a future peripheral explicitly requires it.

## Layout and Validation Priorities

- Keep trigger and ADC front ends physically separated from coil, injector,
  switching-regulator, and high-current output nodes.
- Place protection at the connector, filtering/conditioning near the MCU side,
  and avoid dumping input-fault energy into `+3V3_ANA`.
- Validate Hall glitch rejection with ignition active, including worst-case
  dwell and spark events.
- Validate ADC noise, ratiometric accuracy, thermistor self-heating, and ADC
  settling before freezing resistor networks or deciding whether the optional
  analogue LDO is necessary.

## Open Items Before Schematic Freeze

1. Select Hall and thermistor part numbers, cable lengths, connectors, and
   resulting pull-up/filter values.
2. Confirm ignition-coil and injector electrical data and select their driver
   devices.
3. Freeze the generic digital I/O count, per-channel current ratings, and
   connector allocation.
4. Select 5 V-tolerant, automotive-suitable comparators and input-protection
   components for generic digital inputs.
5. Select the STM32H747 package and complete a pin assignment that preserves
   all timer, ADC, optional DAC, debug, and communications resources.
6. Define CAN and other communications interfaces separately.