This page describes how to use the executable API demo available on https://schema.knx.org (with a DEMO button). It shows how a possible client (browser) may visualize ETS project data from a KNX installation using the KNX IoT 3rd Party API.

Versioning

The API demo is based on the (written) KNX IoT 3rd Party API specification 3/10/4 with version 1.0.0. The demo as such uses the same versioning as the electronic file (2.0.0) that is an additional part of the KNX IoT 3rd Party API specification.

The API demo as such is not versioned, it goes along with the above mentioned parts of the specification. Therefore it is recommended to clear your (Firefox, Chrome, ...) browser cache occasionally, this is reloading the most recent (improved/bug corrected) API demo. 

Feature List

Default Project

The API demo has a build in default project to start with. It contains of the following common concepts:

• buildings/floors/rooms
• functions
• datapoints

It is possible to upload own - previously semantically exported - ETS projects in the following formats:

• Turtle
• JSON-LD
• RDF/XML

See also clause Notes below.

Implemented

The following functionality is implemented in this API demo version.

Concepts

It is possible to display the following concepts of an ETS project:

• buildings
• datapoints
• installations
• equipment

The concepts can be selected in the API demo, tee view drop down selector. By default a similar view as the popular ETS building view is chosen.

Endpoints

For each concept from above it is possible to see the here involved API endpoints (at the top of right hand side list view).

• /locations (ETS buildings/floors, ...)
• /functions (ETS functions)
• /datapoints (KNX group addresses)
• /devices  (ETS devices)
• /installations (the ETS project as such)

Underneath of an endpoint an example of the here retrievable response payload content per item is shown, including:

• type and id of an item
• attributes, such as the name from a room or datapoint
• relationships, such as the relation from a datapoint to the function hosting the datapoint, when clicking this relation the related content is also shown underneath (if available)
• meta information, such as an additional item type (expressed as an OWL class identifier or URN from the KNX Information Model) or a link to an external description of this concept.

Open

The following functionality is not implemented in this API demo version.

• to connect the API demo project to a real (physical) installation, this will be possible ONLY in for the local environment, see clause Notes below
• a possibility to trigger a subscription (push notification) by simulating a predefined/ artificial change of a datapoint value
  
• to filter for specific elements of a collection with the defined filter criteria (such as all rooms in a location with the room usage kitchen)
• Only boolean types are supported to:
  • update an IoT Datapoint from the KNX System 
  • subscribe from Web Socket/ HTTP 
  • write values from the 3rd Party client (PUT) or from the Web Socket

Notes

To get the KNX IoT 3rd Party API (written) specification, the ETS App to semantically export an ETS project and/or the docker based image to test the API demo in a (real) local environment, please refer to this link.