commit c393353ecea879978e682bc403805d6379852f73
parent 0d0d610794c751e61617031f1949f37b6bf2a728
Author: Daniel Barlow <dan@telent.net>
Date: Mon, 12 Jan 2026 17:57:46 +0000
flesh README out a little
Diffstat:
| M | README.md | | | 47 | ++++++++++++++++++++++++++++++++++++++++++++++- |
1 file changed, 46 insertions(+), 1 deletion(-)
diff --git a/README.md b/README.md
@@ -1,4 +1,49 @@
# Eculocate
Read data from the K-line of a Honda motorbike ECU and publish it
-using UDP over Wifi
+using UDP over Wifi.
+
+Comprises:
+
+* some code for an ESP32-C3 wich can be connected (via level
+shifters and other electronics, don't plug it straight in) to the
+bike's ECU,
+
+* a very PoC implementation of an android client, using Termux
+
+## Building
+
+The repo is split into two crates in a cargo workspace: code in
+ecu-portable can be built and run using the native compiler, hence is
+unit-testable, and code in ecu-esp32 depends on all the esp32 gubbins
+so you can test it only by running it.
+
+```
+ cargo test -p ecu-portable --target x86_64-unknown-linux-gnu
+ SSID=my-wifi PASSWORD="my-wifi-password" cargo run --release
+```
+
+
+## How it works
+
+The ESP32 is connected to the diagnostic port of the ECU and can
+interrogate it to dump its "tables". This is based on "K-line", a 1
+wire 10400 baud serial connection operating with 12V logic.
+
+It connects to a wifi network (wifi credentials are presently
+hardcoded) and listens on a UDP socket for incoming subscription
+requests. When it receives a subscription request, it starts to
+periodically query the ECU for the requested tables and sends the
+value using UDP back to the subscriber.
+
+To avoid using hardcoded IP addresses, it uses multicast DNS/DNS
+service discovery to advertise itself as providing the
+`_keihin._udp.local" service, so a client can use
+zeroconf/bonjour/avahi to find where it is.
+
+For the moment, there is no security on the UDP service. Until and
+unless that canges, you probably shouldn't tell it to connect to
+untrusted wifi networks.
+
+There is a prototype/example client in android-termux-client/. Consult
+the README in that directory for details.
