In this release

Several new features for multiple areas of ProptechOS come with this release. One of the most significant improvements is the new opportunity to observe the twin lifecycle, with an audit trail. There is now a general view of all twins for quick high level info. Additionally this release includes support for the real estate subclass Land and improvements in actuation and telemetry flows.

New functionality

Twin history

With /history it is possible to track a twin’s update history with snapshots – the state of the twin after each create/update/delete operation. It is possible to retrieve snapshots for a selected period (if no period is provided, the last 24 hours will be taken by default).

New history endpoints:

  • GET /api/json/realestate/{id}/history
  • GET /api/json/realestatecomponent/{id}/history
  • GET /api/json/buildingcomponent/{id}/history
  • GET /api/json/room/{id}/history
  • GET /api/json/storey/{id}/history
  • GET /api/json/asset/{id}/history
  • GET /api/json/device/{id}/history
  • GET /api/json/sensor/{id}/history
  • GET /api/json/actuator/{id}/history
  • GET /api/json/actuationinterface/{id}/history

Each endpoint accepts a mandatory path parameter `id` – twin id and two optional parameters `startTime` and `endTime`.

The response is returned in the following format:

[
  {
    “snapshotTime”: “2022-03-24T21:26:14.219Z”,
    “operation”: “[CREATE|UPDATE|DELETE]”,
    “agent”: [email protected],
    “snapshot”: {
    “id”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
    “hasAlias”: [
      {
        “id”: “string”,
        “isMemberOfAliasNamespace”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”
    }
  ],
  “hasGeoReferenceOrigo”: “0.0;0.0;0.0″,
  “littera”: “string”,
  “popularName”: “string”,
  “class”: “RealEstate”,
  “ownedBy”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
 }
}
]

General twin endpoints

Two endpoints added to retrieve any twin, regardless of its class, by its id, or by littera, alias or popular name:

  • GET /api/json/twin
  • GET /api/json/twin/{id}

‘Not Started’ sensor edge status

The ProptechOS edge status feature was improved by adding ‘Not started’. So that the lifecycle is reflected: Not StartedWarmupOKWarningError ( OK …)

This Not Started state is for sensors that have been created, but are not yet sending any observation. As soon as a sensor sends its first observation, its status will be changed to Warm up.

New field ‘startedTime’ for Devices, Sensors and Actuators

startedTime is a new field in Device, Sensor and Actuator.

  • Sensor startedTime represents the time when a sensor sends its first observation to ProptechOS.
  • Actuator startedTime represents the time when ProptechOS received the first Actuation command response from an actuator.
  • Device startedTime is the earliest startedTime out of all the device’s Sensors and Actuators

Actuation payload data types

/actuator/{id}/actuation now supports all main data types in its payload:

  • string
  • number
  • boolean.

For example: both of the following requests are correct and acceptable:

{
  “targetInterface”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
  “payload”: “25”
}

And

{
  “targetInterface”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
  “payload”: 25
}

Inherited system members

Devices, Sensors and Actuators are now included in System collections by virtue of inheritance.

  • If Sensors have aliases that make them members of a system, their super devices (“parent devices”) also become members of the system (even if the Devices do not have aliases that explicitly qualifies them as members.).
  • Oppositely, if Devices have aliases that make them members of a system, their sub devices (“child devices”) Sensors and Actuators also become members of the system (even if the Sensors and Actuators do not have aliases that explicitly qualifies them as members.).

Improved Edge development with error notification

Incorrect Device-to-cloud edge messages (e.g. with formatting errors) result in a diagnostic notification being sent back to the originating device (result in a cloud-to-device message with notification of the error). In case of validation error of an observation, the notification device message will be sent back to the original device of the observation. This is a feature making it much easier to develop and troubleshoot RealEstateCore edge connectors. As long as the connector authenticates with the ProptechOS IoT Hub, then either the edge messages are correct, and can be seen in ProptechOS (UI, API or stream), or they are incorrect and the device will receive a notification message confirming the error (e.g. format validation error).

Breaking changes

GET RealEstateComponent includes the additional subclass Land

Although technically not necessarily breaking, this added feature can have a breaking effect for applications that have used the /realestatecomponent endpoint assuming that it will always return Buildings and nothing else. (hence, the default filtering, see below).

Land – is a subclass of RealEstateComponent. It is similar to Building by its functionality. The GET /realestatecomponent endpoints now return both Building(s) and Land(s).

  • GET /api/json/realestatecomponent
  • GET /api/json/realestatecomponent/{id}

Classes can be filtered using the query parameter `realestatecomponent_classes` – to return only Building , only Land or both (Building,Land).

NOTE: the default class filter is Building, meaning that if no value is provided,`Building` is taken as default).

The GET RealEstateComponent endpoint now accept the new query parameter `realestatecomponent_ids`.

Deprecated

The following will continue to be in effect/be supported at least throughout the year 2022 or until ProptechOS v4.0, whichever comes last.

  • RealEstateComponent endpoint query parameter `building_ids` is deprecated:
    GET /api/json/realestatecomponent?building_ids=
  • The default value (Building) of the realestatecomponent_classes parameter is deprecated.

Patch endpoint for BuildingComponent

The following endpoint to patch building component is deprecated

  • PATCH /api/json/buildingcomponent/{id}/class/{class}

With a new endpoint can be used instead

PATCH /api/json/buildingcomponent/{id}.

Fixes and minor updated

None