Danfoss offers an intelligent heating system. It includes various devices, for example a wireless thermostatic radiator head or the Danfoss Icon floor heating control.
These devices communicate via the Zigbee interface with the Danfoss Ally Gateway central unit, which is used to communicate with the Danfoss Cloud.
The Danfoss Ally mobile application is used to register devices (assign them to the user's e-mail address) and manually control them. For larger installations, the web portal https://allypro.northeurope.cloudapp.azure.com is available, where multiple sites can be created and several buildings (objects) in each site. Individual buildings can have several floors, and for each floor it is possible to define a floor plan and place individual devices, monitor their status and control them.
Well... but what if we want to read operational information from the D2000? And possibly also set the desired temperature and other parameters - manually, based on time channels or, in the case of a hotel, based on information about the arrival of a guest?
In this case, the Danfoss Ally API is available. Using HTTPS queries, it is possible to obtain current information about registered devices and also set required values.
Since it basically involves the processing of JSON messages received using the curl utility (in the case of controlling their generation and sending), we implemented the communication as an ESL script - if you are interested, it can be downloaded directly from our web.
In order to be able to access the devices, each user account to which Danfoss devices are assigned in the Danfoss Ally mobile application must be registered on the developer portal https://developer.danfoss.com. Subsequently, an "application" must be created under the account (called e.g. D2000) and the "Danfoss Ally API" interface must be added to it. The application is assigned a pair of keys "Consumer Key" and "Consumer Secret". These must be copied and the string Consumer Key:Consumer Secret must be created and converted to BASE64, e.g. using https://www.base64encode.org.
The resulting key must be saved in the structured variable SV.Danfoss_Credentials – D2000 therefore supports working with multiple user accounts. The key will be used by the D2000 to obtain a token from the Danfoss cloud (from https://api.danfoss.com/oauth2/token). The token is used for authorization when working with Danfoss devices that are assigned to a specific account. The token is currently valid for 1 hour, so before the token expires the D2000 must obtain a new token - again using the key.
Currently, the D2000 can work with three types of devices, each type is stored in its own structured variable:
- SV.Danfoss_Ally_Gateway - "Danfoss Ally™ Gateway" type devices
- SV.Danfoss_Ally_Radiator_Thermostat - "Danfoss Ally™ Radiator Thermostat" type devices
- SV.Danfoss_Icon_RT - "Icon RT" (Room Thermostat) type devices
- SV.Danfoss_Icon_Zigbee_Module - "Icon Zigbee Module" type devices
- SV.Danfoss_Zigbee_Repeater - "Danfoss Zigbee Repeater" type devices
These structures are automatically resized and filled with devices read from the Danfoss cloud.
After downloading the list of devices and their values (from https://api.danfoss.com/ally/devices), the E.Danfoss_Cloud script searches the SV.Danfoss_DeviceType structured variable for each device in the list. The above three structures are connected in it and it also contains device type identifiers.
The first column Device_type contains device types (identical to the JSON message), the second column Structure contains individual structures. The third column Transform describes transformations and value types. For example, the online item is Boolean, status.mode is Text, status.battery_percentage is a number multiplied by 1 (M1), status.temp_set is a number multiplied by 10 (M10). Additional transformations can be added as needed.
Thus, once the destination structure for a particular type of device is identified, it can be populated. Let's look at the JSON content for one device:
We see several items at the top level (id, name, device_type, online). These are common to all types of devices. However, the specific values are within the status field and are code - value pairs.
That's why we designed the parsing so that top-level JSON items correspond to structured variable columns with the same name (id, name, device_type, online) and specific JSON items to structured variable columns named status.<code>, e.g. status.switch, status.temp_set. By simply adding additional columns with the required syntax (e.g. status.fault) it is possible to achieve the processing of additional items.
After reading the item from the JSON message, it is then transformed (see the Transform field described above). In the case of Text, Boolean and Integer (M1) items, this is simple filtering (the value is assigned to the structure only if it has changed), in the case of M10, the value is divided by ten. Thermostats and other devices that are battery powered and optimized for low power consumption probably don’t use real numbers and represent all values as integers.
In the JSON message, you can also notice the text values of the value item, e.g. {"code":"mode","value":"manual"}
{"code":"SetpointChangeSource","value":"Schedule"}
For such items, in the future (when we get a specification of all possible values from Danfoss) we can create a new type of conversion mapping text values to a number (e.g. manual -> 0, auto -> 1).
If the structure does not contain a specific device, an empty row (a row with an empty id) is searched for and used. If an empty row is not found, the structure is resized (by 10 rows). This mechanism will be used mainly at the first launch and then exceptionally - when adding new devices or replacing them.
In order to avoid multiple resizes structured variables, we recommend changing the size of individual structured variables in advance according to the number of devices, possibly also with a margin.
In the first column of structured variables for individual device types (named idCred) is the row number of the SV.Danfoss_Credentials structure, i.e. it is clear to which user account the particular device belongs. This may be necessary for application reasons, but it is also necessary for control.
Control is implemented via the address https://api.danfoss.com/ally/devices/<device_id>/commands using a POST command that contains JSON text. An example is in the E.Danfoss_TestWrite script – setting the desired temperature for the first thermostat in the SV.Danfoss_Ally_Radiator_Thermostat structure.
See that the write is implemented by the CommandDevice RPC (remote procedure call) in the E.Danfoss_Cloud script. It can also be seen that the set value must be transformed (in the example, multiplied by ten). This functionality could be automated in the future (based on the Transform column of the SV.Danfoss_DeviceTypes structure).
Conclusion
The Danfoss Cloud communication protocol implemented as an ESL script is freely available for use in D2000. In the future, we anticipate its expansion and the addition of other types of equipment according to customer requirements. The E.Danfoss_Cloud script can also serve for study purposes - it contains examples of working with an external utility (curl), parsing JSON files and working with structured variables.
April 11, 2024, Ing. Peter Humaj, www.ipesoft.com
