dbc updates

tools/radar/RADAR_RESEARCH.md

@@ -111,8 +111,8 @@ contained in that family.
 
 | Source | Runtime layout | Current role | Status and next proof |
 | --- | --- | --- | --- |
-| `0x3A5–0x3C4` | 32 × 24-byte messages at 20 Hz | Front | Confirmed on compatible routes. It is the only family with a confirmed `MOTION_STATE` and deep cross-platform signal study. Sportage HEV 2026 has an incompatible overlapping layout. |
-| `0x210–0x21F` | 16 × 32-byte messages at 20 Hz; two tracks per message | Likely front | Implemented. Confirm role and signal semantics across its platform group; K8 HEV's supplied route contained no active tracks. |
+| `0x3A5–0x3C4` | 32 × 24-byte messages at 20 Hz | Front | Confirmed across 21 common-layout routes and 817,852 checksum-valid frames. `TRACK_QUALITY`, `RCS`, lifecycle, kinematics, and the optional rich extension are decoded. No dedicated oncoming value was found. Sportage HEV 2026 has an incompatible overlapping layout. |
+| `0x210–0x21F` | 16 × 32-byte messages at 20 Hz; two tracks per message | Front | Confirmed across 16 active routes and two dialects. Detailed and compact layouts share the core; compact adds persistent object IDs and uses motion code 3 for stopped and 4 for oncoming, while detailed has no dedicated oncoming value. Three additional streams were empty and one non-HDA2 Telluride route had no 210 range. |
 | `0x500–0x51F` | 32 × 8-byte messages at 20 Hz | Likely front | Implemented. Confirm special behavior around `0x501/0x502` and validate lateral conversion from azimuth. |
 | `0x602–0x617` | Generator has double-track `0x602–0x611` and alternate single-track `0x612–0x617` formats | Likely front | Partially implemented: runtime currently consumes only `0x602–0x611`. Confirm whether `0x612–0x617` is the same objects, an alternate view, or a separate output before expanding it. |
 | `0x235–0x248` | 20 × 32-byte messages at 33 Hz; one track per message | Corner candidate | Implemented geometry, but the post's corner classification still needs HDA2 route/video confirmation. |
@@ -153,15 +153,15 @@ topology; it does not claim that either is present.
 
 | Platform | Front | Corner | Extras/fused | Rear |
 | --- | --- | --- | --- | --- |
-| Hyundai Elantra HEV 2024 | `210–21F` implemented; verify | Unknown | Unknown | Unknown |
-| Hyundai Ioniq 5 | `210–21F` implemented; verify | HDA2 candidate | Unknown | Unknown |
-| Hyundai Palisade 2023 | `210–21F` implemented; verify | HDA2 candidate | Unknown | Unknown |
-| Kia EV6 | `210–21F` implemented; verify | Four-block prototype candidate | Unknown | Prototype family may include rear corners |
-| Kia K8 HEV 1st gen | Range observed, supplied route empty | Unknown | Unknown | Unknown |
-| Hyundai Santa Cruz 2025 | `210–21F` implemented; verify | Unknown | Unknown | Unknown |
-| Hyundai Tucson 4th gen | `210–21F` implemented; verify | Unknown | Unknown | Unknown |
-| Hyundai Tucson HEV 2025 | `210–21F` implemented; verify | Unknown | Unknown | Unknown |
-| Kia Sportage 5th gen | `210–21F` implemented; verify | Unknown | Unknown | Unknown |
+| Hyundai Elantra HEV 2024 | `210–21F` detailed confirmed | Unknown | Unknown | Unknown |
+| Hyundai Ioniq 5 | `210–21F` detailed confirmed on two active routes; one route empty | HDA2 candidate | Unknown | Unknown |
+| Hyundai Palisade 2023 | `210–21F` detailed confirmed on one active route; one route empty | HDA2 candidate | Unknown | Unknown |
+| Kia EV6 | `210–21F` detailed confirmed on four active routes; one route empty | Four-block prototype candidate | Unknown | Prototype family may include rear corners |
+| Kia K8 HEV 1st gen | Historical supplied route empty; outside the 20-route validation set | Unknown | Unknown | Unknown |
+| Hyundai Santa Cruz 2025 | `210–21F` compact confirmed | Unknown | Unknown | Unknown |
+| Hyundai Tucson 4th gen | `210–21F` compact confirmed on four routes | Unknown | Unknown | Unknown |
+| Hyundai Tucson HEV 2025 | `210–21F` compact confirmed | Unknown | Unknown | Unknown |
+| Kia Sportage 5th gen | `210–21F` compact confirmed on two routes | Unknown | Unknown | Unknown |
 
 ### Platforms with legacy implemented layouts
 

tools/radar/SIGNALS.md

@@ -1,6 +1,7 @@
-# Hyundai 3A5-3C4 radar signal notes
+# Hyundai 3A5-3C4 and 210-21F radar signal notes
 
-This document tracks the evidence behind the 24-byte `RADAR_3A5_3C4` layout.
+This document tracks the evidence behind the 24-byte `RADAR_3A5_3C4` layout
+and its shared signal semantics with the 32-byte `RADAR_210_21F` layout.
 It deliberately separates a signal being active from its meaning being known.
 The cross-family and per-platform investigation plan lives in
 [RADAR_RESEARCH.md](RADAR_RESEARCH.md).
@@ -21,6 +22,13 @@ An optional field that is dead on one platform is not globally dead.
 ## Evidence corpus
 
 - The original layout was checked against 817,852 frames from 21 forum routes.
+- The 3A5 checksum was rechecked on all 817,852 frames and matched the HKG
+  CAN-FD checksum with the CAN address as data ID, with zero failures.
+- All 726 advertised 210-route segments were scanned across 20 unique routes:
+  16 routes had active targets, three had complete but empty streams, and one
+  non-HDA2 Telluride route had no 210 stream. The 16 active routes split evenly
+  between detailed and compact dialects, with no third active layout.
+- The 210 HKG checksum matched all 13,210,543 checked frames.
 - The documented route corpus was expanded to 107 route/segment entries:
   all 36 canonical Hyundai/Kia CAN-FD test routes plus the forum radar and
   consecutive-range route lists. A qlog pre-screen identified candidates
@@ -43,21 +51,26 @@ An optional field that is dead on one platform is not globally dead.
   local-recording frames; all remained zero.
 - The Sportage HEV 2026 forum route has an incompatible overlapping layout and
   is excluded from this matrix.
+- A downloaded Hyundai DBC archive supplied two related but non-bit-compatible
+  object layouts. The BN7 front-radar DBC defines a persistent global object
+  ID and `0/1/2/3 = unknown/stationary/moving/stopped`; the HMVS4 object DBC
+  independently defines value 3 as stopped, a 7-bit quality level, and alive
+  age/lifetime. Neither DBC directly contains the 210 or 3A5 radar layout.
 
 ## Signal matrix
 
 | Signal | Status | Availability and evidence |
 | --- | --- | --- |
-| `CHECKSUM` | Active unknown | A 16-bit per-track checksum. Useful once its algorithm and data ID are known. |
+| `CHECKSUM` | Confirmed core | 16-bit HKG CAN-FD checksum using the CAN address as data ID. It matched all 817,852 checked 3A5 frames. |
 | `COUNTER` | Confirmed core | Global transmit-cycle counter covering 0-255 and wrapping. |
 | `STATE_ALT` | Redundant | Exact compressed mirror in all 325,110 active samples: `STATE=3 -> 2`, `STATE=4 -> 3`. |
-| `MOTION_STATE` | Confirmed core | Ground-frame class: unknown, stationary, or moving. Correctly marked observed crossing traffic as moving. |
+| `MOTION_STATE` | Confirmed core | Ground-frame class: unknown, stationary, or moving. Correctly marked observed crossing traffic as moving. Related Hyundai radar data assigns the unused fourth 2-bit value to stopped, not oncoming; that bit remained zero throughout the tested 3A5 corpus. |
 | `TRACK_COUNTER` | Confirmed core | Modulo-4 per-track update counter. Separate from the transmit counter. |
-| `NEW_SIGNAL_2` | Active unknown | Signed value from -64 to 63. Active on every sampled platform, but correlations with age, distance, and velocity are inconsistent. |
-| `AGE` | Confirmed core | Per-track update age, 0-255. |
+| `TRACK_QUALITY` | Confirmed core | Unsigned 7-bit track quality/existence score. Empty and tentative tracks are low, measured tracks are high, and coasted tracks decline with `COAST_AGE`. A related Hyundai object layout describes its 7-bit quality level as reliability, validity, or probability evidence; the radar's raw scale is not confirmed to be a percentage. |
+| `AGE` | Confirmed core | Per-track alive age/lifetime count, 0-255. |
 | `COAST_AGE` | Confirmed core | Zero for measured tracks and increments while a track is coasted/predicted. |
 | `STATE` | Confirmed core | Track lifecycle: empty, tentative, measured, coasted, or unresolved tentative. |
-| `NEW_SIGNAL_8` | Active unknown | Smooth signed attribute observed from -33 to 43. Return-strength/RCS-like behavior remains plausible but unproven. |
+| `RCS` | Confirmed core | Signed radar cross-section/return-strength value. At controlled distances its median consistently increases from small to passenger to large targets. The raw unit is not calibrated. |
 | `LONG_DIST` | Confirmed core | Longitudinal target distance in meters. |
 | `LAT_DIST` | Confirmed core | Lateral target position relative to the ego axis in meters. |
 | `REL_SPEED` | Confirmed core | Longitudinal target speed relative to ego. |
@@ -69,14 +82,63 @@ An optional field that is dead on one platform is not globally dead.
 | `WIDTH` | Optional useful | Target width in 0.1 m units. Populated on EV9/Ioniq 9; passenger-car values cluster around 1.8-2.0 m. Zero means unavailable on other sampled platforms. Every address in 3A5-3C4 can carry it, so it does not identify a separate track bank. |
 | `LENGTH` | Optional useful | Target length in 0.1 m units. Passenger cars cluster around 4 m and long vehicles reach roughly 13-15.5 m. It is available on the same target samples as `WIDTH`. |
 | `ABS_SPEED` | Optional useful | Absolute target-speed magnitude. On Ioniq 9 it matches `hypot(vEgo + REL_SPEED, REL_LAT_SPEED)` with about 0.08-0.15 m/s median error. It was populated for 28,735/28,860 active Ioniq 9 samples and 23,252/27,339 EV9 samples, including many targets without dimensions. Zero is the platform default when unsupported. |
-| `ORIENTATION_ANGLE` | Optional useful | Target orientation relative to the ego axis. Ioniq 9 follows motion heading within roughly 2 degrees median; EV9 crossing traffic rotated from about -45 to -83 degrees. It is associated with dimension-bearing targets. `+/-180` is unavailable/default; compatible non-rich platforms consistently use +180. |
+| `ORIENTATION_ANGLE` | Optional useful | Target orientation relative to the ego axis. Ioniq 9 follows motion heading within roughly 2 degrees median; EV9 crossing traffic rotated from about -45 to -83 degrees. It is associated with dimension-bearing targets. Values near `+/-180` can represent real rearward orientation on rich tracks, while compatible non-rich platforms consistently use +180 as unavailable/default. |
 | `NEW_SIGNAL_13` | Optional active unknown | Shape/geometry metadata from 0-10. It was nonzero only on dimension-bearing targets in the EV9/Ioniq 9 routes. Confidence-like behavior is plausible but not established. |
-| `NEW_SIGNAL_12` | Optional active unknown | Shape/geometry metadata from 0-10. It was nonzero only on dimension-bearing targets; values 10 and 0 dominate. Exact meaning is unknown. |
+| `NEW_SIGNAL_12` | Optional active unknown | Strong geometry-age/maturity candidate. Two independent Ioniq 9 routes progressed `0 -> 1 -> 2 -> ... -> 10` and saturated at 10. It remains unnamed pending confirmation on another rich platform. |
 | `NEW_SIGNAL_14` | Optional active unknown | Shape/geometry category 0-3. It is zero when the associated geometry metadata is unavailable. |
 | `NEW_SIGNAL_15` | Optional active unknown | Shape/geometry category 0-2. It is zero when the associated geometry metadata is unavailable. |
 | `NEW_SIGNAL_16` | Optional active unknown | Shape/geometry category 0-3. It is zero when the associated geometry metadata is unavailable. |
 | `NEW_SIGNAL_17` | Optional active unknown | Shape/geometry category 0-2. It is zero when the associated geometry metadata is unavailable. The most common rich-layout `14/15/16/17` tuple is `2/2/2/1`. |
 
+## Cross-family layout and naming findings
+
+Both families expose 32 tracks at approximately 20 Hz per address:
+
+| Layout | Envelope | Tracks per message | Shared core | Family-specific extension |
+| --- | --- | --- | --- | --- |
+| 210 detailed | `0x210-0x21F`, 32 bytes | 2 | State, motion, quality, age/coast age, RCS, range, relative velocity/acceleration | Detailed state/RCS/category are populated; compact object-ID bytes are normally zero |
+| 210 compact | `0x210-0x21F`, 32 bytes | 2 | Same bit positions and scales except for the documented lateral-speed sign convention | Uses `STATE_ALT`, per-target status and persistent 6-bit `OBJECT_ID`; detailed state/RCS/category remain zero |
+| 3A5 common | `0x3A5-0x3C4`, 24 bytes | 1 | Homologous first 16 bytes | Bytes 16-23 carry measurement status and optional dimensions, absolute speed, orientation, and geometry metadata |
+
+The shared signal conclusions are:
+
+- The old signed `NEW_SIGNAL_2` decoding was wrong. Raw values use 0-99 in the
+  tested corpus, and the signed interpretation created an artificial wrap at
+  63/64. The standardized name is `TRACK_QUALITY`, unsigned 7-bit.
+- Detailed 210 and 3A5 `TRACK_QUALITY` distributions are nearly identical.
+  Compact 210 uses a higher calibration, commonly around 70 while measured,
+  that falls toward the low 20s at long coast ages. The semantic name is
+  shared, but no percentage unit is assigned.
+- The old `NEW_SIGNAL_8` is standardized as `RCS`. Detailed 210 and 3A5 have
+  closely matching distributions, and size ordering is preserved within every
+  tested distance band. 210 supplies eight signed bits; 3A5 supplies seven
+  because the remaining bit extends `LONG_DIST` from 12 to 13 bits.
+- `NEW_SIGNAL_4` occupies the same physical two bits and has nearly identical
+  0-2 distributions in detailed 210 and 3A5, but its exact category remains
+  unknown.
+- Compact 210 `OBJECT_ID` remains strongly supported: it held through 99.9%
+  of consecutive same-track updates and changed when a slot acquired a
+  replacement target. A related Hyundai BN7 radar DBC independently defines
+  `ObjectId` as a global ID that remains constant while an object is tracked.
+  Sparse 3A5 `NEW_SIGNAL_5` does not behave like the same field and remains
+  unknown.
+
+## Oncoming classification
+
+Oncoming candidates were cross-checked using fresh ego speed and
+`vEgo + REL_SPEED < -3 m/s`.
+
+| Layout | Evidence | Conclusion |
+| --- | --- | --- |
+| 210 compact | Motion code 4 appeared on 4,870 active rows. Synchronized code-4 rows had -13.30 m/s median ground-frame longitudinal speed, with 3,516 strong oncoming candidates. Related Hyundai BN7 radar and HMVS4 object DBCs independently label motion value 3 as stopped. | `MOTION_STATE=3` is stopped and `MOTION_STATE=4` is the compact oncoming class. |
+| 210 detailed | Bit 29 never set across 317,965 active rows. Its 4,924 physics-based candidates remained in motion values 0-2. | No dedicated detailed-210 oncoming value. |
+| 3A5 common | Bit 29 remained zero in all 817,852 frames. Among 6,104 physics-based candidates across 14 routes, motion was 0 for 5,792, 1 for 312, and never 2. | No dedicated 3A5 oncoming value or flag. |
+
+`NEW_SIGNAL_4` and `NEW_SIGNAL_18` also failed to isolate the 3A5 oncoming
+candidates. Do not widen 3A5 `MOTION_STATE` to three bits. If oncoming
+classification is needed for 3A5 or detailed 210, derive it from ego-relative
+kinematics with persistence, hysteresis, and lane plausibility.
+
 ## Platform and cluster conclusions
 
 | Architecture | Compatible examples | Rich geometry |
@@ -113,8 +175,12 @@ routes.
 
 - Detect support per radar source instead of treating extension defaults as
   real measurements.
-- Treat zero dimensions and `+/-180` orientation as unavailable.
+- Treat zero dimensions as unavailable. Treat +180 as unavailable on non-rich
+  platforms, but do not discard near-180 rich tracks without checking their
+  other geometry and lifecycle fields.
 - Do not use any `NEW_SIGNAL_*` field for control or filtering until its
   meaning is independently validated.
+- `TRACK_QUALITY` and `RCS` are decoded for research and diagnostics, but
+  neither has a calibrated physical/percentage scale suitable for control.
 - `REL_LAT_SPEED` is suitable for debugging cross traffic, but a production
   cross-traffic filter still needs lane-change validation and track history.

tools/radar/old/radar_helpers.py

@@ -29,11 +29,11 @@ BO_ {addr_dec} RADAR_TRACK_{addr_hex}: 24 RADAR
  SG_ STATE_ALT : 25|2@0+ (1,0) [0|3] "" XXX
  SG_ MOTION_STATE : 28|2@0+ (1,0) [0|2] "" XXX
  SG_ TRACK_COUNTER : 31|2@0+ (1,0) [0|3] "" XXX
- SG_ NEW_SIGNAL_2 : 38|7@0- (1,0) [-64|63] "" XXX
+ SG_ TRACK_QUALITY : 38|7@0+ (1,0) [0|127] "" XXX
  SG_ AGE : 47|8@0+ (1,0) [0|255] "" XXX
  SG_ COAST_AGE : 51|4@0+ (1,0) [0|15] "" XXX
  SG_ STATE : 54|3@0+ (1,0) [0|7] "" XXX
- SG_ NEW_SIGNAL_8 : 62|7@0- (1,0) [-33|37] "" XXX
+ SG_ RCS : 62|7@0- (1,0) [-64|63] "" XXX
  SG_ LONG_DIST : 63|13@1+ (0.05,0) [0|409.55] "m" XXX
  SG_ LAT_DIST : 76|12@1- (0.05,0) [-102.4|102.35] "m" XXX
  SG_ REL_SPEED : 88|14@1- (0.01,0) [-81.92|81.91] "m/s" XXX