Berto Web Server

The Berto Web Server driver provides a simple HTTP server that can serve requests to interrogate your system and also update variables to trigger events. The driver allows you to create a set of variables defined in properties which in turn can be set using simple GET requests. You can also run other C4 driverworks commands using using GET and POST requests which allow parameters to be specified. A request with no command specified will return all available commands that can be executed. With GET requests command parameters are passed on the URL line separated by & after the first ?. With POST requests parameters are passed on the body in JSON fomrat using the args field.

The Web Serever is started on port 10080 on the IP address of the controller and can be protected with a username and password but this is only using Basic HTTP authentication. The server is only available over HTTP and not secure HTTPS therefore should never be exposed outside you local network. Secure requests can be made by proxying the HTTP connections through an external web server such as Nginx or Apache. An installed IOT Hub has HTTPS proxying configured automatically. Requests can be made using GET and POST HTTP methods and results are returned in a JSON format.

When a request is received the request variables will be updated and a request event is fired. Requests can also be sent from programming and the response received will update response variables and fire a response event.

Examples.

• curl http://user:pass@192.168.1.200:10080 will return all available commands.
• curl http://user:pass@192.168.1.200:10080/GetUniqueMAC will return the MAC address of the main controller.
• curl -k https://user:pass@192.168.1.10/GetUniqueMAC will return the MAC address of the main controller using HTTPS via an installed IOT Hub or HTTPS Proxy.
• curl http://user:pass@192.168.1.200:10080/GetDeviceDisplayName?1 will return the device display name of device with Id 1, ie. the Project name.
• curl -d '{ “args”: 1 }' http://user:pass@192.168.1.200:10080/GetDeviceDisplayName is the same as the previous example but using POST method.
• curl -d '{ “args”: 1234, “SET_LEVEL”, “{ LEVEL = 100 }” }' http://user:pass@192.168.1.200:10080/SendToDevice will send the SET_LEVEL command to device 1234 setting the LEVEL to 100. Note that you will need to escape the " with a \ when using them inside the JSON body.

To update variables created in properties you can use the Set command eg.

• curl http://192.168.1.200:10080/Set?STATE=ON will set the STATE variable to ON.

The server will also accept Websocket client connections. Clients can connect to the controller IP address on any path that can then be used to send and receive data from within the driver under programming. The /echo path is a special path that provides an Echo back service to test websocket clients. The server does not send any keepalive pings therefore the client should be configured to send pings at the approproate interval. Testing can be done using a websocat eg.

• websocat --ping-interval 5 ws://user:pass@192.168.1.200:10080/echo - Connect to the Echo service with keepalives sent every 5 seconds.
• websocat --ping-interval 5 wss://user:pass@192.168.1.10/updates - Connect to /updates over HTTPS.

There is a limit of receiving 100 requests per day with the Basic subscription level.

Properties

• Username - Username required to authenticate.
• Password - Password required to authenticate.
• Text Variables - A list of text variables separated by commands that will be created to be used under programming.
• Number Variables - A list of number variables separated by commands that will be created to be used under programming.
• Boolean Variables - A list of boolean variables separated by commands that will be created to be used under programming.

Variables

• RECEIVED - Date and time of last request received.
• REQUEST METHOD - Request method received.
• REQUEST URL - Request URL received.
• REQUEST BODY - Request body received.
• RESPONSE CODE - Response code received when request sent from programming.
• RESPONSE BODY - Response body received when request sent from programming.

Release Notes

v1.00 - 2020-03-15

• Initial Release.

v1.10 - 2020-03-29

• Add Auto Update Time property to select preferred time of automatic updates for all Berto drivers.

v1.11 - 2020-04-17

• Added Console option to Debug Mode property to allow for external logging output.

v1.12 - 2020-06-15

• Fixed issue with passing parameters to commands and updated documentation.

Licence

DM