# linux-can/can-utils architecture

> Architecture diagram of the GitHub repository linux-can/can-utils, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/linux-can/can-utils
- Repository: https://github.com/linux-can/can-utils

## Overview

##### Project type and purpose
- This is an open-source collection of userspace CLI utilities (c-written) for interacting with the Linux CAN (SocketCAN) subsystem.
- Purpose: display, record, generate, replay, and bridge CAN traffic; provide measurement/test tools; support ISO-TP, J1939 protocols; configure serial-to-CAN (“slcan”) interfaces.

##### File structure
- Top level: CMakeLists.txt, Makefile, individual .c/.h files, utility subdirectories (calc-bit-timing, isobusfs, j1939_timedate, j1939_vehicle_position, mcp251xfd).
- /: shared headers for CAN and other protocols.
- cmake/: toolchain cross-compile configs.
- .github/workflows/: CI build and static analysis.
- Licenses, style guides, build scripts (check_cc.sh).

##### Extract insights from README
- Utilities are grouped by functionality: basic CAN tools, IP-socket CAN, in-kernel gateway config, bus measurement/testing, ISO-TP, J1939/ISOBus, log converters, serial line config.
- Mentions external projects: socketcand, cannelloni.
- Build instructions use CMake, support Android, Raspberry Pi, cross-compiling.

##### Main components
a. External environment:
– Physical CAN bus (CAN transceiver, CAN hardware).
– Serial interface (slcan adapter/line discipline).
– IP network (for socketcand/cannelloni or isotpserver).
b. Kernel layers:
– CAN network stack (CAN_RAW, BCM, ISO-TP, SOC_J1939 sockets).
– slcan line discipline driver.
– J1939 kernel module.
c. Userspace libraries:
– lib.c, lib.h (common routines).
– libj1939.c, libj1939.h (J1939 helper functions).
d. Build system:
– CMake toolchain files, Makefile, GitHub CI workflows.
– Basic tools: candump, canplayer, cansend, cangen, cansequence, cansniffer.
– Gateway config: cangw (netlink).
– Bus measurement: canbusload, calc-bit-timing, canfdtest, canerrsim.
– ISO-TP: isotpsend/recv/sniffer/dump, isotpserver, isotpperf, isotptun.
– J1939: j1939acd, j1939cat, j1939spy, j1939sr, testj1939 (use SOC_J1939).
– Log converters: asc2log, log2asc, log2long.
– SLCAN: slcan_attach, slcand, slcanpty.
– Special sub-projects: isobusfs, j1939_timedate, j1939_vehicle_position, mcp251xfd (show these as separate functional clusters with their own source directories).

##### Relationships and interactions
- Utilities open specific socket types (CAN_RAW, BCM, ISO-TP, SOC_J1939) to send/receive frames via the kernel.
- slcan tools bind a serial line to a virtual CAN network interface.
- isotpserver and socketcand bridge between CAN and TCP/IP.
- cangw uses netlink to configure in-kernel CAN gateway.
- Shared code (lib.c/libj1939) is linked into each utility.
- The build system compiles each .c into separate executables and installs headers/libraries.

##### Important architectural patterns
- Layered architecture: Physical CAN → Kernel drivers/stacks → Shared libraries → CLI utilities.
- Modular CLI tools: each utility is its own component, reusing common libs.
- Extensibility: subdirectories (calc-bit-timing, mcp251xfd, isobusfs, etc.) represent optional modules.

##### Final checklist
- All major utilities and sub-projects represented.
- Kernel interfaces clearly labeled.
- Build system and CI shown as separate supporting component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Physical Layer
    CANBus["Physical CAN Bus"]:::physical
    SerialIF["Serial Interface\n(slan adapter)"]:::physical
    IPNet["IP Network"]:::physical

    %% Kernel Layer
    CANStack["CAN Network Stack\n(CAN_RAW, BCM, ISO-TP, SOC_J1939)"]:::kernel
    slcandrv["slcan Line Discipline Driver"]:::kernel
    j1939mod["J1939 Kernel Module"]:::kernel

    %% Shared Libraries
    libcommon["lib.c / lib.h"]:::lib
    libj1939["libj1939.c / libj1939.h"]:::lib

    %% Utilities Layer
    subgraph "Basic CAN Tools" 
        direction TB
        candump["candump"]:::util
        canplayer["canplayer"]:::util
        cansend["cansend"]:::util
        cangen["cangen"]:::util
        cansequence["cansequence"]:::util
        cansniffer["cansniffer"]:::util
        canframelen["canframelen"]:::util
    end

    subgraph "IP-Socket CAN Utilities"
        direction TB
        canlogserver["canlogserver"]:::util
        bcmserver["bcmserver"]:::util
    end

    subgraph "Gateway Configuration"
        direction TB
        cangw["cangw"]:::util
    end

    subgraph "Bus Measurement & Testing"
        direction TB
        canbusload["canbusload"]:::util
        calcbit["calc-bit-timing"]:::util
        canfdtest["canfdtest"]:::util
        canerrsim["canerrsim"]:::util
    end

    subgraph "ISO-TP Utilities"
        direction TB
        isotpsend["isotpsend"]:::util
        isotprecv["isotprecv"]:::util
        isotpsniffer["isotpsniffer"]:::util
        isotpdump["isotpdump"]:::util
        isotpserver["isotpserver"]:::util
        isotpperf["isotpperf"]:::util
        isotptun["isotptun"]:::util
    end

    subgraph "J1939 / ISOBus Utilities"
        direction TB
        j1939acd["j1939acd"]:::util
        j1939cat["j1939cat"]:::util
        j1939spy["j1939spy"]:::util
        j1939sr["j1939sr"]:::util
        testj1939["testj1939"]:::util
    end

    subgraph "Log Converters"
        direction TB
        asc2log["asc2log"]:::util
        log2long["log2long"]:::util
    end

    subgraph "Serial-Line CAN Tools"
        direction TB
        slcan_attach["slcan_attach"]:::util
        slcand["slcand"]:::util
        slcanpty["slcanpty"]:::util
    end

    subgraph "Special Sub-Projects"
        direction TB
        isobusfs["isobusfs"]:::util
        j1939_timedate["j1939_timedate"]:::util
        j1939_vehicle_position["j1939_vehicle_position"]:::util
        mcp251xfd["mcp251xfd"]:::util
    end

    %% Build & CI Infrastructure
    subgraph "Build & CI" 
        direction TB
        CMakeLists["CMakeLists.txt"]:::infra
        Makefile["Makefile"]:::infra
        cmake_dir["cmake/"]:::infra
        workflows[".github/workflows/"]:::infra
    end

    %% Connections Physical -> Kernel
    CANBus --> CANStack
    SerialIF --> slcandrv
    IPNet --> isotpserver
    IPNet --> canlogserver
    IPNet --> bcmserver

    %% Kernel -> Shared Libraries & Modules
    slcandrv --> CANStack
    j1939mod --> CANStack

    %% Shared Libraries -> Kernel
    libcommon --> CANStack
    libj1939 --> CANStack

    %% Utilities -> Shared Libraries
    candump --> libcommon
    canplayer --> libcommon
    cansend --> libcommon
    cangen --> libcommon
    cansequence --> libcommon
    cansniffer --> libcommon
    canframelen --> libcommon

    canlogserver --> libcommon
    bcmserver --> libcommon

    cangw --> libcommon

    canbusload --> libcommon
    calcbit --> libcommon
    canfdtest --> libcommon
    canerrsim --> libcommon

    isotpsend --> libcommon
    isotprecv --> libcommon
    isotpsniffer --> libcommon
    isotpdump --> libcommon
    isotpserver --> libcommon
    isotpperf --> libcommon
    isotptun --> libcommon

    j1939acd --> libcommon
    j1939cat --> libcommon
    j1939spy --> libcommon
    j1939sr --> libcommon
    testj1939 --> libcommon
    j1939acd --> libj1939
    j1939cat --> libj1939
    j1939spy --> libj1939
    j1939sr --> libj1939
    testj1939 --> libj1939

    asc2log --> libcommon
    log2long --> libcommon

    slcan_attach --> libcommon
    slcand --> libcommon
    slcanpty --> libcommon

    isobusfs --> libcommon
    j1939_timedate --> libcommon
    j1939_vehicle_position --> libcommon
    mcp251xfd --> libcommon

    %% Utilities -> Kernel interfaces
    candump -->|"CAN_RAW socket"| CANStack
    canplayer -->|"CAN_RAW socket"| CANStack
    cansend -->|"CAN_RAW socket"| CANStack
    cangen -->|"CAN_RAW socket"| CANStack
    cansequence -->|"CAN_RAW socket"| CANStack
    cansniffer -->|"CAN_RAW socket"| CANStack
    canframelen -->|"CAN_RAW socket"| CANStack

    canlogserver -->|"BCM/TCP"| CANStack
    bcmserver -->|"BCM/TCP"| CANStack

    cangw -->|"netlink"| CANStack

    canbusload -->|"CAN_RAW socket"| CANStack
    calcbit -->|"calc timing"| CANStack
    canfdtest -->|"CAN_RAW socket"| CANStack
    canerrsim -->|"CAN_RAW socket"| CANStack

    isotpsend -->|"ISO-TP socket"| CANStack
    isotprecv -->|"ISO-TP socket"| CANStack
    isotpsniffer -->|"ISO-TP socket"| CANStack
    isotpdump -->|"ISO-TP socket"| CANStack
    isotpperf -->|"ISO-TP socket"| CANStack
    isotptun -->|"ISO-TP tunnel"| CANStack

    j1939acd -->|"SOC_J1939 socket"| CANStack
    j1939cat -->|"SOC_J1939 socket"| CANStack
    j1939spy -->|"SOC_J1939 socket"| CANStack
    j1939sr -->|"SOC_J1939 socket"| CANStack
    testj1939 -->|"SOC_J1939 socket"| CANStack

    slcan_attach --> slcandrv
    slcand --> slcandrv
    slcanpty --> slcand

    %% Build & CI links
    CMakeLists --> libcommon
    CMakeLists --> libj1939
    CMakeLists --> candump
    Makefile --> CMakeLists
    cmake_dir --> CMakeLists
    workflows --> CMakeLists

    %% Click Events
    click libcommon "https://github.com/linux-can/can-utils/blob/master/./lib.c"
    click libcommon "https://github.com/linux-can/can-utils/blob/master/./lib.h"
    click libj1939 "https://github.com/linux-can/can-utils/blob/master/./libj1939.c"
    click libj1939 "https://github.com/linux-can/can-utils/blob/master/./libj1939.h"

    click CMakeLists "https://github.com/linux-can/can-utils/blob/master/./CMakeLists.txt"
    click Makefile "https://github.com/linux-can/can-utils/tree/master/./Makefile"
    click cmake_dir "https://github.com/linux-can/can-utils/tree/master/./cmake/"
    click workflows "https://github.com/linux-can/can-utils/tree/master/./.github/workflows/"

    click candump "https://github.com/linux-can/can-utils/blob/master/./candump.c"
    click canplayer "https://github.com/linux-can/can-utils/blob/master/./canplayer.c"
    click cansend "https://github.com/linux-can/can-utils/blob/master/./cansend.c"
    click cangen "https://github.com/linux-can/can-utils/blob/master/./cangen.c"
    click cansequence "https://github.com/linux-can/can-utils/blob/master/./cansequence.c"
    click cansniffer "https://github.com/linux-can/can-utils/blob/master/./cansniffer.c"
    click canframelen "https://github.com/linux-can/can-utils/blob/master/./canframelen.c"
    click canframelen "https://github.com/linux-can/can-utils/blob/master/./canframelen.h"

    click canlogserver "https://github.com/linux-can/can-utils/blob/master/./canlogserver.c"
    click bcmserver "https://github.com/linux-can/can-utils/blob/master/./bcmserver.c"

    click cangw "https://github.com/linux-can/can-utils/blob/master/./cangw.c"

    click canbusload "https://github.com/linux-can/can-utils/blob/master/./canbusload.c"
    click calcbit "https://github.com/linux-can/can-utils/tree/master/./calc-bit-timing/"
    click canfdtest "https://github.com/linux-can/can-utils/blob/master/./canfdtest.c"
    click canerrsim "https://github.com/linux-can/can-utils/blob/master/./canerrsim.c"

    click isotpsend "https://github.com/linux-can/can-utils/blob/master/./isotpsend.c"
    click isotprecv "https://github.com/linux-can/can-utils/blob/master/./isotprecv.c"
    click isotpsniffer "https://github.com/linux-can/can-utils/blob/master/./isotpsniffer.c"
    click isotpdump "https://github.com/linux-can/can-utils/blob/master/./isotpdump.c"
    click isotpserver "https://github.com/linux-can/can-utils/blob/master/./isotpserver.c"
    click isotpperf "https://github.com/linux-can/can-utils/blob/master/./isotpperf.c"
    click isotptun "https://github.com/linux-can/can-utils/blob/master/./isotptun.c"

    click j1939acd "https://github.com/linux-can/can-utils/blob/master/./j1939acd.c"
    click j1939cat "https://github.com/linux-can/can-utils/blob/master/./j1939cat.c"
    click j1939spy "https://github.com/linux-can/can-utils/blob/master/./j1939spy.c"
    click j1939sr "https://github.com/linux-can/can-utils/blob/master/./j1939sr.c"
    click testj1939 "https://github.com/linux-can/can-utils/blob/master/./testj1939.c"

    click asc2log "https://github.com/linux-can/can-utils/blob/master/./asc2log.c"
    click log2long "https://github.com/linux-can/can-utils/blob/master/./log2long.c"

    click slcan_attach "https://github.com/linux-can/can-utils/blob/master/./slcan_attach.c"
    click slcand "https://github.com/linux-can/can-utils/blob/master/./slcand.c"
    click slcanpty "https://github.com/linux-can/can-utils/blob/master/./slcanpty.c"

    click isobusfs "https://github.com/linux-can/can-utils/tree/master/./isobusfs/"
    click j1939_timedate "https://github.com/linux-can/can-utils/tree/master/./j1939_timedate/"
    click j1939_vehicle_position "https://github.com/linux-can/can-utils/tree/master/./j1939_vehicle_position/"
    click mcp251xfd "https://github.com/linux-can/can-utils/tree/master/./mcp251xfd/"

    %% Styles
    classDef physical fill:#b7e4c7,stroke:#2d6a4f,color:#1b4332
    classDef kernel fill:#a0c4ff,stroke:#1d3557,color:#1d3557
    classDef lib fill:#ffe066,stroke:#c77f00,color:#6f1d1b
    classDef util fill:#ffadad,stroke:#c9184a,color:#6a040f
    classDef infra fill:#d3d3d3,stroke:#495057,color:#212529
```
