Skip to main content

Device mapping

Introduction​

In Inimco.facts, mapping using JSON paths allows users to link specific data points within a device's telemetry data to corresponding capabilities of the device. This process simplifies the task of managing and interpreting data from various devices.

What is a JSON path​

A JSON path expression is structured to pinpoint the exact location of a data item within a JSON document. It begins with a $ symbol, representing the root element, and is followed by a sequence of child elements. These elements are usually separated by square brackets or dot notation.

A typical JSON path looks like $["data"]["temperature"] or $.data.temperature, where data and temperature are the keys in the JSON structure.

Example​

A smart thermostat sends telemetry data to Inimco.facts. This thermostat reports various data points including current temperature, humidity, and device status.

Telemetry data format​

The thermostat sends its telemetry in a JSON format like this:

{
  "device_id": "thermostat123",
  "telemetry": {
    "temperature": 72,
    "humidity": 50,
    "status": "on"
  },
  "timestamp": "2024-01-15T08:30:00Z"
}

Mapping options​

Our goal is to map the temperature data from the thermostat's telemetry to a temperature capability in Inimco.facts. This can be be done in various ways depending on your requirements.

Basic temperature data mapping​

  • Objective: Map the current temperature reported by the smart thermostat.
  • JSON Path: $.telemetry.temperature
  • Result: This path directly accesses the temperature value within the telemetry object.

Conditional mapping for specific node IDs​

  • Objective: Map data from a device telemetry where the Node ID matches a specific value.
  • JSON Path: $..[?(@.NodeId=='ns=2;i=2')].Value.Value
  • Result: Useful for devices sending complex telemetry with multiple nodes, this path filters data based on the Node ID and retrieves its value.

Accessing specific array elements​

  • Objective: Map the first temperature reading from an array of readings.
  • JSON Path: $["deviceReadings"][0]["temperature"]
  • Result: Targets the first (0 index) temperature reading in an array called deviceReadings.

Retrieving all instances of a specific data point​

  • Objective: Collect all temperature readings, regardless of their position in the telemetry data.
  • JSON Path: $..temperature
  • Result: The deep scan operator (..) is used to find and map every temperature value in the data, ideal for unstructured or deeply nested data.

Wildcard mapping for broad data retrieval​

  • Objective: Map all data points under a specific object.
  • JSON Path: $.telemetry.*
  • Result: Retrieves all values under the telemetry object, useful for devices that send a wide range of data points.

Steps for Mapping​

  1. Log in to Inimco.facts.
  2. Go to the Devices.
  3. Find and select thermostat123 from your list of devices.
  4. Navigate to the Mapping tab.
  5. In the Value JSON path field, enter the JSON path to access the temperature value.
  6. Select thermostat123 from the Device field.
  7. From the Capability menu, select the capability that corresponds to temperature readings. This might be labeled something like "Temperature" or "Temp".
  8. If you want to map more data points, click +ADD MAPPING and repeat the process for other telemetry data like humidity or status.
  9. Click Save to apply these settings.

Result​

Now, every time thermostat123 sends its telemetry data, Inimco.facts will automatically extract the temperature value using the defined JSON path and map it to the thermostat’s temperature capability. This mapping enables easier monitoring and analysis of the temperature data on the dashboards.