contracts/schema/signals.json

{
  "$comment": "Single source for signal identity. Topic name and envelope unit are both derived from these entries and are never authored separately. source=obd2 is standardised (OBD-II mode 01 over the K-line, through the ELM327): calibration references, every name prefixed obd_ (project-yukart decision 30); source=host is the Orin itself (orin-status), not the car. source=gnss is the receiver (svc-core gnss), on yukart/gnss/<signal>. source=imu is the WT61 IMU, already turned into the car's frame (mounting and gravity handled by its publisher), on yukart/imu/<signal>. source=z27ag is reverse-engineered from the car's own broadcast frames, and its 'can' block is the only place its layout is written down: id (11-bit, hex string), byte (first data byte, 0-7), length in bits (1, 8, 16 or 24), bit (length 1 only: 0 = LSB of that byte), order (lengths 16 and 24: big = byte first is most significant, little = the reverse), signed (lengths 8 and up: two's complement; default unsigned), scale and offset (value = raw * scale + offset; booleans are raw != 0). 'evidence' names the contracts report that found it.",
  "signals": {
    "obd_vehicle_speed_kph": {
      "unit": "kph",
      "type": "number",
      "source": "obd2",
      "description": "Road speed",
      "range": [
        0,
        255
      ]
    },
    "obd_coolant_temp_c": {
      "unit": "celsius",
      "type": "number",
      "source": "obd2",
      "description": "Engine coolant temperature",
      "range": [
        -40,
        215
      ]
    },
    "obd_intake_air_temp_c": {
      "unit": "celsius",
      "type": "number",
      "source": "obd2",
      "description": "Intake air temperature",
      "range": [
        -40,
        215
      ]
    },
    "obd_throttle_pct": {
      "unit": "percent",
      "type": "number",
      "source": "obd2",
      "description": "Throttle position",
      "range": [
        0,
        100
      ]
    },
    "obd_engine_load_pct": {
      "unit": "percent",
      "type": "number",
      "source": "obd2",
      "description": "Calculated engine load",
      "range": [
        0,
        100
      ]
    },
    "obd_fuel_level_pct": {
      "unit": "percent",
      "type": "number",
      "source": "obd2",
      "description": "Fuel tank level",
      "range": [
        0,
        100
      ]
    },
    "obd_intake_pressure_kpa": {
      "unit": "kpa",
      "type": "number",
      "source": "obd2",
      "description": "Intake manifold absolute pressure",
      "range": [
        0,
        255
      ]
    },
    "obd_maf_gps": {
      "unit": "g/s",
      "type": "number",
      "source": "obd2",
      "description": "Mass air flow rate",
      "range": [
        0,
        656
      ]
    },
    "obd_engine_rpm": {
      "unit": "rpm",
      "type": "number",
      "source": "obd2",
      "description": "Engine speed (OBD-II 0C): the reference for the decoded engine_rpm",
      "range": [
        0,
        8000
      ]
    },
    "obd_timing_advance_deg": {
      "unit": "degree",
      "type": "number",
      "source": "obd2",
      "description": "Ignition timing advance before TDC, cylinder 1",
      "range": [
        -64,
        64
      ]
    },
    "obd_stft_pct": {
      "unit": "percent",
      "type": "number",
      "source": "obd2",
      "description": "Short-term fuel trim, bank 1: positive adds fuel",
      "range": [
        -100,
        100
      ]
    },
    "obd_ltft_pct": {
      "unit": "percent",
      "type": "number",
      "source": "obd2",
      "description": "Long-term fuel trim, bank 1: positive adds fuel",
      "range": [
        -100,
        100
      ]
    },
    "obd_o2_b1s1_v": {
      "unit": "V",
      "type": "number",
      "source": "obd2",
      "description": "Upstream oxygen sensor voltage (narrowband: ~0.1 lean … ~0.9 rich)",
      "range": [
        0,
        1.275
      ]
    },
    "engine_rpm": {
      "unit": "rpm",
      "type": "number",
      "source": "z27ag",
      "description": "Engine speed",
      "range": [
        0,
        8000
      ],
      "can": {
        "id": "0x210",
        "byte": 4,
        "length": 16,
        "order": "big",
        "scale": 1,
        "offset": 0,
        "evidence": "Z27AG-DECODE-1"
      }
    },
    "accel_pedal_pct": {
      "unit": "percent",
      "type": "number",
      "source": "z27ag",
      "description": "Accelerator pedal position (0x00 at rest, 0xFA flat)",
      "range": [
        0,
        100
      ],
      "can": {
        "id": "0x210",
        "byte": 0,
        "length": 8,
        "scale": 0.4,
        "offset": 0,
        "evidence": "Z27AG-DECODE-1"
      }
    },
    "steering_angle_deg": {
      "unit": "degree",
      "type": "number",
      "source": "z27ag",
      "description": "Steering wheel angle: positive to the left. About -2.7° driving straight; lock to lock about ±475° (ratio about 16:1)",
      "range": [
        -600,
        600
      ],
      "can": {
        "id": "0x0C0",
        "byte": 0,
        "length": 16,
        "order": "little",
        "signed": true,
        "scale": 0.1,
        "offset": 0,
        "evidence": "Z27AG-DECODE-2"
      }
    },
    "brake_pedal": {
      "unit": "",
      "type": "boolean",
      "source": "z27ag",
      "description": "Brake pedal switch: pressed",
      "can": {
        "id": "0x231",
        "byte": 4,
        "bit": 1,
        "length": 1,
        "evidence": "Z27AG-DECODE-1"
      }
    },
    "handbrake": {
      "unit": "",
      "type": "boolean",
      "source": "z27ag",
      "description": "Handbrake applied",
      "can": {
        "id": "0x239",
        "byte": 0,
        "bit": 2,
        "length": 1,
        "evidence": "Z27AG-DECODE-1"
      }
    },
    "indicator_left": {
      "unit": "",
      "type": "boolean",
      "source": "z27ag",
      "description": "Left indicator lamp, as it flashes (on and off at the flasher's rate)",
      "can": {
        "id": "0x423",
        "byte": 2,
        "bit": 6,
        "length": 1,
        "evidence": "Z27AG-DECODE-1"
      }
    },
    "indicator_right": {
      "unit": "",
      "type": "boolean",
      "source": "z27ag",
      "description": "Right indicator lamp, as it flashes. Hazards were seen on the left bit only: open",
      "can": {
        "id": "0x423",
        "byte": 2,
        "bit": 5,
        "length": 1,
        "evidence": "Z27AG-DECODE-1"
      }
    },
    "side_lights": {
      "unit": "",
      "type": "boolean",
      "source": "z27ag",
      "description": "Side (position) lights on; also on with dipped beam",
      "can": {
        "id": "0x423",
        "byte": 2,
        "bit": 2,
        "length": 1,
        "evidence": "Z27AG-DECODE-1"
      }
    },
    "dipped_beam": {
      "unit": "",
      "type": "boolean",
      "source": "z27ag",
      "description": "Probably not dipped beam: clean in daylight (2026-10-13) but flickering at each switch movement at night (2026-10-15), and the Z27AG's cluster has no dipped-beam lamp (side lights, main beam and fogs only), so frame 423, the cluster's status, has little reason to carry it. Kept under this name until a light-switch walk shows what it is",
      "can": {
        "id": "0x423",
        "byte": 3,
        "bit": 1,
        "length": 1,
        "evidence": "Z27AG-DECODE-1"
      }
    },
    "main_beam": {
      "unit": "",
      "type": "boolean",
      "source": "z27ag",
      "description": "Main beam lamp on, flash-to-pass included",
      "can": {
        "id": "0x423",
        "byte": 2,
        "bit": 7,
        "length": 1,
        "evidence": "Z27AG-DECODE-2"
      }
    },
    "front_fogs": {
      "unit": "",
      "type": "boolean",
      "source": "z27ag",
      "description": "Front fog lamps on (they need side lights or dipped beam)",
      "can": {
        "id": "0x423",
        "byte": 2,
        "bit": 4,
        "length": 1,
        "evidence": "Z27AG-DECODE-2"
      }
    },
    "door_open": {
      "unit": "",
      "type": "boolean",
      "source": "z27ag",
      "description": "Any door open, the tailgate included (the bonnet has no switch)",
      "can": {
        "id": "0x423",
        "byte": 2,
        "bit": 1,
        "length": 1,
        "evidence": "Z27AG-DECODE-1"
      }
    },
    "driver_door_open": {
      "unit": "",
      "type": "boolean",
      "source": "z27ag",
      "description": "Driver's door open: the only door with its own bit",
      "can": {
        "id": "0x423",
        "byte": 0,
        "bit": 4,
        "length": 1,
        "evidence": "Z27AG-DECODE-1"
      }
    },
    "ac_compressor": {
      "unit": "",
      "type": "boolean",
      "source": "z27ag",
      "description": "A/C compressor engaged (engine running)",
      "can": {
        "id": "0x13D",
        "byte": 6,
        "bit": 7,
        "length": 1,
        "evidence": "Z27AG-DECODE-1"
      }
    },
    "vehicle_speed_kph": {
      "unit": "kph",
      "type": "number",
      "source": "z27ag",
      "description": "Road speed from the ABS (CAN), scaled against GNSS on this car's tyres: OBD-II speed reads 3 % lower",
      "range": [
        0,
        250
      ],
      "can": {
        "id": "0x231",
        "byte": 6,
        "length": 16,
        "order": "little",
        "scale": 0.0577,
        "offset": 0,
        "evidence": "Z27AG-DECODE-2"
      }
    },
    "wheel_speed_fr_kph": {
      "unit": "kph",
      "type": "number",
      "source": "z27ag",
      "description": "Front right wheel speed from the ABS (CAN), scaled against GNSS while cruising. Which word is which wheel: from cornering (outer wheels faster, fronts on a wider arc than rears), not yet checked on jack stands",
      "range": [
        0,
        250
      ],
      "can": {
        "id": "0x235",
        "byte": 0,
        "length": 16,
        "order": "little",
        "scale": 0.0578,
        "offset": 0,
        "evidence": "Z27AG-DECODE-3"
      }
    },
    "wheel_speed_fl_kph": {
      "unit": "kph",
      "type": "number",
      "source": "z27ag",
      "description": "Front left wheel speed from the ABS (CAN), scaled against GNSS while cruising. Which word is which wheel: from cornering (outer wheels faster, fronts on a wider arc than rears), not yet checked on jack stands",
      "range": [
        0,
        250
      ],
      "can": {
        "id": "0x235",
        "byte": 2,
        "length": 16,
        "order": "little",
        "scale": 0.0578,
        "offset": 0,
        "evidence": "Z27AG-DECODE-3"
      }
    },
    "wheel_speed_rr_kph": {
      "unit": "kph",
      "type": "number",
      "source": "z27ag",
      "description": "Rear right wheel speed from the ABS (CAN), scaled against GNSS while cruising. Which word is which wheel: from cornering (outer wheels faster, fronts on a wider arc than rears), not yet checked on jack stands",
      "range": [
        0,
        250
      ],
      "can": {
        "id": "0x235",
        "byte": 4,
        "length": 16,
        "order": "little",
        "scale": 0.0581,
        "offset": 0,
        "evidence": "Z27AG-DECODE-3"
      }
    },
    "wheel_speed_rl_kph": {
      "unit": "kph",
      "type": "number",
      "source": "z27ag",
      "description": "Rear left wheel speed from the ABS (CAN), scaled against GNSS while cruising. Which word is which wheel: from cornering (outer wheels faster, fronts on a wider arc than rears), not yet checked on jack stands",
      "range": [
        0,
        250
      ],
      "can": {
        "id": "0x235",
        "byte": 6,
        "length": 16,
        "order": "little",
        "scale": 0.0581,
        "offset": 0,
        "evidence": "Z27AG-DECODE-3"
      }
    },
    "odometer_km": {
      "unit": "km",
      "type": "number",
      "source": "z27ag",
      "description": "Total distance (CAN), whole kilometres: steps once per kilometre driven (12 steps over 11.9 km). Not yet compared with the cluster's display",
      "range": [
        0,
        16777215
      ],
      "can": {
        "id": "0x570",
        "byte": 4,
        "length": 24,
        "order": "little",
        "scale": 1,
        "offset": 0,
        "evidence": "Z27AG-DECODE-3"
      }
    },
    "coolant_temp_c": {
      "unit": "celsius",
      "type": "number",
      "source": "z27ag",
      "description": "Engine coolant temperature (CAN): equal to OBD-II's within 1 °C over 86-97 °C",
      "range": [
        -40,
        215
      ],
      "can": {
        "id": "0x449",
        "byte": 2,
        "length": 8,
        "scale": 1,
        "offset": -40,
        "evidence": "Z27AG-DECODE-2"
      }
    },
    "front_wiper": {
      "unit": "",
      "type": "boolean",
      "source": "z27ag",
      "description": "Front wiper running (low or high; interval not seen in a 4 s window). Medium confidence",
      "can": {
        "id": "0x423",
        "byte": 3,
        "bit": 3,
        "length": 1,
        "evidence": "Z27AG-DECODE-2"
      }
    },
    "orin_cpu_temp_c": {
      "unit": "celsius",
      "type": "number",
      "source": "host",
      "description": "Orin CPU cluster temperature",
      "range": [
        -40,
        110
      ]
    },
    "orin_gpu_temp_c": {
      "unit": "celsius",
      "type": "number",
      "source": "host",
      "description": "Orin GPU temperature",
      "range": [
        -40,
        110
      ]
    },
    "orin_soc_temp_c": {
      "unit": "celsius",
      "type": "number",
      "source": "host",
      "description": "Orin SoC temperature, hottest of its sensors",
      "range": [
        -40,
        110
      ]
    },
    "orin_tj_temp_c": {
      "unit": "celsius",
      "type": "number",
      "source": "host",
      "description": "Orin junction temperature: the hottest point on the die, which throttling acts on",
      "range": [
        -40,
        110
      ]
    },
    "orin_cpu_pct": {
      "unit": "percent",
      "type": "number",
      "source": "host",
      "description": "CPU utilisation, all cores",
      "range": [
        0,
        100
      ]
    },
    "orin_gpu_pct": {
      "unit": "percent",
      "type": "number",
      "source": "host",
      "description": "GPU utilisation",
      "range": [
        0,
        100
      ]
    },
    "orin_ram_used_mb": {
      "unit": "MB",
      "type": "number",
      "source": "host",
      "description": "Memory in use, CPU and GPU together (one shared pool): total minus available",
      "range": [
        0,
        8192
      ]
    },
    "orin_ram_used_pct": {
      "unit": "percent",
      "type": "number",
      "source": "host",
      "description": "Memory in use as a share of the total",
      "range": [
        0,
        100
      ]
    },
    "orin_swap_used_mb": {
      "unit": "MB",
      "type": "number",
      "source": "host",
      "description": "Swap in use",
      "range": [
        0,
        16384
      ]
    },
    "orin_power_w": {
      "unit": "W",
      "type": "number",
      "source": "host",
      "description": "Orin module input power (VDD_IN), from the onboard INA3221",
      "range": [
        0,
        30
      ]
    },
    "orin_fan_rpm": {
      "unit": "rpm",
      "type": "number",
      "source": "host",
      "description": "Cooling fan speed",
      "range": [
        0,
        10000
      ]
    },
    "net_wifi_up": {
      "unit": "",
      "type": "boolean",
      "source": "host",
      "description": "WiFi associated and up"
    },
    "net_wifi_ssid": {
      "unit": "",
      "type": "string",
      "source": "host",
      "description": "Network name (SSID) of the WiFi the Orin is associated with; not sent while WiFi is down"
    },
    "net_wifi_signal_dbm": {
      "unit": "dBm",
      "type": "number",
      "source": "host",
      "description": "WiFi signal level",
      "range": [
        -100,
        0
      ]
    },
    "net_wifi_rx_kbps": {
      "unit": "kbit/s",
      "type": "number",
      "source": "host",
      "description": "WiFi receive rate (into the Orin)",
      "range": [
        0,
        1000000
      ]
    },
    "net_wifi_tx_kbps": {
      "unit": "kbit/s",
      "type": "number",
      "source": "host",
      "description": "WiFi transmit rate (out of the Orin)",
      "range": [
        0,
        1000000
      ]
    },
    "net_lte_state": {
      "unit": "",
      "type": "string",
      "source": "host",
      "description": "Modem state as ModemManager reports it (connected, registered, searching, disabled, …), or absent with no modem"
    },
    "net_lte_tech": {
      "unit": "",
      "type": "string",
      "source": "host",
      "description": "Access technology in use (lte, umts, …); empty when not registered"
    },
    "net_lte_signal_pct": {
      "unit": "percent",
      "type": "number",
      "source": "host",
      "description": "Modem signal quality",
      "range": [
        0,
        100
      ]
    },
    "net_lte_rx_kbps": {
      "unit": "kbit/s",
      "type": "number",
      "source": "host",
      "description": "LTE receive rate (into the Orin)",
      "range": [
        0,
        150000
      ]
    },
    "net_lte_tx_kbps": {
      "unit": "kbit/s",
      "type": "number",
      "source": "host",
      "description": "LTE transmit rate (out of the Orin)",
      "range": [
        0,
        50000
      ]
    },
    "net_tablet_up": {
      "unit": "",
      "type": "boolean",
      "source": "host",
      "description": "USB link to the tablet has carrier"
    },
    "net_tablet_rx_kbps": {
      "unit": "kbit/s",
      "type": "number",
      "source": "host",
      "description": "USB tablet link, tablet to Orin",
      "range": [
        0,
        480000
      ]
    },
    "net_tablet_tx_kbps": {
      "unit": "kbit/s",
      "type": "number",
      "source": "host",
      "description": "USB tablet link, Orin to tablet",
      "range": [
        0,
        480000
      ]
    },
    "can_up": {
      "unit": "",
      "type": "boolean",
      "source": "host",
      "description": "The recorder's CAN interface (the PEAK, can_pcan) is present and up; false when absent or down"
    },
    "can_bus_state": {
      "unit": "",
      "type": "string",
      "source": "host",
      "description": "CAN controller state: ERROR-ACTIVE (normal), ERROR-WARNING, ERROR-PASSIVE, BUS-OFF, STOPPED (down), or absent with no adapter"
    },
    "can_rx_fps": {
      "unit": "frames/s",
      "type": "number",
      "source": "host",
      "description": "CAN frames received per second on that interface",
      "range": [
        0,
        10000
      ]
    },
    "elm_connected": {
      "unit": "",
      "type": "boolean",
      "source": "host",
      "description": "Bluetooth link to the OBD-II adapter (the ELM327 on the K-line) is up: obd-poller holds it while the ECU answers"
    },
    "cam_up": {
      "unit": "",
      "type": "boolean",
      "source": "host",
      "description": "A USB (UVC) camera is present for svc-vision: any V4L2 device on USB"
    },
    "vision_up": {
      "unit": "",
      "type": "boolean",
      "source": "host",
      "description": "yukart-vision (the camera's live view) is running"
    },
    "ups_battery_v": {
      "unit": "V",
      "type": "number",
      "source": "host",
      "description": "UPS battery pack voltage (3S Li-ion, 9.0–12.6 V)",
      "range": [
        0,
        16
      ]
    },
    "ups_current_a": {
      "unit": "A",
      "type": "number",
      "source": "host",
      "description": "UPS battery current: positive charging, negative discharging",
      "range": [
        -5,
        5
      ]
    },
    "ups_battery_pct": {
      "unit": "percent",
      "type": "number",
      "source": "host",
      "description": "UPS charge estimate from cell voltage, corrected for load. An estimate, steadiest at rest",
      "range": [
        0,
        100
      ]
    },
    "ups_state": {
      "unit": "",
      "type": "string",
      "source": "host",
      "description": "charging, discharging (running on battery) or idle (on input power, not charging)"
    },
    "gnss_fix": {
      "unit": "",
      "type": "string",
      "source": "gnss",
      "description": "Fix quality: none, 2d or 3d (gpsd TPV mode)"
    },
    "gnss_speed_kph": {
      "unit": "kph",
      "type": "number",
      "source": "gnss",
      "description": "Speed over ground; null without a fix",
      "range": [
        0,
        300
      ]
    },
    "gnss_heading_deg": {
      "unit": "degree",
      "type": "number",
      "source": "gnss",
      "description": "Course over ground, true north; null without a fix or at a standstill",
      "range": [
        0,
        360
      ]
    },
    "gnss_lat": {
      "unit": "degree",
      "type": "number",
      "source": "gnss",
      "description": "Latitude, WGS84",
      "range": [
        -90,
        90
      ]
    },
    "gnss_lon": {
      "unit": "degree",
      "type": "number",
      "source": "gnss",
      "description": "Longitude, WGS84",
      "range": [
        -180,
        180
      ]
    },
    "gnss_alt_m": {
      "unit": "m",
      "type": "number",
      "source": "gnss",
      "description": "Altitude above mean sea level; null without a 3D fix",
      "range": [
        -500,
        9000
      ]
    },
    "gnss_satellites": {
      "unit": "",
      "type": "number",
      "source": "gnss",
      "description": "Satellites used in the fix",
      "range": [
        0,
        64
      ]
    },
    "imu_roll_deg": {
      "unit": "degree",
      "type": "number",
      "source": "imu",
      "description": "Body roll in the car's frame: positive leaning right (right side down)",
      "range": [
        -180,
        180
      ]
    },
    "imu_pitch_deg": {
      "unit": "degree",
      "type": "number",
      "source": "imu",
      "description": "Body pitch in the car's frame: positive nose up",
      "range": [
        -90,
        90
      ]
    },
    "imu_accel_lon_g": {
      "unit": "g",
      "type": "number",
      "source": "imu",
      "description": "Longitudinal acceleration in the car's frame, gravity removed: positive forward (speeding up), negative braking",
      "range": [
        -4,
        4
      ]
    },
    "imu_accel_lat_g": {
      "unit": "g",
      "type": "number",
      "source": "imu",
      "description": "Lateral acceleration in the car's frame, gravity removed: positive to the right (a right turn reads positive)",
      "range": [
        -4,
        4
      ]
    },
    "imu_yaw_rate_dps": {
      "unit": "degree/s",
      "type": "number",
      "source": "imu",
      "description": "Yaw rate: positive turning left (counter-clockwise from above)",
      "range": [
        -500,
        500
      ]
    }
  }
}