In this release

We introduce breaking changes for Device.

The relations

  • Device servedBy Device
  • Device servesDevice Device
  • Device servesBuildingComponent Building Component
  • Device servesBuilding Building

now supports many-to-many and is represented in the API as arrays of IDs instead of single IDs.

Space Collection is expanded with areaQuantities information.

New /restore endpoint is introduced that allows users to change the ‘Archived’ twin status to ‘Valid’.

Also it is now possible to retrieve actuator edge status similar to what was previously available only for sensors.

New functionality

 

Area Quantity for Space Collection(s)

Now a Space Collection can keep a list of area quantity items.

Area Quantity model:

{
    “type”: “BOA”,
    “value”: 250.0,
    “measurementUnit”: “https://w3id.org/rec/core/SquareMeter”
}

Where:

  • ‘type’ : is a string describing the area quantity type (e.g. Gross Area, Net Area, Leasable area, BOA, LOA, ATEMP, etc.)
  • ‘measurementUnit’ default value is m2 or “https://w3id.org/rec/core/SquareMeter”
  • Note: ‘measurementUnit’ should be a valid measurement unit IRI.

Area Quantity may be populated via the existing create or update endpoints:

  • POST /json/spacecollection
  • PUT /json/spacecollection

Example of full Space collection json:

{
  “propertyOwner”:“3fa85f64-5717-4562-b3fc-2c963f66afa6”,
  “areaQuantities”:[
    {
      “type”:“BOA“,
      “value”:200,
      “measurementUnit”:
      “https://w3id.org/rec/core/SquareMeter”
    }
  ],
  “status”:“Valid”,
  “littera”:“AA0011”,
  “createdByAgent”: null,
  “updatedByAgent”: null,
  “popularName”:“5MGzdWyZsoQ7eu0”,
  “comment”: {},
  “createdTime”: null,
  “updatedTime”: null,
  “hasAlias”: null,
  “locatedInBuildings”: [],
  “source”: {},
  “class”:“SpaceCollection”
}

Restore Twin endpoint

In case an agent has enough permission to conduct an update operation, then Restore action is allowed, meaning that a twin’s status changes (is restored) from ‘Archived’ to ‘Valid’.

The following endpoints are introduced:

  • PUT /json/realestate/{id}/restore
  • PUT /json/realestatecomponent/{id}/restore
  • PUT /json/buildingcomponent/{id}/restore
  • PUT /json/room/{id}/restore
  • PUT /json/storey/{id}/restore
  • PUT /json/asset/{id}/restore
  • PUT /json/device/{id}/restore
  • PUT /json/sensor/{id}/restore
  • PUT /json/actuator/{id}/restore
  • PUT /json/aliasnamespace/{id}/restore
  • PUT /json/collection/{id}/restore
  • PUT /json/apartment/{id}/restore
  • PUT /json/tenantunit/{id}/restore
  • PUT /json/region/{id}/restore
  • PUT /json/spacecollection/{id}/restore
  • PUT /json/system/{id}/restore

For example:

  • /json/room/c21b3128-779e-48f7-a33c-650b092fe044/restore

Actuator Edge Status

For the Actuators, a new endpoint is available. If the Actuator is of a read/write type, and it is able to receive actuations and send observations, now it is possible to get edge status. The logic and statistical model for determining the actuator edge status is the same as for sensor edge status.

  • GET /json/actuator/{id}/edgestatus

Request example:

  • /json/actuator/f1e60b09-746e-47cb-8d5a-07720f8a36bc/edgestatus

Response example:

{
 “actuatorId”: “f1e60b09-746e-47cb-8d5a-07720f8a36bc”,
“edgeStatus”: {
“code”: “OK”,
“message”: “Actuator is connected”
}
}

Global coordinates for Asset

Asset (and Asset subclasses including AccessControlPanel, AccessReader, Chair, Desk, Elevator, FireExtinguisher, Gate, Window, Door) has global coordinates via the new property hasGeoReferenceOrigo in addition to its local coordinates (isLocatedAtLocalCoordinates).

  • The property accepts three coordinates (latitude, longitude, altitude above sea level) separated with `;`.
  • The property is not mandatory.

Breaking changes

Device Serves and Served by Device

Device Serves Device(s) and Device Serves Space(s) (Building Component) will now be many-to-many.

Next Device (Sensor and Actuator) properties change their type from single UUID to array of UUIDs:

servedBy: [“37dc4979-7052-4a04-b3a8-72776fe312a1”]
servesDevice: [“ab11f614-43c9-4fde-a28c-8e09f98b484d”]
servesBuildingComponent: [“7d6746af-763c-494a-99e4-1092abdefa7d”]
servesBuilding: [“5099d86c-7c4c-4e5b-83e7-9b51c8e8dec8”]

List of affected endpoints :

PUT /json/devices

POST /json/devices

GET /json/device

PUT /json/device

POST /json/device

GET /json/device/{id}

PATCH /json/device/{id}

PUT /devices

POST /devices

GET /device

PUT /device

POST /device

GET /device/{id}

PUT /json/sensors

POST /json/sensors

GET /json/sensor

PUT /json/sensor

POST /json/sensor

GET /json/sensor/{id}

PATCH /json/sensor/{id}

PUT /sensors

POST /sensors

GET /sensor

PUT /sensor

POST /sensor

GET /sensor/{id}

PUT /json/actuators

POST /json/actuators

GET /json/actuator

PUT /json/actuator

POST /json/actuator

GET /json/actuator/{id}

PATCH /json/actuator/{id}

PUT /actuators

POST /actuators

GET /actuator

PUT /actuator

POST /json/actuator

GET /actuator/{id}

GET /system/{id}/includes

GET /json/system/{id}/includes

GET /collection/{id}/includes

GET /json/collection/{id}/includes – in case if collection includes devices, sensors and actuators

Be aware that if your application relies on those properties to be a single id, you will need to do adjustments in code!

Example of full Device object json:

{
  “id”: “b3e99007-d20b-4bae-be3b-d26f60ea74f8”,
  “status”: “Valid”,
  “createdTime”: null,
  “updatedTime”: null,
  “popularName”: null, 
  “createdByAgent”: null,
  “updatedByAgent”: null,
  “comment”: {},
  “source”: {},
  “class”: “Device”,
  “littera”: null,
  “startedTime”: null,
  “hasAlias”: [],
  “hasDeviceFunctionType”: null,
  “isMountedInBuildingComponent”:
  “d0a7cbe9-01e9-48d1-ab38-21e1ffab17b6”,
  “servesBuildingComponent”: [],
  “servesBuilding”: [],
  “servedBy”: [],
  “servesDevice”: [],
  “hasSuperDevice”: null,
  “hostedBy”: null,
  “hasGeoReferenceOrigo”: null,
  “hasSubDevice”: []
}

Fixes and minor updated

None.