# Flashing Sequence (ECU Programming)

This document outlines the expected flashing workflow using the `HexFlasher` scaffold over the LIN interface and where you can plug in your production flasher (UDS).

## Overview

- Flashing is controlled by configuration (`flash.enabled`, `flash.hex_path`)
- The `flash_ecu` session fixture invokes the flasher before tests
- The flasher uses the same `LinInterface` as tests

## Mermaid sequence

```mermaid
sequenceDiagram
  autonumber
  participant P as pytest
  participant F as flash_ecu fixture
  participant H as HexFlasher
  participant L as LinInterface (mock/babylin)
  participant E as ECU

  P->>F: Evaluate flashing precondition
  alt flash.enabled == true and hex_path provided
    F->>H: HexFlasher(lin).flash_hex(hex_path)
    H->>L: connect (ensure session ready)
    H->>E: Enter programming session (UDS)
    H->>E: Erase memory (as required)
    loop For each block in HEX
      H->>L: Transfer block via LIN frames
      L-->>H: Acks / flow control
    end
    H->>E: Verify checksum / signature
    H->>E: Exit programming, reset if needed
    H-->>F: Return success/failure
  else
    F-->>P: Skip flashing
  end
```

## Implementation notes

- `ecu_framework/flashing/hex_flasher.py` is a stub — replace with your protocol implementation (UDS)
- Validate timing requirements and chunk sizes per ECU
- Consider power-cycle/reset hooks via programmable poewr supply.

## Error handling

- On failure, the fixture calls `pytest.fail("ECU flashing failed")`
- Make flashing idempotent when possible (can retry or detect current version)

## Configuration example

```yaml
flash:
  enabled: true
  hex_path: "firmware/ecu_firmware.hex"
```