# smongrot SDK — llms-full.txt (ภาษาไทย) GENERATED by tools/build_llms_full.mjs from site/th/*.md, spec/*.json and vectors/. Do not edit. Level 1 = read-only Honda K-Line diagnostics. The JSON spec below is normative; Thai prose is a guide. ============================================================================== # FILE: site/th/llms.txt ============================================================================== # smongrot SDK > อ่านอย่างเดียว (level 1) สำหรับวินิจฉัย ECU รถจักรยานยนต์ Honda ผ่านสาย K-Line: ตัวตนของ ECU, live data ของเครื่องยนต์, และรหัสข้อผิดพลาดที่เก็บไว้ (beta) มีสเปกที่เครื่องอ่านได้พร้อม golden test vector และมี SDK ภาษา JavaScript (npm `@smongrot/sdk`) กับ Dart (pub `smongrot_sdk`) สัญญาอนุญาต MIT รุ่น v0.1 แหล่งความจริงคือสเปก JSON จะถือว่า implementation ถูกต้องก็ต่อเมื่อผ่าน vector ทุกชุดใน `vectors/` ## กฎที่ implementation ต้องทำตาม - K-Line 10400 baud 8N1 ตัด TX echo ทุกครั้งที่อ่านกลับ (spec/kline.json `echo_strip`) - Checksum = (0x100 − (sum mod 256)) mod 256 และ mask ให้เหลือ 8 บิตเสมอ (ถ้าบอดี้รวมกันได้ 0x100 ค่า checksum คือ 0x00) ห้ามใช้ผลบวกธรรมดา - Wake = LOW 70 ms จับเวลาแบบ atomic บน adapter แล้ว idle 130 ms ลอง wake + StartComm + liveness ใหม่ได้สูงสุด 4 ครั้ง - ส่ง StartDiag `72 05 71 00 18` ก่อนอ่านตาราง live data ทุกครั้ง - ใช้ข้อมูล reply ได้เฉพาะ frame `02 L ` อันสุดท้ายที่ checksum ถูกต้อง reply ที่สั้นกว่า `data_len` ของตารางถือว่าไม่มีข้อมูล - ค่าที่หายไปหรือเป็น sentinel คือ "absent" ไม่ใช่ 0 ค่าที่อยู่นอกช่วงคือ "invalid" และห้ามใช้ค่าจากแหล่ง fallback มาแทน - เก็บที่มาของทุกค่าไว้ (bench / field / reference / provisional) อย่าซ่อน "provisional" - รหัสข้อผิดพลาดเป็น beta: ถอดรหัสเฉพาะกล่อง Keihin สิ่งที่ parse ไม่ได้คือ "unreadable" ห้ามเดา - Level 1 ไม่ส่ง frame ที่เขียน ที่ลบ หรือที่เปลี่ยนสถานะ (ไม่มีการล้าง DTC) ห้ามเรียกเครือข่ายจากตัวถอดรหัส - ชื่อรุ่นไม่บังคับ มาจาก `GET https://api.smongrot.com/v1/ecu/identify?ecm=<10 hex>` ด้วย API key ฟรี ถ้าค้นไม่สำเร็จ จะได้ model เป็น null และไม่ทำให้ identify, live data หรือรหัสข้อผิดพลาดพัง ## แพลตฟอร์ม (v0.1) - ใช้สายอย่างเดียว: Chrome / Edge บนเดสก์ท็อป (WebSerial), Node (`serialport`), Flutter เดสก์ท็อป (`smongrot_sdk_libserialport`), Android USB-OTG (`smongrot_sdk_usb_serial`) - ยังไม่มี: iOS (บน iOS ไม่มี USB serial) และบอร์ด SMR แบบ Bluetooth ทั้งคู่มาใน v0.2 ## สเปก - [spec/kline.json](https://developers.smongrot.com/spec/kline.json): สาย, wake, session, checksum, การตัด echo, จังหวะเวลา - [spec/live.json](https://developers.smongrot.com/spec/live.json): โปรไฟล์ live data, การดึงค่า, กติกาของค่า, การตรวจจับ - [spec/dtc.json](https://developers.smongrot.com/spec/dtc.json): อ่านและถอดรหัสรหัสข้อผิดพลาด (beta) - [spec/board-ble.json](https://developers.smongrot.com/spec/board-ble.json): BLE ของบอร์ด SMR เฉพาะคำสั่ง level 1 (การรองรับบอร์ดอยู่ใน v0.2) - JSON Schema: [common.schema.json](https://developers.smongrot.com/spec/schema/common.schema.json), [kline.schema.json](https://developers.smongrot.com/spec/schema/kline.schema.json), [live.schema.json](https://developers.smongrot.com/spec/schema/live.schema.json), [dtc.schema.json](https://developers.smongrot.com/spec/schema/dtc.schema.json), [board-ble.schema.json](https://developers.smongrot.com/spec/schema/board-ble.schema.json); ชุด vector ใช้ `vectors-.schema.json` ในโฟลเดอร์เดียวกัน ## Vectors - [vectors/checksum.json](https://developers.smongrot.com/vectors/checksum.json), [vectors/echo.json](https://developers.smongrot.com/vectors/echo.json), [vectors/session.json](https://developers.smongrot.com/vectors/session.json) - Live: [vectors/live/extract.json](https://developers.smongrot.com/vectors/live/extract.json), [vectors/live/detect.json](https://developers.smongrot.com/vectors/live/detect.json), [vectors/live/t17.sub8.json](https://developers.smongrot.com/vectors/live/t17.sub8.json), [vectors/live/t17.sub4.json](https://developers.smongrot.com/vectors/live/t17.sub4.json), [vectors/live/t13.type7.json](https://developers.smongrot.com/vectors/live/t13.type7.json), [vectors/live/t11.type1.json](https://developers.smongrot.com/vectors/live/t11.type1.json), [vectors/live/generic.t17.json](https://developers.smongrot.com/vectors/live/generic.t17.json) - [vectors/dtc.json](https://developers.smongrot.com/vectors/dtc.json) ## เอกสาร อ่านตามลำดับนี้: - [หน้าแรก](https://developers.smongrot.com/th/docs): v0.1 คืออะไร สามอย่างที่สร้างได้ ควิกสตาร์ต 60 วินาที แพลตฟอร์ม และสิ่งที่ไม่ทำ - [แนวคิด](https://developers.smongrot.com/th/docs/concepts): วงจร session, ECM-ID, โปรไฟล์ live, สถานะฟิลด์ (`ok` / `absent` / `invalid`), ผู้ผลิต, จังหวะเวลา - [ฮาร์ดแวร์](https://developers.smongrot.com/th/docs/hardware): สาย K-Line, สัญญาณบนขั้ว, FTDI VCP, 10400 8N1, Android OTG, ทำไม iOS ใช้สายไม่ได้ - [ความปลอดภัย](https://developers.smongrot.com/th/docs/safety): เฟรมแบบอ่านอย่างเดียว, absent ไม่ใช่ 0, ค่า provisional, รหัสข้อผิดพลาด beta - [เริ่มต้นใช้งาน: JavaScript](https://developers.smongrot.com/th/docs/quickstart-js): WebSerial บนเบราว์เซอร์ และ Node `serialport` - [เริ่มต้นใช้งาน: Dart](https://developers.smongrot.com/th/docs/quickstart-dart): Flutter เดสก์ท็อป (`smongrot_sdk_libserialport`) และ Android OTG (`smongrot_sdk_usb_serial`) - [ตัวอย่าง](https://developers.smongrot.com/th/docs/examples): ตัวบันทึก CSV บน Node, เกจบนเบราว์เซอร์, หน้าจอ live ของ Flutter, Android OTG, อ่าน DTC, API key - [ระบุตัวกล่องและ API key](https://developers.smongrot.com/th/docs/identify): ECM-ID แบบออฟไลน์, ชื่อรุ่นจาก `GET /v1/ecu/identify`, ข้อผิดพลาดที่ไม่ทำให้ identify พัง - [อ้างอิง API](https://developers.smongrot.com/th/docs/api): ทุกฟังก์ชัน ชนิด ตัวเลือก และข้อผิดพลาดที่ export ทั้ง JS และ Dart - [ภาพรวมโปรโตคอล](https://developers.smongrot.com/th/docs/protocol): รูปแบบบนสาย, wake, ไบต์ของ session, การตัด live, การอ่านรหัสข้อผิดพลาด - [แก้ปัญหา](https://developers.smongrot.com/th/docs/troubleshooting): ทุก `code` (`ECU_SILENT`, `API_*`, …) พร้อมสาเหตุและวิธีแก้ รวมอาการที่ดูคล้ายบั๊ก - [คำถามที่พบบ่อย](https://developers.smongrot.com/th/docs/faq): SDK ฟรีสัญญาอนุญาต MIT, API key ฟรี, 1000 คำขอต่อวัน, ใช้เชิงพาณิชย์ได้, ความเป็นส่วนตัว, แผน v0.2 ## ไม่บังคับ - [llms-full.txt](https://developers.smongrot.com/th/llms-full.txt): รวมเอกสารและไฟล์สเปกทั้งหมดเป็นข้อความเดียว สร้างขึ้นอัตโนมัติ ============================================================================== # FILE: site/th/index.md ============================================================================== [English](https://developers.smongrot.com/docs) # smongrot SDK > อ่าน ECU รถจักรยานยนต์ Honda ผ่านสาย K-Line แบบอ่านอย่างเดียว: ดูว่ากล่องเป็นตัวไหน อ่าน live data และอ่านรหัสข้อผิดพลาดที่เก็บไว้ (beta) v0.1 คุยกับกล่อง Keihin และ Shindengen จาก JavaScript (`@smongrot/sdk`) และ Dart (`smongrot_sdk`) ทั้งคู่ใช้สัญญาอนุญาต MIT session บนสายไม่เขียนอะไรลง ECU ```sh npm i @smongrot/sdk # JavaScript (browser + Node) dart pub add smongrot_sdk # Dart / Flutter ``` ## เอาไปทำอะไรได้ - **เครื่องมือวินิจฉัยในร้าน.** บนคอมร้าน เปิด session แล้วโชว์ ECM-ID กับชื่อรุ่น เกจ live สักสองสามตัว และรหัสข้อผิดพลาดเป็นคำใบ้ - **แดชบอร์ดฟลีต.** แต่ละคันส่ง ECM-ID กับ live data ไม่กี่ค่า ถ้าอยากได้ชื่อรุ่นบนการ์ด ให้ใส่ API key ฟรี ตัวเลข live อยู่บนเครื่องนั้น ไม่ถูกส่งออก - **เครื่องบันทึกข้อมูล.** เรียก `live()` แล้วต่อท้าย rpm อุณหภูมิ และแบตลงไฟล์ ฟิลด์ที่ไม่มีคือช่องว่าง rpm เป็น `0` ตอนเครื่องดับคือค่าจริง ## เริ่มใน 60 วินาที บิดกุญแจไปที่ ON (ดับเครื่องได้) เสียบสาย K-Line แบบ FTDI หรือ KKL ที่ขั้ววินิจฉัยของรถ บน Chrome หรือ Edge เดสก์ท็อป เรียกจากคลิกปุ่ม (WebSerial ต้องเกิดจากท่าทางของผู้ใช้ และหน้าต้องเป็น https หรือ localhost): ```js import { connect, openWebSerial } from '@smongrot/sdk'; document.querySelector('button').onclick = async () => { const port = await navigator.serial.requestPort(); const s = await connect(await openWebSerial(port)); try { console.log((await s.identify()).ecmId); // 10 hex, read from the box for await (const f of s.live()) { const rpm = f.fields.rpm; console.log(rpm?.status === 'ok' ? rpm.value : '—'); break; } } finally { await s.close(); } }; ``` Node, Flutter เดสก์ท็อป และ Android ใช้ `connect` / `identify` / `live` / `close` ชุดเดียวกัน ต่างกันแค่ transport ดู [เริ่มต้นใช้งาน: JavaScript](https://developers.smongrot.com/th/docs/quickstart-js) และ [เริ่มต้นใช้งาน: Dart](https://developers.smongrot.com/th/docs/quickstart-dart) ## แพลตฟอร์มที่รองรับ | แพลตฟอร์ม | วิธีเชื่อมต่อ | v0.1 | |---|---|---| | เบราว์เซอร์บนเดสก์ท็อป (Chrome / Edge) | สาย USB, WebSerial (`openWebSerial`) | ได้ | | Node (Windows / macOS / Linux) | สาย USB, `serialport` (`fromSerialPort`) | ได้ | | Flutter / Dart บนเดสก์ท็อป | สาย USB, `smongrot_sdk_libserialport` | ได้ | | Android (Flutter) | สาย USB-OTG, `smongrot_sdk_usb_serial` | ได้ | | iOS | ไม่มี USB-serial จึงใช้สายไม่ได้ | v0.2 ผ่านบอร์ด SMR แบบ BLE | | บอร์ด SMR (โทรศัพท์เครื่องไหนก็ได้) | Bluetooth LE | v0.2 | เบราว์เซอร์บนโทรศัพท์ไม่มี WebSerial ให้ใช้แถว Android หรือเดสก์ท็อป | ความสามารถ | ต้องใช้ | |---|---| | ECM-ID, live data, รหัสข้อผิดพลาด | แค่สาย และใช้แบบออฟไลน์ได้ | | ชื่อรุ่นใน `identify()` | API key ฟรี ([ระบุตัวกล่องและ API key](https://developers.smongrot.com/th/docs/identify)) | | รหัสข้อผิดพลาด | beta: ถอดรหัสกล่อง Keihin ได้ ของที่ไม่ชัดเป็น `unreadable` | ## ฮาร์ดแวร์ที่ต้องมี สาย **K-Line** แบบ FTDI หรือ KKL และ **ไฟ 12 V ตอนกุญแจ ON** ECU กินไฟจากรถ ไม่ใช่จาก USB ค่าพอร์ตคือ **10400 8N1** รายละเอียดไดรเวอร์ และข้อจำกัดของ Android / iOS อยู่ที่ [ฮาร์ดแวร์](https://developers.smongrot.com/th/docs/hardware) ## สิ่งที่ v0.1 ไม่ทำ - ไม่เขียน ไม่ลบ และไม่เปลี่ยนค่าใน ECU - ไม่อ่าน ROM ทั้งก้อน - ไม่ล้างรหัสข้อผิดพลาด (การล้างจะรีเซ็ตค่าที่ ECU เรียนรู้ไว้ด้วย) - ไม่คุยกับระบบล็อกเครื่อง (immobilizer) สิ่งเหล่านี้ไม่อยู่ใน SDK นี้ ระดับถัดไปที่ต้องใช้บอร์ด SMR ก็ยังไม่มา ## หน้าเอกสาร | หน้า | | |---|---| | [แนวคิด](https://developers.smongrot.com/th/docs/concepts) | session, ECM-ID, ฟิลด์ live, ผู้ผลิต, จังหวะเวลา | | [ฮาร์ดแวร์](https://developers.smongrot.com/th/docs/hardware) | สาย, ขั้ว, ไดรเวอร์, 10400 8N1, Android, iOS | | [ความปลอดภัย](https://developers.smongrot.com/th/docs/safety) | สิ่งที่ v0.1 ส่ง และความหมายของค่าที่ไม่มี | | [เริ่มต้นใช้งาน: JavaScript](https://developers.smongrot.com/th/docs/quickstart-js) | เบราว์เซอร์ (WebSerial) และ Node | | [เริ่มต้นใช้งาน: Dart](https://developers.smongrot.com/th/docs/quickstart-dart) | Flutter เดสก์ท็อป และ Android | | [ตัวอย่าง](https://developers.smongrot.com/th/docs/examples) | ตัวบันทึก CSV, เกจ, Flutter, DTC, API key | | [อ้างอิง API](https://developers.smongrot.com/th/docs/api) | ทุก export พร้อมชนิดและค่าเริ่มต้น | | [ระบุตัวกล่องและ API key](https://developers.smongrot.com/th/docs/identify) | ECM-ID, ชื่อรุ่น, key ฟรี | | [ภาพรวมโปรโตคอล](https://developers.smongrot.com/th/docs/protocol) | ข้อมูลที่วิ่งบนสาย | | [แก้ปัญหา](https://developers.smongrot.com/th/docs/troubleshooting) | รหัสข้อผิดพลาดทุกตัว และอาการที่ดูคล้ายบั๊ก | | [คำถามที่พบบ่อย](https://developers.smongrot.com/th/docs/faq) | ราคา, สัญญาอนุญาต, ความเป็นส่วนตัว, แผน v0.2 | | [llms.txt](https://developers.smongrot.com/th/llms.txt) · [llms-full.txt](https://developers.smongrot.com/th/llms-full.txt) | สำหรับเครื่องมือ AI ที่ช่วยเขียนโค้ด | สเปกที่เป็นเกณฑ์คือ [kline](https://developers.smongrot.com/spec/kline.json), [live](https://developers.smongrot.com/spec/live.json), [dtc](https://developers.smongrot.com/spec/dtc.json) และ [board-ble](https://developers.smongrot.com/spec/board-ble.json) (การรองรับบอร์ดอยู่ใน v0.2) implementation จะถูกก็ต่อเมื่อผ่าน vector ที่เผยแพร่ไว้ใน [llms.txt](https://developers.smongrot.com/th/llms.txt) ถัดไป: [แนวคิด](https://developers.smongrot.com/th/docs/concepts) ============================================================================== # FILE: site/th/concepts.md ============================================================================== [English](https://developers.smongrot.com/docs/concepts) # แนวคิด > session ของ level 1 เดินยังไง ECM-ID คืออะไร และทำไมค่า live ที่ไม่มีไม่ใช่ 0 ## วงจรของ session `connect(transport)` เป็นทางเดียวที่จะเปิด session มันทำ wake, StartComm, liveness และ StartDiag แล้วคืนมาตอน `state === 'ready'` จากนั้นค่อยเรียก `identify()`, `live()` และ `dtc.read()` `close()` ปล่อยพอร์ต ``` App Cable / ECU |-- connect() ------------------------------------------->| | wake: line LOW 70 ms, release, idle 130 ms | | StartComm FE 04 72 8C (reply not required) | | liveness first non-empty reply means "up" | | 72 05 00 F0 99 | | 72 05 71 00 18 | | 7E 06 01 01 00 7A | |<------------------------ any reply --------------------| | StartDiag 72 05 71 00 18 | |<------------------------ 02 0F 71 00 <5-byte id> .. ----| | | | state is now "ready" | |-- identify() ------------------------------------------>| | 72 07 72 00 00 05 10 up to 3 tries, 300 ms apart | |<------------------------ 02 0B 72 00 00 <5 bytes> ck ---| |-- live() or dtc.read() (not at the same time) ------>| |<------------------------ frames -----------------------| |-- close() --------------------------------------------->| | state is "closed" | ``` ถ้า probe ของ liveness ไม่มีตัวไหนตอบ `connect` จะทำ wake + StartComm + liveness ซ้ำ สูงสุด **4** ครั้ง แล้ว throw `ECU_SILENT` ต้องส่ง StartDiag ไม่งั้นตาราง live จะเงียบ `connect` ส่งให้แล้ว `state` เริ่มที่ `idle` แล้ว `waking` แล้ว `ready` `live()` ย้ายไป `live` และกลับมา `ready` เมื่อลูปจบ `identify`, `detect`, `live` และ `dtc.read` ต้องอยู่ในสถานะ `ready` หยุดลูป live ก่อนอ่านรหัสข้อผิดพลาด `identify()` จำผลไว้ การเรียกครั้งที่สองไม่แตะสาย ## ECM-ID ECM-ID คือ **5 ไบต์** เขียนเป็นเลขฐานสิบหกตัวใหญ่ **10 ตัว** เช่น `0104780D01` `identify()` เลือก frame อ่าน ID โดยเฉพาะก่อน ถ้า frame นั้นไม่มา จะใช้ ID ที่มากับ reply ของ StartDiag (`source` เป็น `id_frame`, `start_diag` หรือ `null`) ID ไม่ใช่ชื่อรุ่น ชื่อ ผู้ผลิต และรหัสอะไหล่มาจาก `lookupModel` เท่านั้น (ดู [ระบุตัวกล่องและ API key](https://developers.smongrot.com/th/docs/identify)) live data กับรหัสข้อผิดพลาดไม่ต้องใช้ชื่อรุ่น ## โปรไฟล์ live `live()` ที่ไม่ส่ง `profile` จะ probe ตาราง **`0x17` แล้ว `0x13` แล้ว `0x11`** (ตารางละ 2 ครั้ง) แล้วเลือก layout ส่ง `profile` ก็ต่อเมื่อรู้ id อยู่แล้ว | โปรไฟล์ | ผู้ผลิต | ฟิลด์ | |---|---|---| | `t17.sub8` | Keihin | `rpm`, `tps_v`, `tps`, `ect`, `batt`, `inj_ms`, `ign`, `ltft`, `o2r` | | `t17.sub4` | Shindengen | `rpm`, `tps_v`, `tps`, `eot`, `batt`, `inj_ms`, `ign` | | `t13.type7` | Keihin | `rpm`, `tps`, `ect`, `batt`, `inj_ms`, `ign`, `o2r` | | `t11.type1` | Keihin | `rpm`, `tps`, `ect`, `batt`, `inj_ms`, `ign`, `o2r` | | `generic.t17` | ได้ทั้งคู่ | `rpm`, `tps`, `inj_ms`, `ign` | `generic.t17` เป็นทางสำรองเมื่อตาราง `0x17` ตอบ แต่ไม่เข้า layout ย่อยทั้งสอง มีเฉพาะฟิลด์ที่ตรงกันทั้งสองผู้ผลิต อุณหภูมิและแบตจึง `absent` โดยตั้งใจ แต่ละค่าคือ `raw × scale + add` จากไบต์แบบ big-endian สเกลอยู่ใน [spec/live.json](https://developers.smongrot.com/spec/live.json) SDK ไม่ส่งฟิลด์ `o2_v` ถ้าจะโชว์เป็นโวลต์ ให้ใช้ `o2r × 0.0195` ตอน `o2r` เป็น `ok` การแปลงนี้เป็น provisional และเซ็นเซอร์ narrowband บอกได้แค่หนาหรือบาง ไม่ใช่ค่าอัตราส่วนอากาศต่อเชื้อเพลิง `detect()` คืน `{ profile, method, mismatch }` หรือ `null` `method` เป็น `probed` หรือ `generic` `mismatch` เป็นจริงเมื่อมี maker hint และผู้ผลิตของโปรไฟล์ทั้งคู่ และทั้งสองค่าไม่ตรงกัน layout ที่อ่านได้จริงยังชนะอยู่ ## สถานะของฟิลด์ ทุกฟิลด์ถูกส่งในทุก frame แม้ตารางของมันจะยังไม่ตอบ | `status` | ความหมาย | ให้โชว์ | |---|---|---| | `ok` | `value` เป็นตัวเลข | ตัวเลขนั้น | | `absent` | ไม่มีใน frame นี้ | `—` | | `invalid` | นอกช่วง หรือสองแหล่งไม่ตรงกัน | `—` ไม่ใช่ตัวเลขดิบ | `absent` คือกรณี "ไม่มีค่า" **ไม่ใช่ 0** ไบต์ sentinel (เช่น อุณหภูมิ `0xFF` หรือแบต `0`) เป็น `absent` ตารางที่ยังไม่ถูกอ่านเป็น `absent` ฟิลด์ที่โปรไฟล์นี้ไม่มีก็เป็น `absent` ถ้าเอา 0 ไปแทน จะเห็นเซ็นเซอร์ที่ตายเป็นศูนย์จริง rpm ไม่มี sentinel ถ้าตารางตอบ จะเป็น `status: 'ok'` เสมอ แม้เครื่องดับ ตอนเปิดกุญแจแต่เครื่องดับ กล่องอาจส่ง `0` **หรือเลขที่ไม่มีความหมาย** (กล่อง Keihin K03-H01 บน bench ส่งราว 17,500 รอบ และอุณหภูมิ −30 °C) ให้ดู `frame.engine` ถ้าเป็น `'off'` (หัวฉีด 0 ms และองศาจุดระเบิด 0°) แปลว่ารอบกับอุณหภูมิไม่ใช่ค่าจริง ซ่อน หรือขึ้นว่า "เครื่องดับ" `prov` คนละเรื่องกับ `status` มีได้เป็น `bench` (วัดบน ECU จริง), `field` (สอดคล้องในล็อกภาคสนาม ยังไม่ได้เทียบมิเตอร์), `reference` (มาจากตัวถอดรหัสอ้างอิงอย่างเดียว) หรือ `provisional` (ตัวอย่างเดียว หรือเป็นการอนุมาน) ให้โชว์ค่า `provisional` ได้ แต่อย่าให้มันตัดสินใจเพียงลำพัง แบตบน layout ของ Shindengen เป็น provisional `prov` ไม่ใช่ status อย่าเช็ค `status === 'provisional'` ใน Dart `reading.ok` คือ `status == 'ok'` ใน JavaScript ต้องเช็ค `reading.status === 'ok'` ก่อนใช้ `value` frame ที่ `primaryOk: false` อ่านตารางหลักไม่สำเร็จ ฟิลด์ของตารางนั้นเป็น `absent` ใน tick นี้ SDK ไม่เอาเลขของเฟรมก่อนมาใช้ซ้ำ ## ผู้ผลิต | ผู้ผลิต | รหัสอะไหล่ขึ้นต้น | รหัสข้อผิดพลาดใน v0.1 | |---|---|---| | `keihin` | `38770-` | ถอดรหัสได้ (beta) | | `shindengen` | `30400-` | อ่าน frame เดียวกัน แต่ payload ที่ไม่เป็นศูนย์ทั้งหมดเป็น `unreadable` | `makerHint` ตอน `connect` หรือ `model.maker` / `model.partCode` หลัง `identify()` เป็นตัวเลือกตัวถอดรหัส ผู้ผลิตที่ไม่รู้บวก payload ที่ไม่เป็นศูนย์ คือ `unreadable` พร้อม `reason: 'maker_unknown'` payload ที่เป็นศูนย์ทั้งหมดคือ `clean` ได้ทั้งสองผู้ผลิต SDK ไม่เดารหัส ## จังหวะเวลา ค่าเริ่มต้น (`DEFAULT_TIMING` ใน JavaScript, `Timing()` ใน Dart) แก้ฟิลด์ก็ต่อเมื่อตั้งใจ | | ค่าเริ่มต้น | |---|---| | Wake LOW / idle หลัง wake | 70 ms / 130 ms | | จำนวนครั้งของ wake (wake + StartComm + liveness) | 4 | | จำนวนครั้งของ ECM-ID / ช่องว่าง | 3 / 300 ms | | command quiet / timeout | 120 ms / 2000 ms | | ตาราง live quiet / timeout | 120 ms / 500 ms | | ช่องว่างระหว่างการอ่านรหัสข้อผิดพลาด | 60 ms | | หน่วย tick ของ live (ตารางรองถึงรอบเมื่อไหร่) | 300 ms | | ช่องเป้าระหว่าง frame / ช่องต่ำสุด | 150 ms / 60 ms | การอ่านจบเมื่อเงียบครบ `quiet` มิลลิวินาที หรือครบ `timeout` อย่างใดอย่างหนึ่งมาก่อน timeout ไม่ throw จะได้ reply ว่าง แล้วฟิลด์หรือผล DTC จะบอกเอง ตาราง live หลักถูกอ่านทุก frame ตารางรอง (`o2r` บน `t20`, แบต Shindengen บน `d0`) อ่านได้มากสุดหนึ่งตารางต่อ frame ฟิลด์พวกนั้นจึง `absent` ในเฟรมแรก ๆ นั่นคือจังหวะการโพล ไม่ใช่เซ็นเซอร์เสีย ถัดไป: [ฮาร์ดแวร์](https://developers.smongrot.com/th/docs/hardware) ============================================================================== # FILE: site/th/hardware.md ============================================================================== [English](https://developers.smongrot.com/docs/hardware) # ฮาร์ดแวร์ > ต้องเสียบอะไร: สาย K-Line, กุญแจ ON, 10400 8N1 และโทรศัพท์เครื่องไหนเปิดสายได้ ## เลือกสาย ต้องใช้ **สาย USB K-Line (KKL)** ที่ชิปเป็น FTDI, CP210x หรือ CH340 ต้องพูดได้ที่ **10400 baud 8N1** และดึงสายลง LOW เพื่อ wake ได้ (serial-break หรือ FTDI bit-bang) สาย USB-UART ธรรมดาที่ไม่มีตัวรับส่ง K-Line ใช้ไม่ได้ บัสเป็นเส้นเดียว half-duplex และสายจะ echo ทุกไบต์ที่ส่ง session ตัด echo ให้ ถ้าเลือกได้ ให้ใช้สาย FTDI การ bit-bang ที่ขา TXD เป็น LOW นาน 70 ms คือ wake ที่ใช้บนม้านั่ง กล่อง Shindengen ที่เพิ่งบิดไปที่ ON จะตอบแบบนี้ตั้งแต่ครั้งแรก break ของระบบปฏิบัติการ (ที่ adapter บนเดสก์ท็อปใช้) นาน 70 ms และพอสำหรับ Keihin adapter บน Android bit-bang ไม่ได้ wake จึงสั้นกว่า (ดูด้านล่าง) ไฟของ ECU มาจากรถ ไฟ USB ฝั่งคอมพิวเตอร์ไม่เลี้ยงกล่อง ## ขั้ว ขั้ววินิจฉัยของ Honda มีสามสัญญาณที่สายต้องใช้ จับคู่สายของเคเบิลให้ตรงสัญญาณ หน้านี้ไม่ลงผังขา | สัญญาณ | หน้าที่ | |---|---| | K-Line | สายข้อมูล ISO 9141 เส้นเดียว | | GND | กราวด์รถ ร่วมกับกราวด์ของสาย | | +12 V | แบตของรถ มีตอนกุญแจ ON เป็นไฟเลี้ยง ECU | กุญแจ ON เครื่องดับ คือสถานะปกติในร้าน กุญแจ OFF แปลว่า ECU ไม่มีไฟ และ `connect` จะจบที่ `ECU_SILENT` ## ค่าพอร์ตอนุกรม | ค่า | | |---|---| | Baud | 10400 | | Data bits | 8 | | Parity | none | | Stop bits | 1 | | Flow control | none | adapter ที่มากับ SDK ตั้งค่านี้ให้ ถ้าเปิดพอร์ตเองแล้วส่งเข้า `fromSerialPort` baud ต้องเป็น 10400 และเฟรมต้องเป็น 8N1 ไม่งั้นได้ `BAD_PORT` `fromDuplex` ไม่ตรวจค่าพวกนี้ ต้องตั้งพอร์ตก่อนห่อ ระดับว่างของบัสคือสูง ## ไดรเวอร์ | ระบบ | ต้องติดตั้งอะไร | |---|---| | Windows | ไดรเวอร์ Virtual COM Port ของชิปนั้น สาย FTDI ใช้ FTDI VCP พอร์ตจะขึ้นเป็น `COM3` (เลขไม่คงที่) | | macOS | สาย FTDI FT232 ของแท้ไม่ต้องลงอะไร ไดรเวอร์ของระบบทำ 10400 ได้ เปิด `/dev/cu.usbserial-…` ไม่ใช่โหนด `tty` | | Linux | ไดรเวอร์ในเคอร์เนล (`ftdi_sio` สำหรับ FTDI) สร้าง `/dev/ttyUSB0` ผู้ใช้ต้องมีสิทธิ์บนโหนดนั้น (กลุ่ม `dialout` บนดิสโทรส่วนใหญ่) | สาย CP210x และ CH340 ต้องใช้ไดรเวอร์ของผู้ผลิตชิปนั้นบนเดสก์ท็อป ถอดอุปกรณ์อนุกรมตัวอื่นออกก่อนตอนหาพาธ `SerialPort.list()` (Node) และ `SerialPort.availablePorts` (Flutter เดสก์ท็อป) พิมพ์พาธให้ ## Android (USB-OTG) โทรศัพท์ต้องเป็น USB host ใช้หัวแปลง OTG สายที่ชาร์จอย่างเดียวจะไม่ขึ้นอุปกรณ์ `smongrot_sdk_usb_serial` พูดได้กับ FTDI, CP210x, CH34x และ CDC `UsbSerial.listDevices()` แล้ว `device.create()` จะขอสิทธิ์ เรียก `create()` จากหน้าจอที่รันอยู่แล้ว (จากปุ่ม) ไม่ใช่ตอนโปรเซสเพิ่งเริ่ม ชิปนี้ไม่มี break adapter จึง wake โดยลด baud แล้วส่ง `0x00` หนึ่งไบต์ ซึ่งดึงสายลง LOW **ประมาณ 45 ms** แล้วกลับไป 10400 กล่อง Keihin ส่วนใหญ่ตอบพัลส์นี้ กล่อง Shindengen ที่เพิ่งบิดกุญแจไป ON อาจไม่สนใจ `connect` ยังลอง 4 ครั้ง ถ้ามี FTDI bit-bang แบบ native ให้ส่งเข้า `atomicWake` แล้ว adapter จะใช้ตัวนั้นแทน ## ทำไม iOS ใช้สายไม่ได้ iOS ไม่เปิดพอร์ต USB-serial ให้แอป จึงไม่มีสาย K-Line เส้นไหนที่เปิดได้ v0.2 ถึงรถผ่านบอร์ด SMR บน Bluetooth LE ซึ่งใช้บน iOS ได้ v0.1 ไม่มี adapter สายสำหรับ iOS ถัดไป: [ความปลอดภัย](https://developers.smongrot.com/th/docs/safety) ============================================================================== # FILE: site/th/safety.md ============================================================================== [English](https://developers.smongrot.com/docs/safety) # ความปลอดภัย > v0.1 อ่านอย่างเดียว ไม่เขียน ECU ไม่อ่าน ROM ทั้งก้อน และไม่ล้างรหัสข้อผิดพลาด **v0.1 อ่านอย่างเดียว (level 1)** SDK ส่งได้เฉพาะ frame เหล่านี้: พัลส์ wake, StartComm, liveness, StartDiag, การอ่าน ECM-ID, การอ่านตาราง live data, และการอ่านรหัสข้อผิดพลาดสามชุด ไม่มีฟังก์ชันสำหรับเขียน ลบ หรือแก้ไขอะไรใน ECU และไม่อ่าน ROM ทั้งก้อน การล้างรหัสข้อผิดพลาดไม่รวมอยู่ด้วย เพราะจะรีเซ็ตค่าที่ ECU เรียนรู้ไว้ด้วย SDK ส่งได้เฉพาะ frame อ่านที่ระบุไว้ใน spec เท่านั้น: มี allowlist คุมไว้ที่จุดเขียน จุดเดียว และ frame อื่นทั้งหมดถูกปฏิเสธ (`FRAME_NOT_ALLOWED`) ก่อนถึงสาย ตอนเชื่อมต่อ SDK จะส่ง frame keep-alive มาตรฐาน "tester present" (`7E 06 01 01 00 7A` ซึ่งเป็น liveness probe ใน spec/kline.json) ซึ่งไม่เปลี่ยน ความจำของ ECU การเขียน ลบ และการล้างรหัสข้อผิดพลาด ทำผ่าน SDK นี้ไม่ได้ - ค่าที่ไม่มี คือ **absent** ไม่ใช่ 0 ให้แสดง "—" - ค่า `provisional` (เช่น ค่าแบตเตอรี่บางค่า) ห้ามใช้ตัดสินใจเพียงลำพัง ให้คนขี่ยืนยันก่อน - รหัสข้อผิดพลาดเป็น **beta** ถอดรหัสได้เฉพาะกล่อง Keihin ให้แสดงเป็นคำใบ้ และคงผล "unreadable" ตามจริง - ตาราง live data ตอบก็ต่อเมื่อส่ง StartDiag แล้ว กล่องที่เงียบหลัง wake คือ "ไม่มีคำตอบ" ไม่ใช่ "กล่องเสีย" การเรียกเครือข่ายมีอย่างเดียว คือการค้นชื่อรุ่นซึ่งไม่บังคับ (`smongrotApi`) ส่งไปแค่ ECM-ID. live data กับรหัสข้อผิดพลาดไม่แตะเครือข่าย **Level 2–3 (จะมาภายหลัง)** เพิ่มการอ่านแบบเต็มและการเขียน ECU ทำงานผ่านบอร์ด smongrot SMR เท่านั้น พร้อม ticket ที่เซิร์ฟเวอร์เซ็นให้ต่อการเขียนหนึ่งครั้ง และ safety gate ครบทุกชั้นบนบอร์ด ยังไม่ใช่ส่วนหนึ่งของ SDK นี้ ถัดไป: [เริ่มต้นใช้งาน: JavaScript](https://developers.smongrot.com/th/docs/quickstart-js) ============================================================================== # FILE: site/th/quickstart-js.md ============================================================================== [English](https://developers.smongrot.com/docs/quickstart-js) # เริ่มต้นใช้งาน: JavaScript > ติดตั้ง `@smongrot/sdk` แล้วเปิด session แบบอ่านอย่างเดียวจากเบราว์เซอร์บนเดสก์ท็อปหรือจาก Node สายและไดรเวอร์: [ฮาร์ดแวร์](https://developers.smongrot.com/th/docs/hardware) สูตรที่ยาวกว่า: [ตัวอย่าง](https://developers.smongrot.com/th/docs/examples) ```sh npm i @smongrot/sdk ``` แพ็กเกจนี้เป็น ESM ไม่มี dependency ตอนรัน สัญญาอนุญาต MIT ใช้ได้บน Node ≥ 18 หรือ Chrome / Edge บนเดสก์ท็อป (WebSerial) บิดกุญแจไปที่ ON (ดับเครื่องได้) แล้วเสียบสายที่ขั้ววินิจฉัยของรถ ## เบราว์เซอร์ ```js import { connect, openWebSerial } from '@smongrot/sdk'; button.onclick = async () => { const port = await navigator.serial.requestPort(); const s = await connect(await openWebSerial(port)); const { ecmId } = await s.identify(); for await (const f of s.live()) { const rpm = f.fields.rpm; show(rpm?.status === 'ok' ? rpm.value : '—'); // never show 0 for a missing value } }; ``` ## Node `serialport` เป็น optional peer dependency ให้ติดตั้งเอง ```sh npm i @smongrot/sdk serialport ``` ```js import { SerialPort } from 'serialport'; import { connect, fromSerialPort } from '@smongrot/sdk'; const port = new SerialPort({ path: '/dev/cu.usbserial-XXXX', baudRate: 10400, autoOpen: false }); const s = await connect(await fromSerialPort(port)); console.log(await s.identify()); console.log(await s.dtc.read()); // beta: result.beta === true await s.close(); ``` แพ็กเกจมีตัวอย่างที่รันได้ที่ `examples/node-serialport.mjs` Duplex stream อื่นที่ 10400 8N1 ใช้กับ `fromDuplex(stream, { setBreak | wake })` ได้ ## ชื่อรุ่น ใส่ API key ฟรี เพื่อให้ `identify()` คืนชื่อรุ่น (ดู [ระบุตัวกล่องและ API key](https://developers.smongrot.com/th/docs/identify)): ```js import { smongrotApi } from '@smongrot/sdk'; const api = smongrotApi({ apiKey: process.env.SMONGROT_API_KEY }); const s = await connect(transport, { lookupModel: api.lookupModel }); ``` ## ทดสอบโดยไม่มีรถ ```js import { connect, FakeEcuTransport } from '@smongrot/sdk'; const fake = new FakeEcuTransport({ replies: { '72 07 72 17 00 0F EF': '02 15 72 17 00 0D EE 67 45 F8 0A FF FF FF FF 7D 0C 0D A8 55 28' }, }); const s = await connect(fake, { sleep: async () => {} }); for await (const f of s.live()) { console.log(f.fields.rpm.value); break; } // 3566 ``` ถัดไป: [เริ่มต้นใช้งาน: Dart](https://developers.smongrot.com/th/docs/quickstart-dart) ============================================================================== # FILE: site/th/quickstart-dart.md ============================================================================== [English](https://developers.smongrot.com/docs/quickstart-dart) # เริ่มต้นใช้งาน: Dart > ติดตั้ง `smongrot_sdk` แล้วเปิด session แบบอ่านอย่างเดียวบน Flutter เดสก์ท็อปหรือ Android สายและไดรเวอร์: [ฮาร์ดแวร์](https://developers.smongrot.com/th/docs/hardware) สูตรที่ยาวกว่า: [ตัวอย่าง](https://developers.smongrot.com/th/docs/examples) ```sh dart pub add smongrot_sdk flutter pub add smongrot_sdk_libserialport # desktop cable flutter pub add smongrot_sdk_usb_serial # Android USB-OTG cable ``` `smongrot_sdk` เป็น Dart ล้วน ไม่ต้องใช้ Flutter และคอมไพล์ขึ้นเว็บได้ สัญญาอนุญาต MIT transport ของสายแยกเป็นแพ็กเกจเล็ก ๆ เพื่อให้ core ไม่มี native code ## เดสก์ท็อป (Windows / macOS / Linux) ```dart import 'package:smongrot_sdk/smongrot_sdk.dart'; import 'package:smongrot_sdk_libserialport/smongrot_sdk_libserialport.dart'; print(SerialPort.availablePorts); final s = await connect(LibSerialPortTransport.open('/dev/cu.usbserial-XXXX')); final id = await s.identify(); await for (final f in s.live()) { final rpm = f.fields['rpm']!; print(rpm.ok ? rpm.value : '—'); // never show 0 for a missing value } ``` ## Android (USB-OTG) ```dart import 'package:smongrot_sdk/smongrot_sdk.dart'; import 'package:smongrot_sdk_usb_serial/smongrot_sdk_usb_serial.dart'; final devices = await UsbSerial.listDevices(); final port = await devices.first.create(); // Android asks for USB permission final s = await connect(await UsbSerialTransport.open(port!)); final dtc = await s.dtc.read(); // beta: dtc.beta == true await s.close(); ``` `usb_serial` ดึงสายค้างที่ LOW โดยตรงไม่ได้ adapter บน Android จึงส่งพัลส์ baud ต่ำสั้น ๆ แทน (ประมาณ 45 ms) กล่อง Keihin ส่วนใหญ่ตอบพัลส์นี้ กล่อง Shindengen ทันทีหลังบิดกุญแจไปที่ ON อาจไม่ตอบ และ `connect` จะลองใหม่ 4 ครั้ง ถ้ามีตัวช่วย FTDI bit-bang แบบ native ให้ส่งเข้ามาทาง `atomicWake` iOS เข้าถึง USB-serial ไม่ได้ การรองรับ iOS จะมาใน v0.2 พร้อมบอร์ด SMR ## ชื่อรุ่น ```dart final api = SmongrotApi(apiKey: myKey); final s = await connect(transport, lookupModel: api.lookupModel); ``` ดู [ระบุตัวกล่องและ API key](https://developers.smongrot.com/th/docs/identify) ## ทดสอบโดยไม่มีรถ ```dart final fake = FakeEcuTransport(replies: { '72 07 72 17 00 0F EF': '02 15 72 17 00 0D EE 67 45 F8 0A FF FF FF FF 7D 0C 0D A8 55 28', }); final s = await connect(fake, sleep: (_) async {}); print((await s.live().first).fields['rpm']!.value); // 3566.0 ``` ถัดไป: [ตัวอย่าง](https://developers.smongrot.com/th/docs/examples) ============================================================================== # FILE: site/th/examples.md ============================================================================== [English](https://developers.smongrot.com/docs/examples) # ตัวอย่าง > สูตรที่รันได้ แต่ละอันใช้เฉพาะฟังก์ชันที่ export จริง ฟิลด์ที่ไม่มีไม่ถูกโชว์เป็น 0 กฎร่วม: - อ่าน `value` ก็ต่อเมื่อ `status === 'ok'` (Dart: `reading.ok`) - `close()` ใน `finally` รวมกรณีที่ `connect` สำเร็จแล้วคำสั่งถัดไป throw - เรียก `dtc.read()` ก็ต่อเมื่อ `state` เป็น `ready` หยุด `live()` ก่อน - รหัสข้อผิดพลาดเป็น beta โชว์ `outcome` ตามจริง อย่าล้าง กุญแจ ON เครื่องดับ สายอยู่ที่ขั้ววินิจฉัย วิธีติดตั้งอยู่ที่ [JavaScript](https://developers.smongrot.com/th/docs/quickstart-js) และ [Dart](https://developers.smongrot.com/th/docs/quickstart-dart) ## ตัวบันทึก CSV บน Node ```sh npm i @smongrot/sdk serialport node logger.mjs /dev/cu.usbserial-XXXX ``` ```js // logger.mjs import { createWriteStream } from 'node:fs'; import { SerialPort } from 'serialport'; import { connect, fromSerialPort } from '@smongrot/sdk'; const path = process.argv[2]; if (!path) { console.log('usage: node logger.mjs '); for (const p of await SerialPort.list()) console.log(' ', p.path, p.manufacturer ?? ''); process.exit(1); } const port = new SerialPort({ path, baudRate: 10400, dataBits: 8, stopBits: 1, parity: 'none', autoOpen: false, }); const t = await fromSerialPort(port); const out = createWriteStream('live.csv'); out.write('t_ms,profile,rpm,ect,eot,batt\n'); const t0 = Date.now(); let n = 0; let s; const cell = (f, key) => (f.fields[key]?.status === 'ok' ? f.fields[key].value : ''); try { s = await connect(t); for await (const f of s.live()) { out.write(`${Date.now() - t0},${f.profile},${cell(f, 'rpm')},${cell(f, 'ect')},${cell(f, 'eot')},${cell(f, 'batt')}\n`); if (++n === 50) break; } } finally { if (s) await s.close(); else await t.close(); out.end(); } ``` `ect` กับ `eot` เป็นคนละฟิลด์ บนโปรไฟล์หนึ่งจะมีอันใดอันหนึ่งว่าง ช่องว่างแปลว่า `absent` หรือ `invalid` ไม่ใช่ศูนย์ แพ็กเกจ npm ยังมี `examples/node-serialport.mjs` ซึ่งพิมพ์ไม่กี่เฟรมกับรหัสข้อผิดพลาด ## เกจ live บนเบราว์เซอร์ Chrome หรือ Edge บนเดสก์ท็อป หน้าต้องเป็น https หรือ localhost `requestPort()` ต้องอยู่ในตัวจัดการคลิก ```html

—

``` การ abort สัญญาณจบลูปโดยไม่ throw จากนั้น `close()` ปล่อยพอร์ต เสิร์ฟไฟล์จาก bundler ที่ resolve `@smongrot/sdk` ได้ อย่าใส่ API key ในหน้านี้ ## หน้าจอ live บน Flutter เดสก์ท็อป ```sh flutter pub add smongrot_sdk smongrot_sdk_libserialport ``` ```dart import 'package:flutter/material.dart'; import 'package:smongrot_sdk/smongrot_sdk.dart'; import 'package:smongrot_sdk_libserialport/smongrot_sdk_libserialport.dart'; void main() { final ports = SerialPort.availablePorts; runApp(MaterialApp( home: ports.isEmpty ? const Scaffold(body: Center(child: Text('No serial port'))) : LiveScreen(portName: ports.first), )); } class LiveScreen extends StatefulWidget { const LiveScreen({super.key, required this.portName}); final String portName; @override State createState() => _LiveScreenState(); } class _LiveScreenState extends State { String _rpm = '—'; @override void initState() { super.initState(); _run(); } Future _run() async { final t = LibSerialPortTransport.open(widget.portName); Session? s; try { s = await connect(t); await for (final f in s.live()) { if (!mounted) break; final rpm = f.fields['rpm']!; setState(() => _rpm = rpm.ok ? rpm.value!.round().toString() : '—'); } } finally { if (s != null) { await s.close(); } else { await t.close(); } } } @override Widget build(BuildContext context) { return Scaffold(body: Center(child: Text(_rpm, style: const TextStyle(fontSize: 64)))); } } ``` `LibSerialPortTransport.open` เป็นแบบซิงโครนัส และ throw `PORT_OPEN` (เป็น `SmongrotException`) เมื่อเปิดพาธไม่ได้ `rpm.ok` คือ `status == 'ok'` การออกจากหน้าทำให้ `mounted` เป็นเท็จ เฟรมถัดไปจะหลุดจากลูป แล้ว `finally` ปิดพอร์ต ## Android OTG ```sh flutter pub add smongrot_sdk smongrot_sdk_usb_serial ``` เรียกจากปุ่ม `create()` แสดงหน้าขอสิทธิ์ USB และคืน null ถ้าผู้ใช้ปฏิเสธ ```dart import 'package:smongrot_sdk/smongrot_sdk.dart'; import 'package:smongrot_sdk_usb_serial/smongrot_sdk_usb_serial.dart'; Future readOnce() async { final devices = await UsbSerial.listDevices(); if (devices.isEmpty) return; final port = await devices.first.create(); if (port == null) return; final t = await UsbSerialTransport.open(port); Session? s; try { s = await connect(t); final id = await s.identify(); print(id.ecmId ?? '—'); final f = await s.live().first; final rpm = f.fields['rpm']!; print(rpm.ok ? rpm.value : '—'); } finally { if (s != null) { await s.close(); } else { await t.close(); } } } ``` `live().first` ยกเลิกสตรีมหลังหนึ่งเฟรม ซึ่งทำให้ session กลับไป `ready` wake ของ adapter นี้เป็นพัลส์ baud ต่ำสั้น ๆ เว้นแต่ส่ง `atomicWake`: ```dart await UsbSerialTransport.open(port, atomicWake: myFtdiBitBang); ``` `myFtdiBitBang` มีชนิด `Future Function(Duration low)` และต้องดึง K-Line ลง LOW นานเท่า `low` (70 ms) บนชิป ## อ่านรหัสข้อผิดพลาด (beta) หยุด live data ก่อน ถอดรหัสได้เฉพาะ payload ของ Keihin `beta` เป็นจริงเสมอ `critical` เป็นจริงสำหรับรหัส 12, 33 และ 52 — โน้ตในสเปกสำหรับรหัสเหล่านี้คือเครื่องอาจเดินไม่ปกติและควรตรวจเร็ว ๆ `benchConfirmed` เป็นจริงเฉพาะ `7-1` และ `8-1` ที่เหลือเป็นคำใบ้ `meaning` เป็น null เมื่อป้ายไม่อยู่ในตาราง ```js async function showFaults(s) { // s.state must be 'ready'. Do not call this from inside live(). const dtc = await s.dtc.read(); if (dtc.outcome !== 'faults') { console.log(dtc.outcome); // clean | unreadable | failed return; } for (const c of dtc.codes) { console.log(c.label, c.meaning ?? '', c.critical ? 'critical' : '', c.benchConfirmed ? 'bench' : 'hint'); } } ``` ```dart Future showFaults(Session s) async { final dtc = await s.dtc.read(); if (dtc.outcome != 'faults') { print(dtc.outcome); return; } for (final c in dtc.codes) { print('${c.label} ${c.meaning ?? ''} ${c.critical ? 'critical' : ''} ${c.benchConfirmed ? 'bench' : 'hint'}'); } } ``` `unreadable` แปลว่าไบต์ parse ไม่ได้ หรือกล่องไม่ใช่ Keihin และ payload ไม่ได้เป็นศูนย์ทั้งหมด ให้โชว์คำนั้น อย่าแทนด้วยลิสต์ว่าง ไม่มีฟังก์ชันล้าง `dtc.read(maker: 'keihin')` (Dart) หรือ `dtc.read({ maker: 'keihin' })` (JS) ทับ hint ใช้ก็ต่อเมื่อรู้ผู้ผลิตจริง hint ที่ผิดบนกล่อง Shindengen จะลองตัวถอดรหัส Keihin และมักได้ `unreadable` ## ชื่อรุ่นจาก API key key ฟรี หนึ่ง session เรียก API ได้มากสุดครั้งเดียว ในการ `identify()` ครั้งแรก live data ไม่ใช้เครือข่าย `transport` ด้านล่างคือ `Transport` ที่เปิดไว้แล้วจากสูตรด้านบน ```js import { connect, smongrotApi } from '@smongrot/sdk'; const api = smongrotApi({ apiKey: process.env.SMONGROT_API_KEY, onError: (e) => console.warn(e.code, e.message), }); const s = await connect(transport, { lookupModel: api.lookupModel }); try { const id = await s.identify(); console.log(id.ecmId); // from the box, offline console.log(id.model?.model ?? '—'); // may be Thai; null if no key, 404, or offline console.log(id.model?.maker, id.model?.ecuCode); } finally { await s.close(); } ``` ```dart import 'dart:io'; import 'package:smongrot_sdk/smongrot_sdk.dart'; final key = Platform.environment['SMONGROT_API_KEY']; final api = key == null ? null : SmongrotApi(apiKey: key, onError: (e) => print('${e.code} ${e.message}')); final s = await connect(transport, lookupModel: api?.lookupModel); try { final id = await s.identify(); print(id.ecmId); print(id.model?.model ?? '—'); } finally { await s.close(); api?.close(); } ``` บนเบราว์เซอร์ อย่าใส่ key ไปกับหน้า ให้ยิง GET จากเซิร์ฟเวอร์ของคุณ แล้วส่ง `lookupModel(ecmId)` ของคุณที่คืน `ModelInfo` หรือ `null` ฟังก์ชันรูปร่างนี้ใช้ได้ทั้งหมด ดู [ระบุตัวกล่องและ API key](https://developers.smongrot.com/th/docs/identify) ## ไม่มีรถ `FakeEcuTransport` ตอบเฟรมที่เขียนสคริปต์ไว้ และไม่มีการรอเวลา trace ม้านั่งเริ่มต้นระบุตัวเป็น `0104780D01` ต้องใส่ reply ของตาราง live ไม่งั้น `live()` throw `LIVE_UNSUPPORTED` ```js import { connect, FakeEcuTransport } from '@smongrot/sdk'; const fake = new FakeEcuTransport({ replies: { '72 07 72 17 00 0F EF': '02 15 72 17 00 0D EE 67 45 F8 0A FF FF FF FF 7D 0C 0D A8 55 28', }, }); const s = await connect(fake, { sleep: async () => {} }); for await (const f of s.live()) { console.log(f.fields.rpm.value); // 3566 break; } await s.close(); ``` ```dart final fake = FakeEcuTransport(replies: { '72 07 72 17 00 0F EF': '02 15 72 17 00 0D EE 67 45 F8 0A FF FF FF FF 7D 0C 0D A8 55 28', }); final s = await connect(fake, sleep: (_) async {}); print((await s.live().first).fields['rpm']!.value); // 3566.0 await s.close(); ``` ถัดไป: [อ้างอิง API](https://developers.smongrot.com/th/docs/api) ============================================================================== # FILE: site/th/identify.md ============================================================================== [English](https://developers.smongrot.com/docs/identify) # ระบุตัวกล่องและ API key > อ่าน ECM-ID จากกล่องแบบออฟไลน์ และถ้าต้องการชื่อรุ่นให้ใช้ API key ฟรี `identify()` อ่าน **ECM-ID** จากกล่อง เป็น 5 ไบต์ แสดงเป็นตัวอักษร hex 10 ตัว (เช่น `0101880D01`) ใช้แค่สาย และทำงานออฟไลน์ได้ **ชื่อรุ่น** (พร้อมผู้ผลิต, รหัส ECU, และ live profile ที่แนะนำ) มาจาก smongrot API ต้องใช้ API key ฟรีจาก https://developers.smongrot.com ถ้าไม่มี key ก็ไม่พัง: live data กับรหัสข้อผิดพลาดทำงานเหมือนเดิม และ `model` เป็น `null` ## JavaScript ```js import { connect, smongrotApi } from '@smongrot/sdk'; const api = smongrotApi({ apiKey: process.env.SMONGROT_API_KEY }); const s = await connect(transport, { lookupModel: api.lookupModel }); const id = await s.identify(); console.log(id.ecmId); // "0101880D01", read from the box console.log(id.model?.model ?? '—'); // model name (may be Thai), or "—" if unknown / offline / no key ``` ## Dart ```dart final api = SmongrotApi(apiKey: myKey); final s = await connect(transport, lookupModel: api.lookupModel); final id = await s.identify(); print(id.ecmId); print(id.model?.model ?? '—'); ``` ## `model` มีอะไรบ้าง | ฟิลด์ | | |---|---| | `model` | ชื่อรุ่นที่คนขี่ใช้เรียก อาจเป็นภาษาไทย และไม่มีปีรุ่น | | `maker` | `keihin` หรือ `shindengen` (ใช้เลือกตัวถอดรหัสข้อผิดพลาดด้วย) | | `ecuCode` | รหัสอะไหล่เต็ม เช่น `38770-K03-H01` (ตั้งเป็น `partCode` ด้วย) | | `liveProfile` | รหัส live profile ที่แนะนำ มักเป็น `null` เพราะ `live()` ตรวจ profile เอง จึงไม่ต้องใส่ | | `verified` | `true` ถ้า ECM-ID นี้ถูกยืนยันกับกล่องจริงแล้ว | | `ecmId` | ECM-ID ที่ API ตอบกลับ | ตัวอย่าง `data`: `{"ecm_id": "0101880D01", "maker": "keihin", "model": "", "ecu_code": "38770-K03-H01", "live_profile": null, "verified": true}` ## คำขอ `GET https://api.smongrot.com/v1/ecu/identify?ecm=<10 hex>` พร้อม header `Authorization: Bearer ` สำเร็จได้ `{ "data": { "ecm_id", "maker", "model", "ecu_code", "live_profile", "verified" } }` ผิดพลาดได้ `{ "error": { "code", "message", "docs_url" } }` ส่งไปแค่ ECM-ID ## ข้อผิดพลาดไม่ทำให้ identify พัง `lookupModel` ไม่ throw ECU ที่ไม่รู้จัก (404), key ผิด, rate limit, timeout (ค่าเริ่มต้น 5 วินาที ตั้งที่ `timeoutMs` / `timeout`) หรือไม่มีเครือข่าย ทุกกรณีนี้ได้ `model: null` อยากรู้สาเหตุ ให้ส่ง `onError`: ```js smongrotApi({ apiKey, onError: (e) => console.warn(e.code, e.message) }); ``` รหัส: `API_UNAUTHORIZED`, `API_RATE_LIMITED`, `API_NETWORK`, `API_ERROR`, `API_BAD_RESPONSE`, `API_BAD_INPUT` ถ้าลืมใส่ key ถือเป็นความผิดพลาดตอนเขียนโปรแกรม จะ throw `NO_API_KEY` ตอนสร้างตัวช่วย ไม่ใช่ระหว่าง identify ## เก็บ key ไว้เป็นความลับ อย่าใส่ key ในหน้าเว็บสาธารณะ ถ้าเป็นแอปบนเบราว์เซอร์ ให้เรียก API จาก เซิร์ฟเวอร์ของคุณเอง แล้วส่ง `lookupModel(ecmId)` ของคุณเข้า `connect` ฟังก์ชันที่คืน `{ model, maker, ... }` หรือ `null` ใช้ได้ทั้งหมด ถัดไป: [ภาพรวมโปรโตคอล](https://developers.smongrot.com/th/docs/protocol) ============================================================================== # FILE: site/th/api.md ============================================================================== [English](https://developers.smongrot.com/docs/api) # อ้างอิง API > ทุก export ของ `@smongrot/sdk` และ `smongrot_sdk`: ชนิด ค่าเริ่มต้น และตัวอย่างเรียกสั้น ๆ เปิด session ด้วย `connect` อย่าสร้าง `Session` เอง (ใน Dart คอนสตรักเตอร์เป็น private) ชื่อตรงกันทั้งสองภาษา ยกเว้นแถวด้านล่าง | | JavaScript | Dart | |---|---|---| | แพ็กเกจ | `@smongrot/sdk` | `smongrot_sdk` | | ข้อผิดพลาด | `SmongrotError extends Error` | `SmongrotException implements Exception` | | `live()` | async generator | `Stream` | | `LiveFrame.at` | มิลลิวินาทีตั้งแต่ epoch (`number`) | `DateTime` | | หยุด `live()` | `break` หรือ `signal: AbortSignal` | `break`, ยกเลิก subscription หรือ `await stream.first` | | DTC `status` | `status: 'beta'` และ `beta: true` | getter `beta` เป็น `true` ไม่มีฟิลด์ `status` | | แก้จังหวะเวลา | อ็อบเจกต์บางฟิลด์ ผสานเข้า `DEFAULT_TIMING` | อินสแตนซ์ `Timing(...)` | | ค่าคงที่ฐาน API | `DEFAULT_API_BASE` | `defaultApiBase` | | สเปกที่ฝังมา | `SPEC` | `spec` | | reply ของม้านั่ง | `BENCH_SESSION` | `benchSession` | | ปิดตัวช่วย HTTP | ไม่มี | `api.close()` | | ไม่มี `fetch` ตอนเริ่ม | throw `NO_FETCH` | ไม่มีกรณีนี้ (`http` เป็น dependency) | `core.*` ใน JavaScript คือฟังก์ชันชุดเดียวกับที่ Dart export ที่ระดับบน (`import 'package:smongrot_sdk/smongrot_sdk.dart'`) ## `connect` ```ts connect(transport: Transport, opts?: ConnectOptions): Promise ``` ```dart Future connect(Transport transport, { bool matchV2 = false, String? makerHint, FutureOr Function(String ecmId)? lookupModel, Timing? timing, Sleep? sleep, DateTime Function()? now, }) ``` ปลุก ECU ส่ง StartComm รอ reply ของ liveness ตัวใดก็ได้ แล้วส่ง StartDiag คืนตอน `state === 'ready'` Throw `ECU_SILENT` หลัง `wakeTries` (ค่าเริ่มต้น 4) Throw `NO_WAKE` เมื่อ transport ของ JS ไม่มีทั้ง `wake` และ `setBreak` ```js const s = await connect(transport, { makerHint: 'keihin' }); ``` ```dart final s = await connect(transport, makerHint: 'keihin'); ``` ### `ConnectOptions` / อาร์กิวเมนต์แบบชื่อ | ชื่อ | ชนิด | ค่าเริ่มต้น | | |---|---|---|---| | `matchV2` | `boolean` | `false` | ใช้กติกา `match_v2` ในโปรไฟล์ที่สเปก live มี ปล่อยปิดไว้ frame ที่เข้าได้เฉพาะกติกานั้นจะตั้งฟิลด์ใน `v2_provisional` เป็น `provisional` | | `makerHint` | `'keihin' \| 'shindengen'` | ไม่ตั้ง | ใช้กับตัวถอดรหัสข้อผิดพลาด และกับ `detect().mismatch` ไม่ได้บังคับโปรไฟล์ live | | `lookupModel` | `(ecmId: string) => ModelInfo \| null` | ไม่ตั้ง | ไม่บังคับ session ไม่เปิดซ็อกเก็ตเอง throw ในฮุกกลายเป็น `model: null` | | `timing` | `Timing` บางฟิลด์ (JS) / `Timing` (Dart) | ค่าด้านล่าง | ทับจังหวะตอนเปิด session และการโพล | | `sleep` | JS `(ms: number) => Promise` / Dart `Future Function(Duration)` | ตัวจับเวลาจริง | เทสส่งฟังก์ชันว่าง | | `now` | JS `() => number` / Dart `DateTime Function()` | `Date.now` / `DateTime.now` | นาฬิกาสำหรับ timeout และ `LiveFrame.at` | ## `Session` `state` เป็น `'idle' | 'waking' | 'ready' | 'live' | 'closed'` อ่านได้ อย่ากำหนดเอง `identify`, `detect`, `live` และ `dtc.read` ต้องอยู่ใน `'ready'` ไม่งั้น `BAD_STATE` ### `identify() → Identity` ส่ง `72 07 72 00 00 05 10` สูงสุด 3 ครั้ง ห่างกัน 300 ms ถ้าไม่ได้ใช้ ECM-ID ที่เก็บจาก StartDiag จากนั้นถ้าตั้ง `lookupModel` และมี id จะเรียกครั้งเดียว ผลถูกจำบน session ```js const id = await s.identify(); id.ecmId; // "0104780D01" | null id.source; // "id_frame" | "start_diag" | null id.model; // ModelInfo | null ``` ```dart final id = await s.identify(); id.ecmId; id.model?.model; ``` ### `Identity` | ฟิลด์ | ชนิด | | |---|---|---| | `ecmId` | `string \| null` | เลขฐานสิบหกตัวใหญ่ 10 ตัว หรือ null | | `ecmIdBytes` | `number[] \| null` / `List?` | 5 ไบต์เดียวกัน หรือ null | | `source` | `'id_frame' \| 'start_diag' \| null` | frame ไหนให้ `ecmId` | | `model` | `ModelInfo \| null` | จาก `lookupModel` ไม่งั้น null | ### `ModelInfo` | ฟิลด์ | ชนิด | | |---|---|---| | `model` | `string?` | ชื่อที่คนขี่ใช้ จาก API อาจเป็นภาษาไทย และไม่มีปี | | `maker` | `'keihin' \| 'shindengen'?` | | | `partCode` | `string?` | รหัสอะไหล่เต็มเมื่อเข้ากับ `NNNNN-…` (ใช้กติกาผู้ผลิตของ DTC) | | `ecuCode` | `string?` | รหัสอะไหล่เต็มตามที่ API ส่ง เช่น `38770-K03-H01` | | `liveProfile` | `string?` | คำแนะนำ มักเป็น null `live()` ตรวจโปรไฟล์เอง | | `ecmId` | `string?` | id ที่ API ตอบ | | `verified` | `boolean` | `true` ถ้า ECM-ID นี้ถูกยืนยันบนกล่องจริง `modelInfoFromApi` ตั้ง `false` เมื่อ API ไม่ได้ส่ง `true` คอนสตรักเตอร์ของ Dart ค่าเริ่มต้นเป็น `false` | ### `detect() → Detected | null` Probe `0x17` แล้ว `0x13` แล้ว `0x11` null แปลว่าไม่มีตาราง live ตอบ ```js const d = await s.detect(); d?.profile; // "t17.sub8" d?.method; // "probed" | "generic" d?.mismatch; // boolean ``` ### `Detected` | ฟิลด์ | ชนิด | | |---|---|---| | `profile` | `string` | id ของโปรไฟล์ | | `method` | `'probed' \| 'generic'` | | | `mismatch` | `boolean` | มีทั้ง maker hint และผู้ผลิตของโปรไฟล์ และทั้งสองไม่ตรงกัน ไม่เป็นจริงบนโปรไฟล์ generic | ### `live(options?) → frames` อ่านตารางหลักหนึ่งครั้งต่อเฟรม แล้วตารางรองที่ถึงรอบมากสุดหนึ่งตาราง ไม่จบจนกว่าคุณจะหยุด การเรียกครั้งแรกยังรัน `identify()` (ใช้ค่าที่จำไว้ถ้าเรียกไปแล้ว) ```ts live(o?: { profile?: string; signal?: AbortSignal; onFrame?: (f: LiveFrame) => void }): AsyncGenerator ``` ```dart Stream live({String? profile, void Function(LiveFrame f)? onFrame}) ``` | ตัวเลือก | ค่าเริ่มต้น | | |---|---|---| | `profile` | ตรวจเอง | id ที่รู้จักจะข้ามการตรวจ id ที่ไม่รู้จัก throw `BAD_PROFILE` | | `signal` | ไม่มี | เฉพาะ JS เมื่อ abort ลูปจบโดยไม่ throw | | `onFrame` | ไม่มี | ถูกเรียกด้วยอ็อบเจกต์เดียวกับที่ yield ก่อน yield | Throw `LIVE_UNSUPPORTED` ถ้าตรวจไม่เจออะไร Throw `BAD_PROFILE` เมื่อ id ไม่รู้จัก หลังลูป `state` กลับเป็น `'ready'` เว้นแต่คุณ `close()` ไปแล้ว ```js for await (const f of s.live()) { const rpm = f.fields.rpm; if (rpm?.status === 'ok') console.log(rpm.value); break; } ``` ```dart await for (final f in s.live()) { final rpm = f.fields['rpm']!; if (rpm.ok) print(rpm.value); break; } ``` ### `LiveFrame` | ฟิลด์ | JS | Dart | | |---|---|---|---| | `at` | `number` (ms) | `DateTime` | นาฬิกาจาก `now` | | `profile` | `string` | `string` | id ของโปรไฟล์ | | `primaryOk` | `boolean` | `boolean` | `false` → ฟิลด์ของตารางหลักเป็น `absent` ในเฟรมนี้ ไม่ใช่ค่าของเฟรมก่อน | | `match` | `boolean` | `boolean` | กติกา match ของโปรไฟล์ยังเข้ากับข้อมูลที่สะสมมา | | `engine` | `'running' \| 'off' \| 'unknown'` | `String` (getter) | `off` = หัวฉีด 0 ms และองศาจุดระเบิด 0° ตอนเครื่องดับ รอบกับอุณหภูมิไม่ใช่ค่าจริง (กล่อง Keihin ขึ้นราว 17,500 รอบ และ −30 °C) ควรซ่อน `unknown` = อ่านสองฟิลด์นี้ไม่ได้ ใช้ `core.engineState(fields)` / `engineState(fields)` ได้ด้วย | | `fields` | `Record` | `Map` | ทุกฟิลด์ของโปรไฟล์ ทุกเฟรม | ### `Reading` | ฟิลด์ | ชนิด | | |---|---|---| | `status` | `'ok' \| 'absent' \| 'invalid'` | `absent` คือไม่มีค่า ไม่ใช่ 0 | | `value` | `number?` / `double?` | มีก็ต่อเมื่อ `ok` | | `prov` | `'bench' \| 'field' \| 'reference' \| 'provisional'` | ไม่ใช่ status | | `source` | `string?` | id ของตารางที่ชนะ เฉพาะตอน `ok` | Dart: `reading.ok` คือ `status == 'ok'` ### `dtc.read(options?) → DtcResult` ```ts dtc.read(o?: { maker?: string }): Promise ``` ```dart Future read({String? maker}) ``` อ่านสามครั้ง `72 05 74 01/02/03` ห่างกัน 60 ms `maker` ทับ hint เฉพาะการเรียกนี้ ต้องอยู่ใน `ready` ```js const dtc = await s.dtc.read(); dtc.beta; // true dtc.outcome; // "faults" | "clean" | "unreadable" | "failed" ``` ### `DtcResult` | ฟิลด์ | ชนิด | | |---|---|---| | `beta` | `true` | เสมอ | | `status` | `'beta'` | เฉพาะ JS | | `outcome` | `'faults' \| 'clean' \| 'unreadable' \| 'failed'` | ดู [แนวคิด](https://developers.smongrot.com/th/docs/concepts) | | `reason` | `'no_reply' \| 'maker_unknown' \| 'bad_payload' \| null` | เหตุที่ไม่มีโค้ด `maker_unknown` = กล่องตอบมีข้อมูล แต่ไม่รู้ว่ายี่ห้อไหน เลยไม่ถอดโค้ด ใส่ API key (`smongrotApi`) หรือ `dtc.read({ maker: 'keihin' })` ถ้ารู้ยี่ห้อกล่อง เป็น null เมื่อ `faults` หรือ `clean` | | `maker` | `string \| null` | hint ที่ใช้ หรือ null | | `codes` | `DtcCode[]` | ว่าง เว้นแต่ `outcome` เป็น `faults` | | `replies` | `{ sub: number, hex: string }[]` | ทั้งสาม sub `hex` เป็นตัวใหญ่คั่นด้วยช่องว่าง `""` ถ้าเงียบ Dart เป็นเรคคอร์ด `({int sub, String hex})` | ### `DtcCode` | ฟิลด์ | ชนิด | | |---|---|---| | `label` | `string` | รูปแบบรหัสกระพริบของ Honda เช่น `7-1` | | `meaning` | `string \| null` | ชื่อเซ็นเซอร์ภาษาอังกฤษ และต่อท้าย `, signal too low` / `, signal too high` สำหรับรหัส 1, 7, 8, 9, 54 เมื่อ sub เป็น 1 หรือ 2 เป็น null ถ้ารหัสไม่อยู่ในตาราง | | `critical` | `boolean` | `true` สำหรับรหัส 12, 33, 52 | | `benchConfirmed` | `boolean` | `true` เฉพาะ `7-1` และ `8-1` | ### `close() → Promise` ตั้ง `state` เป็น `'closed'` และปิด transport ถ้ามี `close` เรียกจาก `finally` ได้ เรียกอะไรที่คุยกับ ECU หลังจากนั้นจะ throw `CLOSED` ```js await s.close(); ``` ## Timing ```ts interface Timing { wakeLowMs: number; wakeIdleMs: number; wakeTries: number; commandQuietMs: number; commandTimeoutMs: number; tableQuietMs: number; tableTimeoutMs: number; ecmIdTries: number; ecmIdGapMs: number; dtcGapMs: number; liveTickUnitMs: number; liveTargetTickMs: number; liveMinGapMs: number; } const DEFAULT_TIMING: Readonly; ``` ```dart class Timing { Timing({int? wakeLowMs, int? wakeIdleMs, int wakeTries = 4, /* same fields */}); } ``` | ฟิลด์ | ค่าเริ่มต้น | |---|---| | `wakeLowMs` | 70 | | `wakeIdleMs` | 130 | | `wakeTries` | 4 | | `commandQuietMs` | 120 | | `commandTimeoutMs` | 2000 | | `tableQuietMs` | 120 | | `tableTimeoutMs` | 500 | | `ecmIdTries` | 3 | | `ecmIdGapMs` | 300 | | `dtcGapMs` | 60 | | `liveTickUnitMs` | 300 | | `liveTargetTickMs` | 150 | | `liveMinGapMs` | 60 | Dart ไม่มีค่าคงที่ `DEFAULT_TIMING` `Timing()` ใส่ค่าเหล่านี้ `Timing(wakeTries: 6)` ทับหนึ่งฟิลด์ ```js await connect(transport, { timing: { wakeTries: 6 } }); ``` ```dart await connect(transport, timing: Timing(wakeTries: 6)); ``` ## Transport ทำให้เองเมื่อจะเพิ่มสาย พอร์ตเป็น 10400 8N1 อยู่แล้ว session ตัด echo ให้ ```ts interface Transport { write(bytes: Uint8Array): Promise; read(timeoutMs: number): Promise; flush?(): Promise; wake?(lowMs: number): Promise; setBreak?(on: boolean): Promise; close?(): Promise; } ``` ```dart abstract class Transport { Future write(Uint8List bytes); Future read(Duration timeout); Future flush(); // default: no-op bool get hasAtomicWake; // default false Future wake(Duration low); // used only when hasAtomicWake Future setBreak(bool on); // fallback wake Future close(); } ``` | สมาชิก | | |---|---| | `write` | ไบต์ดิบ รวม checksum | | `read` | chunk ถัดไปที่รับมา หรือ null เมื่อ timeout JS รับมิลลิวินาที Dart รับ `Duration` | | `flush` | ทิ้งไบต์ที่รับค้าง ถูกเรียกก่อน request ทุกครั้ง | | `wake` | ดึงสายลง LOW ตามเวลาที่ให้ จับเวลาบน adapter ทางที่ควรใช้ | | `setBreak` | `true` ดึงลง LOW, `false` ปล่อย ทางสำรองเมื่อไม่มี `wake` | | `close` | ปล่อยพอร์ต | Dart เรียก `wake` ก็ต่อเมื่อ `hasAtomicWake` เป็นจริง `setBreak` ค่าเริ่มต้น throw `UnsupportedError` ไม่ใช่ `NO_WAKE` JS throw `NO_WAKE` เมื่อไม่มีทั้งคู่ ### `ChunkQueue` คิว FIFO ที่ adapter ใช้ `push(chunk)` ไม่สนใจ chunk ว่าง `read` คืน chunk ถัดไปหรือ null เมื่อครบเวลา `clear()` ทิ้งของที่ค้าง `close()` ทำให้การอ่านถัดไปคืน null ```js const q = new ChunkQueue(); q.push([0x02, 0x04]); await q.read(50); ``` ```dart final q = ChunkQueue(); q.push([0x02, 0x04]); await q.read(const Duration(milliseconds: 50)); ``` ## ข้อผิดพลาด ```ts class SmongrotError extends Error { code: string } ``` ```dart class SmongrotException implements Exception { final String code; final String message; } ``` Session: `ECU_SILENT`, `BAD_STATE`, `LIVE_UNSUPPORTED`, `BAD_PROFILE`, `CLOSED`, `NO_WAKE`, `FRAME_NOT_ALLOWED` (SDK ไม่ยอมส่งเฟรมที่อยู่นอกรายการอ่านอย่างเดียว), `RESPONSE_TOO_LARGE` (อุปกรณ์ส่งข้อมูลเกิน 4 KB ในคำตอบเดียว) Adapter: `BAD_PORT`, `PORT_OPEN`, `WRITE_FAILED` ตัวช่วย API: `NO_API_KEY` และ `NO_FETCH` ของ JS รหัส `API_*` ไปที่ `onError` อย่างเดียว สาเหตุและวิธีแก้: [แก้ปัญหา](https://developers.smongrot.com/th/docs/troubleshooting) ```js try { await connect(transport); } catch (e) { if (e instanceof SmongrotError && e.code === 'ECU_SILENT') console.error(e.message); } ``` ```dart try { await connect(transport); } on SmongrotException catch (e) { if (e.code == 'ECU_SILENT') print(e.message); } ``` ## API ชื่อรุ่น ### `smongrotApi` / `SmongrotApi` ```ts smongrotApi(opts: { apiKey: string; baseUrl?: string; // default DEFAULT_API_BASE fetch?: typeof fetch; timeoutMs?: number; // default 5000 onError?: (e: SmongrotError) => void; }): { baseUrl: string; lookupModel(ecmId: string): Promise } ``` ```dart class SmongrotApi { SmongrotApi({ required String apiKey, String baseUrl = defaultApiBase, http.Client? client, Duration timeout = const Duration(seconds: 5), void Function(SmongrotException e)? onError, }); final String baseUrl; Future lookupModel(String ecmId); void close(); } SmongrotApi smongrotApi({required String apiKey, String baseUrl = defaultApiBase, http.Client? client, Duration timeout = const Duration(seconds: 5), void Function(SmongrotException e)? onError}); ``` `DEFAULT_API_BASE` / `defaultApiBase` คือ `https://api.smongrot.com/v1` เครื่องหมาย `/` ท้ายถูกตัดออก `lookupModel` ไม่ throw 404 (ไม่รู้จัก ECU) คืน null และไม่เรียก `onError` ความล้มเหลวอื่นเรียก `onError` แล้วคืน null id ต้องเป็นเลขฐานสิบหก 10 ตัว ไม่งั้น `onError` ได้ `API_BAD_INPUT` Throw `NO_API_KEY` เมื่อ `apiKey` ว่าง JS ยัง throw `NO_FETCH` เมื่อไม่มี fetch ```js const api = smongrotApi({ apiKey: process.env.SMONGROT_API_KEY, onError: (e) => console.warn(e.code) }); const s = await connect(transport, { lookupModel: api.lookupModel }); ``` ```dart final api = SmongrotApi(apiKey: myKey, onError: (e) => print(e.code)); final s = await connect(transport, lookupModel: api.lookupModel); api.close(); ``` ### `modelInfoFromApi(data) → ModelInfo | null` แปลงอ็อบเจกต์ `data` ของ API (`ecm_id`, `maker`, `model`, `ecu_code`, `live_profile`, `verified`) คืน null เมื่อ `model`, `ecu_code` และ `maker` ใช้ไม่ได้สักตัว `maker` ถูกทำเป็นตัวเล็ก และเก็บไว้ก็ต่อเมื่อเป็น `keihin` หรือ `shindengen` ```js modelInfoFromApi({ ecm_id: '0101880D01', maker: 'Keihin', model: 'เวฟ 110i', ecu_code: '38770-K03-H01', verified: true }); ``` ```dart modelInfoFromApi({'ecm_id': '0101880D01', 'maker': 'Keihin', 'model': 'เวฟ 110i', 'ecu_code': '38770-K03-H01', 'verified': true}); ``` ## Adapter สาย (JavaScript) ### `openWebSerial(port) → Promise` ```ts openWebSerial(port: SerialPort): Promise ``` เปิดพอร์ต Web Serial ที่ 10400 8N1 ไม่มี flow control `port` มาจาก `navigator.serial.requestPort()` และต้องยังไม่ถูกเปิด wake คือ `setBreak` นาน 70 ms `close()` ยกเลิก reader แล้วปิดพอร์ต ความล้มเหลวของเบราว์เซอร์ reject ด้วย `DOMException` ไม่ใช่ `SmongrotError` ```js const s = await connect(await openWebSerial(await navigator.serial.requestPort())); ``` ### `fromSerialPort(port, opts?) → Promise` ```ts fromSerialPort(port: SerialPort, o?: { wake?: (lowMs: number) => Promise; closeStream?: boolean }): Promise ``` ห่อ `SerialPort` ของ `serialport` เปิดให้ถ้ายังไม่เปิด Reject `BAD_PORT` เมื่อค่าไม่ใช่ SerialPort, baud ถูกตั้งและไม่ใช่ 10400 หรือเฟรมไม่ใช่ 8N1 wake คือ `port.set({ brk })` นาน 70 ms เว้นแต่ส่ง `wake` `closeStream` ค่าเริ่มต้นคือปิดพอร์ตตอน `close()` `serialport` เป็น optional peer ติดตั้งเอง แพ็กเกจนี้ไม่ import มัน ```js import { SerialPort } from 'serialport'; const port = new SerialPort({ path: '/dev/cu.usbserial-XXXX', baudRate: 10400, autoOpen: false }); const s = await connect(await fromSerialPort(port)); ``` ### `fromDuplex(stream, opts?) → Transport` ```ts fromDuplex(stream: Duplex, o?: { setBreak?: (on: boolean) => Promise; wake?: (lowMs: number) => Promise; closeStream?: boolean; // default true (stream.destroy() on close) }): Transport ``` Duplex ของ Node ที่เป็น 10400 8N1 อยู่แล้ว ไม่ตรวจ baud ถ้าไม่มี `wake` หรือ `setBreak` `connect` จะ throw `NO_WAKE` `write` reject ด้วยข้อผิดพลาดของสตรีม ไม่ใช่ `SmongrotError` ```js const t = fromDuplex(stream, { setBreak: (on) => new Promise((ok, no) => port.set({ brk: on }, (e) => e ? no(e) : ok())) }); ``` ## Adapter สาย (Dart) เผยแพร่แยก เพื่อให้ core เป็น Dart ล้วน ทั้งคู่ตั้ง 10400 8N1 และไม่มี flow control ### `LibSerialPortTransport` (`smongrot_sdk_libserialport`) เดสก์ท็อป Windows, macOS, Linux ผ่าน `flutter_libserialport` re-export `SerialPort` | สมาชิก | | |---|---| | `LibSerialPortTransport.open(name)` | เปิดอ่านเขียน ตั้ง 10400 8N1 Throw `PORT_OPEN` | | `LibSerialPortTransport.fromOpenPort(port)` | ห่อพอร์ตที่เปิดไว้แล้ว ตั้ง 10400 8N1 | | `LibSerialPortTransport.configureKLine(port)` | baud 10400, 8 data bits, ไม่มี parity, 1 stop bit, ไม่มี flow control | | `setBreak(on)` | break ของระบบปฏิบัติการ Throw `NO_WAKE` ถ้าไดรเวอร์ปฏิเสธ | | `write` | throw `WRITE_FAILED` ถ้าไบต์ไม่ถูกยอมรับครบ (timeout การเขียน 1000 ms) | wake เป็น break 70 ms ไม่มี `hasAtomicWake` ```dart import 'package:smongrot_sdk_libserialport/smongrot_sdk_libserialport.dart'; print(SerialPort.availablePorts); final s = await connect(LibSerialPortTransport.open('/dev/cu.usbserial-XXXX')); ``` ### `UsbSerialTransport` (`smongrot_sdk_usb_serial`) Android USB-OTG ผ่าน `usb_serial` re-export `UsbSerial`, `UsbPort`, `UsbDevice` ```dart static Future open(UsbPort port, {Future Function(Duration low)? atomicWake}) ``` Throw `PORT_OPEN` ถ้า `port.open()` คืน false ตั้ง DTR และ RTS ให้ต่ำ `hasAtomicWake` เป็นจริง: `wake` เรียก `atomicWake` เมื่อคุณส่งมา ไม่งั้นใช้ `emulatedWake` (LOW ประมาณ 45 ms) ```dart import 'package:smongrot_sdk_usb_serial/smongrot_sdk_usb_serial.dart'; final devices = await UsbSerial.listDevices(); final port = await devices.first.create(); final s = await connect(await UsbSerialTransport.open(port!)); ``` ### `emulatedWake` / `emulatedWakeBaud` / `kLineBaud` อยู่ใน core ของ Dart สำหรับคนที่เขียน adapter เอง | | | |---|---| | `kLineBaud` | `10400` | | `emulatedWakeBaud(lowMs)` | `round(9000 / lowMs)` บีบไว้ที่ 200..600 ที่ 70 ms ได้ 129 แล้วถูกบีบเป็น 200 | | `emulatedWake(lowMs, {setBaud, write, sleep})` | สลับไป baud นั้น เขียน `0x00` หนึ่งไบต์ รอ `ceil(10000 / baud) + 60` ms แล้วกลับ 10400 ไดรเวอร์ที่ปฏิเสธ baud ต่ำจะข้ามพัลส์ สายถูกคืนเป็น 10400 เสมอ | ```dart await emulatedWake( 70, setBaud: (baud) async { /* switch your chip, including back to 10400 */ }, write: (bytes) async { /* write these bytes */ }, ); ``` `setBaud` คือ `Future Function(int baud)` `write` คือ `Future Function(Uint8List bytes)` `sleep` ค่าเริ่มต้นคือ `Future.delayed` ## ตัวแทนสำหรับเทส ### `FakeEcuTransport` ECU ที่ตอบตามสคริปต์ `read` ไม่รอตัวจับเวลา: ได้ chunk ถัดไป หรือ null ทันที ส่ง `sleep: async () => {}` (JS) หรือ `sleep: (_) async {}` (Dart) ให้ `connect` เพื่อไม่ให้เทสรอ 70 ms กับ 130 ms ```ts new FakeEcuTransport(o?: { replies?: Record string | null)>; raw?: Record; bench?: boolean; // default true echo?: boolean; // default true chunkSize?: number; // default 0 = one chunk }) ``` ```dart FakeEcuTransport({ Map replies = const {}, Map raw = const {}, bool bench = true, bool echo = true, int chunkSize = 0, }) ``` | | | |---|---| | `replies` | hex ของคำขอ → hex ของ reply ที่ส่งหลัง echo `null` คือเงียบ ค่าของ JS เป็นฟังก์ชันของไบต์ tx ได้ ค่าของ Dart เป็นสตริงอย่างเดียว | | `raw` | hex ของคำขอ → สิ่งที่อ่านกลับตรง ๆ ไม่ผ่านกติกา echo | | `bench` | โหลด `BENCH_SESSION` / `benchSession` (StartComm, liveness, StartDiag, ECM-ID) `identify()` จะได้ `0104780D01` | | `writes` | hex ของทุกเฟรมที่ถูกเขียน | | `badChecksumWrites` | ส่วนย่อยที่ checksum ผิด | | `wakes` | JS: `number[]` ของ low-ms Dart: `List` | ตัวปลอมที่มีแค่ bench ไม่มีตาราง live `live()` throw `LIVE_UNSUPPORTED` จนกว่า `replies` จะมีหนึ่งตาราง reply ที่ควิกสตาร์ตใช้ถอด rpm ได้ 3566 ```js const s = await connect(new FakeEcuTransport(), { sleep: async () => {} }); console.log((await s.identify()).ecmId); // 0104780D01 ``` ```dart final s = await connect(FakeEcuTransport(), sleep: (_) async {}); print((await s.identify()).ecmId); ``` ## `SPEC` / `spec` สเปก level 1 ที่ฝังมา: `kline`, `live`, `dtc` ข้อความที่เป็นเกณฑ์คือ JSON ที่เผยแพร่คู่กับเอกสารนี้ ใน JavaScript `SPEC` ก็คือ `core.SPEC` ```js SPEC.kline.physical.baud; // 10400 ``` ```dart spec['kline']['physical']['baud']; // 10400 ``` ## ตัวช่วยโปรโตคอล (`core.*` / ระดับบนของ Dart) ฟังก์ชันบริสุทธิ์ ไม่มี I/O กับรถจริงให้ใช้ `connect` ใช้ชุดนี้เมื่อจะทดสอบเฟรม หรือสร้างเครื่องมือบนกติกาเดียวกัน ### `fromHex(s) → bytes` `'72 07 72 17 00 0F'` → `[0x72, 0x07, 0x72, 0x17, 0x00, 0x0F]` มีแต่ช่องว่าง → `[]` ```js core.fromHex('72 05 71 00 18'); ``` ```dart fromHex('72 05 71 00 18'); ``` ### `toHex(bytes) → string` ตัวใหญ่ คั่นด้วยช่องว่าง `toHex([0x72, 0x07])` → `'72 07'` ### `checksum(body) → number` `(0x100 − (sum mod 256)) mod 256` มาสก์เหลือ 8 บิต ```js core.checksum(core.fromHex('72 07 72 17 00 0F')); // 0xEF ``` ### `isValidFrame(frame) → boolean` จริงเมื่อเฟรมไม่ว่าง และผลรวมของไบต์เป็น 0 mod 256 ### `validReplyLength(raw, p) → number | null` ความยาว `L` ของเฟรมที่ถูกต้องซึ่งเริ่มที่ `p` หรือ null `L = raw[p+1]`, `L >= 4`, เฟรมอยู่ในบัฟเฟอร์ และผลรวมของไบต์เป็น 0 mod 256 ### `peelEcho(raw, tx) → { echo, distorted, reply }` ตัด echo ของการอ่านกลับหนึ่งครั้ง คืน echo, บอกว่า echo เพี้ยนหรือไม่ และไบต์ของ reply ```js core.peelEcho(core.fromHex('72 05 00 F0 99 02 04 00 FA'), core.fromHex('72 05 00 F0 99')); // { echo: true, distorted: false, reply: [0x02, 0x04, 0x00, 0xFA] } ``` ### `ecmIdFrom(raw) → string | null` เลขฐานสิบหกตัวใหญ่ 10 ตัวจาก reply หรือ null เลือก `02 0B 72 00 00` ก่อน ไม่งั้น `02 0F 71 00` ### `extractData(reply, request, headerLen, dataLen) → bytes | null` ไบต์ข้อมูลของเฟรม `02 L
` อันสุดท้ายที่ checksum ถูก เป็น null เมื่อไม่มีเฟรม หรือสั้นกว่า `dataLen` ### `normalizeEcmId(s) → string` ตัดช่องว่างแล้วทำเป็นตัวใหญ่ `'01 04780d01'` → `'0104780D01'` ### `profiles()` / `profiles` JS: `core.profiles()` คืนอาเรย์ของโปรไฟล์ Dart: `profiles` เป็น getter ของ `List` (`Profile` คือ `Map`) ### `profileById(id) → profile | null` อ็อบเจกต์โปรไฟล์ หรือ null JS: `core.profileById('t17.sub8')` ### `tableDef(profile, id)` / `primaryTable(profile)` เฉพาะ Dart อ็อบเจกต์ตารางในโปรไฟล์ และตารางหลัก JS อ่าน `profile.tables[id]` กับ `profile.tables[profile.primary]` จากอ็อบเจกต์ของ `profileById` ### `profileMatches(profile, data, matchV2?) → boolean` `data` คือ `{ tableId: bytes }` JS: `core.profileMatches(p, data, false)` Dart: `profileMatches(p, data, matchV2: false)` ### `decodeLive(profile, data, { ecmId?, matchV2? }) → fields` รูปร่างเดียวกับ `LiveFrame.fields` ```js const p = core.profileById('generic.t17'); core.decodeLive(p, { t17: core.fromHex('0D EE 00 00 FF FF FF FF FF FF 00 00 00 00 00') }); ``` ### `makerForPartCode(partCode) → 'keihin' | 'shindengen' | null` `38770-…` → `keihin` `30400-…` → `shindengen` ที่เหลือ รวม null → null ```js core.makerForPartCode('38770-K03-H01'); // "keihin" ``` ### `probeTables() → { table, def }[]` ลำดับการ probe `table` คือไบต์ `23`, `19`, `17` (`0x17`, `0x13`, `0x11`) `def` คืออ็อบเจกต์ตารางหลักของโปรไฟล์นั้น (`request`, `reply_header_len`, `data_len`) ### `chooseProfile(table, data, { makerHint?, matchV2? }) → detection | null` JS คืน `{ profile, method, mismatch }` โดย **`profile` เป็นอ็อบเจกต์โปรไฟล์** หรือ null Dart คืน `Detected?` โดย **`profile` เป็นสตริง id** `session.detect()` คืน id ทั้งสองภาษา `table` คือไบต์ (`23`, `19` หรือ `17`) `data` คือไบต์ของตารางหลัก ```js const c = core.chooseProfile(0x17, bytes, { makerHint: 'keihin' }); c?.profile.id; ``` ```dart final c = chooseProfile(0x17, bytes, makerHint: 'keihin'); c?.profile; // the id ``` ### `dtcPayloadOf(reply, sub?) → bytes | null` payload ของเฟรม `02 … 74` ที่ถูกต้องอันสุดท้าย ถ้าส่ง `sub` ต้องตรงกับไบต์ sub ของ reply ### `decodeDtcPayload(payload) → string[] | null` ป้าย หรือ null เมื่อ payload อ่านไม่ได้ ลิสต์ว่างแปลว่า payload นี้ไม่มีรหัส ### `decodeDtcReplies(replies, subs?) → string[] | null` ยูเนียนของป้าย หรือ null ถ้า reply ใดอ่านไม่ได้ เมื่อส่ง `subs` ต้องมีหนึ่งค่าต่อหนึ่ง reply ### `describeDtc(label) → meaning | null` JS คืน `{ meaning, critical, benchConfirmed }` หรือ **null** เมื่อรหัสไม่อยู่ในตาราง Dart คืน `DtcCode` ที่ `meaning` เป็น null ในกรณีนั้น (ป้ายยังอยู่) ```js core.describeDtc('7-1'); // { meaning: "engine temperature sensor, signal too low", critical: false, benchConfirmed: true } ``` ```dart describeDtc('7-1').meaning; ``` ถัดไป: [ระบุตัวกล่องและ API key](https://developers.smongrot.com/th/docs/identify) ============================================================================== # FILE: site/th/protocol.md ============================================================================== [English](https://developers.smongrot.com/docs/protocol) # ภาพรวมโปรโตคอล (level 1) > K-Line ของ level 1: 10400 8N1, wake, session, checksum, ตาราง live และการอ่านรหัสข้อผิดพลาด กฎฉบับเต็ม: [kline](https://developers.smongrot.com/spec/kline.json), [live](https://developers.smongrot.com/spec/live.json), [dtc](https://developers.smongrot.com/spec/dtc.json) ## สาย - ISO 9141 K-Line: สายเส้นเดียว, half-duplex, **10400 baud 8N1** - สายจะ **echo** ทุกไบต์ที่ส่ง ก่อนที่ ECU จะตอบ ให้ตัด echo ออก ตัดได้เมื่อเป็นสำเนาตรงทุกไบต์ หรือเป็นสำเนาที่บิตถูกเคลียร์ได้แต่ไม่ถูกเซ็ตเพิ่ม และมี reply ที่ถูกต้องตามมา - Frame: `[header][total length incl. checksum][service][args…][checksum]` request ขึ้นต้น `0x72` (หรือ `0xFE` สำหรับ StartComm) reply ขึ้นต้น `0x02` - **Checksum** = `(0x100 − (sum of bytes mod 256)) mod 256` frame ที่ถูกต้อง ผลรวมเป็น 0 mod 256 ผลบวกธรรมดาใช้ไม่ได้ ตัวอย่าง: `72 07 72 17 00 0F` → `EF` ## Session 1. Wake: ดึงสายลง LOW นาน **70 ms** จับเวลาแบบ atomic แล้ว idle 130 ms 2. StartComm `FE 04 72 8C` (ไม่จำเป็นต้องมี reply) 3. Liveness: `72 05 00 F0 99` แล้ว `72 05 71 00 18` แล้ว `7E 06 01 01 00 7A` ตัวแรกที่ได้ reply กลับมา แปลว่า session พร้อมแล้ว ลองขั้นที่ 1–3 ใหม่ได้สูงสุด 4 ครั้ง 4. StartDiag `72 05 71 00 18` (ต้องส่งก่อน ตาราง live data จึงจะตอบ) 5. ECM-ID `72 07 72 00 00 05 10` → `02 0B 72 00 00 <5 bytes> ck` ลองได้สูงสุด 3 ครั้ง ห่างกันครั้งละ 300 ms ถ้าไม่ได้ ให้ใช้ ID ที่อยู่ใน reply ของ StartDiag ## Live data อ่านด้วย `72 07 72
00 ck` แล้วตัดไบต์ข้อมูลจาก frame `02 L 72
` อันสุดท้ายที่ถูกต้อง แต่ละฟิลด์คือ `raw × scale + add` จากไบต์ big-endian มี sentinel (absent), ช่วงค่า (invalid), clamp, แหล่งแยกตาม ECM-ID และลำดับ fallback ทุกค่ามีที่มาติดไปด้วย: bench / field / reference / provisional มี layout ห้าแบบ (`t17.sub8` Keihin, `t17.sub4` Shindengen, `t13.type7`, `t11.type1`, `generic.t17`) SDK ตรวจ layout โดย probe ตาราง `0x17 → 0x13 → 0x11` ## รหัสข้อผิดพลาด (beta) `72 05 74 01/02/03` → `02 0C 74 ck` payload ขึ้นต้นด้วยไบต์ `00` แล้วตามด้วยคู่ (code, sub) อ่านเป็นรหัสกระพริบของ Honda เช่น `7-1` ถอดรหัสได้เฉพาะ กล่อง Keihin ถ้ามีจุดที่ parse ไม่ได้ ผลคือ "unreadable" ไม่มีการเดา ถัดไป: [แก้ปัญหา](https://developers.smongrot.com/th/docs/troubleshooting) ============================================================================== # FILE: site/th/troubleshooting.md ============================================================================== [English](https://developers.smongrot.com/docs/troubleshooting) # แก้ปัญหา > รหัส `code` ทุกตัวที่ SDK throw หรือรายงาน สาเหตุ และสิ่งที่ต้องเปลี่ยน JavaScript throw `SmongrotError` (`e.code`, `e.message`) Dart throw `SmongrotException` (ฟิลด์เดียวกัน) จับสองชนิดนี้ การค้นรุ่นไม่ throw: `lookupModel` คืน `null` และเรียก `onError` ยกเว้นกรณี "ไม่รู้จัก ECU" ```js try { const s = await connect(transport); } catch (e) { if (e instanceof SmongrotError) console.error(e.code, e.message); else throw e; } ``` ```dart try { final s = await connect(transport); } on SmongrotException catch (e) { print('${e.code} ${e.message}'); } ``` ความล้มเหลวของ adapter และเบราว์เซอร์บางครั้ง reject ด้วยข้อผิดพลาดเดิมโดยไม่มี `code` (`DOMException` จาก WebSerial, ข้อผิดพลาดของสตรีมจาก `fromDuplex`) จับ `SmongrotError` ก่อน แล้วค่อยจัดการที่เหลือ ## Session ### `ECU_SILENT` ไม่มี reply ของ liveness หลัง wake 4 ครั้ง (LOW 70 ms, idle 130 ms, StartComm, probe สามตัว) ข้อความคือ `no answer after wake (key ON? cable on the DLC?)` **สาเหตุ.** กุญแจ OFF, สายเสียบผิดขั้ว, พอร์ตอนุกรมผิด, baud ไม่ใช่ 10400 หรือ wake ที่กล่องไม่สนใจ **แก้.** บิดกุญแจ ON ตรวจพาธพอร์ต ดู [ฮาร์ดแวร์](https://developers.smongrot.com/th/docs/hardware) แล้วลองใหม่ กล่อง Shindengen ที่เพิ่งบิดไป ON มักต้องใช้ wake แบบ atomic 70 ms (FTDI bit-bang) พัลส์บน Android ประมาณ 45 ms และ adapter บนเดสก์ท็อปใช้ break ของระบบปฏิบัติการ `connect` ลองให้ครบ 4 ครั้งแล้ว ค่าเริ่มต้นคือ 4 ครั้ง เรียก `connect` ใหม่ หรือส่ง `wakeTries` สูงขึ้นเมื่อมีเหตุผล ### `BAD_STATE` การเรียกไม่ตรงกับ `session.state` ข้อความคือ `session is , needs ` **สาเหตุ.** เรียก `identify`, `detect`, `live` หรือ `dtc.read` ตอน state ไม่ใช่ `ready` กรณีที่พบบ่อยคือเรียก `dtc.read()` หรือ `live()` ครั้งที่สองจากในลูป live (`state` เป็น `live`) รวมถึงใช้ session ก่อน `connect` สำเร็จ หรือหลัง `close()` **แก้.** `await` `connect` ให้จบก่อน ออกจากลูป live (หรือ abort สัญญาณ / ยกเลิก subscription ของ Dart) แล้วรอจนลูปจบ `state` กลับเป็น `ready` จากนั้นค่อยอ่านรหัสข้อผิดพลาด อย่ากำหนด `state` เอง ### `LIVE_UNSUPPORTED` `live()` probe `0x17`, `0x13` และ `0x11` แล้วไม่มีตารางไหนคืนข้อมูล **สาเหตุ.** session ขึ้นแล้ว แต่กล่องนี้ไม่ตอบตาราง live รวมถึงสายที่หลุดหลัง wake หรือ timeout ของตาราง (500 ms) บนลิงก์ที่ช้ามาก **แก้.** อยู่บน session นี้แล้วเรียก `identify()` ถ้า ECM-ID มา แปลว่าบัสใช้ได้ และกล่องนี้ไม่มีตาราง live ของ level 1 (`detect()` คืน `null`) ถ้า ID เป็น null ด้วย ให้แก้สายแล้วเชื่อมใหม่ อย่าเติมจอด้วยศูนย์ ### `BAD_PROFILE` `live({ profile })` ได้ id ที่ไม่มีในสเปก **สาเหตุ.** พิมพ์ผิด หรือสตริง `liveProfile` จาก API ที่ SDK รุ่นนี้ไม่มี คำแนะนำจาก API มักเป็น `null` อยู่แล้ว **แก้.** ไม่ต้องส่ง `profile` ให้ `live()` ตรวจเอง id ที่ใช้ได้: `t17.sub8`, `t17.sub4`, `t13.type7`, `t11.type1`, `generic.t17` ### `CLOSED` เรียกอะไรก็ตามที่คุยกับ ECU หลัง `close()` **สาเหตุ.** ลูป live หรือ `identify` ที่มาช้ายังทำงานอยู่ตอนปิด หรือเรียกซ้ำบน session เดิม **แก้.** ทิ้ง session แล้ว `connect` ใหม่ `close()` เป็นจุดจบ ### `NO_WAKE` **สาเหตุ.** JavaScript: transport ไม่มีทั้ง `wake(lowMs)` และ `setBreak(on)` Dart เดสก์ท็อป: ไดรเวอร์ปฏิเสธ break (`break on/off refused by the driver`) **แก้.** ใช้ adapter ที่มากับ SDK หรือทำให้ transport ของคุณมี `wake` (ทางที่ควรใช้) หรือ `setBreak` สตรีมของ `fromDuplex` ต้องมี `{ setBreak }` หรือ `{ wake }` ในตัวเลือก การส่ง `wake` ให้ `fromSerialPort` จะใช้ตัวนั้นแทน break ### `FRAME_NOT_ALLOWED` **สาเหตุ.** มีการพยายามส่งเฟรมที่ไม่อยู่ในรายการอ่านอย่างเดียวของ SDK (เริ่ม session, อ่าน ECM ID, keep-alive, ตาราง live, อ่านรหัสปัญหา) SDK ปฏิเสธก่อนที่อะไรจะออกไปถึงสาย **แก้.** การใช้งานปกติไม่ต้องแก้อะไร เพราะ API สาธารณะส่งเฉพาะเฟรมที่อนุญาต การเขียน การลบ และการล้างรหัสปัญหาทำผ่าน SDK นี้ไม่ได้ ### `RESPONSE_TOO_LARGE` **สาเหตุ.** อุปกรณ์ส่งข้อมูลเกิน 4 KB ในคำตอบเดียว ECU จริงที่ 10400 baud ไม่ส่งแบบนี้ แปลว่าน่าจะเลือกพอร์ตผิด adapter มีปัญหา หรืออุปกรณ์ไม่ใช่ ECU **แก้.** ตรวจพอร์ตกับสาย แล้ว `connect` ใหม่ ## Adapter ### `BAD_PORT` เฉพาะ `fromSerialPort` ค่าที่ส่งมาไม่ใช่ `SerialPort` ของ `serialport`, baud ถูกตั้งและไม่ใช่ 10400 หรือเฟรมไม่ใช่ 8N1 **แก้.** `new SerialPort({ path, baudRate: 10400, dataBits: 8, stopBits: 1, parity: 'none', autoOpen: false })` ปล่อย baud ว่างได้ก็ต่อเมื่อยังไม่ได้เปิดจริง baud ที่ผิดจะถูกปฏิเสธ ### `PORT_OPEN` adapter ของ Dart เดสก์ท็อป: `LibSerialPortTransport.open` เปิดพาธไม่ได้ Android: `UsbSerialTransport.open` ได้ `false` จาก `port.open()` (ไม่ให้สิทธิ์ หรือถอดสาย) **แก้.** เดสก์ท็อป: ใช้พาธจาก `SerialPort.availablePorts` และมีสิทธิ์บนโหนดอุปกรณ์ Android: เรียก `device.create()` เพื่อให้หน้าขอสิทธิ์ขึ้น แล้ว `open` พอร์ตที่มันคืน เสียบสาย OTG ก่อนลิสต์ ### `WRITE_FAILED` เฉพาะ Dart เดสก์ท็อป `LibSerialPortTransport.write` รับไบต์ไม่ครบ (timeout ของการเขียนคือ 1000 ms) **สาเหตุ.** พอร์ตค้าง หรือถูกถอดกลางทาง **แก้.** ปิด เสียบใหม่ แล้ว `connect` อีกครั้ง การเขียนบน Android ไม่ใช้รหัสนี้ ข้อผิดพลาด USB จะ reject `Future` จาก `port.write` ### `NO_FETCH` เฉพาะ JavaScript throw ตอน **สร้าง** `smongrotApi` เมื่อไม่มี `globalThis.fetch` และคุณไม่ได้ส่ง `fetch` **แก้.** Node 18 ขึ้นไปมี fetch บนรันไทม์ที่เก่ากว่า ให้ส่ง `fetch` ในตัวเลือก Dart ไม่มีรหัสนี้ (`http` เป็น dependency จริง) ## API key รหัสที่ throw มีแค่ `NO_API_KEY` รหัส `API_*` ทุกตัวไปที่ `onError` `lookupModel` ยังคืน `null` และ `identify()` ยังคืน ECM-ID ### `NO_API_KEY` `apiKey` หายหรือเป็นช่องว่าง throw จาก `smongrotApi(...)` / `SmongrotApi(...)` ไม่ใช่จาก `identify` **แก้.** ส่ง key หรืออย่าสร้างตัวช่วย ถ้าไม่มีตัวช่วย ให้ `connect` โดยไม่ส่ง `lookupModel` แล้ว `model` จะเป็น `null` ขอ key ฟรีที่ https://developers.smongrot.com ### `API_BAD_INPUT` `onError` สตริงที่ส่งให้ `lookupModel` ไม่ใช่เลขฐานสิบหก 10 ตัว หลังจากตัดช่องว่างและทำตัวอักษรให้เป็นตัวใหญ่ **แก้.** ส่ง `identity.ecmId` ซึ่งเป็นเลขฐานสิบหกตัวใหญ่ 10 ตัวอยู่แล้ว หรืออย่าเรียก `lookupModel` เมื่อ `ecmId` เป็น null ### `API_UNAUTHORIZED` `onError` HTTP 401 หรือ 403 **แก้.** key ผิด หรือถูกตัดคำว่า `Bearer` ออกไปแล้ว ตัวช่วยส่ง `Authorization: Bearer ` เอง ส่ง key ดิบ ไม่ใช่ทั้งหัว ### `API_RATE_LIMITED` `onError` HTTP 429 key ฟรีใช้ได้ **1000 คำขอต่อวัน** **แก้.** เก็บชื่อรุ่นของ ECM-ID นั้นไว้ในแอป live data ไม่เรียก API `identify()` ก็จำผลไว้: หนึ่ง session ค้นครั้งเดียว ### `API_NETWORK` `onError` คำขอ throw หรือชน timeout (ค่าเริ่มต้น **5 วินาที**, `timeoutMs` ใน JS, `timeout` ใน Dart) **แก้.** ออฟไลน์เป็นสถานะที่รองรับ โชว์ ECM-ID แล้วปล่อยชื่อรุ่นเป็น `—` เพิ่ม `timeoutMs` ก็ต่อเมื่อเครือข่ายช้าจริง อย่ารีทรายในลูปถี่ ### `API_ERROR` `onError` ข้อผิดพลาด HTTP อื่น ๆ `e.message` มีสถานะ และ `error.code` / `error.message` ของ API เมื่อบอดี้มีค่าพวกนั้น **แก้.** อ่าน `e.message` ECM-ID ที่อ่านจากกล่องยังใช้ได้ ### `API_BAD_RESPONSE` `onError` HTTP 200 แต่ JSON ไม่มี `data` ที่ใช้ได้ (`model`, `ecu_code` หรือ `maker`) **แก้.** ถือว่าไม่รู้จักรุ่น อย่า parse บอดี้ด้วยวิธีที่สอง `modelInfoFromApi` คือตัว parse ### ECU ที่ไม่รู้จัก HTTP **404** คืน `null` และ **ไม่** เรียก `onError` กล่องนั้นยังไม่อยู่ในแคตตาล็อก โชว์ ECM-ID ## Timeout, NAK, echo สิ่งเหล่านี้ไม่ใช่รหัสข้อผิดพลาด **Timeout.** การอ่านคำสั่งจบหลังเงียบ 120 ms หรือครบ 2000 ms การอ่านตาราง live จบหลังเงียบ 120 ms หรือครบ 500 ms ไม่มีอะไรถูก throw ได้ reply สั้นหรือว่าง: ฟิลด์กลับมาเป็น `absent` หรือ `dtc.read()` กลับมาเป็น `failed` แก้สายและกุญแจก่อนไปแตะ `timing` แก้ `commandTimeoutMs` / `tableTimeoutMs` (JS) หรือฟิลด์คู่กันของ `Timing` (Dart) ก็ต่อเมื่อวัดแล้วว่าลิงก์ช้า **NAK.** reply ของรหัสข้อผิดพลาดที่มีไบต์ `0x7F` นับเป็นไม่มีคำตอบ ถ้าการอ่าน `72 05 74` ทั้งสามครั้งเงียบหรือเป็น NAK `outcome` คือ `failed` SDK ไม่แต่งรหัสจาก NAK เชื่อมใหม่ตอนกุญแจ ON อย่าล้างรหัส v0.1 ไม่มีฟังก์ชันล้าง **Echo.** session ตัด echo ของทุกเฟรมที่ส่งให้เอง ไม่ต้องจัดการเอง | `echo` | `distorted` | เกิดอะไร | |---|---|---| | `true` | `false` | สาย echo คำขอตรงทุกไบต์ ปกติ | | `true` | `true` | echo แค่เคลียร์บิต (ไม่มีการเซ็ตบิตเพิ่ม) และมี reply ที่ถูกต้องตามมา สาย USB บางเส้นเป็นแบบนี้ reply ยังถูกใช้ | | `false` | `false` | สิ่งที่อ่านกลับไม่ได้ขึ้นต้นด้วยคำขอ baud ผิด, พอร์ตที่ไม่ถูก flush หรือมีสอง session บนสายเส้นเดียว | `distorted: true` ครั้งหนึ่งใน session ไม่ใช่การอ่านที่ล้ม `echo: false` พร้อม `reply` ว่าง เป็นอาการเดียวกับ `ECU_SILENT`: ตั้งพอร์ตให้ถูก (10400 8N1, ไม่มี flow control) และใช้ session เดียว ## อาการที่ดูเหมือนบั๊ก **rpm เป็น 0 หรือเลขสูงมากเช่น 17,500 และอุณหภูมิ −30 °C** เครื่องดับอยู่ (เปิดกุญแจ) ดู `frame.engine === 'off'` (หัวฉีด 0 ms และองศาจุดระเบิด 0°) แปลว่ารอบกับอุณหภูมิไม่ใช่ค่าจริง ให้ขึ้นว่า "เครื่องดับ" rpm ที่ไม่มีจริง (ไม่มีตาราง) เป็น `absent` โชว์เป็น `—` **แบตดูปกติ แต่ค่าอื่นเป็น `absent`.** ดู `frame.profile` - `generic.t17` มีแค่ `rpm`, `tps`, `inj_ms`, `ign` ไม่มีอุณหภูมิ ไม่มีแบต - Shindengen (`t17.sub4`) รายงาน `eot` ไม่ใช่ `ect` การหา `ect` บนโปรไฟล์นั้นเป็น `absent` เสมอ - `o2r` อยู่บนตารางรองที่โพลทุก 5 tick และเลิกถามหลังพลาด 3 ครั้ง เฟรมแรกจึงยังไม่มี - `batt` ของ Shindengen เป็น provisional ไบต์ดิบ `0` เป็น `absent` ไม่ใช่ 0.0 V แหล่งแบตเพิ่มถูกโพลทุก 10 tick ยกเว้น ECM-ID `0105950D01` ที่อ่านจากตารางหลัก - `primaryOk: false` ล้างฟิลด์ของตารางหลักในเฟรมนั้น อย่าเก็บเลขของเฟรมก่อน **Shindengen, เพิ่งบิดกุญแจ ON, `connect` ล้มหรือใช้หลายครั้ง.** wake 70 ms ต้องจับเวลาบน adapter break ของระบบปฏิบัติการบางครั้งพลาด และพัลส์ประมาณ 45 ms บน Android ถูกระบุว่ากล่อง Shindengen ที่เพิ่งออกจาก key ON จะไม่สนใจ ปล่อยให้ครบ 4 ครั้ง ถ้ายัง throw `ECU_SILENT` ให้ใช้สาย FTDI แล้วส่ง `wake` / `atomicWake` แบบ atomic ที่ดึงสายลง LOW ตาม `lowMs` ที่ได้รับ (70 ms) `connect` wake ให้อยู่แล้ว พัลส์เพิ่มก่อน `connect` มีแต่ทำให้จังหวะเพี้ยน **`model` เป็น null.** ไม่ได้ส่ง `lookupModel`, key ถูกปฏิเสธ, เครือข่ายล้ม, ชนลิมิตต่อวัน หรือไม่รู้จัก ECU (404) `id.ecmId` ยังเป็นค่าจากกล่อง อ่าน `onError` เพื่อดูว่าเป็นรหัส `API_*` ตัวไหน 404 เงียบ **เบราว์เซอร์ไม่มี `navigator.serial`.** WebSerial คือ Chrome หรือ Edge บนเดสก์ท็อป ในบริบทที่ปลอดภัย และเรียกจากคลิก Firefox, Safari และเบราว์เซอร์บนโทรศัพท์ไม่มี ใช้ Node หรือ adapter ของ Flutter **Android `listDevices()` ว่าง.** สายไม่ใช่ OTG, หัวชาร์จอย่างเดียว หรือโทรศัพท์ไม่ได้อยู่ในโหมด USB host ลิสต์ใหม่หลังได้สิทธิ์ `create()` คืน null เมื่อผู้ใช้ปฏิเสธ นั่นจะเป็น `PORT_OPEN` ก็ต่อเมื่อเอาพอร์ตที่เป็น null ไปเปิด ตรวจ null ก่อน (ตัวอย่างทำแบบนั้น) ถัดไป: [คำถามที่พบบ่อย](https://developers.smongrot.com/th/docs/faq) ============================================================================== # FILE: site/th/faq.md ============================================================================== [English](https://developers.smongrot.com/docs/faq) # คำถามที่พบบ่อย > ราคา, สัญญาอนุญาต MIT, อะไรออกจากเครื่อง, ถามที่ไหน, และ v0.2 เพิ่มอะไร ## SDK ฟรีไหม ฟรี `@smongrot/sdk` และ `smongrot_sdk` (รวม adapter สายสองตัว) ไม่มีค่าใช้จ่าย สัญญาอนุญาตคือ MIT **API key ฟรี** เปลี่ยน ECM-ID เป็นชื่อรุ่น ผู้ผลิต และรหัสอะไหล่ live data กับรหัสข้อผิดพลาดไม่ต้องใช้ key และไม่กินโควตา key ใช้ได้ **1000 คำขอต่อวัน** เกินกว่านั้นได้ HTTP 429, `onError` ได้ `API_RATE_LIMITED` และ `model` เป็น null ECM-ID ที่อ่านจากกล่องไม่เปลี่ยน ขอ key ได้ที่ https://developers.smongrot.com ## เอาไปขายในผลิตภัณฑ์เชิงพาณิชย์ได้ไหม ได้ MIT อนุญาตให้ใช้ แก้ไข และขายซอฟต์แวร์ที่มี SDK นี้ เก็บข้อความลิขสิทธิ์และตัวสัญญาอนุญาตไว้กับสำเนาของคุณ v0.1 ไม่ต้องซื้อสัญญาอนุญาตเชิงพาณิชย์แยก เงื่อนไขของแอปคุณเป็นเรื่องของคุณ อย่าใส่ API key ในหน้าเว็บสาธารณะ ให้ค้นชื่อรุ่นที่เซิร์ฟเวอร์ของคุณ ดู [ระบุตัวกล่องและ API key](https://developers.smongrot.com/th/docs/identify) ## SDK ส่งอะไรออกจากเครื่อง ไม่มีอะไร เว้นแต่คุณส่ง `lookupModel` เข้าไป `smongrotApi({ apiKey }).lookupModel` ส่งคำขอเดียว: `GET https://api.smongrot.com/v1/ecu/identify?ecm=<10 hex>` พร้อม `Authorization: Bearer ` ข้อมูลของ ECU ในคำขอนั้นมีแค่ ECM-ID frame ของ live, รหัสข้อผิดพลาด และไบต์ดิบบนสาย อยู่บนเครื่องนั้น ถ้าไม่ส่ง `lookupModel` `identify()` ยังคืน ECM-ID และ SDK ไม่เปิดซ็อกเก็ต การค้นที่ล้มไม่บล็อกการวินิจฉัย รายละเอียดอยู่ที่ [ระบุตัวกล่องและ API key](https://developers.smongrot.com/th/docs/identify) ## ขอความช่วยเหลือที่ไหน ช่องทางซัพพอร์ต: **placeholder** (ยังไม่เปิดใน v0.1) จนกว่าจะมีช่องทางบน https://developers.smongrot.com ทางที่ตอบ `connect` ที่ล้มคือรหัส `code` กับหน้า [แก้ปัญหา](https://developers.smongrot.com/th/docs/troubleshooting) ## ใน v0.2 มีอะไร - บอร์ด SMR ผ่าน Bluetooth LE เพื่อให้โทรศัพท์ที่ไม่มีพอร์ต USB-serial ทำ level 1 ได้ - iOS ผ่านบอร์ดนั้น สายบน iOS ยังใช้ไม่ได้ - SDK ภาษา Kotlin และ Swift คู่กับ JavaScript และ Dart v0.2 ยังไม่อยู่ในแพ็กเกจเหล่านี้ v0.1 ยังอ่านอย่างเดียว: ไม่เขียน ECU ไม่อ่าน ROM ทั้งก้อน และไม่ล้างรหัสข้อผิดพลาด ถัดไป: [หน้าแรก](https://developers.smongrot.com/th/docs) ============================================================================== # FILE: spec/kline.json ============================================================================== { "$schema": "./schema/kline.schema.json", "spec": "smongrot.kline", "spec_version": "1.0.0-phase1", "level": 1, "status": "stable", "summary": "Honda PGM-FI diagnostic K-Line: physical layer, wake, session bring-up, frame format, checksum and echo handling. Level 1 = read-only diagnostics (identity, live data, DTC read).", "authority": "Reference implementation (framing, checksum, echo strip, USB session, ECM-ID retry, live pacing). Bench log: Shindengen Lead K2TA, FTDI cable, 2026-10-08.", "out_of_scope": [ "ROM / calibration read", "any ECU write, erase, flash, recovery", "access or programming procedures of any kind", "immobilizer", "DTC clear (service 0x60 changes ECU state)" ], "physical": { "bus": "ISO 9141 K-Line, one wire, half-duplex", "baud": 10400, "data_bits": 8, "parity": "none", "stop_bits": 1, "idle_level": "high (recessive)", "echo": "The transceiver (e.g. L9637D, FTDI cables) reads back every byte the tester sends, before the ECU reply. Strip it: see echo_strip.", "notes": [ "macOS FTDI FT232R can do non-standard bauds; level 1 only uses 10400.", "Some USB cables echo with bits cleared (never set); see echo_strip.distorted." ] }, "wake": { "summary": "ISO 9141 wake: hold the line LOW for low_ms, release HIGH, open the UART at 10400 8N1, wait idle_after_ms, then send StartComm.", "low_ms": 70, "idle_after_ms": 130, "before": [ "flush/purge RX", "set baud 10400" ], "must_be_atomic": true, "why_atomic": "The LOW width must be a tight 70 ms. Building it from separate remote commands (e.g. two BLE writes) adds tens of ms of jitter and the ECU wakes only sometimes. Time it locally on the adapter (board opcode 0x16, FTDI bit-bang).", "transports": { "usb_ftdi": "Bit-bang the TXD pin LOW for low_ms, then back to UART at 10400 (bench: Shindengen Lead K2TA answers this on the first try).", "usb_emulated": "Fallback for chips without bit-bang: switch to baud round(9000/low_ms) clamped to 200..600, send one 0x00 byte (start + 8 zero bits held low), wait ceil(10000/baud)+60 ms, back to 10400. At 70 ms this gives about 45 ms LOW; Shindengen boxes fresh off key-ON ignore it.", "board_ec20_tunnel": "Opcode 0x16 + u16 LE low_ms on the control characteristic (spec/board-ble.json raw_tunnel).", "board_klineble": "The SMR board wakes the bus itself (HIGH 100 ms, LOW 70 ms, idle 150 ms) before its own polls; the phone never times it (spec/board-ble.json klineble)." } }, "frames": { "summary": "Every frame = [header][total length incl. checksum][service][args...][checksum]. Requests from the tester start with 0x72 (diagnostic request) or 0xFE (StartComm); ECU replies start with 0x02.", "request": { "layout": [ "header (0x72)", "L = total bytes including checksum", "service", "args...", "checksum" ], "table_read": { "layout": "72 07 72
", "example": "72 07 72 17 00 0F EF", "note": "count = number of data bytes asked. Only 0x0000..0x00FF style small reads are level 1 (identity and live tables)." } }, "reply": { "layout": [ "0x02", "L = total bytes including checksum", "service echo (e.g. 0x72, 0x71, 0x74)", "args echo...", "data...", "checksum" ], "table_read": "02 L 72
(5 header bytes)", "valid_when": "L >= 4, the frame fits in the buffer, and all L bytes sum to 0 mod 256." } }, "checksum": { "name": "Honda 8-bit two's complement", "compute": "ck = (0x100 - (sum(body) mod 256)) mod 256", "equivalent_forms": [ "((sum & 0xFF) ^ 0xFF) + 1, then & 0xFF", "(-sum) & 0xFF" ], "edge_case": "When sum(body) mod 256 == 0 the checksum is 0x00. The form ((sum & 0xFF) ^ 0xFF) + 1 without the final & 0xFF gives 0x100 there: always mask.", "verify": "A frame (body + checksum) is valid when all its bytes sum to 0 mod 256.", "not_this": "A plain sum (sum & 0xFF) is WRONG: the ECU ignores such frames (a bug once seen in early firmware, fixed).", "worked_example": { "body": "72 07 72 17 00 0F", "sum": "0x72+0x07+0x72+0x17+0x00+0x0F = 0x111", "sum_mod_256": "0x11", "xor_ff": "0xEE", "plus_1": "0xEF", "frame": "72 07 72 17 00 0F EF" } }, "echo_strip": { "summary": "Applied to every raw read-back of one request (reference implementation). T = the exact request bytes, RAW = everything read back for it.", "rules": [ "exact: if RAW starts with T → echo = true, reply = RAW[len(T):] (even when what follows is not a valid frame or is empty).", "distorted: else if len(RAW) > len(T), every one of the first len(T) bytes only CLEARS bits of T ((RAW[i] & ~T[i]) == 0), and a valid reply frame starts at RAW[len(T)] → unless a valid frame starting at RAW[0] is LONGER than len(T), echo = true, distorted = true, reply = RAW[len(T):].", "otherwise: echo = false, reply = RAW unchanged (the reply is never cut on position alone)." ], "valid_reply_at": "valid frame at position p: p+2 <= len(RAW), L = RAW[p+1] >= 4, p+L <= len(RAW), RAW[p..p+L-1] sums to 0 mod 256. Its length is L.", "distorted_note": "Field: some USB cables echo with bits cleared. Counted once per session for telemetry; no other behaviour change.", "level2_note": "The app also accepts one fixed-length level-2 reply form in valid_reply_at; it never occurs in level-1 traffic and is not part of this spec." }, "session": { "summary": "Bring-up order used by the reference USB path (and by the EC20 raw tunnel). Bench trace: Shindengen Lead K2TA, FTDI cable, 2026-10-08.", "steps": [ { "id": "wake", "do": "wake (see wake)", "retry": "wake + start_comm + liveness together up to 4 attempts (kConnectWakeTries) before 'ECU silent'." }, { "id": "start_comm", "request": "FE 04 72 8C", "expect_reply": false, "note": "Reply not required: on the Shindengen bench only the echo came back." }, { "id": "liveness", "do": "Send each in order; the first with a non-empty echo-stripped reply = session up. None answered = no bike / key off → next wake attempt.", "requests": [ { "name": "ecm_query", "request": "72 05 00 F0 99", "bench_reply": "02 04 00 FA" }, { "name": "start_diag", "request": "72 05 71 00 18" }, { "name": "alt_keepalive", "request": "7E 06 01 01 00 7A", "note": "Some Keihin V850 boxes (Giorno/Lead) answer only this. Reproduced for parity with the app; it is a status poll, not a write." } ] }, { "id": "start_diag", "request": "72 05 71 00 18", "reply": "02 0F 71 00 <5-byte ECM-ID> <5 bytes> ", "bench_reply": "02 0F 71 00 01 04 78 0D 01 EE 00 00 00 00 05", "required": "Yes. Without it StartComm succeeds but the live tables stay silent (bench 2026-09-14)." }, { "id": "ecm_id", "request": "72 07 72 00 00 05 10", "reply": "02 0B 72 00 00 <5-byte ECM-ID> ", "bench_reply": "02 0B 72 00 00 01 04 78 0D 01 F6", "retry": { "tries": 3, "gap_ms": 300, "why": "The first ID read right after StartDiag can come back empty." }, "fallback": "If no valid ID frame: use the ECM-ID from this session's StartDiag reply.", "format": "10 upper-case hex chars, e.g. 0104780D01" }, { "id": "live", "do": "Detect the profile and poll (spec/live.json)." } ], "ecm_id_extraction": { "summary": "ECM-ID bytes over an echo-stripped reply.", "rules": [ "Prefer the FIRST position i (scanning forward) where RAW[i..] = 02 0B 72 00 00 and RAW[i..i+10] sums to 0 mod 256: ID = RAW[i+5..i+9].", "Else the FIRST position where RAW[i..] = 02 0F 71 00 and RAW[i..i+14] sums to 0 mod 256: ID = RAW[i+4..i+8].", "Else no ID (never a slice taken by position)." ] } }, "timing": { "command_quiet_ms": 120, "command_timeout_ms": 2000, "table_read_quiet_ms": 120, "table_read_timeout_ms": 500, "dtc_gap_ms": 60, "live_min_gap_ms": 60, "note": "A read ends after quiet_ms of RX silence (the window restarts on every received chunk and starts right after the write) or at timeout_ms. Values are what the app uses, not ECU limits." } } ============================================================================== # FILE: spec/live.json ============================================================================== { "$schema": "./schema/live.schema.json", "spec": "smongrot.live", "spec_version": "1.0.0-phase1", "level": 1, "status": "stable", "summary": "Honda K-Line live data (engine sensors). Poll one or more 0x72 table reads, cut the data bytes out of each reply, and decode every field from a declarative rule. Requires an open diagnostic session (spec/kline.json session).", "authority": "Reference implementation (live decoder, detector and profile set). If this file and the reference implementation ever disagree, the reference wins and this file is a bug.", "derived_from": { "file": "reference implementation: live profile set", "schema_v": 1, "profile_set_version": 2 }, "reply_extraction": { "summary": "How the data bytes of one table read are taken from the echo-stripped reply (reference table read).", "steps": [ "Strip the TX echo (spec/kline.json echo_strip). Call the rest R.", "Scan start index i from len(R)-4 down to 0 (the LAST matching frame wins).", "Skip i unless R[i] == 0x02 and R[i+2] == request[2] (service byte, 0x72) and R[i+3] == request[3] (table byte).", "L = R[i+1] (total frame length incl. the checksum). Skip i unless L >= reply_header_len + 1 and i + L <= len(R).", "Skip i unless the bytes R[i .. i+L-1] sum to 0 mod 256 (spec/kline.json checksum.verify).", "data = R[i+reply_header_len .. i+L-2] (after the header, before the checksum).", "If len(data) >= data_len return data, else return NO DATA. Stop at this first checksum-valid match either way (do not keep scanning).", "No match: NO DATA." ], "header_layout": "Reply = 02 L 72
; reply_header_len 5 for every profile table.", "no_data_means": "The table is absent for this tick: every field read from it is 'absent'." }, "value_rule": { "summary": "Per source: raw = unsigned big-endian integer over `width` bytes at data[offset]. If raw is in null_if → absent. value = raw * scale + add (IEEE-754 double, in that order). If range is given and value < range[0] or value > range[1] → invalid. Then, if clamp is given, value = min(max(value, clamp[0]), clamp[1]). Otherwise ok.", "absent_when": [ "the source's table has no data yet", "offset + width > len(data)", "raw is listed in null_if" ], "invalid_when": [ "value outside range (inclusive bounds)" ], "chain": [ "A field has 1..n sources tried in order. A source with `ecm` is skipped (not read at all) unless the session's ECM-ID, normalised (whitespace removed, upper case), is in that list; an unknown ECM-ID skips it too.", "absent → try the next source.", "invalid → the FIELD is invalid; stop. An out-of-range value is never masked by a later source.", "ok and the field has no `agree` → the field is this value; stop.", "ok and the field has `agree` → keep the first ok value, keep reading later sources: if a later source is invalid → field invalid; if a later source is ok and |later - first| > agree → field invalid; else continue. At the end the field is the FIRST ok value.", "No ok source → absent. Never 0." ], "result": "Each field yields {status: ok|absent|invalid, value (only when ok), prov, source (table id of the winning source, only when ok)}.", "prov_rule": "ok → the winning source's prov. absent/invalid → the first source's prov. Exception: v2_provisional (see detection.match_v2) forces prov = provisional for the listed fields in every status.", "prov_values": { "bench": "proven on a real ECU on the bench", "field": "consistent across real field logs, not meter-checked", "reference": "from the reference live-data tool source only", "provisional": "single sample / inferred; show it, but ask the rider to confirm before any decision" }, "every_field_reported": "Decode returns an entry for every field of the profile, even when its table never answered." }, "units": { "rpm": "engine speed, rev/min", "tps_v": "throttle sensor volts", "tps": "throttle opening, % of the box's full-open angle (0..100). The raw byte is the angle in 0.5 degree steps.", "ect": "engine temperature, degC (coolant or oil, depending on the bike; display label only)", "eot": "engine temperature, degC (Shindengen layout)", "batt": "battery volts as the ECU measures it", "inj_ms": "injector pulse width, ms", "ign": "ignition advance, degrees", "ltft": "long-term fuel trim, %", "o2r": "narrowband O2 sensor raw byte (1..255); see derived_values" }, "derived_values": [ { "key": "o2_v", "from": "o2r", "formula": "o2r * 0.0195", "unit": "V", "prov": "provisional", "source": "Reference implementation (8-bit ADC over 5 V). The reference live-data tool uses o2r / 753.75 * 14.7 (= o2r * 0.019502), equal within 0.0005 V for every raw byte.", "note": "Display only. Narrowband O2 says rich/lean side, not an AFR number." } ], "polling": { "tick_unit_ms": 300, "summary": "A table's poll_every_ticks counts ticks of tick_unit_ms wall time (the board firmware's POLL_MS). The primary table is read every tick; at most ONE secondary table per tick, round-robin. A secondary with give_up_after_misses = N is not asked again this session after N misses in a row while the primary answered.", "usb_target_tick_ms": 150, "min_gap_between_frames_ms": 60, "read_timeout_ms": 500, "read_quiet_ms": 120, "source": "Reference implementation (USB live pacing, table read)." }, "detection": { "summary": "Pick a profile once per connect (reference detector, probe branch).", "probe_table_order": [ 23, 19, 17 ], "probe_table_order_hex": [ "0x17", "0x13", "0x11" ], "probe_request_source": "For each table byte, the request of the first profile (in file order) whose primary table has that table byte.", "tries_per_table": 2, "steps": [ "For each probe table in order: send its request up to tries_per_table times until reply_extraction gives data. No data → next table.", "On data: candidates = non-generic profiles whose primary table has this table byte and whose match rules ALL hold on {primary: data}.", "match_v2 off (default): use `match`. match_v2 on: a profile with `match_v2` uses those rules instead; a profile that matched ONLY by match_v2 (its `match` rules fail) is dropped when a maker hint is given and differs from the profile maker.", "Sort candidates by specificity (number of rules in the active rule list) descending, then range_score descending. Take the first → method 'probed'.", "No candidate → the first generic profile on this table → method 'generic'. No generic → next table.", "No table answered → no profile (connected, live data not supported)." ], "rule_test": "A rule reads raw = unsigned big-endian over width bytes at data[offset] of its table (false when the table is missing or too short). eq: raw must equal eq. ne: raw must not equal ne. A profile with no rules always matches.", "range_score": "Decode the frame with NO ECM-ID; among fields whose status is not absent, the fraction that are ok (0 when none). Used only as a tie-break.", "maker_hint": "From the part code: '38770-' → keihin, '30400-' → shindengen, else none. The observed layout always wins; mismatch = hint and profile maker both set and different (never on a generic profile).", "match_v2": { "flag": "live_temp_v2", "default": false, "summary": "App build flag (internal-test builds only, not server-controlled). When on, profiles that have match_v2 use it in place of match, and fields in v2_provisional get prov = provisional on a frame that matches only by match_v2.", "why": "The reference live-data tool picks Type-4 sub 4 only when data[4..5] == FF FF; build 196's rule (data[4] != FF) sent some Keihin frames to generic.t17 (no temperature)." }, "cache": "Optional, app-specific: remember profile id per ECM-ID; on reconnect validate with one primary read + match, else drop the cache and probe. A cached generic profile is always dropped and re-probed.", "tie_note": "On the shipped profiles no two candidates on one table can both match, so the tie-break order never decides a real frame." }, "profiles": [ { "id": "t17.sub8", "maker": "keihin", "generic": false, "notes": [ "Keihin Type-4 layout (bench: Wave 110i 38770-K03-H01, 2026-10-02). Request 72 07 72 17 00 0F EF is the reference tool's 'Table 20' read for ECM Type 4.", "tps: data[3] is the throttle angle in 0.5 degree steps; shown as % of the box's full-open angle (scale = 50 / full-open degrees, rounded up). Full-open per ECM-ID from real ride plateaus (not meter-checked): 01040F0D01 78, 0105550D01 79, 01033E0D01 74, 0103FA0D01 73, everything else 80.", "t20 = narrowband O2 table 0x20 (reference tool _cmdO2, read every few cycles). o2r = data[0]; 0 = no reading. Not captured on a running bike yet.", "v2_provisional batt: a frame that matches only by match_v2 (data[4] = FF) is on a layout no bench confirmed for that box, so its battery is provisional." ], "primary": "t17", "tables": { "t17": { "request": "72 07 72 17 00 0F EF", "reply_header_len": 5, "data_len": 15, "poll_every_ticks": 1, "optional": false, "give_up_after_misses": null }, "t20": { "request": "72 07 72 20 00 0B EA", "reply_header_len": 5, "data_len": 1, "poll_every_ticks": 5, "optional": true, "give_up_after_misses": 3 } }, "match": [ { "table": "t17", "offset": 4, "width": 1, "ne": 255 } ], "match_v2": [ { "table": "t17", "offset": 4, "width": 2, "ne": 65535 } ], "v2_provisional": [ "batt" ], "fields": [ { "key": "rpm", "unit": "rpm", "sources": [ { "table": "t17", "offset": 0, "width": 2, "scale": 1, "add": 0, "null_if": [], "prov": "bench", "range": [ 0, 20000 ] } ] }, { "key": "tps_v", "unit": "V", "sources": [ { "table": "t17", "offset": 2, "width": 1, "scale": 0.0195, "add": 0, "null_if": [], "prov": "reference", "range": [ 0, 5.1 ] } ] }, { "key": "tps", "unit": "%", "sources": [ { "table": "t17", "offset": 3, "width": 1, "scale": 0.641026, "add": 0, "null_if": [], "prov": "field", "range": [ 0, 120 ], "clamp": [ 0, 100 ], "ecm": [ "01040F0D01" ] }, { "table": "t17", "offset": 3, "width": 1, "scale": 0.632912, "add": 0, "null_if": [], "prov": "field", "range": [ 0, 120 ], "clamp": [ 0, 100 ], "ecm": [ "0105550D01" ] }, { "table": "t17", "offset": 3, "width": 1, "scale": 0.675676, "add": 0, "null_if": [], "prov": "field", "range": [ 0, 120 ], "clamp": [ 0, 100 ], "ecm": [ "01033E0D01" ] }, { "table": "t17", "offset": 3, "width": 1, "scale": 0.684932, "add": 0, "null_if": [], "prov": "field", "range": [ 0, 120 ], "clamp": [ 0, 100 ], "ecm": [ "0103FA0D01" ] }, { "table": "t17", "offset": 3, "width": 1, "scale": 0.625, "add": 0, "null_if": [], "prov": "field", "range": [ 0, 120 ], "clamp": [ 0, 100 ] } ] }, { "key": "ect", "unit": "degC", "sources": [ { "table": "t17", "offset": 5, "width": 1, "scale": 1, "add": -40, "null_if": [ 255 ], "prov": "bench", "range": [ -40, 160 ] } ] }, { "key": "batt", "unit": "V", "sources": [ { "table": "t17", "offset": 10, "width": 1, "scale": 0.1, "add": 0, "null_if": [ 0 ], "prov": "bench", "range": [ 6, 18 ] } ] }, { "key": "inj_ms", "unit": "ms", "sources": [ { "table": "t17", "offset": 11, "width": 2, "scale": 0.004, "add": 0, "null_if": [], "prov": "bench", "range": [ 0, 100 ] } ] }, { "key": "ign", "unit": "deg", "sources": [ { "table": "t17", "offset": 13, "width": 1, "scale": 0.5, "add": -64, "null_if": [], "prov": "bench", "range": [ -64, 64 ] } ] }, { "key": "ltft", "unit": "%", "sources": [ { "table": "t17", "offset": 14, "width": 1, "scale": 0.78, "add": -100, "null_if": [], "prov": "reference", "range": [ -100, 100 ] } ] }, { "key": "o2r", "unit": "raw", "sources": [ { "table": "t20", "offset": 0, "width": 1, "scale": 1, "add": 0, "null_if": [ 0 ], "prov": "reference", "range": [ 1, 255 ] } ] } ] }, { "id": "t17.sub4", "maker": "shindengen", "generic": false, "notes": [ "Shindengen Type-4 layout (bench: Lead 30400-K2TA-T02, 2026-10-02 and 2026-10-08). EOT proven by a bench knob sweep.", "batt chain: t17 data[10] x 0.1 V, read ONLY on ECM-ID 0105950D01 (Lead 125 K2TG; inferred from field logs, the reference tool has no Shindengen case), then D0 data[0] on every sub4 box. Both provisional until a multimeter check. 0 = absent; out of range or the two more than 0.5 V apart = invalid.", "tps full-open 85 degrees from one Shindengen ride (provisional until more rides)." ], "primary": "t17", "tables": { "t17": { "request": "72 07 72 17 00 0F EF", "reply_header_len": 5, "data_len": 15, "poll_every_ticks": 1, "optional": false, "give_up_after_misses": null }, "d0": { "request": "72 07 72 D0 00 10 35", "reply_header_len": 5, "data_len": 16, "poll_every_ticks": 10, "optional": true, "give_up_after_misses": null } }, "match": [ { "table": "t17", "offset": 4, "width": 1, "eq": 255 }, { "table": "t17", "offset": 5, "width": 1, "eq": 255 } ], "fields": [ { "key": "rpm", "unit": "rpm", "sources": [ { "table": "t17", "offset": 0, "width": 2, "scale": 1, "add": 0, "null_if": [], "prov": "bench", "range": [ 0, 20000 ] } ] }, { "key": "tps_v", "unit": "V", "sources": [ { "table": "t17", "offset": 2, "width": 1, "scale": 0.0195, "add": 0, "null_if": [], "prov": "reference", "range": [ 0, 5.1 ] } ] }, { "key": "tps", "unit": "%", "sources": [ { "table": "t17", "offset": 3, "width": 1, "scale": 0.588236, "add": 0, "null_if": [], "prov": "field", "range": [ 0, 120 ], "clamp": [ 0, 100 ] } ] }, { "key": "eot", "unit": "degC", "sources": [ { "table": "t17", "offset": 9, "width": 1, "scale": 1, "add": -40, "null_if": [ 255 ], "prov": "bench", "range": [ -40, 160 ] } ] }, { "key": "batt", "unit": "V", "agree": 0.5, "sources": [ { "table": "t17", "offset": 10, "width": 1, "scale": 0.1, "add": 0, "null_if": [ 0 ], "prov": "provisional", "range": [ 6, 18 ], "ecm": [ "0105950D01" ] }, { "table": "d0", "offset": 0, "width": 1, "scale": 0.1, "add": 0, "null_if": [ 0 ], "prov": "provisional", "range": [ 6, 18 ] } ] }, { "key": "inj_ms", "unit": "ms", "sources": [ { "table": "t17", "offset": 11, "width": 2, "scale": 0.004, "add": 0, "null_if": [], "prov": "bench", "range": [ 0, 100 ] } ] }, { "key": "ign", "unit": "deg", "sources": [ { "table": "t17", "offset": 13, "width": 1, "scale": 0.5, "add": -64, "null_if": [], "prov": "bench", "range": [ -64, 64 ] } ] } ] }, { "id": "t13.type7", "maker": "keihin", "generic": false, "notes": [ "Keihin Type-7 per the reference tool ParseType7 (table 0x13, 14 bytes). Not bench-proven." ], "primary": "t13", "tables": { "t13": { "request": "72 07 72 13 00 0E F4", "reply_header_len": 5, "data_len": 14, "poll_every_ticks": 1, "optional": false, "give_up_after_misses": null }, "t20": { "request": "72 07 72 20 00 0B EA", "reply_header_len": 5, "data_len": 1, "poll_every_ticks": 5, "optional": true, "give_up_after_misses": 3 } }, "match": [], "fields": [ { "key": "rpm", "unit": "rpm", "sources": [ { "table": "t13", "offset": 0, "width": 2, "scale": 1, "add": 0, "null_if": [], "prov": "reference", "range": [ 0, 20000 ] } ] }, { "key": "tps", "unit": "%", "sources": [ { "table": "t13", "offset": 3, "width": 1, "scale": 0.625, "add": 0, "null_if": [], "prov": "reference", "range": [ 0, 120 ], "clamp": [ 0, 100 ] } ] }, { "key": "ect", "unit": "degC", "sources": [ { "table": "t13", "offset": 5, "width": 1, "scale": 1, "add": -40, "null_if": [ 255 ], "prov": "reference", "range": [ -40, 160 ] } ] }, { "key": "batt", "unit": "V", "sources": [ { "table": "t13", "offset": 10, "width": 1, "scale": 0.1, "add": 0, "null_if": [ 0 ], "prov": "reference", "range": [ 6, 18 ] } ] }, { "key": "inj_ms", "unit": "ms", "sources": [ { "table": "t13", "offset": 11, "width": 2, "scale": 0.004, "add": 0, "null_if": [], "prov": "reference", "range": [ 0, 100 ] } ] }, { "key": "ign", "unit": "deg", "sources": [ { "table": "t13", "offset": 13, "width": 1, "scale": 0.5, "add": -64, "null_if": [], "prov": "reference", "range": [ -64, 64 ] } ] }, { "key": "o2r", "unit": "raw", "sources": [ { "table": "t20", "offset": 0, "width": 1, "scale": 1, "add": 0, "null_if": [ 0 ], "prov": "reference", "range": [ 1, 255 ] } ] } ] }, { "id": "t11.type1", "maker": "keihin", "generic": false, "notes": [ "Keihin Type-1 per the reference tool ParseType1 (table 0x11, 20 bytes). LTFT omitted: its reference offset is past the table. Not bench-proven." ], "primary": "t11", "tables": { "t11": { "request": "72 07 72 11 00 14 F0", "reply_header_len": 5, "data_len": 20, "poll_every_ticks": 1, "optional": false, "give_up_after_misses": null }, "t20": { "request": "72 07 72 20 00 0B EA", "reply_header_len": 5, "data_len": 1, "poll_every_ticks": 5, "optional": true, "give_up_after_misses": 3 } }, "match": [], "fields": [ { "key": "rpm", "unit": "rpm", "sources": [ { "table": "t11", "offset": 0, "width": 2, "scale": 1, "add": 0, "null_if": [], "prov": "reference", "range": [ 0, 20000 ] } ] }, { "key": "tps", "unit": "%", "sources": [ { "table": "t11", "offset": 3, "width": 1, "scale": 0.625, "add": 0, "null_if": [], "prov": "reference", "range": [ 0, 120 ], "clamp": [ 0, 100 ] } ] }, { "key": "ect", "unit": "degC", "sources": [ { "table": "t11", "offset": 5, "width": 1, "scale": 1, "add": -40, "null_if": [ 255 ], "prov": "reference", "range": [ -40, 160 ] } ] }, { "key": "batt", "unit": "V", "sources": [ { "table": "t11", "offset": 12, "width": 1, "scale": 0.1, "add": 0, "null_if": [ 0 ], "prov": "reference", "range": [ 6, 18 ] } ] }, { "key": "inj_ms", "unit": "ms", "sources": [ { "table": "t11", "offset": 14, "width": 2, "scale": 0.004, "add": 0, "null_if": [], "prov": "reference", "range": [ 0, 100 ] } ] }, { "key": "ign", "unit": "deg", "sources": [ { "table": "t11", "offset": 16, "width": 1, "scale": 0.5, "add": -64, "null_if": [], "prov": "reference", "range": [ -64, 64 ] } ] }, { "key": "o2r", "unit": "raw", "sources": [ { "table": "t20", "offset": 0, "width": 1, "scale": 1, "add": 0, "null_if": [ 0 ], "prov": "reference", "range": [ 1, 255 ] } ] } ] }, { "id": "generic.t17", "maker": null, "generic": true, "notes": [ "Fallback when table 0x17 answers but no sub-layout matches: only fields proven identical on Keihin AND Shindengen." ], "primary": "t17", "tables": { "t17": { "request": "72 07 72 17 00 0F EF", "reply_header_len": 5, "data_len": 15, "poll_every_ticks": 1, "optional": false, "give_up_after_misses": null } }, "match": [], "fields": [ { "key": "rpm", "unit": "rpm", "sources": [ { "table": "t17", "offset": 0, "width": 2, "scale": 1, "add": 0, "null_if": [], "prov": "bench", "range": [ 0, 20000 ] } ] }, { "key": "tps", "unit": "%", "sources": [ { "table": "t17", "offset": 3, "width": 1, "scale": 0.625, "add": 0, "null_if": [], "prov": "field", "range": [ 0, 120 ], "clamp": [ 0, 100 ] } ] }, { "key": "inj_ms", "unit": "ms", "sources": [ { "table": "t17", "offset": 11, "width": 2, "scale": 0.004, "add": 0, "null_if": [], "prov": "bench", "range": [ 0, 100 ] } ] }, { "key": "ign", "unit": "deg", "sources": [ { "table": "t17", "offset": 13, "width": 1, "scale": 0.5, "add": -64, "null_if": [], "prov": "bench", "range": [ -64, 64 ] } ] } ] } ] } ============================================================================== # FILE: spec/dtc.json ============================================================================== { "$schema": "./schema/dtc.schema.json", "spec": "smongrot.dtc", "spec_version": "1.0.0-phase1", "level": 1, "status": "beta", "summary": "Honda PGM-FI stored fault codes: send three 72 05 74 0x reads, cut the payload out of each reply, decode (code, sub) pairs as Honda blink codes.", "status_reason": "The 72 05 74 0x frames answer on real boxes, and one bench run with two induced faults (Keihin K03-H01, 2026-11-04) gave 07 01 / 08 01. The code meaning of those bytes (Honda blink code, plain binary) is INFERRED, no box with a naturally stored fault has been read, and only the Keihin layout was ever seen. Treat output as beta.", "authority": "Reference implementation (fault-code read frames, decoder and scan result rules).", "requires": "An open diagnostic session (spec/kline.json session, StartDiag sent).", "read": { "requests": [ { "sub": 1, "request": "72 05 74 01 14" }, { "sub": 2, "request": "72 05 74 02 13" }, { "sub": 3, "request": "72 05 74 03 12" } ], "gap_ms": 60, "reply": "02 0C 74 <7-byte payload> ", "bench_replies": { "74 01 (ECT knob at max temp + TPS knob at 0)": "02 0C 74 01 00 07 01 08 01 00 00 6C", "74 02": "02 0C 74 02 00 00 00 00 00 00 00 7C", "74 03": "02 0C 74 03 00 00 00 00 00 00 00 7B" } }, "payload_extraction": { "summary": "Payload of one reply (per sub) over an echo-stripped reply.", "steps": [ "Scan i from len(R)-5 down to 0 (the LAST matching frame wins).", "Skip i unless R[i] == 0x02 and R[i+2] == 0x74, and (when sub is given) R[i+3] == sub.", "L = R[i+1]; skip unless L >= 6 and i + L <= len(R).", "Skip unless R[i .. i+L-1] sums to 0 mod 256.", "payload = R[i+4 .. i+L-2]." ], "none": "No such frame → that reply is unreadable." }, "payload_decode": { "summary": "Decode one payload. payload = [lead byte][code, sub] pairs.", "rules": [ "Unreadable (null) if the payload is empty or its length is even (must be 1 + 2n).", "Unreadable if payload[0] != 0x00 (0x00 is the only value ever seen; its meaning is unknown).", "For each pair (c, s): 00 00 = empty slot, skip; exactly one of them 0 = unreadable; else code c-s.", "Codes are de-duplicated, first-seen order kept." ], "encoding": "Plain binary, not BCD: 0x07 0x01 = blink code 7-1, 0x15 0x01 = 21-1 (INFERRED from the K03-H01 ROM code table).", "label": "\"-\", e.g. 7-1" }, "read_decode": { "summary": "Decode all replies of one scan (replies + subs).", "rules": [ "No replies → unreadable.", "If subs is given it must have one entry per reply, and reply k must carry sub subs[k].", "Any reply unreadable (no frame, or payload unreadable) → the WHOLE read is unreadable. Never guess.", "Else the union of all codes, de-duplicated in order. Empty list = clean." ] }, "maker_rule": { "summary": "Scan result rule: only Keihin boxes (part code 38770-) are decoded. Shindengen / unknown makers answer the same frames but any non-zero payload is reported 'unreadable' until bench-confirmed.", "outcomes": { "faults": "Keihin, read_decode gives at least one code", "clean": "every 74 reply answered and all payloads are zero", "unreadable": "a reply does not parse, or a non-Keihin box returned non-zero payload", "failed": "no reply (or only NAK) to any request" }, "nak": "A reply containing byte 0x7F is treated as a NAK (no answer) by the board's classifier." }, "codes": { "summary": "Generic Honda PGM-FI blink codes the app names. Best-known reference, NOT bench-proven except where bench_confirmed. Meanings translated from the app's Thai names; unknown codes are shown as their label only.", "voltage_split": { "codes": [ 1, 7, 8, 9, 54 ], "sub_1": "signal too low", "sub_2": "signal too high" }, "critical": { "codes": [ 12, 33, 52 ], "meaning": "the engine may not run right; stop and get it checked soon" }, "bench_confirmed": [ "7-1", "8-1" ], "list": [ { "code": 1, "meaning_en": "intake manifold pressure (MAP) sensor" }, { "code": 7, "meaning_en": "engine temperature sensor" }, { "code": 8, "meaning_en": "throttle position sensor" }, { "code": 9, "meaning_en": "intake air temperature sensor" }, { "code": 11, "meaning_en": "vehicle speed sensor" }, { "code": 12, "meaning_en": "injector" }, { "code": 21, "meaning_en": "O2 sensor" }, { "code": 23, "meaning_en": "O2 sensor heater" }, { "code": 29, "meaning_en": "idle air control valve" }, { "code": 33, "meaning_en": "ECU memory" }, { "code": 52, "meaning_en": "crank position sensor" }, { "code": 54, "meaning_en": "bank angle (fall) sensor" } ] }, "not_included": [ "An older OBD-style P-code packing in the reference implementation: a best-guess legacy mapping, never used on a real Honda reply.", "DTC clear (72 05 60 0x): changes ECU state and resets learned values; not level 1." ] } ============================================================================== # FILE: spec/board-ble.json ============================================================================== { "$schema": "./schema/board-ble.schema.json", "spec": "smongrot.board-ble", "spec_version": "1.0.0-phase1", "level": 1, "status": "stable", "summary": "Minimal BLE GATT needed for level 1 over a smongrot board. There are TWO firmwares with different GATT: `klineble` (what shipped SMR boards run: the board talks K-Line itself and sends decoded JSON) and `raw_tunnel` (dev firmware: the phone sends raw K-Line frames and times nothing but the wake). Pick by the service UUID the board exposes.", "authority": "SMR board firmware (KLineBLE, klineble-1.0.11) and the reference app BLE client; dev firmware raw tunnel. Level-1 commands only.", "out_of_scope": [ "image / OTA characteristics (ff13, ff15, EC24, EC27) and every write, flash, recovery, ROM-read or OTA command", "access or programming procedures of any kind" ], "klineble": { "status": "production (SMR boards)", "advertising": { "name": "SMR-<6 upper-case hex from the BT MAC>, e.g. SMR-A526F17C", "scan_by": "service 0000ff10-... OR the name prefix SMR- (iOS/macOS often put the service UUID only in the scan response, and may cache an old name)." }, "service": "0000ff10-0000-1000-8000-00805f9b34fb", "characteristics": { "cmd": { "uuid": "0000ff11-0000-1000-8000-00805f9b34fb", "props": [ "write", "write_without_response" ], "payload": "ASCII text command, no terminator" }, "data": { "uuid": "0000ff12-0000-1000-8000-00805f9b34fb", "props": [ "notify" ], "payload": "UTF-8: one JSON object or one text line per message" }, "ver": { "uuid": "0000ff14-0000-1000-8000-00805f9b34fb", "props": [ "read" ], "payload": "JSON {\"fw\": \"klineble-x.y.z\", \"hw\": ..., \"sn\": \"<6 hex>\", ...}; absent on legacy boards" } }, "mtu": { "board_sets": 512, "note": "A notify carries at most MTU-3 bytes; iOS may negotiate 185 (182 B) while a live JSON can be ~210 B." }, "reassembly": "Join ff12 notifies while a JSON object's braces are unbalanced (drop pieces older than 1 s or longer than 2048 B); a cut-off object never parses and must yield no value. Text lines pass through unchanged.", "wake_and_session": "Done by the board: HIGH 100 ms, LOW 70 ms, UART 10400 8N1, idle 150 ms, then FE 04 72 8C and 72 05 00 F0 99 (session up when that answers); up to 5 wakes; re-opened every 1.5 s while down. The realtime loop does not send StartDiag before polling.", "commands": [ { "cmd": "R", "does": "Start realtime. Board answers the line `STAT realtime on`, then one JSON object per successful poll (every 300 ms).", "board_poll_request": "72 05 71 17 01", "note": "The board polls 72 05 71 17 01, not the 72 07 72 17 00 0F EF read in spec/live.json. Its reply has 4 header bytes; the board decodes it itself (see realtime_json)." }, { "cmd": "S", "does": "Stop realtime. Answer `STAT realtime off`." }, { "cmd": "ECMID", "does": "Read the ECM-ID (72 07 72 00 00 05 10 on the wire).", "answer": "`ECMID <10 hex>` or `ECMID FAIL`", "parse": "split on whitespace; parts[0] == 'ECMID' and parts[1] matches ^[0-9A-Fa-f]{10}$ → upper-case it; anything else = no ID.", "note": "Send one at a time per link: two ECMIDs on one K-Line session collide. App timeout 12 s." }, { "cmd": "DTCPROBE", "status": "beta", "does": "Board opens a session, sends StartDiag, then a sweep of read candidates including 72 05 74 01/02/03 (labels RD_74_01..RD_74_03) and reports one line per candidate, 60 ms apart. Realtime stops; re-send R afterwards if wanted.", "line": "STAT dtcprobe