DIVUS VISION API Software User Manual

DIVUS VISION API Software

Specifications

• Product: DIVUS VISION API
• Manufacturer: DIVUS GmbH
• Version: 1.00 REV0 1 – 20240528
• Location: Pillhof 51, Eppan (BZ), Italy

Product Information

The DIVUS VISION API is a software tool designed for interfacing with DIVUS VISION systems. It allows users to access and control various elements within the system using MQTT protocols.

FAQ

Q: Can I use the DIVUS VISION API without prior knowledge of PC or automation technology?

A: The manual is tailored for users with previous knowledge in these areas to ensure efficient usage of the API.

GENERAL INFORMATION

• DIVUS GmbH Pillhof 51 I-39057 Eppan (BZ) – Italy

Operating instructions, manuals and software are protected by copyright. All rights reserved. Copying, duplicating, translating, translating in whole or in part is not permitted. An exception applies to the creation of a backup copy of the software for personal use.
The manual is subject to change without notice. We cannot guarantee that the data contained in this document and on the storage media supplied are free of errors and correct. Suggestions for improvements as well as hints on errors are always welcome. The agreements also apply to the specific annexes to this manual. The designations in this document may be trademarks whose use by third parties for their own purposes may infringe the rights of their owners. User instructions: Please read this manual before using it for the first time and keep it in a safe place for future reference. Target group: The manual is written for users with previous knowledge of PC and automation technology.

PRESENTATION CONVENTIONS

Introduction

GENERAL INTRODUCTION

This manual describes the VISION API (Application Programming Interface) – an interface through which VISION can be addressed and controlled from external systems.
In practical terms, this means that you can use systems such as

• MQTT Explorer (https://www.microsoft.com/store/… – for testing),
• Home Assistant (https://www.home-assistant.io/) or
• Node-RED (https://nodered.org/)

to control the elements managed by VISION or read out their status. Access and communication take place via the MQTT protocol, which uses so-called topics to address individual functions or sets of functions or to be informed about changes to them. An MQTT server (broker) is used for this purpose, which handles security and the management/distribution of messages to the participants. In this case, the MQTT server is located directly on the DIVUS KNX IQ and is specially configured for this purpose. Although the VISION API can also be used without programming knowledge, this functionality is suitable for advanced users.

PREREQUISITES

As explained in the VISION manual, the API user must by default first be activated in order to be able to use it the API access only works using the Api users authentication data. As far as the user rights are concerned, the activation for this functionality can then be configured either on all or on individual elements. See Chap.0. Of course, you also need a VISION project in which the elements that you want to control from outside are fully configured and the connection to them has been successfully tested. To be able to address individual elements via the API, their element ID must beknown: this is displayed at the bottom of the element’s settings form

SECURITY

For security reasons, API access is only possible locally (i.e. not via the cloud). The security risk when activating API access is therefore low. Nevertheless, security-relevant elements should not be enabled or explicitly denied for API access.

MQTT AND ITS TERMS – BRIEF EXPLANATION

• In MQTT, the role of centralised management and distribution of all messages is that of the broker. Although MQTT server and MQTT broker are not synonyms (server is a broader term for a role that MQTT clients can also play), the broker is always meant in this manual when MQTT server is mentioned. The DIVUS KNX IQ itself plays the MQTT broker / MQTT server role in the context of this manual.
• An MQTT server uses so-called topics: a hierarchical structure with which data is categorised, managed and published.
• Publishing has the primary goal of making data available to other participants through topics. If you want to change a value, you write to the desired topic together with the desired value change, also using a publishing action. The target device or the MQTT server reads the desired change that affects it and adopts it accordingly. To check that the change has been applied, you can look in the subscribed real-time topic to see whether the change is reflected there – if everything has worked out fine.
• Clients select the topics that interest them: this is called subscribing. Every time a value changes in/below a topic, all subscribed clients are informed – i.e. without having to explicitly ask whether something has changed or what the current value is.
• You can open (or address) a separate communication channel with the MQTT server by entering any unique string called client_id in a topic. The client_id must be used in the topic to process values. This serves to identify the origin of each change, helps with any errors and does not affect the other clients, as the corresponding responses from the server, including any error codes and messages, also only reach the topic with the same client_id (and thus only that client). The clientid is a unique character string consisting of any combination of the characters 0-9, a-z, A-Z, “-“, “”.
• In general, the subscribe topics of the MQTT server of the DIVUS KNX IQ contain the keyword status, while the publish topics contain the keyword request. Those with status are automatically updated as soon as there is an external value change or as soon as a value change has been requested by the client itself via a publish and has been successfully applied. Those for publishing are further divided into those of type (request/)get and those of type (request/)set.
• Value changes and other optional parameters are added to the topic with the so-called payload. The parameters of the individual elements (element-id, name, type, functions)

The main difference between MQTT and the classic client-server model, where the client requests and then changes data, is centred on the concepts of subscribe and publish. Participants may publish data, making it available to others, who if interested may subscribe to it. This architecture makes it possible to minimise data exchange and still keep all interested parties up to date. More about the details here: and special parameters (uuid, filters) are to be used here. Although there are several options, the payload is shown formatted as JSON in this manual. JSON uses brackets and commas to represent data of any structure and thus minimises the size of the data packets to be transmitted. More details about payloads can be found later in the manual.

• For special purposes, it is possible to filter according to the type of function, e.g. to address only on/off i.e. 1-bit switches. The filters parameter in the payload is used for this purpose. Filtering is currently only possible by function type.
• To be able to address individual elements, their element ID is required. This can be found in VISION in the element properties menu or can also be read directly from the data that is displayed in front of each available element in the general subscribe of the MQTT Explorer (elements there are listed alphabetically by element ID).

Configuration for the API access

CONFIGURING VISION FOR API USER ACCESS

In VISION as an administrator, go to Configuration – User/API Access Management, click on Users/API access and right-click on API User (or press and hold) to open the editing window. There you will find these parameters and data

• Enable (checkbox)
  • The user is first enabled here. Default is disabled
• Username
  • This string is required for access via API – copy it from here
• Password
  • This string is required for access via API – copy it from here
• Permissions
  • The default rights for reading and writing the values of the VISION elements can be defined here, i.e. what is defined here applies to all existing and future elements. If you only want to allow access to individual elements, you should not change these default rights

PERMISSIONS ON INDIVIDUAL ELEMENTS

It is recommended that you do not grant API access to the entire project, but only to the desired elements. Proceed as follows

1. log in to VISION as an administrator
2. select the desired element and open its settings menu (right-click or keep pressed, then Settings)
3. under the menu entry General – Permissions, activate “Override default permissions” and then go to the sub-item Permissions, which shows the permissions matrix.
4. activate the control permission here, which also enables the view permission directly. If you only want to read data via the API access, it is sufficient to enable the view permission.
5. repeat the same procedure for all the elements you want to access

Connection via MQTT

INTRODUCTION

As an example, we will demonstrate access via the MQTT API of the DIVUS KNX IQ with a relatively simple, free software called MQTT Explorer (see chap. 1.1), which is available for Windows, Mac and Linux. A basic knowledge and experience with MQTT is implied.

DATA REQUIRED FOR THE CONNECTION

As mentioned earlier (see section 2.1), the username and password of the API user are required. Here is an overview of all the data that must be collected before a connection is established:

• Username Read out on the detail page of the API user
• Password Read out on the detail page of the API user
• IP address Read out in the launcher settings under General – Network – Ethernet (or via Synchronizer)
• Port 8884 (this port is reserved for this purpose)

FIRST CONNECTION WITH MQTT EXPLORER AND GENERAL SUBSCRIBE

Normally, MQTT distinguishes between the activities subscribe and publish. MQTT Explorer simplifies this by automatically subscribing to all available topics (topic #) when the first connection is made. As a result, the tree that leads to all available elements (i.e. API user access granted) can be seen directly in the left-hand area of the MQTT Explorer window after a successful connection. To enter further subscribe topics or to replace the # with a more specific topic, go to Advanced in the connection window. The topic shown on the upper right looks something like this:

where 7f4x0607849x444xxx256573x3x9x983 is the API username and objects_list contains all the available elements.This topic is always kept up to date i.e. any value changes are reflected there in real-time. If you only want to subscribe to individual elements, enter the element ID of the desired element after objects_list/.

Note: This type of subscribe roughly corresponds to the logic behind the KNX feedback addresses; it shows the current status of the elements and may be used to check whether the desired changes have been successfully applied. If you only want to read out data but not change it, this type of subscribe is sufficient .

A single simple element looks something like this in JSON notation

Note: All values have the syntax shown above e.g. { “value”: “1” } as the output of the subscribe topics, while the value is written directly in the payload to change a value (i.e. for publish topics) – the brackets and “value” are omitted e.g. “onoff”: “1”.

Advanced commands

INTRODUCTION

There are 3 kinds of topics in general:

1. Subscribe topic(s) to see the available elements and to get real-time value changes
2. Subscribe topic(s) to get the answers to ( the clients ) publish requests
3. Publish topic(s) to get or to set elements with their values

We shall later refer to these kinds using the numbering shown here (e.g. topics of type 1, 2, 3). More details in the following sections and in chap. 4.2.

SUBSCRIBE TOPICS TO SEE THE AVAILABLE ELEMENTS AND TO GET REAL-TIME VALUE CHANGES

These have already been described

SUBSCRIBE TOPICS TO GET THE ANSWERS TO THE CLIENT’S PUBLISH REQUESTS

This kind of topics is optional. It allows to

• open a unique communication channel with the MQTT server by using an arbitrary client_id. More about that in chap. 4.2.2
• get the result of publish requests on the corresponding subscribe topic: success or failure with error code and message.

There are different topics to get answers to get or to set publish commands. The corresponding difference in Once you get the needed topics for your system straight, you may decide to remove this step and directly use publish topics.

PUBLISH TOPICS TO GET OR TO SET ELEMENTS WITH THEIR VALUES

These topics use a path similar to the ones for subscribing – the only change is the word “request” in place of the “status” used to subscribe. Complete topic paths are shown later in chap. 4.2.2\ A get topic will request to read the MQTT server’s elements and values. The payload may be used to filter based on the function type of the elements. A set topic will request to change some parts of an element, as detailed in its payload.

PREFIX FOR COMMANDS AND CORRESPONDING RESPONSES

SHORT EXPLANATION

All commands that are sent to the MQTT server have a common initial part, namely:

DETAILED EXPLANATION

The real-time topics (type 1) will have the general prefix (see above) then followed by

or

For set commands, the payload obviously plays the main role as it will contain the desired changes (i.e. changed values for the element’s functions). A Warning: Never use the retain option in your type 3 commands as it may cause issues on the KNX side.

EXAMPLE: PUBLISH FOR CHANGING A SINGLE ELEMENT’S VALUE(S)

The simplest case is to want to change the value of one of the elements shown by the general subscribe .
Generally speaking, changing/switching a function of VISION via MQTT consists of 3 steps, not all of which areabsolutely necessary, but we nevertheless recommend carrying them out as described.

1. The topic that contains the function we want to edit is subscribed using a custom client_id
2. The topic for editing is published together with the payload with the desired changes using the client_id chosen in 1.
3. To check, you can then see the answer in topic (1.) – i.e. whether (2.) worked or not
4. In the general subscribe, where all values are updated when changes are made, you can see the desired value change(s) if everything has worked out fine.

The steps to do this are:

1. select a client_id e.g. “Divus” and insert it in the path after the API username
   This is the complete topic for subscribing to your own communication channel with the MQTT server. This tells the server where you expect the responses to the changes you intend to send. Notice the status/set part which defines a. that it is a subscribe topic and b. that it will get the answers to set type commands.

2. The publish topic will be the same except for switching the status-request keywords

3. what the change should consist of is written in the payload. Here are some examples.

   • Switching off an element that has the on/off function (1 bit):
   • Switching on an element that has the on/off function (1 bit). In addition, if several such commands are started from the same client, the uuid parameter (“unique ID”, is usually a 128-bit string formatted as 8-4-4-4-12 digits hex) can be used to assign the response to the corresponding query, as this parameter – if present in the query – can also be found in the response.
   • Switching on and setting the brightness of a dimmer to 50%
   • The answer to the topic shown and subscribed to above (its payload, to be precise) is then, for example.
     The above response is an example in the case of a correct payload, although the element has no dimming function. If there are more serious problems leading the payload not to be interpreted correctly, the response will look like this (e.g.):
     for an explanation of the error codes and messages but in general, like for http, 200 codes are positive answers while 400 are negative.

EXAMPLE: PUBLISH FOR CHANGING MULTIPLE ELEMENTS VALUES

The procedure is similar to the one shown before to change a single element. The difference is that you omit the element_id from the topics and then indicate the set of element_ids in front of the data inside the payload. See the syntax and structure below.

FILTER BY FUNCTION TYPE IN QUERIES

The filters parameter in the payload allows only the desired function(s) of an element to be addressed. The on/off function of a switch or dimmer is called “onoff”, for example, and the corresponding filter is defined in this way :

The answer then looks like this, for example

The square bracket indicates that you can also filter by several functions, e.g.

leads to an answer like this:

Appendix

ERROR CODES

Errors in MQTT communication result in a numerical code. The following table helps to break it down.

PARAMETERS OF THE PAYLOAD

The payload supports different parameters depending on the context. The following table shows which parameters can occur in which topics

VERSION NOTES

• VERSION 1.00

News:

• First publication

References

• Node-RED
• Home Assistant
• MQTT-Explorer - Official app in the Microsoft Store

Read User Manual Online (PDF format)

Download This Manual (PDF format)

Download this manual  >>