Reading car fault codes from a web page: Web Serial and Web Bluetooth vs. cheap ELM327 clones
A cheap ELM327 adapter, Chrome, and two browser APIs are enough to read engine fault codes without installing anything. The protocol part is small; most of the code deals with how real adapters and real browsers misbehave, and that part is what this post covers. Disclosure: I built diagnost.net, and everything below comes from its client-side code ( elm.js , obd.js , kline.js ). It is served to…
To read engine fault codes without installing anything, a cheap ELM327 adapter, Chrome, and two browser APIs are sufficient. The protocol part is relatively simple, while the rest of the code deals with adapting to real adapters and browsers behaving differently. The source code for this can be found on the diagnost.net website.
Web Serial and Web Bluetooth APIs are supported in Chrome and Edge, allowing the adapter to be accessed via USB or BLE. However, Bluetooth LE ELM327 adapters are not compatible with the page. Classic Bluetooth ELM327 adapters using Serial Port Protocol (SPP) are also not supported. Other platforms like Windows, macOS, Linux, and Android support these APIs, but Safari and Firefox do not expose them due to iOS restrictions. Therefore, Chrome on iOS also shares the same limitation as Safari.
The page uses two transports: elm.js for communication with the ELM327 over USB or BLE, and kline.js for direct communication with the car through a dumb USB cable. Both transports expose the same function called 'query'.
The OBD-II layer, implemented in obd.js, reads various types of codes such as stored codes, pending codes, freeze frame data, sensors, VIN, and clears codes. This layer is independent of the underlying hardware and serves as a single interface for all hardware-specific processes.
Web Serial's picker feature requires a fresh user gesture via navigator.serial.requestPort(). Opening the picker only after performing asynchronous tasks can lead to SecurityErrors if the gesture has expired. To avoid this issue, the code checks for available adapters at several baud rates before requesting the picker.
The actual reading process involves a loop that continuously reads data from the port using port.readable.getReader(). The decoded data is then transmitted to the user. It is essential to discard any characters before a new command starts to prevent errors from affecting the subsequent responses.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.