Sensors

Your integration can connect any type of sensor or measurement device to fieldmargin, allowing both real-time and historical data to be shown on the farm.

This data could be anything from temperature readings to whether a gate is open or closed.

We will request sensor data from you via the Data API:

Message	Description
sensors.latest	Sensors on the farm with their current readings
sensors.history	The historical readings from a specific sensor

Supported data types

We accept sensor values of the following types:

Metric type	Description
temperature	Given in Celsius
percentage
length	Given in meters
number	General purpose integer or floating point
string	General purpose string

Currently we expect temperatures and lengths to be given in metric units. The fieldmargin apps allow the user to choose what units they'll see data in.

You may provide numbers as numerical values or as strings.

Data API sensors.latest

Provides the latest readings of all connected devices and sensors.

Message type	sensors.latest
Required scopes	sensors:write

Request

Example request

{
    "type": "sensors.latest",
    "farm_id": "8740a65d-1fdd-4c2b-bb52-d5b84984fa63",
    "token": "3d0daa4b484743bfaf20721f9bf76eb4"
}

We will request the latest sensors readings from you over the Data API. We'll do this regularly so they can be displayed quickly to the user.

Response

Example response

{
    "latest": [
        {
            "sensor": {
                "id": "513977c69edd",
                "name": "Soil probe",
                "location": {
                    "lat": 50.9929848,
                    "lng": -0.8370794
                },
                "active": true,
            },
            "metrics": [
                {
                    "id": "temp_ground",
                    "name": "Ground temperature",
                    "type": "temperature",
                    "value": 17
                }
            ],
            "updated_at": "2018-03-07T14:20:57Z"
        }
    ]
}

The response should contain a list of all sensors on the farm, including inactive ones. It should contain the following fields:

Field	Required	Description
sensor	Required	The physical device that is reporting values
metrics	Optional	The most recent list of values reported. Required if the sensor is active.
updated_at	Optional	The date and time the device reported these readings. Required if metrics have been set.

A sensor is defined as:

Field	Required	Description
id	Required	Unique ID of the sensor
name	Required	Human readable label
active	Required	If the sensor is functional and reporting values
location	Optional	Last known location
vehicle_id	Optional	If this sensor is part of a vehicle

If you don't provide a location for the sensor the user will be able to choose this themselves.

If your integration also provides vehicle locations to us then you can connect sensors to the vehicle by setting the vehicle_id field. You can model data such as engine state and fuel levels as sensors and we'll connect them up in the UI.

A metric is defined as:

Field	Required	Description
id	Required	ID of the metric, unique to the sensor
name	Required	Human readable label
type	Required	One of our supported metric types
value	Required	Value appropriate to the type of metric

Data API sensors.history

Provides historical sensor readings for a particular metric, so a graph timeline can be displayed to the user.

Message type	sensors.history
Required scopes	sensors:write

Request

Example request

{
    "type": "sensors.history",
    "farm_id": "8740a65d-1fdd-4c2b-bb52-d5b84984fa63",
    "token": "3d0daa4b484743bfaf20721f9bf76eb4",
    "body": {
        "sensor_id": "513977c69edd",
        "metric_id": "temp_ground",
        "start": "2018-03-01T14:20:57Z",
        "end": "2018-03-08T14:20:57Z",
    }
}

We will request sensor history from you over the Data API when we need to present it to the user.

The message will contain the following additional fields:

Field	Description
sensor_id	ID of the sensor to query
metric_id	ID of the metric of the sensor
start	Inclusive start date to return values from
end	Inclusive end date to return values until

Response

Example response

{
    "history": [
        {
            "timestamp": "2018-03-07T14:20:57Z",
            "value": 17
        }
    ]
}

The response should contain a list of sensor readings in date ascending order. We may cache your response for a short period, but we won't store it long-term.

You may return as few or as many results to us as you like. Each item is defined as:

Field	Required	Description
timestamp	Required	When the reading was recorded
value	Required	Sensor reading at that time