Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Sensor

ID

Name

Lat_long

Reading_types

Depth

Brand

Model

Part_number

hardware_version

Description

The sensor’s unique external id. This is the identity that will be used to register the sensor with external services and receive readings associated with this sensor.

How the sensor will be labelled in LiteFarm.

The latitude and longitude for the sensor, comma separated.

Comma delimited list of sensor reading types. Valid values are:

  • soil_moisture_content

  • water_potential

  • temperature

Assumed to be in cm, only 1 depth per sensor. For this project depths can be 10, 20, 30, 50.

The brand of sensor.

The model of sensor.

Required?

Required

Required

Required

Required

Required

Optional

Optional

Optional

Optional

Example

WERKTX

“Sensor 1”

-31.362442522541148, -64.21047544487595

soil_moisture_content, water_potential, temperature

10

“Ensemble Scientific”

“Model ABC”

Notes

Where the sensor has been placed in the ground.

Will need to be grouped on the map. This should be default behaviour since sensors are points.

ESCI Add device will fail without this attribute.

ESCI Add device will fail without this attribute.

Definition of a sensor: A device with a single id, name, lat / long, and depth. Must have at least one reading parameter, but may have several. Optionally has a brand and model.

...

Validation should be performed at least via the API and potentially through the UI as well.

Architecture

Please take this as guidance rather than instruction. The following tables seem to make sense to allow users to document sensors and to integrate them with those external services.

  • Sensor: The attributes describing the physical device and it’s location. This should somehow tie to a point location for that sensor.

  • sensor_parameter: The parameters that instruct LiteFarm on how to parse data read by the sensor but don’t change from reading to reading and also aren’t related to the physical nature of the sensor. May just be part of the sensor table!

  • sensor_reading: Readings from the sensor.

  • integration: A table documenting

Sensor

ID

Name

Lat_long

Type

Depth

Elevation

Description

The sensor’s unique id.

How the sensor will be labelled in LiteFarm.

The latitude and longitude for the sensor, comma separated.

Valid values to begin are:

Assumed to be in cm, comma delimited if multiple depths.

The elevation of ground level at the location where the sensor is mounted.

Required?

Required

Required

Required

Required

Optional

Optional

Example

“Sensor 1”

-31.362442522541148, -64.21047544487595

...

Sensor_reading

ID

Read_time

Transmit_time

Sensor_ID

sensor_parameter_id

Value

Description

A unique identifier for this reading. May have some meaning or traceability for Ensemble.

The timestamp when this reading was captured.

The timestamp when this reading was transmitted.

The sensor reporting the reading.

The calibration which instructs on how to interpret the value. Required since each sensor can have multiple types of readings, e.g. “Temperature” and “Moisture”.

The numerical value of the reading.

Required?

Required

Required

Required

Required

Required

Example

Questions:

What are the valid types of sensor (reading) types to start with?

  • soil_moisture_content

  • water_potential

  • temperature

How do we link up sensor_reading_types with a depth via csv upload?

Each sensor will only have 1 depth. We may choose to display sensors with very similar lat / long and different depths as the same sensor via the UI - but they are different in terms of sensor reading types and readings.

How does ensemble tie a reading to a parameter when posting new sensor readings?

It appears to be based on “parameter_number”. Need to explore what exactly this means to ESCI.

Code Block
   "node_esid":"123",
   "sensor_data":[
      {
         "sensor_esid":"124",
         "sensor_values":[
            {
               "parameter_number":1,
               "raw_value":2.910,
               "timestamp":"2022-01-10T17:41:00+0800"
            },
            {
               "parameter_number":1,
               "raw_value":2.110,
               "timestamp":"2022-01-10T17:41:00+0800"
            },
            {
               "parameter_number":2,
               "raw_value":0.001938,
               "timestamp":"2022-01-10T17:41:00+0800"
            }
         ]
         ...

What is the format for registering an organization with ESCI?

https://documenter.getpostman.com/view/18529342/UVXeqchj#b3a26ae9-be68-42a4-ac92-ca8025e7008c (see POST Create an organization)

Code Block
curl --location --request POST 'api.esci.io/organizations/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "tes_org",
    "uuid": "76df1f72-6fb0-11ec-90d6-0242ac120003",
    "website_url": "http://test.com",
    "email": "orgemail@hotmail.com",
    "phone": "123-4567",
    "street_number": "12345",
    "street": "Easy Street",
    "city": "Vancouver",
    "postal": "A1B2C3",
    "state": "British Columbia",
    "country": "Canada"
}'

What is the format for registering a callback address with ESCI?

https://documenter.getpostman.com/view/18529342/UVXeqchj#b3a26ae9-be68-42a4-ac92-ca8025e7008c (assumed to be POST Create organization webhook)

  • Create webhook for organization

    • Will send a confirmation request in the form of an empty array to the url (with authorization if any) before being created

  • Webhooks automatically send any organization data between current time and the webhook's last transmit time based on the webhook's frequency as long as it is active. Will send an empty array if no new data

  • authorization_header is optional

  • frequency is in minutes

  • Errors

    • 400_BAD_REQUEST

      • Invalid json, incorrect url

      • received Response other than 200_OK from url during creation

      • Errors when trying to send confirmation request to the url

  • Only organization admins can call

Code Block
curl --location -g --request POST 'api.esci.io/organizations/{{organization_uuid}}/webhooks/' \
--data-raw '{
    "url": "http://www.example.com",
    "authorization_header": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX3BrIjoxLCJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiY29sZF9zdHVmZiI6IuKYgyIsImV4cCI6MTIzNDU2LCJqdGkiOiJmZDJmOWQ1ZTFhN2M0MmU4OTQ5MzVlMzYyYmNhOGJjYSJ9.NHlztMGER7UADHZJlxNG0WSi22a2KaYSfd1SAuT7lU",
    "frequency": 15
}


// Example json that webhook will post to the url
// [
//   {
//     "node_esid": "123",
//     "sensor_esid": "124",
//     "parameter_number": 1,
//     "unit": "ºC",
//     "time": [
//       "02-09-2022, 22:53:52",
//       "02-09-2022, 22:54:07"
//     ],
//     "value": [
//       1,
//       2
//     ],
//     "validated": [
//       false,
//       false
//     ]
//   },
//   {
//     "node_esid": "123",
//     "sensor_esid": "124",
//     "parameter_number": 2,
//     "unit": "kPa",
//     "time": [
//       "02-09-2022, 22:54:23"
//     ],
//     "value": [
//       3
//     ],
//     "validated": [
//       false
//     ]
//   }
// ]'

What is the format for registering sensors with ESCI?

https://documenter.getpostman.com/view/18529342/UVXeqchj#b3a26ae9-be68-42a4-ac92-ca8025e7008c (assumed to be POST Add a new device)

  • Adds device to cloud with the specified POST data:

    • part_number

    • hardware_version

    • Device ESID will automatically be generated and any device parameters will be created based on the DeviceType's default parameter list if it exists.

    • Any generated parameters will have a 1:1 calibration generated with it as well

    • If device is interfacer, sets configurable to TRUE, so users can modify the device with other APIs

    • Errors:

      • 400_BAD_REQUEST

        • Device type with part_number does not exist

        • Any fields missing

    • Only ESci admins can call

Code Block
curl --location --request POST 'api.esci.io/devices/' \
--data-raw '{
    "part_number": "ESA-12345",
    "hardware_version": "B"
}

// example response.data
// {
//     "esid": "GLMCHJ",
//     "device_type": {
//         "id": 1,
//         "name": "Temperature Pressure Sensor",
//         "part_number": "ESA-1001",
//         "device_category": "S"
//     },
//     "hardware_version": "B",
//     "parameters": [
//         {
//             "parameter_number": 1,
//             "category": "Temperature",
//             "unit": "ºC",
//             "label": "Area 1"
//         },
//         {
//             "parameter_number": 2,
//             "category": "Soil Water Tension",
//             "unit": "kPa",
//             "label": "Area 2"
//         }
//     ]
// }
'

What depths are the sensors at (for this project)?

10, 20, 30, and 50cm. Duplicates at 10 and 30.

...