Skip to content

canair action

usage: canair action [-h] [--json] {list,run,add,set,rm} ...

Profile-defined actions: named requests for make-specific things such as putting the car to sleep. Each action declares live reads and a condition that must be TRUE before it is sent; its requests still pass the command blocklist, which only a code-owned profile quirk can relax for that exact request. An action may also inject a crafted broadcast CAN frame (slcan-tcp only), gated by safety.allow_frame_injection and a per-frame bit mask.

positional arguments:
  {list,run,add,set,rm}
    list                List the actions (default)
    run                 Check the car and send an action (live)
    add                 Add an action
    set                 Change fields of an action
    rm                  Remove an action

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

examples:
  canair action                                  # list the profile's actions
  canair action run sleep --dry-run              # read + check the car, send nothing
  canair action run sleep                        # check, confirm, send
  canair action run sleep --yes                  # no prompt (scripts, agents)
  canair action add sleep --read IGPM:22BC03 \
      --require "IGPM.IGN1_SWITCH == 0" --request functional:10D1:none
  canair action add ig3-read --read IGPM:22BC07 --require "IGPM.IG3_RELAY_OUTPUT == 0" \
      --hold IGPM --request IGPM:2FBC4403 --wait 3 --then-read VCU:2101 \
      --release IGPM:2FBC4400
  canair action run ig3-read --save --label 'IG3 wake read'   # keep the reads
  canair action add remote-climate-start --read VCU:2101 \
      --require "VCU.VCU_IG3_ON == 1" \
      --frame "id=0x587,data=1000000000000000,mask=100000000000000F,counter=7:low,rate_ms=100,duration_s=30"
  canair action set sleep --description "Put every ECU to sleep"
  canair action rm sleep

canair action list

usage: canair action list [-h] [--json]

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

canair action run

usage: canair action run [-h] [--yes] [--dry-run] [--save] [--label TEXT]
                         [--state TEXT] [--notes TEXT] [--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]
                         NAME

Read the action's signals live, refuse unless its condition is TRUE, ask for
confirmation (unless --yes), re-check, then send its requests. --unsafe has no
effect on an action.

positional arguments:
  NAME                  Action name (see `canair action`)

options:
  -h, --help            show this help message and exit
  --yes, -y             Skip the confirmation prompt
  --dry-run             Read and check the car, but send nothing
  --save                Save the action's then: reads to captures/
  --label TEXT          Session label for --save (default: 'action NAME', so
                        nothing is asked while the action holds an output)
  --state TEXT          Session state for --save
  --notes TEXT          Session notes for --save
  --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 action add

usage: canair action add [-h] [--description DESCRIPTION] [--read ECU:PID]
                         [--require EXPR] [--request TARGET:HEX[:none]]
                         [--frame SPEC] [--hold ECU[:MODE]]
                         [--then-read ECU[:PID]] [--wait SECONDS]
                         [--release TARGET:HEX[:none]]
                         name

positional arguments:
  name                  Action name (lower-cased)

options:
  -h, --help            show this help message and exit
  --description, -d DESCRIPTION
                        Human-readable description ('' clears it)
  --read ECU:PID        A PID to read live before sending (repeatable;
                        replaces the list on `set`)
  --require EXPR        Condition over ECU.SIGNAL values that must be TRUE to
                        send, e.g. 'IGPM.IGN1_SWITCH == 0 and IGPM.IGN2_SWITCH
                        == 0' (no 'or'/'not')
  --request TARGET:HEX[:none]
                        A request to send: an ECU name or 'functional', the
                        request hex, and ':none' when no reply is expected
                        (repeatable, sent in order; replaces the list on
                        `set`)
  --frame SPEC          A broadcast CAN frame to inject (slcan-tcp only; needs
                        safety.allow_frame_injection). SPEC is comma-separated
                        k=v: id=0x587,data=1000000000000000,mask=1000000000000
                        00F[,counter=7:low][,rate_ms=100][,count=N|duration_s=
                        S][,bus=NAME]. 'id' must be below 0x700 and every
                        'data'/counter bit must be inside 'mask' (repeatable;
                        replaces the list on `set`, --frame '' clears it)
  --hold ECU[:MODE]     Open a diagnostic session on ECU (MODE two hex digits,
                        default 03) before the requests and keep it alive
                        until the release is sent, as an IOControl needs
                        (repeatable; replaces the list on `set`, and --hold ''
                        clears it)
  --then-read ECU[:PID]
                        Read these after the requests, while the holds last
                        (repeatable; the mini-language selectors of `canair
                        read`; replaces the list on `set`)
  --wait SECONDS        Seconds to wait between the requests and the --then-
                        read reads (0-60)
  --release TARGET:HEX[:none]
                        A request sent at the end, also on Ctrl-C or an error,
                        that hands back what the requests drove. Required for
                        an IOControl that drives an output (repeatable;
                        replaces the list on `set`, and --release '' clears
                        it)

canair action set

usage: canair action set [-h] [--description DESCRIPTION] [--read ECU:PID]
                         [--require EXPR] [--request TARGET:HEX[:none]]
                         [--frame SPEC] [--hold ECU[:MODE]]
                         [--then-read ECU[:PID]] [--wait SECONDS]
                         [--release TARGET:HEX[:none]] [--no-then]
                         name

positional arguments:
  name                  Action name

options:
  -h, --help            show this help message and exit
  --description, -d DESCRIPTION
                        Human-readable description ('' clears it)
  --read ECU:PID        A PID to read live before sending (repeatable;
                        replaces the list on `set`)
  --require EXPR        Condition over ECU.SIGNAL values that must be TRUE to
                        send, e.g. 'IGPM.IGN1_SWITCH == 0 and IGPM.IGN2_SWITCH
                        == 0' (no 'or'/'not')
  --request TARGET:HEX[:none]
                        A request to send: an ECU name or 'functional', the
                        request hex, and ':none' when no reply is expected
                        (repeatable, sent in order; replaces the list on
                        `set`)
  --frame SPEC          A broadcast CAN frame to inject (slcan-tcp only; needs
                        safety.allow_frame_injection). SPEC is comma-separated
                        k=v: id=0x587,data=1000000000000000,mask=1000000000000
                        00F[,counter=7:low][,rate_ms=100][,count=N|duration_s=
                        S][,bus=NAME]. 'id' must be below 0x700 and every
                        'data'/counter bit must be inside 'mask' (repeatable;
                        replaces the list on `set`, --frame '' clears it)
  --hold ECU[:MODE]     Open a diagnostic session on ECU (MODE two hex digits,
                        default 03) before the requests and keep it alive
                        until the release is sent, as an IOControl needs
                        (repeatable; replaces the list on `set`, and --hold ''
                        clears it)
  --then-read ECU[:PID]
                        Read these after the requests, while the holds last
                        (repeatable; the mini-language selectors of `canair
                        read`; replaces the list on `set`)
  --wait SECONDS        Seconds to wait between the requests and the --then-
                        read reads (0-60)
  --release TARGET:HEX[:none]
                        A request sent at the end, also on Ctrl-C or an error,
                        that hands back what the requests drove. Required for
                        an IOControl that drives an output (repeatable;
                        replaces the list on `set`, and --release '' clears
                        it)
  --no-then             Remove the action's then: reads

canair action rm

usage: canair action rm [-h] name

positional arguments:
  name        Action name

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