Sensors

Proposed CSV upload format

This is a proposed format for bulk uploading sensors. To be vetted and verified with Ensemble folks.

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. Ensemble requires a part_number and hardware_version to register it with their service.

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

Architectural guidance

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.

Questions:

How does LiteFarm get a non-expiring token from the Ensemble API?

Probably manually enter this into an “integrations” table to similar to how certifiers have a surveystack link. Ultimately up to ESCI and the owner of LF-2483.

Will LiteFarm need a different token for each organization or will one token allow us to access multiple organizations?

Ideally one token per farm, but may have one universal instead. To verify with ESCI team.

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

• soil_water_content (derived)

• soil_water_potential

• temperature

Mark says that parameter_number is dynamic from device to device. Will need to develop a strategy to make this consistent.

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.

   "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)

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"
}'

• Authenticated users can create an organization.

  • "name" is the only required field

• The creator will automatically become the admin and member of organization

• Preferred UUID for organization can be optionally specified. Otherwise it will be autogenerated

• Returns an error if UUID incorrect or non-unique

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)

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
//     ]
//   }
// ]'

• 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

Do we need a different callback address for each organization or can the callback specify org as part of the hierarchy?

Does the callback only send what has happened since the last update? Is there a failsafe if a callback fails to communicate several rounds of data?

Yes, ESCI will keep track of what has been shared and only send updates.

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)

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"
//         }
//     ]
// }
'

• 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

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

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

Are there any attributes above that are missing?

What data types can we have for sensor reading values?

• soil_water_content: Derived from water_potential and temperature

• water_potential: Sensed

• temperature: Sensed

Requirements

LF-2338 - Getting issue details... STATUS