Initial CAN Physical Layer spec

Architecture/IO_ARCHITECTURE.md

@@ -31,8 +31,9 @@ temperature and pressure sensors, and an external starter switch.
 | 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
+connector or pin budget. CAN is defined separately in
-the scope of this document.
+[CAN_PHYSICAL_LAYER.md](IO_MODULES/CAN_PHYSICAL_LAYER.md); its final connector
+pin allocation remains part of the overall STM32 and harness pin budget.
 
 ## Power-Domain Rules
 
@@ -259,4 +260,6 @@ included unless a future peripheral explicitly requires it.
    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.
+6. Complete the CAN connector and STM32 pin allocation defined in
+   [CAN_PHYSICAL_LAYER.md](IO_MODULES/CAN_PHYSICAL_LAYER.md), alongside any
+   other required communications interfaces.

Architecture/IO_MODULES/CAN_PHYSICAL_LAYER.md

@@ -0,0 +1,191 @@
+# CAN Physical Layer
+
+## Purpose
+
+This module defines the NeoECU V1 physical interface to the vehicle CAN FD
+network. It covers the MCU interface, transceiver, harness topology,
+termination, protection, grounding, layout, and required fault behaviour. It
+does not define CAN identifiers, payloads, or firmware scheduling.
+
+CAN is a telemetry and auxiliary-communications interface. It is not part of
+the hardware engine-permit path: loss, overload, or bus-off of CAN shall never
+remove or assert engine permission.
+
+This is a schematic-design basis, not a released schematic. Final connector
+part numbers, MCU pins, protection component values, and validated harness
+details remain to be confirmed.
+
+## V1 network definition
+
+| Item | V1 decision |
+| --- | --- |
+| Protocol | ISO 11898-2 high-speed CAN FD, with Classical CAN frames also supported |
+| Nominal/arbitration bit rate | 500 kbit/s |
+| CAN FD data-phase bit rate | 2 Mbit/s |
+| External buses implemented | One vehicle CAN bus |
+| Expected nodes | ECU plus one or two vehicle nodes; a debug tool may join through a service connector |
+| Harness extent | Approximately 2--2.5 m end-to-end |
+| ECU position | Mid-bus node, not a physical endpoint |
+| Harness | 120 ohm nominal twisted pair for `CAN_H` and `CAN_L` |
+| Shield | Not required initially; assess only if the final route must run near ignition or other demonstrated high-noise wiring |
+
+All V1 nodes connected to this bus shall support CAN FD at the configured
+rates. A Classical-CAN-only node cannot join a CAN FD network that transmits
+FD frames.
+
+## STM32H747 interface and ownership
+
+The STM32H747 provides two independent CAN FD controllers, `FDCAN1` and
+`FDCAN2`, with shared message RAM. V1 implements only the one external vehicle
+bus on `FDCAN1`. `FDCAN2` remains available for a future separate network; it
+does not imply a second physical bus or a second transceiver in V1.
+
+The Cortex-M4 is the intended owner of CAN telemetry and auxiliary
+communications. The Cortex-M7 retains deterministic engine control. Firmware
+shall define the inter-core message and fault-reporting boundary before either
+core accesses FDCAN resources; neither core may independently initialise or
+reconfigure a live controller.
+
+`PA11` and `PA12` are reserved for the USB-C USB-FS D-/D+ path used by the
+STM32 system-memory DFU recovery route. They shall not be assigned to
+`FDCAN1_RX` or `FDCAN1_TX`. The final `FDCAN1` pin pair shall be selected as
+part of the complete STM32 package and pin allocation, preserving timer, ADC,
+debug, and required serial interfaces. Candidate pairs include `PB8/PB9` and
+`PD0/PD1` where available in the selected package.
+
+The board shall retain accessible `BOOT0`, `NRST`, and SWD/J-Link provisions.
+USB DFU is a recovery path, not a replacement for normal SWD debugging.
+
+## Transceiver and local interface
+
+Use the automotive-qualified **TI TCAN1044AV-Q1** CAN FD transceiver family.
+Select the exact package and orderable suffix at PCB-layout and procurement
+time; the electrical requirements in this module apply to the selected member.
+
+| Transceiver connection | Required implementation |
+| --- | --- |
+| `VCC` | Supply from the protected 5 V logic rail, with the local decoupling specified by the selected-device datasheet. |
+| `VIO` | Supply from `+3V3_MAIN` so `TXD`, `RXD`, and mode logic interface directly to STM32 GPIO. |
+| `TXD` / `RXD` | Connect to the selected `FDCAN1_TX` / `FDCAN1_RX` GPIO alternate functions. The ECU shall drive recessive when it is not intentionally transmitting. |
+| `STB` | Connect to an MCU GPIO and pull externally high to `+3V3_MAIN`. The transceiver therefore defaults to standby while the MCU is reset, booting, or unpowered; firmware drives it low only after it is healthy and has configured FDCAN. |
+| CAN wake capability | Retain the `STB`/`RXD` hardware capability, but V1 has no requirement for an incoming CAN frame to wake a sleeping ECU. |
+| `CANH` / `CANL` | Route only through the defined protection/EMC network to the vehicle-I/O/CAN connector. |
+
+The TCAN1044AV-Q1 uses the 5 V rail for its bus driver and `VIO` for its 3.3 V
+logic interface. Its high-impedance unpowered behaviour is required so an
+unpowered ECU does not load a live vehicle bus. Galvanic isolation is not part
+of V1: all vehicle nodes require a defined common circuit reference.
+
+## Topology, termination, and service access
+
+The vehicle wiring shall be one continuous linear trunk, with a physical bus
+endpoint at the rear and another at the front:
+
+![Vehicle CAN FD trunk with two terminated endpoints, a mid-bus ECU, and a short unterminated service connection](../diagrams/can-topology.svg)
+
+[Editable diagram](../diagrams/can-topology.drawio) · [PNG preview](../diagrams/can-topology.png)
+
+The two segments shown above are trunk segments, not long stubs. The ECU
+transceiver joins the trunk locally on the PCB. Do not make the ECU a 0.5--1 m
+branch from a separate harness junction.
+
+Fit one 120 ohm, 1 %, normally-open termination option across the ECU `CAN_H`
+and `CAN_L` pins, controlled by a clearly labelled solder jumper. It is
+populated only when the ECU is a physical endpoint. The two actual endpoints
+of the installed bus each require one 120 ohm terminator; the intended
+effective resistance measured across a de-energised, correctly terminated bus
+is approximately 60 ohm.
+
+The debug/service connector joins the same bus and shall expose `CAN_H`,
+`CAN_L`, and `CAN_0V`. It shall not fit termination. Keep the on-board service
+branch very short and avoid a permanently attached, long unterminated service
+cable. A connected debug tool counts as a CAN node and must support the V1
+CAN FD rates.
+
+## Harness reference and shielding
+
+`CAN_H` and `CAN_L` shall be one dedicated twisted pair. A shared vehicle
+circuit return must provide a controlled common-mode reference between every
+node. Expose this return as `CAN_0V` at the ECU and service connectors. It may
+be the defined low-current vehicle power-return conductor where that conductor
+is continuous and sized for the connected nodes; it shall not be an
+ignition/injector/starter current-return path.
+
+`CAN_0V` is an electrical reference, not a termination conductor and not a
+cable screen. No shield is required by the V1 2--2.5 m harness definition.
+Route the twisted pair away from ignition-primary/high-voltage wiring,
+injector switching loops, and high-current power pairs. If a long parallel
+route next to one of those sources becomes unavoidable, reassess the shield
+and common-mode filtering from measured EMC results rather than treating a
+screen as a substitute for a twisted pair or a reference conductor.
+
+## Connector protection and EMC provisions
+
+Place a dual-channel, automotive-qualified, low-capacitance CAN/CAN-FD TVS
+device directly behind the vehicle-I/O/CAN connector. It protects `CAN_H` and
+`CAN_L` against connector ESD and assigned cable transients before they reach
+the transceiver. The final part shall be selected after the connector,
+enclosure, and transient environment are known. A suitable class of candidate
+is Nexperia `PESD2CANFD24L-U`; its final standoff, dynamic-clamp, capacitance,
+temperature, and qualification figures shall be checked against the completed
+system rather than inferred from the part label.
+
+The primary TVS return shall have a short, low-inductance path to the defined
+connector-side `CAN_0V`/vehicle-reference return. It shall not dump cable
+transient current through the `+3V3_MAIN` or analogue-ground paths. The final
+PCB stack-up, connector shell, enclosure, and any frame bond must establish
+the actual high-frequency return path before this routing is frozen.
+
+Provide an assembly-selectable common-mode-choke option between the
+connector-side protection network and the transceiver. The default V1
+population is a direct/bypassed path, because the selected transceiver has
+strong EMC performance and an unnecessary choke can reduce signal margin.
+The PCB shall support a choke or its defined bypass arrangement without
+changing the differential-pair geometry. Fit and select a choke only if
+hardware EMC testing demonstrates a need.
+
+Do not add arbitrary series resistance, split termination, or bus capacitance
+without a timing and EMC reason. Any such option must be evaluated against the
+500 kbit/s / 2 Mbit/s bit timing and the final cable capacitance.
+
+## Layout requirements
+
+1. Place the connector-side TVS at the connector entry and keep its return
+   loop short and wide.
+2. Route `CAN_H` and `CAN_L` as a symmetric differential pair through the
+   protection/EMC network to the transceiver. Avoid stubs, unmatched component
+   placements, and large asymmetry between the two paths.
+3. Place the transceiver's 5 V and 3.3 V decoupling capacitors immediately at
+   their respective supply pins, using the datasheet-recommended values and
+   return paths.
+4. Keep the transceiver and MCU-side logic traces clear of ignition,
+   injector, switching-regulator, and high-current return loops.
+5. Keep the termination jumper and resistor close to the local bus interface;
+   label the assembly state and endpoint condition on the schematic and PCB.
+
+## Fault behaviour and validation
+
+Firmware shall report CAN controller error state, error-passive state,
+bus-off, and transceiver standby state to diagnostics. Bus-off recovery and
+retry timing shall be deliberate and rate-limited; it must not cause a reset
+storm or repeatedly disturb the other MCU core. A lost CAN network is a
+telemetry/auxiliary-service failure, not an engine-permit event.
+
+Before schematic freeze, validate the completed interface with the intended
+CAN FD configuration and installed harness:
+
+1. Confirm `CAN_H`, `CAN_L`, and `CAN_0V` connector pins, endpoint locations,
+   cable type, and real end-to-end length.
+2. Confirm the selected STM32H747 package and `FDCAN1` pin pair without
+   conflicting with USB FS DFU, timers, ADC, debug, or required serial I/O.
+3. Select and validate the final TVS against the connector ESD and transient
+   environment, including its clamp at the transceiver pins and its return
+   path.
+4. Verify normal communication, ECU reset/boot standby behaviour, an
+   unpowered ECU on a live bus, debug-tool connection, and correct 60 ohm
+   termination measurement.
+5. Test error handling and controlled bus-off recovery with a missing
+   endpoint, open/shorted bus wires, and a deliberately disturbed node.
+6. Test CAN operation and emissions/immunity with ignition and injector
+   switching active. Populate and evaluate the common-mode choke only if the
+   baseline routing/protection does not meet the assigned EMC target.

Architecture/README.md

@@ -125,7 +125,7 @@ Initial intended I/O categories are:
 | Analogue inputs | Air temperature, coolant/water temperature, pressure sensors, and expansion inputs |
 | Engine outputs | One injector and one ignition-coil primary channel |
 | Auxiliary outputs | Starter-enable logic output to an external high-current MOSFET or IGBT switch |
-| Communications | CAN bus with selectable termination |
+| Communications | One CAN FD vehicle bus with selectable ECU termination; see [CAN_PHYSICAL_LAYER.md](IO_MODULES/CAN_PHYSICAL_LAYER.md) |
 
 The starter-enable output only commands an external high-current switch. The
 ECU does not carry the starter's approximately 40 A current.
@@ -141,7 +141,9 @@ selection are finalised:
 3. Required quantity and exact types of spare analogue and digital I/O.
 4. ECU enclosure, board-size, mounting, environmental, and connector
    requirements.
-5. CAN connector and bus topology.
+5. CAN connector family/pin assignment, final cable construction, and
+   endpoint locations; the V1 CAN FD physical-layer basis is defined in
+   [CAN_PHYSICAL_LAYER.md](IO_MODULES/CAN_PHYSICAL_LAYER.md).
 6. Detailed trigger sensor wiring, connector, and cable-length information.
 
 ## Diagram sources

Architecture/diagrams/README.md

@@ -1,6 +1,6 @@
 # Architecture diagram sources
 
-The architecture Markdown embeds these 22 SVG figures. Matching PNG previews
+The architecture Markdown embeds these 23 SVG figures. Matching PNG previews
 are provided for viewers that do not support SVG. Diagrams describe the working
 architecture; component qualification and schematic-release requirements remain
 in the parent documents.
@@ -11,6 +11,7 @@ in the parent documents.
 | --- | --- |
 | Power | [Sources](power-sources.svg), [protected branches](power-branches.svg) |
 | Analogue acquisition | [Passive input](analog-input.svg), [thermistor](thermistor.svg), [ratiometric acquisition](ratiometric.svg) |
+| Vehicle CAN FD | [Trunk, termination and service access](can-topology.svg) |
 | Timing inputs | [Crank/cam interface](trigger-input.svg) |
 | Deadman | [Contacts and diagnostics](deadman-inputs.svg), [permit gates](deadman-permit.svg), [output gates](deadman-outputs.svg) |
 | Ignition | [Power](ignition-power.svg), [commands](ignition-command.svg), [current flag](ignition-flag.svg), [grounding](ignition-ground.svg) |
@@ -20,8 +21,10 @@ in the parent documents.
 
 ## Editing and regeneration
 
-- The 12 block figures have editable `.drawio` sources. Open them in draw.io.
+- The 13 block figures have editable `.drawio` sources. Open them in draw.io.
-  `build_blocks.py` recreates their baseline layout and `block-connections.json`.
+  `build_blocks.py` recreates the original 12 block layouts and `block-connections.json`.
+  The CAN topology is maintained directly in `can-topology.drawio`, with its
+  own `can-topology.connections.json` manifest; the builder does not overwrite it.
   Running it overwrites manual layout edits, so update the generator when those
   edits should be reproducible, or export the edited `.drawio` directly.
 - The 10 circuit/logic figures are generated by `build_circuits.py`, with a

Architecture/diagrams/can-topology.connections.json

@@ -0,0 +1,132 @@
+{
+  "title": "Vehicle CAN FD topology",
+  "source": "IO_MODULES/CAN_PHYSICAL_LAYER.md: Topology, termination, and service access",
+  "nodes": {
+    "title": {
+      "label": "Vehicle CAN FD \u00b7 continuous linear trunk",
+      "bounds": [
+        30,
+        20,
+        1100,
+        45
+      ]
+    },
+    "subtitle": {
+      "label": "500 kbit/s arbitration  \u00b7  2 Mbit/s data phase  \u00b7  approximately 2\u20132.5 m end-to-end",
+      "bounds": [
+        30,
+        75,
+        1100,
+        40
+      ]
+    },
+    "rear": {
+      "label": "Rear endpoint\n120 \u03a9 across CAN_H / CAN_L",
+      "bounds": [
+        30,
+        170,
+        290,
+        105
+      ]
+    },
+    "ecu": {
+      "label": "ECU \u00b7 local PCB junction\nMid-bus connection",
+      "bounds": [
+        440,
+        170,
+        280,
+        105
+      ]
+    },
+    "front": {
+      "label": "Front endpoint\n120 \u03a9 across CAN_H / CAN_L",
+      "bounds": [
+        840,
+        170,
+        290,
+        105
+      ]
+    },
+    "distance1": {
+      "label": "0.5\u20131 m",
+      "bounds": [
+        320,
+        130,
+        120,
+        40
+      ]
+    },
+    "distance2": {
+      "label": "1\u20131.5 m",
+      "bounds": [
+        720,
+        130,
+        120,
+        40
+      ]
+    },
+    "ecu_note": {
+      "label": "ECU transceiver joins locally on PCB.\nOptional ECU 120 \u03a9 termination: OPEN in V1;\nenable only if the ECU becomes an endpoint.",
+      "bounds": [
+        340,
+        305,
+        710,
+        90
+      ]
+    },
+    "service": {
+      "label": "Debug / service connector\nCAN_H \u00b7 CAN_L \u00b7 CAN_0V\nVery short PCB branch\nNo termination",
+      "bounds": [
+        440,
+        480,
+        350,
+        110
+      ]
+    },
+    "busport": {
+      "label": "Same local ECU bus",
+      "bounds": [
+        60,
+        490,
+        270,
+        80
+      ]
+    },
+    "foot": {
+      "label": "Lines above represent the CAN_H / CAN_L twisted pair, not individual conductors.\nAll nodes also share the defined CAN_0V reference. Avoid a long attached service cable.",
+      "bounds": [
+        30,
+        625,
+        1100,
+        55
+      ]
+    }
+  },
+  "connections": [
+    {
+      "from": "rear",
+      "to": "ecu",
+      "label": ""
+    },
+    {
+      "from": "ecu",
+      "to": "front",
+      "label": ""
+    },
+    {
+      "from": "busport",
+      "to": "service",
+      "label": ""
+    }
+  ],
+  "continuations": {
+    "busport": "ecu"
+  },
+  "bus_model": "Each trunk line represents the differential CAN_H/CAN_L pair. CAN_0V is a separate shared reference.",
+  "termination": {
+    "rear": "120 ohm across CAN_H/CAN_L",
+    "front": "120 ohm across CAN_H/CAN_L",
+    "ecu": "120 ohm option, solder jumper normally open; endpoint use only",
+    "service": "none"
+  }
+}

Architecture/diagrams/can-topology.drawio

@@ -0,0 +1,53 @@
+<?xml version='1.0' encoding='utf-8'?>
+<mxfile host="app.diagrams.net">
+  <diagram name="Vehicle CAN FD topology" id="can-topology">
+    <mxGraphModel page="1" pageWidth="1160" pageHeight="680">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="title" value="Vehicle CAN FD · continuous linear trunk" style="rounded=1;html=0;fontFamily=DejaVu Sans;fontSize=26;fontColor=#172b40;strokeColor=#577086;fillColor=#e8f0fc;strokeColor=none;fillColor=none;align=left;" vertex="1" parent="1">
+          <mxGeometry x="30" y="20" width="1100" height="45" as="geometry" />
+        </mxCell>
+        <mxCell id="subtitle" value="500 kbit/s arbitration  ·  2 Mbit/s data phase  ·  approximately 2–2.5 m end-to-end" style="rounded=1;html=0;fontFamily=DejaVu Sans;fontSize=18;fontColor=#172b40;strokeColor=#577086;fillColor=#e8f0fc;strokeColor=none;fillColor=none;align=left;" vertex="1" parent="1">
+          <mxGeometry x="30" y="75" width="1100" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="rear" value="Rear endpoint&#10;120 Ω across CAN_H / CAN_L" style="rounded=1;html=0;fontFamily=DejaVu Sans;fontSize=18;fontColor=#172b40;strokeColor=#577086;fillColor=#e8f4ed;" vertex="1" parent="1">
+          <mxGeometry x="30" y="170" width="290" height="105" as="geometry" />
+        </mxCell>
+        <mxCell id="ecu" value="ECU · local PCB junction&#10;Mid-bus connection" style="rounded=1;html=0;fontFamily=DejaVu Sans;fontSize=18;fontColor=#172b40;strokeColor=#577086;fillColor=#e8f0fc;" vertex="1" parent="1">
+          <mxGeometry x="440" y="170" width="280" height="105" as="geometry" />
+        </mxCell>
+        <mxCell id="front" value="Front endpoint&#10;120 Ω across CAN_H / CAN_L" style="rounded=1;html=0;fontFamily=DejaVu Sans;fontSize=18;fontColor=#172b40;strokeColor=#577086;fillColor=#e8f4ed;" vertex="1" parent="1">
+          <mxGeometry x="840" y="170" width="290" height="105" as="geometry" />
+        </mxCell>
+        <mxCell id="rear_ecu" source="rear" target="ecu" value="" edge="1" parent="1" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=0;startArrow=none;endArrow=none;strokeWidth=3;strokeColor=#416680;fontSize=18;fontFamily=DejaVu Sans;labelBackgroundColor=#ffffff;exitX=1;exitY=0.5;entryX=0;entryY=0.5;">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="ecu_front" source="ecu" target="front" value="" edge="1" parent="1" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=0;startArrow=none;endArrow=none;strokeWidth=3;strokeColor=#416680;fontSize=18;fontFamily=DejaVu Sans;labelBackgroundColor=#ffffff;exitX=1;exitY=0.5;entryX=0;entryY=0.5;">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="distance1" value="0.5–1 m" style="rounded=1;html=0;fontFamily=DejaVu Sans;fontSize=17;fontColor=#172b40;strokeColor=#577086;fillColor=#e8f0fc;strokeColor=none;fillColor=none;align=left;" vertex="1" parent="1">
+          <mxGeometry x="320" y="130" width="120" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="distance2" value="1–1.5 m" style="rounded=1;html=0;fontFamily=DejaVu Sans;fontSize=17;fontColor=#172b40;strokeColor=#577086;fillColor=#e8f0fc;strokeColor=none;fillColor=none;align=left;" vertex="1" parent="1">
+          <mxGeometry x="720" y="130" width="120" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="ecu_note" value="ECU transceiver joins locally on PCB.&#10;Optional ECU 120 Ω termination: OPEN in V1;&#10;enable only if the ECU becomes an endpoint." style="rounded=1;html=0;fontFamily=DejaVu Sans;fontSize=18;fontColor=#172b40;strokeColor=#577086;fillColor=#e8f0fc;strokeColor=none;fillColor=none;align=left;" vertex="1" parent="1">
+          <mxGeometry x="340" y="305" width="710" height="90" as="geometry" />
+        </mxCell>
+        <mxCell id="service" value="Debug / service connector&#10;CAN_H · CAN_L · CAN_0V&#10;Very short PCB branch&#10;No termination" style="rounded=1;html=0;fontFamily=DejaVu Sans;fontSize=18;fontColor=#172b40;strokeColor=#577086;fillColor=#eef0f3;" vertex="1" parent="1">
+          <mxGeometry x="440" y="480" width="350" height="110" as="geometry" />
+        </mxCell>
+        <mxCell id="busport" value="Same local ECU bus" style="rounded=1;html=0;fontFamily=DejaVu Sans;fontSize=18;fontColor=#172b40;strokeColor=#577086;fillColor=#e8f0fc;" vertex="1" parent="1">
+          <mxGeometry x="60" y="490" width="270" height="80" as="geometry" />
+        </mxCell>
+        <mxCell id="service_branch" source="busport" target="service" value="" edge="1" parent="1" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=0;startArrow=none;endArrow=none;strokeWidth=2;strokeColor=#416680;fontSize=18;fontFamily=DejaVu Sans;labelBackgroundColor=#ffffff;exitX=1;exitY=0.5;entryX=0;entryY=0.5;">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="foot" value="Lines above represent the CAN_H / CAN_L twisted pair, not individual conductors.&#10;All nodes also share the defined CAN_0V reference. Avoid a long attached service cable." style="rounded=1;html=0;fontFamily=DejaVu Sans;fontSize=17;fontColor=#172b40;strokeColor=#577086;fillColor=#e8f0fc;strokeColor=none;fillColor=none;align=left;" vertex="1" parent="1">
+          <mxGeometry x="30" y="625" width="1100" height="55" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>