How openxc/isotp-c works
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.