Telemetry: MQTT, RFID, GPS, sensors

Four connectors read physical telemetry: a sensor bus, a tag reader, a fleet tracker and a fixed probe gateway. Every protocol is implemented natively against its wire format. MQTT 3.1.1 packets, LLRP inventory rounds, Modbus-TCP register reads and NMEA 0183 sentences are written in FACE, with no third-party protocol library. All four emit one row type, SensorReading.

Plant equipment normally lives on private networks, so these connectors allow internal addresses by default. Set allow_internal_network=false on a connection to refuse them. The cloud instance-metadata address, multicast and the unspecified address are always refused. See Networking.

Common rules

• An empty batch is not a success. A connector that connected and received nothing returns Success=false with <type> connector reached <what> and received no readings. A silent reader is reported as silent, never as “no excursions”.
• Zero means “use the default” for every window and cap below. It never means “collect nothing”. Values above a maximum are reduced to the maximum.
• Readings are sorted by observed time, then asset, then metric.
• What Test does not establish. A successful probe does not establish that a sensor is publishing, that an antenna is attached or aimed, that a probe is calibrated, or that any readings exist.

MQTT (sensor bus)

Credentials: password (also mqtt_password, api_key, token); username may also come from the bundle.

• Test dials the broker and completes CONNECT/CONNACK within 10 s, then disconnects. It does not subscribe.
• Execute subscribes, listens for the window, and decodes each message:
  • JSON objects, arrays, numbers, booleans and numeric strings become readings.
  • When a JSON value names no metric, the metric comes from the topic’s last segment.
  • Non-JSON payloads are kept as rows with payload_kind and a short sample.
  • Topic, QoS and retained flags go into attributes.
• WebSocket transport, MQTT 5, QoS 2 delivery and persistent sessions are not implemented. A legacy iot connection that declares a non-MQTT protocol (such as AMQP) is refused by name.
• Explore returns supported=false. MQTT has no catalogue call.

RFID (LLRP and vendor REST)

Credentials for HTTP readers, tried in order:

1. token → Authorization: Bearer
2. api_key → the API-key header
3. password with the username property → HTTP Basic

• Test for LLRP connects and waits for the reader’s connection-attempt event. For HTTP, it makes one GET to the event API within 8 s.
• Execute runs an inventory round and returns one reading per tag sighting. EPC, antenna, RSSI and read count go into attributes when the reader states them. HTTP event bodies are capped at 16 MiB, and an over-cap stream is refused rather than reported as a short round.
• Explore returns supported=false.

GPS and telematics

Credentials by provider:

• Test:
  • Samsara: one GET /fleet/vehicles/stats?types=gps&limit=1
  • Geotab: a Get of one Device
  • Generic REST: one request
  • NMEA: a TCP connect
• Execute returns position fixes as readings (latitude, longitude, geo_stated), with speed and heading in attributes. It also returns sensor channels where requested.
  • At most 5,000 readings and 20 pages. Truncation is stated in the message.
  • REST bodies are capped at 8 MiB.
  • NMEA reads RMC, GGA and VTG sentences, with lines capped at 8,192 bytes.
  • Units are taken from the provider (for example Geotab’s unit-of-measure ids) and never assumed.
• Explore returns supported=false.

Sensor gateway (Modbus-TCP and HTTP)

Each SensorChannel states its own mapping:

HTTP credentials: token, api_key, or username + password.

• Test connects and reads the first channel. For HTTP, it fetches the document and resolves the first channel’s path. A failure names the channel, register and unit. A Modbus exception response is reported as the device’s own refusal.
• Execute polls every channel at the interval for the whole pass. The raw register and count go into attributes.
• Explore returns supported=false. Modbus has no register map, so the channel list you configure is the schema.

The SensorReading row

Every telemetry connector, and the Flipper edge reader, returns rows with these columns, in this order:

The *Stated fields

In the protocol format FACE uses, “the probe read 0 °C” and “the row has no reading” look the same, and in a cold chain they are opposite facts. So every connector sets a *_stated flag from whether the source carried the field, never from whether the value is non-zero:

• A threshold is never assumed. FACE does not assume 2–8 °C because an asset is called REEFER. A band that no one stated stays unstated, and analysis reports that the threshold was not stated.
• A unit that is absent stays absent. FACE never assumes Celsius.
• A position without geo_stated is not a position.

Consumers must read a value only when its *_stated flag is true. See /docs/analysis/ for how these rows feed temperature-excursion and claims evidence.