Do COV subscriptions
The data item at e.g. http://192.168.1.69/bacnetws/.subs is a collection of all current subscriptions in the DINGO device. Subscriptions are generally created by clients and can be deleted either by the clients when they are no longer needed or by the server when they time out.
Values of BACnet properties can be read by polling values on regular intervals. A more sophisticated method, is to have the values pushed to the client, in the instant the value changes - this is what subscriptions can do.
The client can be a remote web-server that is hosting an HTTP-endpoint to deal with the incoming values. The HTTP-endpoint is a URI that will receive the callback POSTs from the subscription. This URI can be a remote web-server, Azure service etc., that will listen to HTTP POST requests from the DINGO device. These endpoints are also referred to as web-hooks and could look something like this: http://remote-server.com/endpoint
The client can also be a browser application, but this needs WebSockets instead of HTTP-endpoint.
A browser uses the GET method to do requests against the web services. To create, re-subscribe and delete subscriptions, one needs to use the POST, PUT and DELETE methods, respectively.
Fiddler can be used to do POST, PUT and DELETE requests, when experimenting with the subscriptions. All major development environments have components for doing HTTP requests (GET, POST, PUT and DELETE) - so read the documentation for your specific development environment.
When a subscription is created, a lifetime is specified. When that lifetime expires, the subscription is automatically deleted by the server. To prevent this, the client has to re-subscribe before the lifetime expires and thereby extend the lifetime of the subscription. We recommend resubscribing every half of the lifetime (lifetime / 2 seconds).
The maximum number of subscriptions in the DINGO-Stack is 2048. So creating 1 subscription in BACnet/WS with 2048 BACnet objects, accounts to 2048 subscriptions in the DINGO-Stack.
Also be aware of the limit that 1 subscription in BACnet/WS can only contain a maximum of 255 BACnet devices at the same time. If there is a need to subscribe to more than 255 devices, then do multiple BACnet/WS subscriptions (chunks) with max. 255 devices. We recommend however that you do not exceed 128 devices in each chunk (as other services can be using some of the 255 device-binding slots at the same time).
If you need to subscribe to more than one such 128 chunk a good practice is to wait maybe 5 seconds between chunks. The same wait-period apply to re-subscriptions and subscription cancellation.
Create subscription
Creating subscriptions is done with the POST method. Below is an example of a payload used to create a subscription.
The payload is a JSON object with this content:
- label: A name provided by the client
- callback: The HTTP-endpoint (URI, web-hook) that will receive the COV values via HTTP POST requests.
- lifetime: The time in seconds, that this subscription should be allowed to life. A good value would be 3600 seconds (1 hour). NB: To keep this substitution alive, we recommend you need to resubscribe every T/2 seconds - in this case every 30 minutes.
- covs: A list of BACnet objects, who’s present-value properties are watched for COVs (change-of-value).
{
"label": "My subscription",
"callback": "http://my-http-endpoint",
"lifetime": "3600",
"covs": {
"1": {
"path": "/.bacnet/.local/1000/analog-input,18",
"increment": "1"
}
}
}
When the subscription is created, the web service will reply with e.g.
Location: http://192.168.1.110/bacnetws/.subs/1
Where the number in the end of the message, is the identifier provided for the created subscription. This identifier is then used when resubscribing or deleting the subscription.
Visit WebSocket instead of HTTP-endpoint as alternative.
Re-subscribe
When a subscription has been created, it will be provided with an identifier, e.g. 1.
To re-subscribe and extend the lifetime of a current subscription, the PUT method is used. It is also enough to use the PLAIN format and provide a number in seconds for the new lifetime, in the payload.
So if the subscription lifetime was set to 3600 seconds (1 hour), then it is recommended to resubscribe every 30 minutes and put 3600 in the payload.
Delete subscription
When a subscription has been created, it will be provided with an identifier, e.g. 1.
To delete a current subscription, the DELETE method is used. No payload is used in this case.
Listing subscriptions
When listing all current subscriptions, use a URL similar to this: http://192.168.1.100/bacnetws/.subs?depth=1
The ?depth=1 in the end of the URL prevents listing all the COV specifications of the subscriptions. Showing all COV specifications can make the listing slower, if there are many subscriptions with many COV specifications. To see all COV specifications, simply remove the ?depth=1 from the URL.
To read a specific subscription, simply add the subscription-identifier to the URL. E.g. http://192.168.1.100/bacnetws/.subs/1?depth=1
As mentioned above the ?depth=1 will hide the COV specifications.
The lifetime in the listings, shows how many seconds are left before the subscription cancels. If you refresh the listing, then you will notice that the lifetime counts down. However a re-subscription will reset the lifetime and keep it alive.
Callback security
Clients (those that are creating the subscription) that require secure callback notifications can use an "https:" callback URI and then perform a TLS client certificate validation to ensure that the notification is from the expected source. This is currently not implemented in the DINGO-Stack.