# openxc/isotp-c architecture

> Architecture diagram of the GitHub repository openxc/isotp-c, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openxc/isotp-c
- Repository: https://github.com/openxc/isotp-c

## Overview

##### Project type and purpose (what you’re diagramming)
This repo is a **platform-agnostic C protocol library** implementing **ISO-TP (ISO 15765-2)** “over” a CAN bus. It is not a full app or service—**it’s an embeddable library** meant to be linked into an ECU/embedded application (or any host app) that already has a CAN interface.

Key architectural idea from the README: **dependency injection via shims**. The library never talks to hardware directly; it calls user-provided functions for:
- sending a CAN frame (`send_can`)
- optional debug logging (`debug`)
- optional timers (`set_timer`, not used in current version)

Current functional scope: **only single-frame ISO-TP messages** (up to 7 payload bytes typical after PCI), though the API anticipates multi-frame (continue loops, flow control, timers).

- Library boundary vs user application boundary
- Shim/API boundary
- Send/receive state machines (“handles”) and callbacks
- Interaction with the underlying CAN driver/bus (external)

From the tree:

##### Core library (src/isotp/*)
- `isotp.c/.h`
Likely the **public API entry points** and orchestration functions:
- `isotp_init_shims`
- `isotp_send`, `isotp_continue_send`
- `isotp_receive`, `isotp_continue_receive`
- `isotp_types.h`
Core types (messages, handles, shim struct, enums/status).
- `send.c/.h`
Send-side logic: frame formatting, handle lifecycle, callback invocation.
- `receive.c/.h`
Receive-side logic: frame parsing, message reassembly (even if currently single-frame), handle lifecycle, callback invocation.
- `allocate.c/.h`
Memory allocation strategy / message buffer management (likely abstracted for portability/controllability).

##### Dependencies
- `deps/bitfield-c`

##### Tests
- `tests/*.c`, `tests/common.c`
Unit tests for allocate/core/send/receive using the **Check** unit testing framework (explicitly called out in README). Tests will likely stub shims (fake CAN send, fake timer).

##### Build + CI
- `Makefile` (build/test/coverage)
- `.github/workflows/main.yml` (CI pipeline)
- `runtests.sh` (test runner helper)

##### ISO-TP marks handle completed (single-frame) and calls `message_sent(...)` if provided
5. (For future multi-frame) App repeatedly calls `isotp_continue_send(...)` feeding in received flow-control frames.

##### Receive
Actors:
- CAN driver delivers raw CAN frames to application
- Application loop
- ISO-TP API (`isotp_receive`, `isotp_continue_receive`)
- Optional callback: `message_received`

Flow:
##### App sets up handle: `isotp_receive(...)`
2. App receives a CAN frame (from driver) and calls `isotp_continue_receive(shims, handle, arb_id, data, size)`
3. ISO-TP parses PCI (likely via bitfield helper), assembles message, sets `message.completed`
##### If complete, ISO-TP returns message and/or calls callback

- “Only single-frame supported currently”
- “Timer shim reserved for multi-frame timeouts”
- “Flow control not yet implemented or partial”

##### Application drives time and IO
- Library does not read CAN itself; it’s fed frames by the app (`continue_receive`).
- Library does not schedule itself; timer shim exists but not used now.

##### Shims are the only hardware/OS touchpoint
- `send_can` is required. Everything else is optional.

##### Handles represent state machines
- `IsoTpSendHandle` / `IsoTpReceiveHandle` are the state containers that evolve across calls.
- Callbacks are an optional async completion hook.

##### Unit tests emulate the world
- Tests substitute shims with fakes to validate behavior deterministically.

This set will be the most accurate representation of the project’s purpose and structure, while staying grounded in what’s actually in the repository.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% View A: Context (C4 L1)
  %% =========================
  subgraph "A) Context: Host Integration (Library is embedded; app drives IO/time)"
    direction TB

    App["User Application\n(ECU firmware / diagnostic tool / host app)"]:::app
    AppLoop["Application Main Loop\n(pump calling continue_*)"]:::app
    ShimImpl["Shim Implementations\n(send_can, debug?, set_timer?)"]:::app

    subgraph "ISO-TP C Library (repo)"
      direction TB
      IsoTpLib["ISO-TP C Library\n(src/isotp)"]:::lib
      ShimPort["Shim Interface (Port)\nIsoTpShims { send_can, debug?, set_timer? }"]:::port
      Callbacks["Optional Callbacks\nmessage_sent(), message_received()"]:::opt
    end

    CanDriver["CAN Driver / HAL / SocketCAN\n(external)"]:::external
    CanBus["CAN Bus\n(external network)"]:::external
    Peer["CAN Peer ECU / Tester\n(external node)"]:::external

    App -->|"calls isotp_init_shims()"| IsoTpLib
    AppLoop -->|"calls isotp_send()/isotp_receive()"| IsoTpLib
    AppLoop -->|"calls isotp_continue_send()"| IsoTpLib
    AppLoop -->|"feeds frames: isotp_continue_receive()"| IsoTpLib

    IsoTpLib -->|"uses shims via function pointers"| ShimPort
    ShimPort -->|"implemented by"| ShimImpl
    ShimImpl -->|"send_can(frame)"| CanDriver
    CanDriver -->|"tx CAN frame"| CanBus
    Peer <-->|"CAN frames"| CanBus
    CanBus -->|"rx CAN frame"| CanDriver
    CanDriver -->|"delivers raw CAN frames"| AppLoop

    IsoTpLib -->|"invokes"| Callbacks
    Callbacks -->|"notify completion/data"| App
  end

  %% =========================
  %% View B: Component (C4 L2)
  %% =========================
  subgraph "B) Library Components: src/isotp/* + internal dependency"
    direction TB

    subgraph "ISO-TP C Library (src/isotp)"
      direction TB
      Api["Public API / Facade\n(isotp.c/.h)"]:::lib
      Types["Core Types / Contracts\n(isotp_types.h)"]:::lib
      Send["Send Engine (state machine)\n(send.c/.h)"]:::lib
      Recv["Receive Engine (state machine)\n(receive.c/.h)"]:::lib
      Alloc["Allocation / Buffer Manager\n(allocate.c/.h)"]:::lib
      ShimIF["Shim Interface\nIsoTpShims { send_can, debug?, set_timer? }"]:::port
    end

    Bitfield["Bitfield Utility\n(deps/bitfield-c)"]:::dep

    Api -->|"dispatches"| Send
    Api -->|"dispatches"| Recv
    Api -->|"uses"| Types

    Send -->|"uses"| Types
    Recv -->|"uses"| Types
    Alloc -->|"uses"| Types

    Send -->|"alloc/release buffers"| Alloc
    Recv -->|"alloc/release buffers"| Alloc

    Send -->|"calls"| ShimIF
    Recv -->|"optional debug/timer"| ShimIF

    Send -.->|"pack/unpack PCI bits"| Bitfield
    Recv -.->|"parse PCI bits"| Bitfield
  end

  %% =========================
  %% View C1: Sequence (Send)
  %% =========================
  subgraph "C1) Runtime Sequence: Send (single-frame today; multi-frame anticipated)"
    direction TB

    sApp["Application"]:::app
    sAPI["ISO-TP API\nisotp_send()/isotp_continue_send()"]:::lib
    sSend["Send Engine\n(send.c)"]:::lib
    sShim["Shim: send_can()"]:::port
    sDrv["CAN Driver/HAL"]:::external
    sCb["Callback: message_sent() (optional)"]:::opt

    sApp -->|"1) isotp_send(payload)"| sAPI
    sAPI -->|"2) build handle + dispatch"| sSend
    sSend -->|"3) format PCI+data into 1 CAN frame"| sSend
    sSend -->|"4) shims.send_can(arb_id,data,size)"| sShim
    sShim -->|"5) transmit frame"| sDrv
    sSend -->|"6) complete handle (single-frame)"| sSend
    sSend -->|"7) invoke message_sent() if set"| sCb
    sCb -->|"8) notify app"| sApp
  end

  %% =========================
  %% View C2: Sequence (Receive)
  %% =========================
  subgraph "C2) Runtime Sequence: Receive (app feeds frames; single-frame today)"
    direction TB

    rDrv["CAN Driver/HAL"]:::external
    rAppLoop["Application Main Loop"]:::app
    rAPI["ISO-TP API\nisotp_receive()/isotp_continue_receive()"]:::lib
    rRecv["Receive Engine\n(receive.c)"]:::lib
    rCb["Callback: message_received() (optional)"]:::opt

    rAppLoop -->|"1) isotp_receive(set up handle)"| rAPI
    rDrv -->|"2) incoming CAN frame"| rAppLoop
    rAppLoop -->|"3) isotp_continue_receive(frame)"| rAPI
    rAPI -->|"4) dispatch parse/assemble"| rRecv
    rRecv -->|"5) parse PCI + assemble message"| rRecv
    rRecv -->|"6) mark message complete (single-frame)"| rRecv
    rRecv -->|"7) invoke message_received() if set"| rCb
    rCb -->|"8) deliver payload"| rAppLoop
  end

  %% =========================
  %% View D: Build & Verification
  %% =========================
  subgraph "D) Build, Test & CI (delivery pipeline)"
    direction TB

    Dev["Developer / CI Runner"]:::external
    Make["Makefile\n(build/test/coverage)"]:::build
    Runner["Test Runner Script\n(runtests.sh)"]:::build
    Tests["Unit Tests (Check)\n(tests/*.c + common stubs)"]:::test
    CI["GitHub Actions Workflow\n(.github/workflows/main.yml)"]:::build
    Docs["Project Documentation\n(README.mkd)"]:::doc

    Dev -->|"runs make test"| Make
    Make -->|"invokes"| Runner
    Runner -->|"executes"| Tests
    Tests -.->|"links against"| Api
    Tests -.->|"fakes shims"| ShimIF

    Dev -->|"push/PR"| CI
    CI -->|"runs build+tests"| Make
    Docs -.->|"describes API/architecture"| Api
  end

  %% =========================
  %% Click Events (from mapping)
  %% =========================
  click IsoTpLib "https://github.com/openxc/isotp-c/tree/master/src/isotp/"
  click Api "https://github.com/openxc/isotp-c/blob/master/src/isotp/isotp.c"
  click Types "https://github.com/openxc/isotp-c/blob/master/src/isotp/isotp_types.h"
  click Send "https://github.com/openxc/isotp-c/blob/master/src/isotp/send.c"
  click Recv "https://github.com/openxc/isotp-c/blob/master/src/isotp/receive.c"
  click Alloc "https://github.com/openxc/isotp-c/blob/master/src/isotp/allocate.c"
  click Bitfield "https://github.com/openxc/isotp-c/tree/master/deps/bitfield-c/"
  click Tests "https://github.com/openxc/isotp-c/tree/master/tests/"
  click Make "https://github.com/openxc/isotp-c/tree/master/Makefile"
  click CI "https://github.com/openxc/isotp-c/blob/master/.github/workflows/main.yml"
  click Runner "https://github.com/openxc/isotp-c/blob/master/runtests.sh"
  click Docs "https://github.com/openxc/isotp-c/blob/master/README.mkd"

  %% Additional click targets for mapped files
  click Api "https://github.com/openxc/isotp-c/blob/master/src/isotp/isotp.h"
  click Send "https://github.com/openxc/isotp-c/blob/master/src/isotp/send.h"
  click Recv "https://github.com/openxc/isotp-c/blob/master/src/isotp/receive.h"
  click Alloc "https://github.com/openxc/isotp-c/blob/master/src/isotp/allocate.h"
  click Tests "https://github.com/openxc/isotp-c/blob/master/tests/common.c"
  click Tests "https://github.com/openxc/isotp-c/blob/master/tests/test_core.c"
  click Tests "https://github.com/openxc/isotp-c/blob/master/tests/test_send.c"
  click Tests "https://github.com/openxc/isotp-c/blob/master/tests/test_receive.c"
  click Tests "https://github.com/openxc/isotp-c/blob/master/tests/test_allocate.c"

  %% =========================
  %% Styles
  %% =========================
  classDef lib fill:#1f6feb,stroke:#0b3d91,color:#ffffff,stroke-width:1px
  classDef app fill:#2ea043,stroke:#176f2c,color:#ffffff,stroke-width:1px
  classDef external fill:#6e7681,stroke:#3d444d,color:#ffffff,stroke-width:1px
  classDef port fill:#a371f7,stroke:#6f42c1,color:#ffffff,stroke-width:1px
  classDef dep fill:#0ea5e9,stroke:#075985,color:#ffffff,stroke-width:1px,stroke-dasharray:4 3
  classDef opt fill:#f59e0b,stroke:#92400e,color:#111827,stroke-width:1px,stroke-dasharray:4 3
  classDef build fill:#fb7185,stroke:#9f1239,color:#111827,stroke-width:1px
  classDef test fill:#f97316,stroke:#9a3412,color:#111827,stroke-width:1px
  classDef doc fill:#eab308,stroke:#854d0e,color:#111827,stroke-width:1px
```
