Skip to content

canair memory

usage: canair memory [-h] <kind> ...

Read ECU memory with ReadMemoryByAddress (0x23) into dumps kept on this machine, and list, compare and export them. Choose a kind:
  image   plan and read an ECU's whole memory image, resumably (talks to the car)
  dump    read address ranges into a new dump (talks to the car)
  ls      list the dumps
  show    summarise a dump, or hex-dump a range of it
  diff    the runs of addresses that differ between two dumps
  export  write a dump as Intel HEX, S-record or binary
  set     set an ECU's memory format, largest block or session

Find which ranges an ECU answers with `canair scan memory`.

positional arguments:
  <kind>
    image     Plan and read an ECU's whole memory image, resumably and checked
    dump      Read address ranges into a local dump
    ls        List the dumps (offline)
    show      Summarise a dump, or hex-dump a range of it
    diff      The address runs whose bytes differ between two dumps of one ECU
    export    Write a dump as Intel HEX, S-record or raw binary
    set       Set an ECU's memory format, largest block or session (writes
              ecus/)

options:
  -h, --help  show this help message and exit

the loop that finds a RAM variable:
  canair scan memory BCM --range FEDE0000-FEDFFFFF
  canair memory dump BCM FEDE0000-FEDFFFFF --label "lights off"
  canair memory dump BCM FEDE0000-FEDFFFFF --label "lights on"
  canair memory diff BCM/20261105-2210-lights-off BCM/20261105-2212-lights-on
  canair pids upsert-param BCM 23/FEDE1234+02 LIGHT_STATE B04

Dumps can hold OEM software and secrets: they stay in your config directory and nothing
that shares a profile can reach them.

canair memory image

usage: canair memory image [-h] [--resume DUMP] [--thorough]
                           [--range START-END[,…]] [--step HEX] [--stride HEX]
                           [--block-limit N] [--state STATE] [--health PID]
                           [--health-every S] [--wait-minutes M]
                           [--label TEXT] [--plan-only] [--dry-run]
                           [--format ALFID|kwp] [--session] [--mode HEX]
                           [--throttle-ms THROTTLE_MS] [--yes] [--wican WICAN]
                           [--transport {slcan-tcp,wican-ws,elm327-tcp}]
                           [--no-fallback] [--wait] [--elm-timeout MS]
                           [--timeout SECONDS] [--no-learn-frames] [--json]
                           [--verbose] [--timings] [--reboot] [--unsafe]
                           [--force]
                           [ECU]

Read the readable memory of one ECU into one dump, unattended. The run maps the space (the readable regions ecus/ records for its software; else --range or the whole space of a memory format with addresses of 3 bytes or fewer, mapped like `scan memory` and written back to ecus/), finds the flash size and any aliasing, surveys which areas hold data, shows the plan with its time estimate and asks before it reads (--yes to skip). It stops after the map when the ECU answers every address of that default space: such an ECU does not check the range, so name its memory with --range. sparse reads the data areas in full and samples the erased ones; --thorough reads every byte twice. The block adapts to errors within the ECU's max_block and --block-limit. A silent ECU, a failed health or state check or a dropped link pauses the job; it reads on by itself when the checks pass within --wait-minutes, and is otherwise saved for --resume. A resume needs the same software build and re-reads the first and the last two extents first. The report has the stability checks, the fault codes against the baseline of the ECU and its bus neighbours, and where the ECU's identity strings sit in the image. Only ReadMemoryByAddress reads memory; nothing is written.

positional arguments:
  ECU                   ECU name or TX id (not with --resume)

options:
  -h, --help            show this help message and exit
  --resume DUMP         Read on in an unfinished job (id, prefix or path)
  --thorough            Read every readable byte, twice (default: sparse, the
                        data areas in full and the erased areas sampled)
  --range START-END[,…]
                        Map these hex ranges first (default: the readable
                        regions ecus/ records for the ECU's software, else the
                        format's whole space if it has addresses of 3 bytes or
                        fewer)
  --step HEX            Map: probe every HEX bytes before bisecting (default
                        1000 with --range; about 256 probes across the default
                        space)
  --stride HEX          Survey one sample every HEX bytes (default 1000)
  --block-limit N       Largest read (default and maximum: the ECU's
                        memory.max_block, else 64)
  --state STATE         A vehicle state that must hold while the run reads
                        (its when: predicate)
  --health PID          The ECU PID read to check its health (default: its
                        first active PID)
  --health-every S      Check health and state every S seconds while reading
                        (default 30)
  --wait-minutes M      How long a paused run waits for the checks to pass
                        again (default 15)
  --label TEXT          A label for the dump
  --plan-only           Map and survey, print the plan, read nothing
  --dry-run             Do not write a new map or block size to the ECU's
                        memory: section in ecus/
  --format ALFID|kwp    Memory format when the ECU declares none: a UDS ALFID
                        (24 = 2-byte size, 4-byte address) or kwp. Saved by
                        `canair memory set` or `canair scan memory`.
  --session             Open a diagnostic session first (--mode, else the
                        ECU's memory.session, else 03)
  --mode HEX            Session mode for --session
  --throttle-ms THROTTLE_MS
                        Delay in ms between reads (default 0)
  --yes, -y             Skip the confirmation before the first read
  --wican WICAN         WiCAN address: ap or IP (default: config
                        transport.host / default_wican=ap)
  --transport {slcan-tcp,wican-ws,elm327-tcp}
                        CAN transport: slcan-tcp (raw CAN), wican-ws (WiCAN
                        ELM327 WebSocket), or elm327-tcp (direct ELM327
                        adapter over TCP). Overrides the config
                        `transport.type` (default: slcan-tcp).
  --no-fallback         Don't auto-fall-back to other configured devices when
                        the selected one is unreachable (see config
                        transport.fallback).
  --wait                Keep retrying to reach the device indefinitely, then
                        start as soon as it comes online (Ctrl-C to stop). For
                        'monitor', also reconnects forever if the connection
                        drops mid-session (auto-failover to another same-
                        transport device is bounded by default; --wait makes
                        it unbounded).
  --elm-timeout MS      ELM327 ECU response timeout in ms (sent as ATSTxx
                        after init)
  --timeout SECONDS     Overall UDS response timeout in seconds (default 3.0
                        ELM / 2.0 raw). Overrides any per-ECU
                        response_timeout_ms for the whole run.
  --no-learn-frames     Don't write response_frames back into the profile's
                        ecus/ when this session confirms how many CAN frames a
                        PID's response occupies (the count that lets the
                        adapter answer without waiting out its full ECU
                        timeout). Use when reading a car the active profile
                        doesn't describe.
  --json                Output results as JSON
  --verbose, -v         Show raw transport traffic and expressions
  --timings             Print per-ECU/PID round-trip timing stats on exit (to
                        stderr)
  --reboot              Reboot WiCAN after session to restore AutoPID mode
                        (skipped on firmware v6, which resumes AutoPID by
                        itself)
  --unsafe              Bypass the dangerous-command blocklist: each refused
                        command asks for typed consent before it is sent.
                        Works only after the user sets safety.allow_unsafe to
                        true at a terminal (canair config set
                        safety.allow_unsafe true)
  --force               Ask a session already holding the connection to
                        release it, then wait for it

examples:
  canair memory image VCU --state CHARGING --plan-only
  canair memory image VCU --state CHARGING --label "vcu flash"
  canair memory image MCU --range 000000-0FFFFF --thorough
  canair memory image --resume VCU/20261108-101500-vcu-flash

canair memory dump

usage: canair memory dump [-h] [--block N] [--label TEXT] [--format ALFID|kwp]
                          [--session] [--mode HEX] [--throttle-ms THROTTLE_MS]
                          [--yes] [--wican WICAN]
                          [--transport {slcan-tcp,wican-ws,elm327-tcp}]
                          [--no-fallback] [--wait] [--elm-timeout MS]
                          [--timeout SECONDS] [--no-learn-frames] [--json]
                          [--verbose] [--timings] [--reboot] [--unsafe]
                          [--force]
                          ECU START-END[,…]

Read address ranges of one ECU into a new dump. The block size alternates
between N and N-1 bytes so a reply to the previous request is always caught by
its length; a block that does not come back whole is halved, after one more
try when the ECU's max_block says that size works. The block grows back,
doubling after 500 clean reads, never above --block (or max_block); errors add
throttle, which falls back to --throttle-ms and no lower. A refused range is
recorded as a gap with its NRC, and a locked one (securityAccessDenied) is
left alone, and so is one that refuses by silence. The dump is written to disk
as it is read, so a keypress (s or escape), Ctrl-C or a killed process keeps
what was read. Asks before the first read (--yes to skip).

positional arguments:
  ECU                   ECU name or TX id
  START-END[,…]         Hex address ranges

options:
  -h, --help            show this help message and exit
  --block N             Bytes per read (default: the ECU's memory.max_block,
                        else 64)
  --label TEXT          A label for the dump
  --format ALFID|kwp    Memory format when the ECU declares none: a UDS ALFID
                        (24 = 2-byte size, 4-byte address) or kwp. Saved by
                        `canair memory set` or `canair scan memory`.
  --session             Open a diagnostic session first (--mode, else the
                        ECU's memory.session, else 03)
  --mode HEX            Session mode for --session
  --throttle-ms THROTTLE_MS
                        Delay in ms between reads (default 0)
  --yes, -y             Skip the confirmation before the first read
  --wican WICAN         WiCAN address: ap or IP (default: config
                        transport.host / default_wican=ap)
  --transport {slcan-tcp,wican-ws,elm327-tcp}
                        CAN transport: slcan-tcp (raw CAN), wican-ws (WiCAN
                        ELM327 WebSocket), or elm327-tcp (direct ELM327
                        adapter over TCP). Overrides the config
                        `transport.type` (default: slcan-tcp).
  --no-fallback         Don't auto-fall-back to other configured devices when
                        the selected one is unreachable (see config
                        transport.fallback).
  --wait                Keep retrying to reach the device indefinitely, then
                        start as soon as it comes online (Ctrl-C to stop). For
                        'monitor', also reconnects forever if the connection
                        drops mid-session (auto-failover to another same-
                        transport device is bounded by default; --wait makes
                        it unbounded).
  --elm-timeout MS      ELM327 ECU response timeout in ms (sent as ATSTxx
                        after init)
  --timeout SECONDS     Overall UDS response timeout in seconds (default 3.0
                        ELM / 2.0 raw). Overrides any per-ECU
                        response_timeout_ms for the whole run.
  --no-learn-frames     Don't write response_frames back into the profile's
                        ecus/ when this session confirms how many CAN frames a
                        PID's response occupies (the count that lets the
                        adapter answer without waiting out its full ECU
                        timeout). Use when reading a car the active profile
                        doesn't describe.
  --json                Output results as JSON
  --verbose, -v         Show raw transport traffic and expressions
  --timings             Print per-ECU/PID round-trip timing stats on exit (to
                        stderr)
  --reboot              Reboot WiCAN after session to restore AutoPID mode
                        (skipped on firmware v6, which resumes AutoPID by
                        itself)
  --unsafe              Bypass the dangerous-command blocklist: each refused
                        command asks for typed consent before it is sent.
                        Works only after the user sets safety.allow_unsafe to
                        true at a terminal (canair config set
                        safety.allow_unsafe true)
  --force               Ask a session already holding the connection to
                        release it, then wait for it

canair memory ls

usage: canair memory ls [-h] [--json] [ECU]

positional arguments:
  ECU         Only this ECU's dumps

options:
  -h, --help  show this help message and exit
  --json      Output as JSON

canair memory show

usage: canair memory show [-h] [--range START-END] [--json] DUMP

positional arguments:
  DUMP               A dump id (from `memory ls`), prefix or path

options:
  -h, --help         show this help message and exit
  --range START-END  Hex-dump this
  --json             Output as JSON

canair memory diff

usage: canair memory diff [-h] [--min-run MIN_RUN] [--json] DUMP_A DUMP_B

Compare two dumps of one ECU and list the runs of addresses whose bytes
differ, with both values. Dumps of two software builds are refused: a reflash
moves what an address holds.

positional arguments:
  DUMP_A             The first dump (id, prefix or path)
  DUMP_B             The second dump, of the same ECU

options:
  -h, --help         show this help message and exit
  --min-run MIN_RUN  Only runs of at least N changed bytes
  --json             Output as JSON

canair memory export

usage: canair memory export [-h] [--format {ihex,srec,bin}] [--fill HEX]
                            [-o FILE]
                            DUMP

Write a dump for other tools. Intel HEX and S-record keep its holes; a raw
binary needs --fill for one. The file holds ECU memory: keep it local.

positional arguments:
  DUMP                  A dump id (from `memory ls`), prefix or path

options:
  -h, --help            show this help message and exit
  --format {ihex,srec,bin}
                        Intel HEX, Motorola S-record or raw binary (default
                        ihex)
  --fill HEX            bin: the byte to write into holes
  -o, --output FILE     Output file (default stdout)

canair memory set

usage: canair memory set [-h] [--format ALFID|kwp] [--max-block N]
                         [--session HEX] [--clear {format,max_block,session}]
                         [--dir DIR] [--no-validate]
                         ECU

Set the memory: section of an ECU: the format its reads take, the largest
block that comes back whole and the session they need. `canair scan memory`
writes the same fields from what it finds.

positional arguments:
  ECU                   ECU name or TX id

options:
  -h, --help            show this help message and exit
  --format ALFID|kwp    UDS ALFID (e.g. 24) or kwp
  --max-block N         Largest read in bytes
  --session HEX         Session mode the reads need ("03")
  --clear {format,max_block,session}
                        Drop a field (repeatable)
  --dir DIR             ecus/ directory (default: active profile)
  --no-validate         Skip the post-edit schema validation gate