Skip to content

Latest commit

 

History

History
95 lines (71 loc) · 4.8 KB

DATA_FORMAT.md

File metadata and controls

95 lines (71 loc) · 4.8 KB
Raw

JSON Data fields

See also the discussion and rationale in merbanan#827

Message Data

These fields are the primary data fields containing the most basic message data and used to identify the specific device. For some devices these are the only fields contained in the message, as the message itself constitutes an event from this particular device model.

  • time (string) (Required)

    • Time stamp. String containing date and time of when the message was received. Format and timezone is dependent on current locale unless options like -M time:unix or -M time:iso and -M time:utc are used.

  • type (string) (Optional)

    • Classification of the general device type. Currently only used for "TPMS".

  • model (string) (Required)

    • Device model. Human readable string concisely describing the device by manufacturer name and manufacturers model designation according to the following syntax: "<Manufacturer>-<Model>".
    • It is common for devices to be sold under different brands, however the Original Equipment Manufacturer name shall be used, where possible to identify.
    • Avoid redundant word like "sensor", "wireless" etc. unless it is part of the manufacturers model designation.
    • Avoid adding device type designations like "Switch", "Temperature", "Thermostat", "Weather Station" etc. Device type can be inferred from the data content.
    • Avoid all non-alphanumeric characters, especially: "/&$*#+[]()".
    • Length of model string should be less than 32 characters.

  • subtype (string) (Optional)

    • Device type or function in a common protocol. Examples are various sensors, triggers, keyfob in wireless security.

  • id (integer, rarely string) (Optional)

    • Device identification. Used to differentiate between devices of same model. Depending on device model it may be a non-volatile value programmed into the device, a volatile value that changes at each power on (or battery change), or a value configurable by user e.g. by switch or jumpers. No assumptions should be made to the id value other than it contains a unique sequence of alphanumeric characters.
    • Length of id should be less than 16 characters.

  • channel (integer, rarely string) (Optional)

    • Secondary device identification. For devices with more than one identification value (e.g. both an internal value and a switch).

  • mic (string) (Optional)

    • Message integrity check. String describing the method used for ensuring the data integrity of the message. Protocol decoders for devices without mic will be disabled by default as they are prone to excessive false positives.
    • Possible values:
      • "CRC" - Cyclic Redundancy Check.
      • "CHECKSUM" - Accumulated sum of data.
      • "PARITY" - Parity bit (odd, even, multiple)

Common Device Data

Various data fields, which are common across devices of different types.

  • battery_ok (double) (Optional)

    • Battery status indication as a level between 0 (empty) and 1 (full). If the sensor can only report a binary status the value shall be 1 for "OK" and 0 for "LOW".

  • battery_V (battery_mV) (double) (Optional)

    • Battery level in Volts. Should be supplemented by battery_ok status indication if possible.

Sensor Data

Due to the large variance in sensor types this list of common values is non-exhaustive. Additional data value fields should follow the form: <Type>_<Unit>, where Unit should be in sensors native units insofar possible with no conversion. Automatic unit conversion can be performed with the -C si or -C customary option.

Examples:

  • temperature_C (temperature_F) (double) (Optional)

    • Temperature from a temperature sensor in degrees Celsius (Fahrenheit).

  • setpoint_C (setpoint_F) (double) (Optional)

    • Thermal set point of a thermostat device in degrees Celsius (Fahrenheit).

  • humidity (double) (Optional)

    • Humidity from a hygrometer sensor in % relative humidity

  • moisture (double) (Optional)

    • Moisture from a soil probe in % relative saturation

  • wind_dir_deg (double) (Optional)

    • Wind direction from wind sensor in compass direction degrees.

  • wind_avg_m_s (wind_avg_km_h, wind_avg_mi_h) (double) (Optional)

    • Average wind speed from wind sensor in m/s. Averaging time is sensor dependent.

  • wind_max_m_s (wind_max_km_h, wind_max_mi_h) (double) (Optional)

    • Gust wind speed from wind sensor in m/s.

  • rain_mm (rain_in) (double) (Optional)

    • Rainfall from rain sensor in mm (inches) since last reset. Reset method is device dependent.

  • rain_rate_mm_h (rain_rate_in_h) (double) (Optional)

    • Rainfall rate from rain sensor in mm per hour (inches per hour).

  • pressure_hPa (pressure_psi) (double) (Optional)

    • Air pressure from barometer or Tire Pressure Monitor in hPa (psi)