In this release

The new Connector management API endpoints go out to preview, giving you full control over connector deployment, and its RealEstateCore representation (as LogicalDevice), and connector configuration. Also, in this release we implemented parsing of edge messages fully using alias ids, without the need for any ProptechOS IDs . Previously, the ProptechOS deviceId remained as a requirement in the edge message.

New functionality

Edge Connector Management

Edge connector management functionality includes LogicalDevice, its configuration and connector deployment process.

LogicalDevice – RealEstateCore representation of the IoT Edge connector. LogicalDevices can be of different “connector type” one type for each kind of system they integrate with. See supported connectors at proptechos.com/apps/#edge-connector Currently the API can manage two connector types: SMHI and Simple-Sample.

Connector – integration software hosted on site (“on the edge”) or in the ProptechOS cloud. Managing sensor telemetry messages and accepting actuation command requests from ProtpechOS and passing them to actuator devices.

LogicalDevice Management

LogicalDevice management operations:

  • GET /preview/json/logicaldevice – list all logical device;
  • GET /preview/json/logicaldevice/{id} – get single logical device;
  • POST /preview/json/logicaldevice – create single logical device;
  • PUT /preview/json/logicaldevice – update single logical device;
  • GET /preview/json/logicaldevice/connectortype – get list of supported connector types:

LogicalDevice Json Schema:

Unset

{
  “isMountedInBuildingComponent”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
  “status”: “Valid”,
  “littera”: “string”,
  “popularName”: “string”,
  “connectorType”: “(smhi | simple-sample)”,
  “connectorName”: “string”,
  “class”: “LogicalDevice”
}

Where:

  • connectorType – supported type of the connector;
  • connectorName – connector deployment name (is generated by the ProptechOS API and can not be changed;

LogicalDevice Config Management

LogicalDevice Configuration – consolidated configuration file that is required by Connector deployment. LogicalDevice Configuration is validated against a number of configuration json schemas.

LogicalDevice Configuration structure could be described as:

  • Base Configuration – this part of configuration includes general connector parameters (e.x. ‘pollingPeriod’, ‘connectorPollingPeriod’, ‘connectorMonitoringReadingPeriod’, etc.)
  • Devices and Sub Devices Configuration – this part of configuration includes collection of Devices and Sub Devices edge configurations.

LogicalDevice Configuration is represented by JSON:

Unset

{
  “logicalDeviceId” : “”,
  “connectorPollingPeriod” : 0,
  “telemetrySendPeriod” : 0,
  “connectorMonitoringReadingPeriod” : 0,
  “devices” : [ {
     “….”
     “sensors” : [ … ],
     “actuators” : [ … ] }]
}

Device / Sub Device connector config structure

Set of connector configuration parameters are regulated by Connector Config Schema. Apart main parameters each edge configuration contains mandatory metadata fields:

  • id – id of the Device or Sub Device this edge configuration is associated with;
  • class – REC class of the Device or Sub Device this edge configuration is associated with;
  • schemaId – id of JSON schema that regulates this edge configuration.

LogicalDevice Configuration management operations:

  1. LogicalDevice base config management operations:

    a. GET /preview/json/logicaldevice/{id}/config – get LogicalDevice base config;
    b. PUT /preview/json/logicaldevice/{id}/config – update LogicalDevice base config;

Note: Base config update will make the connector restart its functional schedulers;

2. Devices and Sub Devices edge config management operations:

a. Operations to manage edge config for single twin:

i. GET /preview/json/logicaldevice/{id}/config/twin/{twinId} – get single twin edge config for specified LogicalDevice;
 ii. POST /preview/json/logicaldevice/{id}/config/twin – create single twin edge config for specified LogicalDevice;
 iii. PUT /preview/json/logicaldevice/{id}/config/twin – update single twin edge config for specified LogicalDevice;
iv. DELETE /preview/json/logicaldevice/{id}/config/twin/{twinId} – delete single twin edge config for specified LogicalDevice;

b. Operations to manage edge configs for batch of twins:
i. GET /preview/json/logicaldevice/{id}/config/twins – get twin edge configs for specified LogicalDevice (twin ids additionally could be specified);
 ii. POST /preview/json/logicaldevice/{id}/config/twins – create batch of twin edge configs for specified LogicalDevice;
 iii. PUT /preview/json/logicaldevice/{id}/config/twins – update batch of twin edge configs for specified LogicalDevice;
 iv. DELETE /preview/json/logicaldevice/{id}/config/twins – remove batch of twin edge configs for specified LogicalDevice;

Note: Twins batch edge configs create or update can be applicable to the configs of the same type (that could be validated against the same schema);

3. Full edge config management operations:

a. GET /preview/json/logicaldevice/{id}/config/full – load full edge config file for specified LogicalDevice;
 b. PUT /preview/json/logicaldevice/{id}/config/setup/job – initiate job to set up full edge config for specified LogicalDevice;
 c. GET /preview/json/logicaldevice/{id}/config/setup/job/{jobId} – get status of earlier initiated job;

Note: Add / replace/ remove devices operation will make the connector restart its functional schedulers;

LogicalDevice Config Schema Management

Each LogicalDevice has its own Twin EdgeConfig Schemas associated with. Each LogicalDevice can be associated with three schemas: Device schema, Sensor schema and Actuator schema. EdgeConfig Schema regulates the content validity of each twin edge config. There can be only one Device, one Sensor and one Actuator schema that can be associated with one and only connector type.

EdgeConfig schema management operations:

  • GET /preview/json/logicaldevice/ {connectorType}/device/schema – get Device edge config schema;
  • POST /preview/json/logicaldevice/ {connectorType}/device/schema – create Device edge config schema;
  • DELETE /preview/json/logicaldevice/ {connectorType}/device/schema – remove Device edge config schema;
  • GET /preview/json/logicaldevice/ {connectorType}/sensor/schema – get Sensor edge config schema;
  • POST /preview/json/logicaldevice/ {connectorType}/sensor/schema – create Sensor edge config schema;
  • DELETE /preview/json/logicaldevice/ {connectorType}/sensor/schema – remove Sensor edge config schema;
  • GET /preview/json/logicaldevice/ {connectorType}/actuator/schema – get Actuator edge config schema;
  • POST /preview/json/logicaldevice/ {connectorType}/actuator/schema – create Actuator edge config schema;
  • DELETE /preview/json/logicaldevice/ {connectorType}/actuator/schema – remove Actuator edge config schema;
  • GET /preview/json/logicaldevice/ {id}/schemas – get edge config schema ids associated with the logical device;
  • PUT /preview/json/logicaldevice/ {id}/schemas – associate edge config schemas with the existing logical device;

LogicalDevice Deployment management

LogicalDevice (Connector) deployment operations:

  • POST /preview/json/logicaldevice/setup/job – initiate connector deployment job. Deployment operations:
    • DEPLOY
    • REMOVE
    • REDEPLOY
    • RESTART_SCHEDULERS
  • GET /preview/json/logicaldevice/{id}/status – get LogicalDevice deployment state;
  • GET /preview/json/logicaldevice/ {id}/setup/job/{jobId} – get status of earlier initiated job;
  • PUT /preview/json/logicaldevice/ {id}/devices/add/job – initiate job to add or replace devices for specified LogicalDevice;
  • PUT /preview/json/logicaldevice/ {id}/devices/remove/job – initiate job to remove devices for specified LogicalDevice;

ExtendedTwinInfo as new allowed value in RPP’s allowWriteTwinClasses

In the scope of providing more security rules for Application Specific properties, a new value was introduced in RPP. The new value is ExtendedTwinInfo, and if RPP contains it in allowWriteTwinClasses, it means that agents with such RPP can perform WRITE operations on property bags related to all allowed to READ twins.

For example:

Unset

{
  “propertyOwner”: “a1ef37aa-aa1f-4177-84d5-93de1f75fc8b”,
  “filters”: null,
  “allowWriteTwinClasses”: [
  “RealEstate”,
  “RealEstateComponent”,
  “BuildingComponent”,
  “Asset”,
  “Device”,
  “Sensor”,
  “Actuator”,
  “Collection”,
  “ExtendedTwinInfo”
  ],
  “includesAll”: true,
  “excludesAll”: null,
  “included”: null,
  “excluded”: null,
  “id”: “a1ef37aa-aa1f-4177-84d5-93de1f75fc8b”,
  “class”: “ResourcePermissionPolicy”,
  “status”: “Valid”,
  “popularName”: “Example ExtendedTwinInfo RPP”
}

Alias id as device id in edge device to cloud messages payload

Previously ProptechOS supported alias based messages where in observations list sensorId and actuatorId were alias ids, but still required the deviceId to be a ProptechOS ID.

In this release we implemented parsing of fully alias based payload.

Keep in mind that to connect to a device in ProptechOS IoT Hub you still need to know ProptechOS ID.

Example of the message:

Unset

{
  “format”: “rec3.3”, 
  “deviceId”: “https://ns.proptechos.com/device/64b65a99a53c”,
  “observations”: [
    {
      “observationTime”: “2023-10-27T20:07:44Z”,
      “value”: 16.1,
      “quantityKind”: “https://w3id.org/rec/core/Temperature”,
      “sensorId” : “https://ns.proptechos.com/sensor/e0d5120b90f1”
    }
  ]
}

Breaking changes

None

Fixes and minor updated (internal links are added only for reference)

Improvements:

  • PLAT-4133 – Forbid schema modification for users that don’t have modification application permission.
  • PLAT-3911 – Add areaQuantities for all BuildingComponent subclasses

Fixes:

  • PLAT-4124 – System fields are missing when queried from generic collection endpoint