canair

CLI for reverse engineering CAN/OBD diagnostics over-the-air using a WiCAN dongle

canair interfaces with a WiCAN OBD-II WiFi dongle to work with a vehicle's data across two domains: request/response diagnostics (querying ECUs over UDS and KWP2000) and the raw broadcast CAN the car emits on its own (passively sniffed, or imported from external logs and DBCs). On top of both it gives you a full analysis suite — capture, decode, statistically correlate, and hunt down which byte carries which signal — then turns the results into a WiCAN vehicle profile or shareable documentation.

Everything ships as a single installable CLI, canair. Vehicle data lives in a profile bundle; the repo ships profiles under profiles/ (the mature profiles/ioniq-2017/, a 2017 Hyundai Ioniq Electric, is the reference example). The tooling is vehicle-agnostic — build one for your car (see Bring your own car).

Built for both human and agentic use. Every capability is a composable, scriptable subcommand with structured (--json) output, so it works equally well driven by a person at a terminal or by an AI coding agent (e.g. Claude). The reverse-engineering workflows are captured as agent skills in .claude/skills/.

Both the WiCAN Pro and the classic (non-Pro) WiCAN are supported over the default raw-SLCAN transport. A few features are Pro-only (AutoPID device sync, wican mode set, the wican-ws transport); set wican_model: classic and canair cleanly refuses them. See connecting your dongle.

📖 Documentation: philipkocanda.github.io/canair — Getting started · Bring your own car (the full new-vehicle walkthrough) · Concepts · Reference. (Source in docs/.)

	Analyzing/decoding a captured signal with canair decode <query> --plot
	Byte-level capture diffs with canair captures <query> --diff (also the default view for canair read on a live vehicle)

canair never talks CAN directly — it reaches the bus through an adapter via one of three explicitly-selected transports: slcan-tcp (default; raw SLCAN over TCP, any WiCAN, canair does ISO-TP+UDS), wican-ws (Pro only; ELM327 over WebSocket, the dongle does ISO-TP), or elm327-tcp (a generic ELM327 clone — Kiwi/vLinker/OBDLink, or the ELM327-Emulator — over a plain TCP socket, no WiCAN needed). The WiCAN is recommended and best-tested; generic clones are best-effort and less likely to work on newer vehicles (long multi-frame ISO-TP, extended addressing).

flowchart LR
    subgraph host["Your computer — canair"]
        cli["canair CLI<br/>transport: wican-ws | slcan-tcp"]
        defs["Profile PID/DID defs<br/>+ captures"]
        isotp["client-side ISO-TP + UDS<br/>(pipelined; slcan-tcp only)"]
    end

    subgraph wican["WiCAN dongle — one protocol at a time"]
        ws["ELM327 WebSocket terminal<br/>ws://HOST/ws"]
        slcan["SLCAN socket<br/>tcp://HOST:PORT"]
    end

    subgraph car["Vehicle (OBD-II port)"]
        bus["CAN bus"]
        ecus["ECUs<br/>BMS · VCU · MCU · IGPM · BCM …"]
    end

    cli -->|"wican-ws:<br/>ELM327 AT + UDS/KWP2000 hex"| ws
    cli --> isotp
    isotp <-->|"slcan-tcp:<br/>raw CAN frames"| slcan
    ws <-->|"dongle does ISO-TP"| bus
    slcan <--> bus
    bus <--> ecus
    defs -.->|"decode responses"| cli

Responses are decoded into named signals using the active profile's definitions. See Architecture for the transports, protocols (UDS / KWP2000 / ISO-TP), and the two data domains.

All functionality is exposed as canair <subcommand>; run canair <cmd> --help for details, or see the CLI reference.

Live device

Analysis

Authoring

Import / export

Setup

The byte-index converter canair bix (WiCAN ↔ ISO-TP ↔ Torque ↔ OBDb) and canair completion round out the utilities.

Separate package wican-cli handles WiCAN device management (config, sleep/power, status, reboots). pip install wican-cli.

You need a WiCAN dongle (Pro or classic), a car with an OBD-II port, and uv.

git clone https://github.com/philipkocanda/canair.git
cd canair
uv tool install .                       # install the `canair` CLI
canair config set devices.home.host 192.168.1.100
canair config set default_wican home
canair status                           # is the device reachable?
canair discover                         # list every ECU on the bus (any car)
canair read BMS:2101                    # read a PID (Ioniq profile)
canair monitor @charging                # monitor a saved selector group (see `canair groups`)

Full setup — installing, connecting the dongle (Pro vs classic, AP vs LAN), tab-completion, and your first read — is in Getting started.

canair checks once a day for a newer release (offline-safe, never blocking) and points you at the changelog; upgrade in place with canair update (checks out the latest release tag + reinstall). See staying up to date.

You don't need to be a CAN expert to start. Reading is safe and free — canair only reads unless you explicitly actuate something, and every state-changing action confirms first. Interacting with a vehicle bus still carries real risk: see the Warning.

The bundled Ioniq profile is just an example. To reverse-engineer your car, build your own profile and let the discovery/scan commands populate it as you go:

flowchart LR
    A["profile create"] --> B["discover --register"]
    B --> C["identity"]
    C --> D["scan"]
    D --> E["capture<br/>(--save while driving/charging)"]
    E --> F["decode · correlate · hunt · investigate"]
    F --> G["pids upsert-param"]
    G --> H["coverage · verify"]
    H --> I["wican autopid write<br/>· share the profile"]

Each step has a dedicated page under Bring your own car: create · discover · identity · scan · capture · analyze · define & verify · share.

A profile bundles one vehicle's data — ecus/ (one file per ECU, the source of truth), profile.yaml, captures/, references/, and generated out/. The repo ships one or more profiles under profiles/ (the mature profiles/ioniq-2017/ is the reference example). Manage them with canair profile list / create / use, and select with --profile / CANAIR_PROFILE / default_profile. See Bundled profiles for the full list and Profiles for the layout, precedence, and discovery order.

The ioniq-2017 profile makes canair a ready-to-use diagnostics toolkit for the 2017 Hyundai Ioniq Electric (28 kWh, AE platform) — read live battery, motor, charging, climate, and body data over WiFi with no dealer tools. It maps 30 ECUs and 350+ signals (the majority verified on the car), including:

• Battery SOC / voltage / current / power, all 96 individual cell voltages, and State of Health
• Motor gear, torque, and temperatures; vehicle speed and individual wheel speeds (from the ESC module)
• Charging state (AC / DC CCS) and charge-port lock
• On-board charger AC/DC (input/output) voltage and current, EVSE pilot current.
• Electric power steering, tyre pressures/temperatures, HVAC/climate, and body controls (locks, trunk, lights, indicators)
• IOControl actuators (UDS 0x2F) for hardware you can safely toggle — lights, horn, locks, charge-cable lock, mirrors, wipers (all auto-release when the session ends)

See the bundled Ioniq profile for the full tour, or the per-ECU files under profiles/ioniq-2017/ecus/.

Reverse-engineered your car? Please contribute it back! A profile you share means the next person with the same vehicle starts with a head start instead of from zero — it's how canair grows beyond one car. Whole profiles, a few decoded signals, corrected offsets, or fixes to canair itself are all welcome as pull requests. See CONTRIBUTING.md and Bring your own car → Share.

Public domain — see LICENSE (Unlicense).

Interacting with your vehicle's CAN bus and ECUs can damage your car, trigger faults, or leave it in an unsafe state. Use this software entirely at your own risk. You are solely responsible for any consequences.