Connect your dongle¶
canair reaches the CAN bus through an adapter: a WiCAN dongle or a generic ELM327 clone. It never talks to the CAN bus directly. This page connects your computer to the dongle and checks that the dongle works.
1. Plug in and power up¶
- Plug the WiCAN into the OBD-II port of the vehicle.
- Switch the car to ignition or accessory mode, so the ECUs are awake.
The dongle takes its power from the port.
2. Get on the same network¶
You have two options:
- Access-point mode. The WiCAN broadcasts its own
WiCAN_xxxxWiFi network. Join this network. The dongle is at192.168.80.1. This is the address that canair uses when you configure none. - Your LAN. Use the WiCAN web UI to connect the dongle to your home WiFi. The dongle gets a normal LAN IP address, and you point canair at it. This setup is more convenient for repeated sessions.
3. Tell canair the address¶
Edit ~/.config/canair/config.yaml, or use canair config set:
Add --wican home|vpn|<ip> to any command to pick a device. Each device can have its own
transport:
If the chosen device is unreachable, canair falls back to the other devices. Add --no-fallback
to a command to turn this off. canair status follows the same fallback, so it reports the device
that a live command would use.
Add --wait to any live command to wait until the device is online. With
canair monitor @driving --save --wait, canair also reconnects when the link drops. The
config reference documents every key.
4. Pro vs. classic¶
canair supports the WiCAN Pro and the regular classic (non-Pro) WiCAN. The default is
pro. If you have a classic, tell canair. Then canair refuses Pro-only features with a clear
message, instead of failing against the device:
Pro-only features:
- AutoPID device sync (
wican autopid upload,downloadanddiff) wican mode set- the
wican-wsWebSocket transport
All the core reverse-engineering features work on both models over the default raw-SLCAN transport. These features are query, scan, discover, decode, DTCs, sniff, and AutoPID JSON generation.
5. Confirm it's working¶
canair config # config locations, WiCAN model + addresses, resolved transport
canair status # what am I talking to, in what mode, is it reachable?
If canair status reports a reachable device, you are ready.
- To try the bundled example car, go to Read live data.
- To build a profile for your own car, go to Bring your own car.
If you use WiCAN firmware v6 or a generic ELM327 adapter, read the two sections below first.
Firmware compatibility¶
canair is built and tested against WiCAN firmware 4.x, specifically 4.50 to 4.52. Version
4.52 changes only the OBD chip firmware that it bundles (V2.3.24). canair has not measured that
chip firmware yet. A 4.x version outside this range still works, with a one-line warning.
WiCAN Pro firmware v6 (6.0.0, in beta) is a rewrite, not an update. Before canair uses a
4.x-only interface, it asks the device which generation it runs. It sends read-only GET
requests: first /api/info, then /check_status (unless /api/info showed v6). If the interface
cannot work, canair refuses it or warns you, and it gives the fix.
| On firmware v6 | Result |
|---|---|
elm327-tcp transport |
Works |
wican-ws transport |
Refused |
slcan-tcp transport (the default) |
Warns, then tries |
sniff --listen-only |
Refused |
wican mode show/set |
Refused |
wican autopid upload/download/diff |
Refused |
--reboot |
Skipped |
Details for each row:
elm327-tcp. v6 serves a plain ELM327 socket on port 35000 by default. The socket is shared. AutoPID (if enabled) takes the chip back after 10 s without a command. canair notes this whentransport.firmware_checkisalways. By default, canair does not probeelm327-tcphosts, because they are usually clones.wican-ws. v6 has no/wsterminal. Useelm327-tcp.slcan-tcp. A stock v6 device serves no SLCAN until you enable three settings (below).sniff --listen-only. v6 ignores the listen-only command of SLCAN. Setcan_manager.silenton the device instead. If canair cannot confirm the generation, it warns that listen-only is not guaranteed.wican mode show/set. v6 has no protocol mode.wican autopid upload/download/diff. v6 changed the AutoPID format and API, and canair cannot sync them yet.autopid writealso generates the v6 table (autopid-v6.json, for6.0.0-beta.3and later). You can load it through the web UI of the device (Share). If canair cannot confirm the generation, an upload goes ahead with a warning.--reboot. v6 resumes AutoPID by itself.
On v6, point canair at the ELM327 socket:
canair config set devices.home.transport elm327-tcp
canair config set devices.home.port 35000
canair status # confirm it's usable
To use slcan-tcp on v6, enable all three of these settings on the device. Then submit them. The
device reboots.
socket_manager: theslcan0server (TCP 3333).bridge_manager: a bridge fromcantoslcan0with the translatorslcan.can_manager: enabled.
If the bridge is missing, or can_manager is off, the SLCAN port accepts the connection and then
discards everything without a message. Every ECU then looks dead.
canair status shows the generation, version and build that it found. It exits with code 2
when the selected transport cannot work on that firmware.
canair config set transport.firmware_check false turns the check off for live commands.
status still reports it. The value always also checks elm327-tcp hosts. See
the reference.
Before upgrading a WiCAN to v6
An upgrade from 4.x erases the saved configuration, the stored files and the logs of the device. To go back, you upload the 4.x image by hand. The device then starts with factory defaults.
Using a generic ELM327 clone (no WiCAN)¶
If you have no WiCAN, a generic WiFi ELM327 adapter works over the elm327-tcp
transport. Examples are Kiwi, vLinker, OBDLink, or any no-name $10 clone. The transport is a plain
TCP socket to the ELM327 terminal of the dongle. You do not need a WiCAN.
canair config set devices.clone.host 192.168.0.10 # the dongle's WiFi IP
canair config set devices.clone.transport elm327-tcp
canair config set devices.clone.port 35000 # most WiFi clones use 35000
canair config set default_wican clone
canair status # confirm it's reachable
First join the WiFi network of the dongle. Many clones host their own access point.
elm327-tcp and wican-ws share one ELM327 protocol engine. Every canair command works the same
way, and the dongle does the ISO-TP. A generic clone has no HTTP config API. For this reason,
canair status probes the ELM socket directly to report whether the transport is reachable.
To point elm327-tcp at a WiCAN with firmware v6, set
transport.firmware_check to always. Then status also shows the firmware.
Third-party dongles are best-effort
The WiCAN is the recommended and best-tested adapter. The firmware quality of generic ELM327 clones varies widely. Cheap clones often fail on newer vehicles, which use long multi-frame ISO-TP responses and extended (29-bit) addressing. If reads are flaky or truncated, or a clone cannot reach an ECU, the adapter is usually the cause, not canair. Try a WiCAN before you file a bug.
To try canair with no hardware at all, see Offline testing with ELM327-Emulator.