kuksa_dart_sdk 0.2.5

Dart/Flutter client SDK for the Eclipse KUKSA databroker (v2): typed access to Vehicle Signal Specification (VSS) signals for embedded Linux IVI navigation.

kuksa_dart_sdk

Dart/Flutter client SDK for the Eclipse KUKSA Vehicle Abstraction Layer.

Connects to a running kuksa-databroker instance and provides typed access to Vehicle Signal Specification (VSS) signals — road friction, traction control, tire pressure, wiper intensity, and more.

Built for driver-assisting navigation applications on embedded Linux IVI systems.

---

Features

• gRPC-based — uses the kuksa.val.v2 VAL API (databroker v0.5+)
• Typed signal access — floatValue, boolValue, int32Value, etc. without protobuf boilerplate
• Snow-safety signal set — pre-defined kSnowSafetySignals covering ESC friction, TCS, ABS, wiper intensity, temperature, TPMS
• Streaming subscriptions — continuous updates as a Dart Stream<Map<String, Datapoint>>
• Batch reads — read multiple signals in one gRPC call
• Secure + insecure — optional JWT token and TLS certificate support

---

Quick Start

# pubspec.yaml
dependencies:
  kuksa_dart_sdk: ^0.2.4

import 'package:kuksa_dart_sdk/kuksa_dart_sdk.dart';

final client = KuksaClient(host: 'localhost', port: 55555);
await client.connect();

// One-shot read
final dp = await client.getValue(kRoadFrictionMostProbable);
print(RoadFriction.classifyDatapoint(dp));  // e.g. "RoadFrictionReading(18.0% → icy)"

// Subscribe to all snow-safety signals
await for (final update in client.subscribe(kSnowSafetySignals)) {
  final road = RoadFriction.classifyDatapoint(update[kRoadFrictionMostProbable]);
  final tcsActive = update[kTcsIsEngaged]?.boolValue ?? false;

  switch (road.grip) {
    case RoadGrip.icy:      // measured ice — activate snow routing mode
    case RoadGrip.reduced:  // measured reduced grip
    case RoadGrip.grip:     // measured normal grip
      if (tcsActive) { /* traction loss despite a good reading */ }
    case RoadGrip.unknown:  // NO reading (absent signal, or out-of-spec value)
      // Show the driver that conditions are UNKNOWN.
      // Do not assume the road is clear.
  }
}

await client.dispose();

---

Road friction

Vehicle.ADAS.ESC.RoadFriction.MostProbable is declared by VSS as datatype: float, unit: percent, min: 0, max: 100 — "0 = no friction, 100 = maximum friction".

It is not a 0.0–1.0 fraction. An ESC on black ice reports about 18.0. Code that compares the raw value against a fraction-scale threshold such as < 0.3 will classify black ice as a clear road.

RoadFriction.classify(double? percent) returns a RoadFrictionReading:

Reading	grip	Meaning
18.0	RoadGrip.icy	measured ice / very low grip (below 30 percent)
45.0	RoadGrip.reduced	measured reduced grip (below 60 percent)
87.0	RoadGrip.grip	measured normal grip
null	RoadGrip.unknown	no reading — signal absent or no provider
120.0, NaN	RoadGrip.unknown (isContractViolation)	producer emitted a value outside the VSS range

Two properties this API guarantees:

• An absent reading is never a safe value. unknown answers false to both isIcy and isNotIcy. Absence of a measurement is not a claim about the road in either direction. There is no ?? 1.0-style default to reach for: percent is null, and requirePercent() throws.
• An out-of-range value is never coerced. It is not clamped (clamping 120 to the maximum would assert perfect grip) and not rescaled. The producer is violating the specification; the honest answer is unknown.

The 30 / 60 percent thresholds are this package's advisory choice. VSS defines the scale, not the driving semantics.

---

Signal Constants

signal_path.dart exports named constants for the most common driver-safety signals. The table below is generated from the COVESA specification vendored in spec/ by tool/gen_signal_table.dart, and CI fails if it drifts.

Constant	VSS path	Datatype	Unit / range (per VSS)
kRoadFrictionMostProbable	Vehicle.ADAS.ESC.RoadFriction.MostProbable	float (sensor)	percent, 0–100
kRoadFrictionLowerBound	Vehicle.ADAS.ESC.RoadFriction.LowerBound	float (sensor)	percent, 0–100
kRoadFrictionUpperBound	Vehicle.ADAS.ESC.RoadFriction.UpperBound	float (sensor)	percent, 0–100
kTcsIsEngaged	Vehicle.ADAS.TCS.IsEngaged	boolean (sensor)	no range declared
kAbsIsEngaged	Vehicle.ADAS.ABS.IsEngaged	boolean (sensor)	no range declared
kWiperFrontIntensity	Vehicle.Body.Windshield.Front.Wiping.Intensity	uint8 (actuator)	no range declared
kRaindetectionIntensity	Vehicle.Body.Raindetection.Intensity	uint8 (sensor)	percent, max 100
kAirTemperature	Vehicle.Exterior.AirTemperature	float (sensor)	Celsius, no range declared
kRoadSurfaceCondition	Vehicle.Exterior.RoadSurfaceCondition	uint8 (sensor)	UNKNOWN | DRY | WET | SNOW | ICE | SLUSH | WET_ICE | LOOSE_GRAVEL
kTirePressureFrontLeft	Vehicle.Chassis.Axle.Row1.Wheel.Left.Tire.Pressure	uint16 (sensor)	kPa, no range declared
kTirePressureFrontRight	Vehicle.Chassis.Axle.Row1.Wheel.Right.Tire.Pressure	uint16 (sensor)	kPa, no range declared
kVehicleSpeed	Vehicle.Speed	float (sensor)	km/h, no range declared
kSnowSafetySignals	—	List<String>	all of the above as one subscription list

Vehicle.ADAS.ESC.RoadFriction.MostProbable is a percent value (0–100), not a 0.0–1.0 fraction: an ESC on black ice reports about 18.0. Classify it with RoadFriction.classify — see Road friction.

---

Prerequisites

• A running kuksa-databroker v0.5+
• Dart SDK ≥ 3.0.0

For development on embedded Linux IVI (e.g., Raspberry Pi 4, Renesas R-Car):

# Start databroker in mock mode (no real vehicle required)
docker run --rm -p 55555:55555 ghcr.io/eclipse-kuksa/kuksa-databroker:latest --mock-datapoints

---

Architecture

Flutter / Dart app
       │
       ▼
 KuksaClient (this package)
       │  gRPC (kuksa.val.v2 / VAL service)
       ▼
 kuksa-databroker  ──────────────────── Vehicle ECUs
       │                                  (CAN, SOME/IP, LIN)
       ▼
  VSS signals: friction, TCS, ABS, wiper, temperature, TPMS

This package is part of the SNGNav winter navigation stack. The navigation_safety package consumes KUKSA signals via kuksa_dart_sdk to adapt routing decisions in real-time based on road surface conditions.

---

Contributing

Issues and PRs welcome. Please file an issue before a large change.

AI-assisted — authored with Claude, reviewed by Komada.