Modules of the Weble building automation supervision are documented here.
The present documentation covers only the main API methods used to interface with internal or external applications.
The system by design is modular and extensible. Core modules methods can be used by internal and external applications in order to interface with the system.
The drivers are loaded dynamically by the core modules. Each driver runs in its own independent unix process.
Communication between the core modules, drivers, logic circuits, or the graphical user interface (browser) is managed by a P2P socket that permits
to remotely retrieve, call, and share API methods between trusted Javascript peers. Connections to the API can be done through websocket (socket.io), TCP socket, or unix file socket. Loading the API from an external web application can be done by sending an HTTP(S) login request as in the following example:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>LOADING API</title>
</head>
<body>
<script>
function apiLogin(host, username, password, callback){
var xhttp = new XMLHttpRequest();
xhttp.onreadystatechange = function() {
if (xhttp.readyState != 4) return;
if (xhttp.status == 200) {
var data = JSON.parse(xhttp.responseText);
eval(data.connect)(host,data,callback)
} else {
callback(this.status+' '+xhttp.responseText);
}
};
xhttp.open('POST', host + '/auth', true);
xhttp.setRequestHeader('Content-Type', 'application/json;charset=UTF-8');
xhttp.send(JSON.stringify({ username: username, password: md5(password) }));
};
apiLogin('http://ipAddress:8080','username','password',function(err, peers){
//if the login succeeded, loads system modules by name.
//load the gateways module, to read, write, and listen to values.
peers('supervision').require('gateways',function(err,gateways){
//here we retrieved the core/gateways module. The gateways object gives access to the gateways api.
gateways.writeValue('4/7/25', 1, function(err){ // write on the KNX bus a 1 for group address 4/7/5.
if(err){
console.error("KNX write failed", err)
}
})
})
//load loggers module to retrieve historical data from the timeseries database.
peers('supervision').require('loggers', function(err, loggers){
loggers.query({ // returns 15 minutes aggregates(min, max, and average) for KNX address 4/7/25
address : '4/7/25',
start : new Date(), // now,
end : new Date(new Date().setDate(new Date().getDate()-1)), //yesterday
aggregate : '15m'
}, function(err, row){
// is called multiple times. returns each rows.
// when the streaming ends, err 'end' is sent.
})
})
peers('supervision').isConnected() // checks if connected to supervision
peers.on('connect supervision', function(){ /*.. supervision is now connected ..*/})
peers.on('disconnect supervision', function(){ /*.. supervision is now disconnected ..*/})
//peers.destroy() => close the connection and remove all subscriptions.
})
</script>
</body>
</html>
Security Considerations
Besides the initial login, the API itself does not implement any form of secure authentication nore encryption. If the security is a concern, it should be deployed externally through VPN secure connections or another mecanism. The API communication relies heavily on the unsafe javascript "eval" function for the objects serialization/deserialization. It means that a bad boy could inject custom javascript code potentially corrupting and harming the whole system. There is also no protection against DOS (denial of service) attacks.