diff --git a/README.ko.md b/README.ko.md index 02026f1..c60d697 100644 --- a/README.ko.md +++ b/README.ko.md @@ -299,9 +299,33 @@ BLE ELM327 어댑터에 연결하여 OBD-II(및 GM mode 22) PID 명령을 전송 | `mode` | string | OBD 모드. `"01"`=표준, `"22"`=제조사 확장. 기본 `"01"`. | | `pid` | string | PID hex 코드. 예: `"0C"`, `"199A"`. | | `formula` | string | 수식. `a`~`t`가 응답의 0~19번째 바이트. 예: `"(a*256+b)/4"`. 응답이 짧아 식에 쓴 바이트가 없으면 그 주기는 발행하지 않음. | +| `decode` | map | `formula` 대신 offset으로 값 추출. 20번째 이후 바이트를 읽어야 할 때 사용 (아래 참조). | | `update_interval` | duration | 이 PID를 폴링하는 간격. 기본 `60s`. | | `pre_commands` | list | 이 PID 전에 전송할 추가 명령 (예: GM 헤더 전환). | +### 긴 응답에서 값 꺼내기 (decode) + +`formula`의 변수는 응답의 **앞 20바이트**(`a`~`t`)까지만 가리킵니다. 그보다 뒤에 있는 값은 +`decode`로 읽습니다. 필드 구성은 [decode 절](#decode--바이트-디코딩)과 같습니다. + +```yaml +# 현대 21 03 블록의 총주행거리 — byte 57~60, 32bit, /1000 = km +- key: odometer + mode: "21" + pid: "03" + pre_commands: ["ATSH7E0"] + decode: { offset: 57, length: 4, type: uint32, endian: big, scale: 0.001 } + unit: "km" + device_class: distance + state_class: total_increasing +``` + +`offset`은 mode/PID 에코를 제외한 데이터의 0-based 위치로, `formula`의 `a`가 `offset: 0`과 +같습니다. 응답이 짧아 `offset + length`가 범위를 벗어나면 그 주기에는 아무것도 발행하지 +않습니다 — 지원하지 않는 차에서 엉뚱한 값이 올라오지 않습니다. + +한 센서에 `decode`와 `formula`를 모두 쓰면 `decode`가 우선합니다. + ### 헤더 복원 (ATSH) ELM327의 전송 헤더는 **한 번 바꾸면 계속 유지**됩니다. 그래서 `pre_commands: ["ATSH7C6"]` 같은 diff --git a/README.md b/README.md index 53e1844..36fbb59 100644 --- a/README.md +++ b/README.md @@ -299,9 +299,33 @@ Connects to an ELM327 BLE adapter, sends OBD-II (and GM mode 22) PID commands, a | `mode` | string | OBD mode. `"01"` = standard, `"22"` = manufacturer specific. Default `"01"`. | | `pid` | string | PID hex code (without mode prefix). E.g. `"0C"`, `"199A"`. | | `formula` | string | Math expression. Variables `a`–`t` are response bytes 0–19. E.g. `"(a*256+b)/4"`. If the response is too short to bind a byte used in the expression, nothing is published for that poll. | +| `decode` | map | Extract the value by byte offset instead of `formula`. Use it to reach bytes past the 20th (see below). | | `update_interval` | duration | How often to poll this PID. Default `60s`. | | `pre_commands` | list | Extra AT/OBD commands to send before this PID (e.g., header switch for GM). | +### Reaching values in long responses (decode) + +`formula` variables only address the **first 20 bytes** of a response (`a`–`t`). Anything +further in is read with `decode`, which takes the same fields as the [decode section](#decode--byte-decoding). + +```yaml +# Odometer in the Hyundai 21 03 block — bytes 57-60, 32-bit, /1000 = km +- key: odometer + mode: "21" + pid: "03" + pre_commands: ["ATSH7E0"] + decode: { offset: 57, length: 4, type: uint32, endian: big, scale: 0.001 } + unit: "km" + device_class: distance + state_class: total_increasing +``` + +`offset` is 0-based into the data with the mode/PID echo removed, so `offset: 0` is the same +byte as `a` in a formula. If the response is too short for `offset + length`, nothing is +published for that poll, so an unsupported car never reports a bogus value. + +`decode` wins if a sensor sets both `decode` and `formula`. + ### Header restore (ATSH) An ELM327 transmit header **stays in effect once set**. So a sensor with diff --git a/templates.yaml b/templates.yaml index 22eb81d..ad80b1c 100644 --- a/templates.yaml +++ b/templates.yaml @@ -217,7 +217,7 @@ templates: state_class: measurement accuracy_decimals: 1 update_interval: 30s - # ── 총주행거리 프로브 (값을 쓰려는 게 아니라 raw 응답을 로그에 남기려는 것) ── + # ── 총주행거리 (엔진 ECU의 DPF 블록에 같이 실려 온다) ────────────── # 엑센트 RB는 계기판(7C6 / 22B002)이 주행거리를 열지 않는다 — 요청하면 7F 22 22. # 대신 엔진 ECU의 21 03 블록에 있다 (OBDb 메이커 공용 HYUNDAI_ODO_V2): # byte 49~52 마지막 DPF 재생 시점의 주행거리 /1000 km @@ -227,17 +227,48 @@ templates: # 그 프로필이 같은 21 03에서 byte 53~55를 읽으므로, 이 차의 응답은 최소 # byte 55까지 도착한다 — 목표는 두 바이트 뒤다. # - # 앱의 formula 변수는 현재 byte 19(t)까지여서 byte 57을 직접 못 읽는다. - # 이 센서는 앱 로그의 raw= hex를 확보하기 위한 것이다. - # hex가 126자(63바이트) 이상이면 byte 57~60이 응답에 들어있다. - # 확인되면 OBD 센서에 offset 기반 decode를 추가해 정식 센서로 교체한다. + # 응답이 byte 57까지 도착하지 않으면 decode가 null을 돌려주고 아무것도 + # 발행되지 않는다 — 미지원 차에서 엉뚱한 값이 올라오지 않는다. + - key: odometer + mode: "21" + pid: "03" + pre_commands: ["ATSH7E0"] + decode: { offset: 57, length: 4, type: uint32, endian: big, scale: 0.001 } + unit: "km" + device_class: distance + state_class: total_increasing + accuracy_decimals: 1 + icon: mdi:counter + update_interval: 60s + # 검산용. 재생시점 주행거리 + 재생후 거리 = 총주행거리가 성립해야 한다. + - key: odometer_at_last_dpf_regen + mode: "21" + pid: "03" + pre_commands: ["ATSH7E0"] + decode: { offset: 49, length: 4, type: uint32, endian: big, scale: 0.001 } + unit: "km" + device_class: distance + accuracy_decimals: 1 + entity_category: diagnostic + update_interval: 60s + - key: distance_since_dpf_regen + mode: "21" + pid: "03" + pre_commands: ["ATSH7E0"] + decode: { offset: 53, length: 4, type: uint32, endian: big, scale: 0.001 } + unit: "km" + device_class: distance + accuracy_decimals: 1 + entity_category: diagnostic + update_interval: 60s + # raw= hex를 로그에 남기기 위한 프로브. 위 센서들이 값을 내면 지워도 된다. - key: probe_2103 mode: "21" pid: "03" pre_commands: ["ATSH7E0"] formula: "a" entity_category: diagnostic - update_interval: 30s + update_interval: 60s - id: gatt_meter_relay name: "GATT power meter + relay"