Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.
ReferenceBeta

Readings and the field dictionary

Reference for tracking readings: the value model, the reading and its unit rules, and the field dictionary with the queries that expose it.

How a reading is encoded, the reading itself, and the field dictionary that gives each reading its title, unit and nature.

Queries

fieldDefinitions

The field dictionary. Needed by any UI that renders readings: without it a client has a name and a number but no title, unit or nature.

Returns an empty list today, whatever codes and includeDeprecated say: the dictionary is not populated yet. The rest of this description is the contract once it is.

Cacheable, but not immutable. What is frozen is an entry's identity — its type, unit and nature never change, and an entry is never renamed — so a cached entry never starts meaning something else. What is not frozen is the dictionary's composition: it changes by design, and an existing entry can still gain deprecated and a replacedBy. So a held copy goes stale in one direction only — it can lack an entry, or miss a deprecation, never misdescribe a field it already has. Refetch when a reading arrives whose code is not in the cache. The locale is separate: it comes from the request headers rather than an argument here, so a client that switches language re-fetches, and a shared cache is keyed per locale or holds only the locale-independent fields. The headers are not honoured yet (TrackingFieldDefinition.title).

fieldDefinitions(
    codes: [Code!]
    includeDeprecated: Boolean = false
  ): [TrackingFieldDefinition!]!

Arguments

Name
Type
Description

codes

[Code!]

Limit to these field names. All entries when omitted.

includeDeprecated

Boolean

Include entries marked deprecated.

Output types:

TrackingFieldDefinition

A field dictionary entry. Entries are never renamed, retyped or deleted — only deprecated with a pointer to the replacement, because an entry describes every value ever recorded under that name, not just new ones.

Field
Type
Description

code

title

String!

Human-readable name of the field, for a UI that renders readings. Localized by design: the language comes from the request, not from an argument — X-Locale or Accept-Language, with English as the fallback. Those headers are not honoured yet, so today the text does not vary by caller. Once they are, this field is the one part of a dictionary entry that is not stable across callers, and a client caching the dictionary caches it per locale.

description

String

Longer explanation of the field, localized on the same terms as title.

unit

String

Reference unit (UCUM): the one the quantity is customarily shown and stored in. Not a default for a value that arrived without one — TrackingReading.unit says when it stands in. Null for dimensionless fields.

channelled

Boolean!

Whether values of this field can carry a channel number.

computed

Boolean!

Always computed by the platform rather than measured (e.g. mileage).

counterScope

For COUNTER fields: what the count runs from.

resettable

Boolean

For COUNTER fields: whether the counter can legitimately be reset (vs. wrapping around).

deprecated

Boolean!

replacedBy

aliases

[Code!]!

Older field names this entry replaces.


Objects

TrackingBoolValue

Field
Type
Description

boolValue

Boolean!


TrackingIntValue

Signed integer of any width (int8…int64).

Field
Type
Description

intValue


TrackingUIntValue

Unsigned integer of any width (uint8…uint64). Values above 2^63-1 — bitmasks, odometer-style counters, identifiers — do not fit Long, so the value rides the kernel's Decimal scalar, which already exists with a coercion and a validation path. A bare String would push the same parse onto the client with nothing checking it.

Field
Type
Description

uintValue


TrackingFloatValue

Field
Type
Description

floatValue

Float!


TrackingStringValue

Field
Type
Description

stringValue

String!


TrackingBytesValue

Opaque binary payload (raw CAN frame, RFID key), Base64-encoded.

Field
Type
Description

bytesValue

String!


TrackingTimestampValue

Field
Type
Description

timestampValue


TrackingDurationValue

A duration, carried by the Duration scalar. Every duration in this schema uses it, so "5m" instead of PT5M is rejected by coercion rather than by a resolver that may or may not check.

Field
Type
Description

durationValue


TrackingArrayValue

Homogeneous list (DTC codes, tachograph cards, acceleration vector).

Field
Type
Description

values


TrackingStructValue

Nested structure whose members are full readings (decoded J1939 frame, tachograph block).

Field
Type
Description

fields


TrackingClearedValue

The value was explicitly cleared. Its own variant so that "nothing was said" and "this no longer holds" can never be confused.

Field
Type
Description

cleared

Boolean!


TrackingReading

One named field of a state — a sensor reading, a device state, a counter, an identity. There is exactly one such list per state: readings are not split into inputs and states.

Field
Type
Description

code

Dictionary name of the field, e.g. lls_level, ignition, hw_mileage.

channel

Channel number for multi-channel fields (lls_level on tank 2), in 0..4294967295. Null when the field has none.

unit

String

Unit of this value (UCUM, e.g. km, Cel, L/h): the unit the message carried. For four legacy fields — board_voltage, battery_voltage, battery_level, hw_mileage — a message without a unit means the dictionary's unit by contract, and this field carries it. For every other field a message without a unit means "unknown", and this field is null: a dictionary Cel on temperature does not make a number that arrived without a unit degrees Celsius. So null covers both "dimensionless" and "unknown". definition.unit tells the two apart when the code is in the dictionary — a dimensionless field has none there. For a code the dictionary does not know, definition is null as well and the two cannot be told apart: the value has no unit a client may rely on. definition.unit is a reference value — the unit the quantity is customarily shown in — never a default for this one.

declaredType

The type that the sender declared for this value in its own source register. When the sender declared none, the type that the telemetry format fixes for this field name, if it fixes one. Null when it's the type that value's own member already implies, unless the format fixes that same type for this field name. Also null when neither the sender nor the format gives a type.

updatedAt

When this value was last received. A reading carries no timestamp of its own — this is the event time of the message it last arrived in, which across a last-known state is not the same for every reading.

definition

Dictionary entry behind code: title, nature, quantity, deprecation. Always null today: the field dictionary is not populated yet, so no code has an entry. TrackingQuery.fieldDefinitions returns an empty list for the same reason.


TrackingFieldDefinition

A field dictionary entry. Entries are never renamed, retyped or deleted — only deprecated with a pointer to the replacement, because an entry describes every value ever recorded under that name, not just new ones.

Field
Type
Description

code

title

String!

Human-readable name of the field, for a UI that renders readings. Localized by design: the language comes from the request, not from an argument — X-Locale or Accept-Language, with English as the fallback. Those headers are not honoured yet, so today the text does not vary by caller. Once they are, this field is the one part of a dictionary entry that is not stable across callers, and a client caching the dictionary caches it per locale.

description

String

Longer explanation of the field, localized on the same terms as title.

unit

String

Reference unit (UCUM): the one the quantity is customarily shown and stored in. Not a default for a value that arrived without one — TrackingReading.unit says when it stands in. Null for dimensionless fields.

channelled

Boolean!

Whether values of this field can carry a channel number.

computed

Boolean!

Always computed by the platform rather than measured (e.g. mileage).

counterScope

For COUNTER fields: what the count runs from.

resettable

Boolean

For COUNTER fields: whether the counter can legitimately be reset (vs. wrapping around).

deprecated

Boolean!

replacedBy

aliases

[Code!]!

Older field names this entry replaces.


Enums

TrackingValueType

Declared type of a value in terms of the source register.

Values: BOOL


TrackingFieldNature

What kind of quantity a field is, which decides how it may be aggregated. Dictionary metadata, not carried by the message.

Value
Description

GAUGE

Instantaneous measurement — averaging and medians are meaningful.

COUNTER

Monotonic accumulator; see counterScope and resettable.

DELTA

Increment since the previous report.

STATE

Holds until it changes — ignition, doors. Averaging is meaningless.

BITSET

Raw bitmask as sent by the device; bit layout belongs to the device model, not the field.

IDENTITY

Identity — VIN, driver card, ICCID.

TEXT

Free-form text.

SUMMARY_MIN

Summary over an interval whose bounds the device does not report.

SUMMARY_MAX

SUMMARY_AVG

SETTING

Device configuration value.


TrackingQuantity

Application-level quantity, from the field dictionary. Drives unit conversion and formatting.


TrackingCounterScope

Values: LIFETIME, TRIP, IGNITION_CYCLE, SINCE_RESET


Unions

TrackingValue

How a reading is encoded: eight scalar variants, two composite ones, and an explicit clear.

An absent variant means the sender had nothing to say and the previous value stands; TrackingClearedValue is the opposite — an assertion that the value no longer holds (driver key pulled, trailer detached).

Each scalar variant names its field after the type — boolValue, intValue, … — instead of all sharing value. A selection set that reads value from two members with different scalars fails validation (FieldsInSetCanMerge, GraphQL spec §5.3.2), so a client rendering readings would have to alias the occurrences.

One of: TrackingBoolValue, TrackingIntValue, TrackingUIntValue, TrackingFloatValue, TrackingStringValue, TrackingBytesValue, TrackingTimestampValue, TrackingDurationValue, TrackingArrayValue, TrackingStructValue, TrackingClearedValue


See also

Last updated

Was this helpful?