canair documentation¶
CLI for reverse engineering CAN/OBD diagnostics over the air with a WiCAN dongle.
canair uses a WiCAN WiFi dongle to work with the data of a vehicle in two domains:
- Diagnostics. canair sends requests to the electronic control units (ECUs) of the car. It uses the UDS (Unified Diagnostic Services) and KWP2000 (Keyword Protocol 2000) protocols.
- Raw broadcast CAN. The car sends these Controller Area Network (CAN) frames on its own. canair listens passively, or imports frames from external logs and DBC (CAN database) files.
canair helps you capture, decode, correlate and document this data. The result is a vehicle profile that you can share.
The monitor: canair's main screen¶
canair monitor polls the ECUs you choose and shows their decoded signals live,
while the car drives, charges or sleeps. From the same screen you record the session, label it,
check and edit signal definitions, and open diagnostic sessions. Every command is in its menus
and its command palette, and it works on a phone over SSH.

Tour the monitor → The recording replays a real drive of the bundled Ioniq profile through the real monitor.
Why canair?¶
- Evidence stays with the definition. Most tools store only the PID, DID and signal definitions. canair also stores the captures that support each definition. Anyone can check a definition against the data, and the community can decode together. A definition without proof has little worth.
- Two kinds of data in one profile. canair combines request/response diagnostics (OBD-II, UDS, KWP2000) with raw broadcast CAN frames (for example from DBC files). Both kinds use the same profile and the same analysis tools. What you know about a signal in one kind of data helps you find the same signal in the other.
- Made for humans and agents. Helpers import and analyze both kinds of captures. Every
capability is a subcommand that you can script, with structured output (
--json). A person or an AI coding agent can use it in the same way. The reverse-engineering workflows are available as agent skills. - Shareable without copied definitions. Profiles come from captures of real cars. They do not copy the definitions of a dealer scan tool. People can share them without copying the content of a vendor tool. This opens vehicle maintenance and diagnostics to a wider community.
See a real car's data, right in your browser¶
The profile explorer shows a whole vehicle profile. You can plot what the car reported. Click an ECU on the CAN bus map. Put signals from different ECUs on one timeline. The explorer shows which signals move together. You do not install or connect anything.
Open the explorer → Try it on the 2017 Ioniq: 30 ECUs, 600+ signals and 100+ recorded sessions.
Browse the buses
See which ECU is on which CAN segment. Open an ECU to see its PIDs, signals, actuators
and research leads. Each one links to its YAML.
Plot signals from any ECU together
One picture shows a drive, a 60 kW fast charge and another drive. It plots battery
power, speed and state of charge, with the vehicle states above.
Find what hides in the data
One strip shows every signal that moved in a session. Similar signals are side by side.
Select a signal to see what follows it. Zoom to a moment to see what reacted.
Where do I start?¶
Answer these questions in order. Take the first path that fits.
- Do you have a WiCAN dongle and a car with an OBD-II port, and canair is not installed yet? Read Install. You install canair, connect the dongle and read live data from the bundled example car in a few minutes. Then watch it in the monitor.
- Does something not work? Read Troubleshooting.
- Is your car one of the bundled cars? Read Bundled profiles. The Ioniq Electric profile is the most complete. Each page lists the ECUs, decoded signals and IOControl actuators.
- Is your car not bundled? Read Bring your own car. This is the main journey. It takes you from an empty profile to decoded, verified signals.
- Do you want to share what you decoded? Read Define & verify, then Share your profile. A whole profile, a few decoded signals or a fix all help other owners of the same car. See also Contributing.
- Do you want to learn from a real hunt? Read the case studies. They show real investigations from start to end, including the wrong turns. One example is finding the hidden AC input voltage.
The command list is in the CLI reference, and Concepts explains how canair works.
What you need¶
- A WiCAN dongle, Pro or classic (non-Pro). Most features work on both. A few are Pro-only.
- A vehicle with an OBD-II port.
uvto install and run canair.
A note on safety¶
Reading data is safe. canair only reads unless you tell it to actuate hardware, and every action that changes state asks for confirmation first. However, work on the CAN bus of a vehicle has real risk. Safety explains what canair does and does not do, and why.