NeoECU-Hardware/Architecture/IO_MODULES/DIGITAL_INPUTS.md

# General-Purpose Digital Input Module

## Purpose

This module defines the generic harness-connected digital-input class for
NeoECU V1. It accepts externally driven 5 V, 12 V, and protected
battery-domain signals, plus dry-contact and open-collector sources when the
appropriate ECU bias option is fitted.

This is not the crank/cam trigger interface and is not the dedicated deadman
engine-permit input. Those functions retain their dedicated conditioning and,
for the deadman, its single-input hardware permission path defined in
[DEAD_MAN.md](DEAD_MAN.md).

V1 provisionally allocates six generic digital-input channels. The allocation,
connector pins, input timing requirements, and final input count remain open.

## Interface and operating assumptions

- Valid externally driven high inputs extend from 5 V through `VBAT_PROT`.
  Firmware configures the reported active polarity; the electrical front end
  is active-high.
- An external source may drive an input while the ECU is unpowered. This must
  not back-power `+3V3_MAIN`, `+5V_MAIN`, `+5V_AUX`, or `VBAT_PROT`.
- `+5V_AUX` may provide optional low-current wetting for a dry contact or
  open-collector output. It is not a general sensor-supply rail and
  `+5V_SENS` shall not be used for this purpose.
- Each channel's maximum switching rate and permitted debounce delay are
  application-dependent. These requirements shall be assigned before the RC
  values are frozen.

## Comparator architecture

Use the fail-safe, automotive-qualified TI `TLV186x-Q1` open-drain comparator
family. Its inputs are high impedance up to 40 V even while its supply is
unpowered, so a battery-domain input cannot inject current into the ECU logic
rails during normal operation, power sequencing, or an ECU-off condition.

The provisional six-channel implementation is one `TLV1864-Q1` quad and one
`TLV1862-Q1` dual. This is an architectural component selection; package,
availability, and final channel count still require schematic-stage
confirmation.

Each comparator is operated in the inverting hysteresis configuration:

`DIG_INx` passes through the protected input network and configurable `R_IN` /
`C_FILTER` stage to the comparator's `IN−` input. `IN+` is the `VTH` node:
`R_REF_H` connects it to `+5V_MAIN`, `R_REF_L` connects it to protected ground,
and `R_HYS` connects it to `DIG_IN_LOGIC` for positive feedback. The
open-drain comparator output is pulled up to `+3V3_MAIN` by `R_PULLUP` and
then connects to the MCU GPIO.

`DIG_IN_LOGIC` is pulled to `+3V3_MAIN` and connects to one STM32 GPIO. The
logic is inverted at this point: a harness voltage above the upper threshold
pulls the comparator output low. Firmware may invert the reported input
polarity, but it does not alter the physical thresholds or protection.

`R_HYS` feeds a controlled fraction of the 3.3 V output state into `VTH`.
When the output is high, the threshold is higher; the input must cross this
upper threshold to pull the output low. Once low, the feedback contribution is
removed and the input must fall through the lower threshold before the output
releases again. This is true hysteresis, not firmware debounce.

The reference-divider ratio, `R_HYS`, output pull-up, and their tolerances
shall be calculated together. The design shall establish thresholds in real
harness volts with sufficient margin for all of the following:

- the lowest valid 5 V external source;
- the lowest `+5V_AUX` voltage and forward drop of the optional wetting diode;
- comparator input offset and leakage over temperature;
- resistor tolerance; and
- expected harness noise.

An initial design objective is an upper threshold in the 2.8--3.2 V range and
a lower threshold in the 1.8--2.2 V range. These are design targets, not
schematic values. They shall be confirmed against the final input definitions
and chosen comparator output-pull-up value.

TI's worked example of this topology is [Inverting Comparator With Hysteresis
Circuit](https://www.ti.com/tool/CIRCUIT060076). The selected comparator's
fail-safe input and output requirements are defined in the [TLV185x-Q1 and
TLV186x-Q1 datasheet](https://www.ti.com/lit/ds/symlink/tlv1861-q1.pdf).

## Optional input biasing

Provide unpopulated per-channel footprints for the following mutually
exclusive options. Through-hole resistor positions are acceptable where
field-level reconfiguration is valuable; DNP SMD positions and solder-jumper
selection are also acceptable when production configuration is known.

At the connector node (`DIG_IN_RAW`), fit the harness TVS before `R_IN`.
`C_FILTER` and the local negative clamp are on the protected `SENSE` side of
`R_IN`. The optional wetting branch is `+5V_AUX` → `R_WET` → `D_WET` →
`DIG_IN_RAW`; the diode cathode faces `DIG_IN_RAW`. `R_PD`, when fitted,
connects `DIG_IN_RAW` to protected ground.

- `R_WET` and `D_WET` form the optional wetting pull-up. `D_WET` has its
  anode toward `+5V_AUX` and cathode toward the input. It prevents a 12 V or
  battery-domain external source from back-feeding `+5V_AUX`.
- `R_PD` is an optional weak pull-down to the protected logic ground.
- With neither component fitted, the channel is intended for an externally
  driven logic signal.
- Do not fit both bias components by default. The required mode is selected
  per channel from the connected vehicle function.

The MCU's internal pull resistors are not a substitute for these footprints:
they act only on the post-comparator 3.3 V GPIO and cannot define or wet the
harness-connected input.

## Harness protection and filtering

The comparator's 40 V fail-safe input capability eliminates power-backfeed
through the comparator; it does not replace harness fault protection. Every
channel shall include the following protection functions:

- **Primary positive clamp:** use a connector-side TVS or equivalent
  protection element. Its working standoff shall exceed the 16.8 V maximum
  normal battery input. Its worst-case dynamic clamp voltage, including
  tolerance, temperature, source impedance, and the specified pulse current,
  shall remain below the comparator's 40 V input capability with design
  margin. A nominal device label such as "20 V" or "24 V" is not sufficient
  evidence of this requirement.
- **Negative clamp:** provide a local low-capacitance clamp path that prevents
  the comparator input from going below its allowed negative input voltage.
  The clamp returns to the protected logic-ground reference, not to a positive
  ECU rail.
- **Series resistance:** `R_IN` limits fault and clamp current, isolates the
  filter capacitor from fast harness events, and shall have adequate pulse
  voltage, power, and surge rating. Split series resistors may be used to
  share voltage stress.
- **RC filtering:** `R_IN` and `C_FILTER` suppress short edge noise. Reserve
  configurable capacitor footprints so the final time constant can support
  both electronic inputs and contact-debounce applications. Hysteresis, not
  an excessively slow RC, provides the primary threshold-noise immunity.
- **Component placement:** place the primary transient protection at the
  connector entry. Keep the comparator-side clamp, filter, reference network,
  and comparator close together and away from ignition, injector, and
  regulator hot loops.

The selected protection network must also be verified for an ECU-off,
externally driven input. The `TLV186x-Q1` input itself remains high impedance
in that state; the completed TVS, clamp, bias, and capacitor network must
likewise have no path that back-powers an ECU rail.

## Power sequencing and output behavior

The comparator and GPIO pull-up use `+3V3_MAIN`. `VTH` is derived from
`+5V_MAIN`; both comparator inputs are fail-safe beyond the comparator supply,
so the reference network does not require an input clamp merely because of a
normal rail sequencing difference.

The open-drain output is allowed to be pulled to `+3V3_MAIN`; no output clamp
to `VBAT_PROT` is required. When `+3V3_MAIN` is absent, the input front end is
protected but neither the comparator output nor the MCU can report an input
state. This is the intended ECU-off behavior.

## Fault behavior

| Condition | Required hardware behavior |
| --- | --- |
| Input open, wetting pull-up fitted | Read as high at the electrical front end. |
| Input grounded, wetting pull-up fitted | Read as low; `R_WET` limits current. |
| Input open, pull-down fitted | Read as low. |
| Valid external 5 V, 12 V, or `VBAT_PROT` drive | Cross the upper threshold with specified margin. |
| External drive while ECU off | No comparator-input back-power path; no reported state until ECU logic is powered. |
| Positive harness transient | Primary clamp and `R_IN` keep the comparator input within its validated limit. |
| Negative harness transient | Local negative clamp and `R_IN` keep the comparator input within its validated limit. |
| `+5V_AUX` shorted or absent | Wetting function is unavailable; it shall not damage or force a battery-domain input high. |

## Validation and open items before schematic freeze

1. Confirm the six-channel count, connector allocation, and maximum event
   rate/debounce requirement for every generic input.
2. Define the harness source types and fault/transient environment, including
   externally powered inputs while the ECU is off.
3. Select and validate the TVS, local negative clamp, `R_IN`, and capacitor
   voltage/pulse ratings from that environment. Verify the actual clamp
   voltage at the comparator pin, not only the nominal clamp designation.
4. Calculate the upper and lower thresholds with worst-case rail voltages,
   diode drop, output levels, resistor tolerance, comparator offset, leakage,
   and temperature.
5. Select the final wetting and pull-down resistor values, assembly method,
   and per-channel default population.
6. Validate noise immunity, contact bounce, ECU-off drive, ESD, and
   ignition/injector switching noise on hardware before freezing values.