Offline testing with ELM327-Emulator¶
You can drive canair with no dongle and no car. Point canair at
ELM327-Emulator. This Python program emulates an
ELM327 adapter (multi-ECU, ISO-TP, KWP2000) and serves the same ELM327 protocol that canair speaks.
It helps you to try commands, to develop, or to debug the
elm327-tcp
transport without hardware. ECU means electronic control unit. ISO-TP is the transport protocol of
the Controller Area Network (CAN). KWP2000 is Keyword Protocol 2000.
1. Install the emulator¶
The emulator ships a legacy build that imports pkg_resources at build time. Recent setuptools
no longer provides it. Install an older setuptools first, and install the emulator without build
isolation:
The emulator is deliberately not a canair dependency, because its build breaks a clean
uv sync. This is a one-off manual step.
2. Start it in TCP mode¶
The command serves on a Transmission Control Protocol (TCP) port. 35000 is the default port of
canair for elm327-tcp. If you use it, you can skip the port config below.
Run it in its own terminal
elm is an interactive program. It drops you at a CMD> prompt. Run it in a dedicated
terminal and leave it in the foreground. If you run it in the background or close its stdin,
its read-eval-print loop (REPL) hits end-of-input and exits. Its -n mode also serves
one client at a time (see the reconnect note below).
3. Point canair at it¶
There are two ways to do this. The difference matters because of one limitation: the port is
config-only. --wican takes a bare host (no host:port), and there is no --port flag. The
flags-only route therefore works only on the default port 35000.
Use 127.0.0.1, not localhost. localhost can resolve to IPv6 ::1 while the emulator
listens on IPv4. This gives a spurious "not reachable".
canair config set devices.emu.host 127.0.0.1
canair config set devices.emu.transport elm327-tcp
canair config set devices.emu.port 35000 # required for a non-35000 -n port
canair config set default_wican emu
canair status # confirm it's reachable
Switch back to your real device later with canair config set default_wican <alias>
(or canair config unset default_wican).
4. Use the test profile for real reads¶
The emulator answers generic On-Board Diagnostics II (OBD-II) at the ECU header 0x7E0. It
does not answer the manufacturer data identifiers (DIDs) of a specific car. The reads of the
bundled Ioniq profile (BMS:2101) therefore get NO DATA. The repo ships a small
elm327-emulator profile for exactly this case. The profile has an ENGINE ECU (0x7E0)
with standard Mode-01 parameter identifiers (PIDs) that decode against the emulator.
P=tests/fixtures/profiles/elm327-emulator
canair --profile $P read ENGINE:010F --transport elm327-tcp --wican 127.0.0.1 # intake temp
canair --profile $P read "ENGINE:010D ENGINE:010C ENGINE:010F" \
--transport elm327-tcp --wican 127.0.0.1
The init string of the profile disables echo and headers (ATE0;ATH0;…). It also filters to the
primary ECU (ATCRA7E8), so responses are the bare, un-duplicated Unified Diagnostic Services
(UDS) payload. The profile is a good template if you want to add more PIDs. canair handles
standard OBD-II PID keys, including all-decimal ones with a leading zero such as 0105.
Reconnect gap & --wait¶
The emulator rebuilds its TCP listener after each client disconnects. For a brief window, the
emulator refuses connections. Back-to-back canair commands can therefore occasionally fail with
"connection refused". Retry, or add --wait (any live command). --wait blocks and retries
until the emulator is reachable, then starts:
What works, what doesn't¶
The emulator is a functional stand-in, not a real car:
- Good for: exercising the
elm327-tcptransport end to end (connect, ELM init, AT commands, single-frame OBD/UDS reads), scripting, and checks of the kind that continuous integration (CI) runs. - Generic OBD-II only: its scenarios answer standard Mode-01/09 PIDs, not the manufacturer
DIDs of a profile. Use the
elm327-emulatortest profile (above), or extend the emulator with a custom scenario (elm -s <scenario>). - Flaky PIDs:
0100("supported PIDs") simulates a multi-secondSEARCHING…bus-init and is unstable over TCP. The emulator does not reliably reassemble multi-frame ISO-TP (the vehicle identification number,0902) over headers-off TCP. Prefer stable stateless PIDs (010C,010D,010F,0105,ATRV).
Automated tests¶
canair ships an opt-in integration test (tests/integration/test_elm327_emulator.py). It
spawns the emulator on an ephemeral port and drives it through the real elm327-tcp engine. It
auto-skips when the emulator is not installed, so the normal uv run pytest stays device-free
and fast. To run it, install the emulator (step 1). Device-free unit tests
(tests/transport/elm327/test_elm327_tcp.py) also guard the decode expressions of the
elm327-emulator profile.
uv sync uninstalls the emulator
The emulator is deliberately not a dev dependency, because its legacy build needs
setuptools<80. It therefore lives outside uv.lock, and uv sync prunes anything that is
not in the lock. After a sync, the test reports one SKIPPED instead of failing. That is easy
to miss. Re-run step 1 to get the emulator back.