Berto Agent

The Berto Agent driver provides integration services to MQTT brokers, SMTP mail servers, IFTTT Webhooks and the Pushover messaging service. The driver also provides a REST interface that allows you to get and set variables for devices in your Control4 project and run Lua code to control devices or return information. The REST Interface can be used to trigger event type actions which can be called from the Apple Shortcuts app specifially using the ‘Get Contents of URL’ action.

The driver also allows use of the following proxy functions from other third party drivers :-

Properties

The Feature Management property provides access to the following additonal services :-

Core Configuration

These settings define the core configuration for the main repository used to download and install/update drivers. You can select Production or Beta which provides the standard Berto repositories or you can select Custom which allows you to define your own download repository.

The respository URL is the top level directory of the download server, the Drivers path defines where the C4Z files are located and the Plugins path provides a download path to custom code and configuration files used by the drivers. A username and password can also be set if needed.

Mail Server

By default the Berto mail server can be used to send email but you can also select Custom to define your own email server settings. When using Microsoft, Google etc. you will need to setup up Application passwords and enter the credentials here. Most SMTP services are supported including SMTP submission over TLS on port 587. You can also write you own drivers and access the SMTP proxy functions as defined above, see the Berto Mail driver which provides source code as an example of how to use the proxy functions

MQTT Brokers

You can define multiple MQTT brokers that are used by other Berto drivers. You can also write you own drivers and access the MQTT proxy functions as defined above, see the Berto MQTT driver which provides source code as an example of how to use the proxy functions. Messages received update Berto Agent MQTT variables whichg can be used under programming. A default broker named Localhost is automatically created and configured to work with the Mosquitto broker on the local controller if it is enabled in System Manager.

IFTTT Messaging

To integrate into the IFTTT Webhooks Service you need to connect your IFTTT account to the Webhooks service and obtain a key. IFTTT messages can be sent from programming.

Pushover Notifications

To integrate into the the Pushover messaging service you need to setup an account on Pushover and purchase the appropriate licences for the devices you intend to send and receive messages with. The licences are by device type and are a small one off cost only.

To send messages from your Control4 system you will also need to setup an Application Token. Messages received update Berto Agent Pushover variables which can be used under programming.

REST Interface

Enabling the REST ineterface provides you with the ability to get and set device varaibles and also run Lua code to either return information or control devices in your project. When enabled the REST service will start on the port specified, default 10080. You can GET and POST requests to you controller IP address on the port. Requests can be sent with a /get, /set, /run, /loc or /evt path to get, set variables, run Lua code, update a Berto Profile location or set an event name on the controller.

Requests can be sent to the REST service either directly to the IP address of the controller on the port specified or to https://live.berto.io or https://live.berto.io which in turn forwards the request to your system over a secure websocket connection. Authentication is provided by your REST Application Token being passed in the URL. The format of the URL is https://live.berto.io/rest/{command}?token={Token}. To send the same the request direct to the controller you need to use the IP address and port the REST Interface is listening on. eg. https://live.berto.io/rest/{command}?token={Token} is the same as http://{Controller IP}:{Port}/{command}?token={Token}. Requests not matching this URL are immediately closed and also any requests with a content length greater that 1024 bytes are shutdown. The Application Token can also be sent in the HTTP headers of the request. The Appplication Token defined in the REST Interface properties allows the /set, /get, /loc and /evt resources to be used. You can also set an Application Token in a Berto Profile which will also allow the /run resource to be used.

To set a variable use the /set suffix. eg. to set the value of the HTTP WEBWVENT variable on the Berto Agent driver to Hello World use curl 'http://192.168.0.200:10080/rest/set?token={Token}&name=WEBEVENT&value=Hello%20World’

The variable will be created with the prefix HTTP if it does not already exist. When seting the value of variables you create you do not need to specfiy the HTTP suffix.

To set the value of an existing variable belonging to another driver eg. to disable room announcements for room with id 22 using curl you send :-

curl 'http://192.168.0.200:10080/rest/set?token={Token}&id=22&name=ANNOUNCEMENT_DISABLED&value=1' or curl 'https://live.berto.io/rest/set?token={Token}&id=22&name=ANNOUNCEMENT_DISABLED&value=1'

To get the value of a variable use the /get suffix eg. get the the value of the HTTP WEBEVENT variable on the Berto Agent driver use curl 'http://192.168.0.200:10080/rest/get?token={Token}&name=HTTP%20WEBEVENT’

To get the value of an existing variable belonging to anotehr driver eg. to get the power state of a room with id 22 you using curl you send :-

curl 'http://192.168.0.200:10080/rest/get?token={Token}&id=22&name=POWER_STATE' or curl 'https://live.berto.io/rest/get?token={Token}&id=22&name=POWER_STATE'

The output is :-

0 or 1

To execute Lua code on the controller you send a curl request with a code as a parameter or in the body and the run command, either a GET or POST. eg. to get the project name you send :-

curl 'http://192.168.0.200:10080/rest/run?token={Token}&code=return%20C4:GetDeviceDisplayName(1)' or curl 'https://live.berto.io/rest/run?token={Token}&code=return%20C4:GetDeviceDisplayName(1)'

You can send the same code in a request with a body as follows :-

curl -d 'return C4:GetDeviceDisplayName(1)' 'http://192.168.0.200:10080/rest/run?token={Token}' or curl -d 'return C4:GetDeviceDisplayName(1)' 'https://live.berto.io/rest/run?token={Token}'

The Control4 API Reference Guide details all the available commands. Code can be written over muitple lines or encapsulated into a single file send sent via curl by sending :-

curl -d@code.lua 'http://192.168.0.200:10080/rest/run?token={Token}' eg. to get a list of all variable names on the Berto Agent driver, ie. where the REST server runs from, your code.lua file would be :-

local vars = {};
for i,v in pairs(C4:GetDeviceVariables(C4:GetDeviceID())) do
    vars[i] = v;
end;
return vars

Note the use of ; in certain places which are required as the code is turned into a single line when executed on the controller.

The REST Interface also accepts location updates for Berto Profile users setup. The format of the request is the same as that used by the OwnTracks service so you can install the OwnTracks app on your phone and configire it to update location status for your users directly into your system. You can also setup your own OwnTracks server, see the OwnTracks Booklet.

To update the location of Berto Profile user Fred for his iPhone using curl you can send :-

curl -d '{"_type":"location","tst":1642757350,"lon":-77.14699623221559,"lat":38.95130243861709,"topic":"owntracks/{System MAC}/Fred/iPhone"}' 'https://live.berto.io/rest/loc?token={Token}'

It is important the the DeviceId in the OwnTracks app is set to the Berto Profile name/Device name otherwise the message will not be matched against a Profile user. The URL should be set to https://live.berto.io/rest/loc?token={Token}.

These are the fields required by the Berto Agent to update a Berto Profile users location but the OwnTracks app will send more.

Vairables for the Berto Profile user are updated when location messages are received and events are fired when a user arrives or leaves home. The home location is based on the logitude and lattitude of the Control4 system.

HTTP reuqests can also be called from the Apple Shortcuts app using the ‘Get Contents of URL’ action. The ‘evt’ resource can be used to set the HTTP EVENT variable within the driver and then fire the HTTP_EVT_RECEIVED event. The ‘Get Contents of URL’ action lets you specifiy the Token as a header variable. eg. https://live.berto.io/rest/evt?name=OpenGates will set the HTTP EVENT variable to OpenGates and then fire the HTTP_EVT_RECEIVED event so from programming you can then action the event.

Driver Management

Driver Management allows the adding of Berto drivers and the renaming of any other installed device in the project.

Actions

Programming

Commands

Release Notes

v2.00 - 2024-01-01

Licence

DM