Replace ASCII diagrams with Mermaid (architecture, FSM, timeline)
Added astro-mermaid integration for client-side rendering. Converted: composition diagram (flowchart), IbusHandler state machine (stateDiagram-v2), and OBD-II protocol timeline. Circuit schematic stays ASCII — Mermaid can't do pin-level schematics.
This commit is contained in:
parent
2aaa6e32a5
commit
f59cd9ac8b
@ -1,11 +1,13 @@
|
||||
import { defineConfig } from 'astro/config';
|
||||
import starlight from '@astrojs/starlight';
|
||||
import mermaid from 'astro-mermaid';
|
||||
|
||||
export default defineConfig({
|
||||
site: 'https://k-line.warehack.ing',
|
||||
telemetry: false,
|
||||
devToolbar: { enabled: false },
|
||||
integrations: [
|
||||
mermaid(),
|
||||
starlight({
|
||||
title: 'K-Line',
|
||||
description: 'BMW I/K-Bus + OBD-II K-line interface for ESP32 with PC817 optocoupler isolation',
|
||||
|
||||
1372
site/package-lock.json
generated
1372
site/package-lock.json
generated
File diff suppressed because it is too large
Load Diff
@ -17,6 +17,7 @@
|
||||
"dependencies": {
|
||||
"@astrojs/starlight": "^0.37.6",
|
||||
"astro": "^5.17.1",
|
||||
"astro-mermaid": "^1.3.1",
|
||||
"sharp": "^0.34.5"
|
||||
}
|
||||
}
|
||||
|
||||
@ -7,58 +7,23 @@ Multi-protocol automotive bus library for ESP32. Handles BMW I/K-Bus and OBD-II
|
||||
|
||||
## Composition Diagram
|
||||
|
||||
```
|
||||
Application Layer
|
||||
+-----------------------------------------+
|
||||
| main.cpp (sniffer) |
|
||||
| |
|
||||
| IbusEsp32 ibus; |
|
||||
| ibus.begin(Serial1, RX, TX, LED); |
|
||||
| ibus.onPacket(callback); |
|
||||
| ibus.run(); |
|
||||
+-----------------------------------------+
|
||||
```mermaid
|
||||
graph TD
|
||||
APP["<b>Application Layer</b><br/>main.cpp / obd2_scanner.cpp"]
|
||||
APP -->|"facade: zero-change migration"| FACADE["<b>IbusEsp32</b><br/>Backward-compatible wrapper"]
|
||||
FACADE --> IBUS
|
||||
|
||||
| (facade: zero-change migration)
|
||||
v
|
||||
subgraph Protocol Handlers
|
||||
IBUS["<b>IbusHandler</b><br/>BMW I/K-Bus FSM<br/>XOR checksum<br/>Source filtering<br/>Packet callback"]
|
||||
OBD2["<b>KLineObd2</b><br/>ISO 9141 slow init<br/>ISO 14230 fast init<br/>Echo clearing<br/>Frame parsing<br/>TesterPresent"]
|
||||
end
|
||||
|
||||
+-------------------+ +-------------------+
|
||||
| IbusHandler | | KLineObd2 |
|
||||
| | | |
|
||||
| BMW I/K-Bus FSM | | ISO 9141 slow init|
|
||||
| XOR checksum | | ISO 14230 fast |
|
||||
| Source filtering | | init |
|
||||
| Packet callback | | Echo clearing |
|
||||
| | | Frame parsing |
|
||||
| | | TesterPresent |
|
||||
+--------+----------+ +---------+---------+
|
||||
| |
|
||||
| reads RX ring | reads RX ring
|
||||
| delegates TX | sends via serial()
|
||||
| | flushes RX
|
||||
v v
|
||||
+-----------------------------------------+
|
||||
| KLineTransport |
|
||||
| |
|
||||
| UART (HardwareSerial) |
|
||||
| GPIO ISR (IRAM_ATTR, RX pin) |
|
||||
| esp_timer (periodic idle check) |
|
||||
| RX ring buffer (256 bytes) |
|
||||
| TX ring buffer (128 bytes) |
|
||||
| Bus idle detection |
|
||||
| TX inversion (uart_set_line_inverse) |
|
||||
| Configurable: KLineConfig struct |
|
||||
+-----------------------------------------+
|
||||
IBUS -->|"reads RX ring<br/>delegates TX"| TRANSPORT
|
||||
OBD2 -->|"reads RX ring<br/>sends via serial()<br/>flushes RX"| TRANSPORT
|
||||
|
||||
|
|
||||
v
|
||||
TRANSPORT["<b>KLineTransport</b><br/>UART · GPIO ISR · esp_timer<br/>RX ring 256B · TX ring 128B<br/>Bus idle detection<br/>TX inversion · KLineConfig"]
|
||||
|
||||
+-----------------------------------------+
|
||||
| RingBuffer |
|
||||
| |
|
||||
| malloc'd circular buffer |
|
||||
| Bounds-checked peek(n), remove(n) |
|
||||
| capacity = size - 1 (standard ring) |
|
||||
+-----------------------------------------+
|
||||
TRANSPORT --> RING["<b>RingBuffer</b><br/>malloc'd circular buffer<br/>Bounds-checked peek/remove"]
|
||||
```
|
||||
|
||||
IbusHandler and KLineObd2 sit as parallel protocol handlers on top of a shared KLineTransport. Neither knows about the other. IbusEsp32 is a facade that composes one transport and one handler, preserving the original API for existing sketches.
|
||||
@ -164,13 +129,17 @@ BMW I/K-Bus protocol parser. Takes a reference to KLineTransport and reads from
|
||||
|
||||
### State Machine
|
||||
|
||||
```
|
||||
FIND_SOURCE --> FIND_LENGTH --> FIND_MESSAGE --> GOOD_CHECKSUM --> (callback, back to FIND_SOURCE)
|
||||
^ | | |
|
||||
| | | v
|
||||
+----- bad ----+ timeout (100ms) BAD_CHECKSUM ----> remove 1 byte, retry
|
||||
| remove 1 byte
|
||||
+<-----------------------------+
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> FIND_SOURCE
|
||||
FIND_SOURCE --> FIND_LENGTH
|
||||
FIND_LENGTH --> FIND_MESSAGE
|
||||
FIND_LENGTH --> FIND_SOURCE : bad length
|
||||
FIND_MESSAGE --> GOOD_CHECKSUM
|
||||
FIND_MESSAGE --> FIND_SOURCE : timeout 100ms\nremove 1 byte
|
||||
GOOD_CHECKSUM --> FIND_SOURCE : callback fired
|
||||
GOOD_CHECKSUM --> BAD_CHECKSUM
|
||||
BAD_CHECKSUM --> FIND_SOURCE : remove 1 byte\nretry
|
||||
```
|
||||
|
||||
The FSM peeks into the RX ring without consuming bytes until it has a complete, checksum-validated message. On `GOOD_CHECKSUM`, it reads the bytes out of the ring and fires the callback. On `BAD_CHECKSUM`, it removes one byte (the presumed bad source byte) and restarts -- this slides the window forward through noise or framing errors.
|
||||
|
||||
@ -63,22 +63,19 @@ In the United States, OBD-II has been mandatory since 1996 for all passenger veh
|
||||
|
||||
### Protocol Timeline
|
||||
|
||||
```
|
||||
1996 ├─── OBD-II mandatory (US) ───────────────────────────────────┤
|
||||
│ Manufacturers choose: ISO 9141, KWP2000, J1850, or CAN │
|
||||
│ │
|
||||
2001 ├─── European OBD (EOBD) mandatory ──────────────────────────┤
|
||||
│ Same protocols, EU emission standards │
|
||||
│ │
|
||||
2003 ├─── CAN bus begins appearing ────────────────────────────────┤
|
||||
│ Manufacturers start transitioning to CAN │
|
||||
│ │
|
||||
2008 ├─── CAN mandatory (US) ─────────────────────────────────────┤
|
||||
│ All new US vehicles must use ISO 15765 (CAN) │
|
||||
│ K-line protocols no longer required │
|
||||
│ │
|
||||
2014 ├─── CAN mandatory (EOBD) ───────────────────────────────────┤
|
||||
EU catches up, CAN required for all new vehicles
|
||||
```mermaid
|
||||
timeline
|
||||
title OBD-II Protocol Evolution
|
||||
1996 : OBD-II mandatory (US)
|
||||
: Manufacturers choose ISO 9141, KWP2000, J1850, or CAN
|
||||
2001 : European OBD (EOBD) mandatory
|
||||
: Same protocols, EU emission standards
|
||||
2003 : CAN bus begins appearing
|
||||
: Manufacturers start transitioning to CAN
|
||||
2008 : CAN mandatory (US)
|
||||
: All new US vehicles must use ISO 15765 (CAN)
|
||||
2014 : CAN mandatory (EOBD)
|
||||
: EU catches up, CAN required for all new vehicles
|
||||
```
|
||||
|
||||
### K-line by Manufacturer
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user