System Design: IoT Sensor Packet

This specification defines the generic sensor packet contract used to integrate external sensor and controller telemetry with BetterFleet Manage.

It uses a Generic Sensor model, a BetterFleet-defined sensor type intended for integrator-side implementation, so new hardware can be added without requiring BetterFleet Manage software changes.

Related design: - BBA Microgrid Controller Generic Packet Translation

Top-Level JSON

{
  "device_id": "string (UUID, required)",
  "timestamp": 1754953373315, // ms since epoch (UTC, required)

  // Gateway identity fields are optional.
  // They may be omitted entirely or included with a null value.
  "manufacturer": "string | null (optional)",
  "model": "string | null (optional)",
  "serial_number": "string | null (optional)",
  "firmware": "string | null (optional)",

  "sensors": [SensorObject, ...] // required
}

Sensor Object

{
  "sensor_id": "string (UUID)",
  "measurands": [MeasurandObject, ...]
}

Sensor identity fields such as manufacturer, model, serial number, and firmware, when provided, should be represented as measurands using the standard keys defined below.

Measurand Object

{
  "key": "string",
  "value": "number | string | null",
  "timestamp": 1754953322917
}

• value should be numeric in SI units when applicable.
• Use null when the measurement is unavailable or invalid.
• Strings are allowed only for textual data such as identity or status.

Standard Measurands

Device manufacturers and integrators should expose these measurands using the exact string keys listed below.

Expected String Key	Description
CURRENT	Total RMS current (A)
FREQUENCY	Grid frequency (Hz)
VOLTAGE	RMS phase-to-neutral voltage (V)
LINE_VOLTAGE	Line-to-line RMS voltage (V)
TOTAL_POWER_LOAD	Total active (real) power (W)
TOTAL_REACTIVE_POWER	Total reactive power (var)
TOTAL_APPARENT_POWER	Total apparent power (VA)
TOTAL_POWER_FACTOR	Total power factor (unitless, -1.0 to 1.0)
PHASE_1N_VOLTAGE_THD	Phase 1-N voltage total harmonic distortion (%)
PHASE_2N_VOLTAGE_THD	Phase 2-N voltage total harmonic distortion (%)
PHASE_3N_VOLTAGE_THD	Phase 3-N voltage total harmonic distortion (%)
PHASE_1_CURRENT_THD	Phase 1 current total harmonic distortion (%)
PHASE_2_CURRENT_THD	Phase 2 current total harmonic distortion (%)
PHASE_3_CURRENT_THD	Phase 3 current total harmonic distortion (%)
ACTIVE_ENERGY_EXPORTED	Total exported active energy (Wh)
ACTIVE_ENERGY_IMPORTED	Total imported active energy (Wh)
ESTOPPED	Emergency-stop has stopped power ("true", "false")
ESTOP_CONTACT	Emergency-stop contact state ("open", "closed")
DIGITAL_INPUTS	Status of generic digital inputs (implementation-specific)
UPS_STATE	UPS operating state
UPS_DESCRIPTION	Text description of UPS condition
MANUFACTURER	Reporting device or sensor manufacturer
MODEL	Model identifier of the device or sensor
SERIAL_NUMBER	Serial number of the device or sensor
FIRMWARE	Firmware version string
AVAILABLE_CHARGING_CAPACITY	Charger capacity calculated by the Microgrid Controller (W)
FAIL_SAFE_CAPACITY	Failsafe capacity calculated by the Microgrid Controller (W)
HEARTBEAT_STATUS	Connection status of the MGC ("ok", "connection_lost", "timeout", "error")
SOC	State of charge (%)
DEVICE_POWER_STATE	Power state of the device ("on", "off")
BESS_OPERATIONAL_MODE	Charger operating state ("charging", "discharging", "automatic", "idle", "error")
LIMIT_PEAK_SHAVING	Limit charging during peak shaving ("true", "false")
LIMIT_DER_EXPORT	Limit charging during distributed energy resource export ("true", "false")

Any other sensor readings can be forwarded unchanged as passthrough keys, with each word title-cased.

Function Blocks and Required Measurands

Function Block	Required Measurands
Update Circuit Load	TOTAL_POWER_LOAD
Update Circuit Measurands	CURRENT, FREQUENCY, VOLTAGE, LINE_VOLTAGE, TOTAL_POWER_LOAD, TOTAL_REACTIVE_POWER, TOTAL_APPARENT_POWER, TOTAL_POWER_FACTOR, PHASE_1N_VOLTAGE_THD, PHASE_2N_VOLTAGE_THD, PHASE_3N_VOLTAGE_THD, PHASE_1_CURRENT_THD, PHASE_2_CURRENT_THD, PHASE_3_CURRENT_THD, ACTIVE_ENERGY_EXPORTED, ACTIVE_ENERGY_IMPORTED
eStop	ESTOPPED, ESTOP_CONTACT
Site Capacity Models	TOTAL_POWER_LOAD (one or more sensors)
Sensor Asset Identity	MANUFACTURER, MODEL, SERIAL_NUMBER, FIRMWARE
MGC Update Circuit Capacity	AVAILABLE_CHARGING_CAPACITY, HEARTBEAT_STATUS

Example Packet

{
  "device_id": "331db959-569d-4469-ae22-33e724bf4b1d",
  "timestamp": 1754953373315,
  "manufacturer": "BetterFleet",
  "model": "BF-GW100",
  "serial_number": "GW-00042",
  "firmware": "v1.3.7",
  "sensors": [
    {
      "sensor_id": "ee946e57-04f4-48fb-84be-2b348345f0e8",
      "measurands": [
        { "key": "TOTAL_POWER_LOAD", "value": 228000.0, "timestamp": 1754953373308 },
        { "key": "CURRENT", "value": 221.8, "timestamp": 1754953373308 },
        { "key": "MANUFACTURER", "value": "Schneider Electric", "timestamp": 1754953373308 },
        { "key": "MODEL", "value": "PM8000", "timestamp": 1754953373308 },
        { "key": "SERIAL_NUMBER", "value": "SN12345678", "timestamp": 1754953373308 },
        { "key": "FIRMWARE", "value": "v2.1.0", "timestamp": 1754953373308 }
      ]
    }
  ]
}

Integration Notes

• Key matching is exact and case-sensitive.
• Values should use the SI units indicated above.
• Devices should provide all measurands where possible.
• Unsupported measurands should be omitted or reported as null.