MCANGEN(1)

NAME
mcangen - high-performance CAN bus frame generator

SYNOPSIS
mcangen [OPTIONS] INTERFACE

DESCRIPTION
mcangen sends CAN frames with configurable IDs, DLC, data patterns, and rate to a Linux SocketCAN interface. It is designed for testing and benchmarking CAN bus stacks and hardware.

Frames can use standard (11-bit) IDs, extended (29-bit) IDs, or a random mix of both. Data length codes range from 0 to 8 bytes. Payload bytes can be random, all zeros, all ones, or an incrementing counter. The frame rate can be set precisely or left unlimited for maximum throughput.

ARGUMENTS

INTERFACE
    CAN interface name (e.g. can0, vcan0).

OPTIONS

-n, --count N
    Exact number of frames to send. 0 means unlimited (default: 0).

-r, --rate FPS
    Target frames per second. 0 means send as fast as possible (default: 5).

--dlc-min N
    Minimum data length code, 0–8 (default: 0).

--dlc-max N
    Maximum data length code, 0–8 (default: 8).

--id-min ID
    Minimum CAN ID in hex or decimal (default: 0x000).

--id-max ID
    Maximum CAN ID in hex or decimal. Clamped to 0x7FF for standard or 0x1FFFFFFF for extended/mixed IDs (default: 0x7FF for standard, 0x1FFFFFFF for extended/mixed).

--id-kind MODE
    ID type: standard (11-bit), extended (29-bit), or mixed (default: standard).

--ext-id-above-sff true|false
    Ensure extended (29-bit) IDs are always greater than 0x7FF so they cannot be mistaken for standard (11-bit) IDs on the receiving side (default: true).

--id-mode MODE
    How CAN IDs are selected: random or sequential (default: random).

--data-mode MODE
    How frame data bytes are filled: random, zero, counter, sequence, ones, or quality-test (default: random). In sequence mode the 8 payload bytes form a big-endian 64-bit sequence number starting at 0. In quality-test mode, payloads follow the CANcorder quality-test protocol: bytes 0–1 are the magic marker 0xCAFE, bytes 2–3 a big-endian 16-bit sequence number, bytes 4–5 a big-endian 16-bit millisecond timestamp offset, byte 6 the test ID (see --test-id), and byte 7 an XOR checksum of bytes 0–6. DLC is forced to 8 in this mode.

-s, --seed SEED
    RNG seed for reproducible runs. 0 uses a random seed (default: 0).

-p, --progress N
    Print a stats line to stderr every N frames. 0 prints only the final summary (default: 0).

-q, --quiet
    Suppress all output except errors.

--burst
    Enable burst mode: alternate between a high-rate and a low-rate phase, emulating the intermittent traffic pattern of ECU reprogramming sessions. Mutually exclusive with --rate.

--burst-high-rate FPS
    Frames per second during the high-rate burst phase (default: 5000).

--burst-low-rate FPS
    Frames per second during the low-rate idle phase (default: 50).

--burst-high-ms MS
    Duration of the high-rate phase in milliseconds (default: 2000).

--burst-low-ms MS
    Duration of the low-rate phase in milliseconds (default: 500).

--test-id ID
    Test ID byte (0–255) embedded in quality-test payloads. Allows multiple concurrent test runs to be distinguished (default: 0).

  UDS Flash Mode

--uds-flash
    Enable UDS flash simulation mode. Generates a realistic ECU reprogramming session directly on the CAN bus, with both tester and ECU frames visible. The session follows a 16-phase sequence: extended diagnostic session, ECU identification reads, programming session, security access (seed/key), communication control, DTC disable, programming precondition check, memory erase (with NRC 0x78 pending responses), firmware download request, multi-frame ISO-TP data transfer (50–150 blocks of 200–256 bytes), transfer exit, dependency check, DTC read/clear/verify, and ECU hard reset.

    In this mode, -n sets the number of sessions (0 = loop forever). Between sessions, OBD-II polling traffic is generated unless --no-obd is given. Mutually exclusive with --burst. The options --rate, --data-mode, --id-*, and --dlc-* are ignored.

--tester-id ID
    CAN ID for tester/diagnostic tool requests in UDS flash mode (default: 0x7E0).

--ecu-id ID
    CAN ID for ECU responses in UDS flash mode (default: 0x7E8).

--speed FACTOR
    Timing multiplier for UDS flash mode. Values above 1.0 speed up the simulation; values below 1.0 slow it down (default: 1.0).

--transfer-blocks N
    Number of data transfer blocks per UDS flash session. 0 picks a random count between 50 and 150 (default: 0).

--no-obd
    Skip OBD-II polling traffic between UDS flash sessions.

--no-errors
    Disable error injection in UDS flash mode. Without this flag, the simulator occasionally injects busy retries (3%), security access failures (15%), wrong block sequence errors (2%), and response-pending delays (5%).

-h, --help
    Print help message and exit.

-V, --version
    Print version and exit.

EXAMPLES
Send 10000 random frames as fast as possible on can0:

    mcangen can0 -r 0 -n 10000

Send at 500 fps with mixed standard and extended IDs:

    mcangen vcan0 -r 500 --id-kind mixed -n 5000

Sequential IDs, fixed DLC of 4, counter payload, with progress:

    mcangen can0 --id-mode sequential --dlc-min 4 --dlc-max 4 \
        --data-mode counter -p 1000

Reproducible test run:

    mcangen vcan0 -n 5000 -r 1000 --seed 42

Burst mode — simulate ECU reprogramming traffic (2 s at 5000 fps, 500 ms at 50 fps):

    mcangen can0 --burst -n 100000

Custom burst parameters (1 s high at 10000 fps, 200 ms low at 100 fps):

    mcangen can0 --burst --burst-high-rate 10000 \
        --burst-low-rate 100 --burst-high-ms 1000 \
        --burst-low-ms 200 -n 50000

CANcorder quality-test protocol on ID 0x7E0:

    mcangen can0 --data-mode quality-test --id-min 0x7E0 \
        --id-max 0x7E0 -r 1000 -n 10000

UDS flash simulation — single reprogramming session:

    mcangen vcan0 --uds-flash -n 1

UDS flash — double speed, 100 blocks, no errors:

    mcangen can0 --uds-flash -n 1 --speed 2.0 \
        --transfer-blocks 100 --no-errors

UDS flash — custom IDs, no OBD polling, 3 sessions:

    mcangen can0 --uds-flash --tester-id 0x641 \
        --ecu-id 0x642 --no-obd -n 3

UDS flash — loop forever (Ctrl-C to stop):

    mcangen vcan0 --uds-flash

RATE LIMITING
When --rate is set, mcangen uses a hybrid sleep/busy-spin strategy for precise timing. For intervals longer than 2 ms it sleeps for most of the wait and busy-spins the final millisecond. If the sender falls behind schedule, it resets rather than bursting to catch up.

When --rate is 0, frames are sent back-to-back with no delay. Actual throughput will be limited by the kernel's send buffer and the CAN bus bitrate. The default rate is 5 fps, matching cangen's default 200 ms gap.

BURST MODE
When --burst is given, mcangen cycles between a high-rate phase and a low-rate phase. This emulates the traffic pattern typical of ECU reprogramming: large blocks of data are transferred at high speed, followed by short idle periods while the ECU erases or programs flash. The default cycle is 2 s at 5000 fps / 500 ms at 50 fps. All four parameters are tuneable. Burst mode is mutually exclusive with --rate.

UDS FLASH MODE
When --uds-flash is given, mcangen generates a complete UDS (Unified Diagnostic Services) ECU reprogramming session directly on the CAN bus. Both the tester (diagnostic tool) and the ECU sides of the conversation are produced, so any CAN bus monitor or application under test sees realistic bidirectional traffic with proper ISO-TP segmentation and timing.

A session consists of 16 phases:

1.  Enter extended diagnostic session (0x10/0x03)

2.  Read ECU identification: VIN, serial, SW/HW version, part number (0x22, multi-frame)

3.  Enter programming session (0x10/0x02)

4.  Security access with seed & key exchange (0x27)

5.  Disable normal communication (0x28)

6.  Disable DTC setting (0x85)

7.  Check programming preconditions (0x31, routine 0xFF00)

8.  Erase memory with response-pending (0x31, routine 0xFF01, NRC 0x78)

9.  Request download for 256 KB at address 0x00080000 (0x34)

10. Transfer data blocks via multi-frame ISO-TP (0x36, 50–150 blocks)

11. Request transfer exit (0x37)

12. Check programming dependencies (0x31, routine 0xFF02)

13. Read and clear DTCs (0x19, 0x14), verify cleared

14. ECU hard reset (0x11)

Unless --no-errors is given, the simulator occasionally injects negative responses with automatic retries: busy repeat request (NRC 0x21), conditions not correct (NRC 0x22), invalid security key (NRC 0x35), wrong block sequence counter (NRC 0x73), and response pending (NRC 0x78).

Between sessions (unless --no-obd), OBD-II polling traffic is generated using functional addressing (0x7DF) with responses on the configured ECU ID. Polled PIDs include engine RPM (0x0C), coolant temperature (0x05), vehicle speed (0x0D), and throttle position (0x11), with simulated sensor values that drift over time.

For more sophisticated ECU simulation with custom services, security algorithms, and configurable identifiers, see the ECUmulator project.

PERMISSIONS
Sending CAN frames requires the CAP_NET_RAW capability. Either run as root or grant the capability:

    sudo setcap cap_net_raw+ep /path/to/mcangen

EXIT STATUS

0   All frames sent successfully.

1   Error (invalid arguments, socket failure, or excessive write errors).

SEE ALSO
cangen(1), candump(1), cansend(1), ip(8)

BUGS
Report bugs at: https://github.com/mickeyl/mcangen/issues

AUTHOR
Dr. Michael 'Mickey' Lauer <mickey@vanille-media.de>

LICENSE
MIT License. See the LICENSE file in the source distribution.