This chapter describes the format of messages exchanged between the various LamPI components. In an asynchronous system like LamPI, sensors and users might generate messages all time and the system has to take action based upon these interrupts.
Between the parts of the LamPI system, several components exchange messages to inform the other of device changes, temperature values, initializations etc etc. This call for a standard message format that we can use between all components. This section describes the messages that are exchanged between the LamPI components. In the middle of all communication is the LamPI-node daemon, therefore we will discuss the messaging seen from the LamPI-daemon as it communicates with GUI's, sensors and other devices/programs.
The function socketHandler() in the LamPI-node.js file handles ALL incoming communication over the sockets (port 5001) and websockets (port 5002). From this function all other functions are called that deal specifically with sensors, GUI, database or other components.
The general message format in (semi-) JSON language is constructed as follows:
var buf = {
'tcnt' : $tcnt."",
'type' : 'raw',
'action' : "<some msg action>",
'field-1' : "<field-1 string>",
...
'field-n' => "<field-n string>"
};
The following functions are recognized by socketHandler(). Some actions do not have additional arguments, some do have additional information in the 'buf' field that is sent with the message. The buf.cmd parameter contains details of such sub command.
| buf.action | buf.cmd sub command | description |
|---|---|---|
| alarm | <none> | Print Alarm message. No specific alarm actions defined yet. |
| console | logs | Send back last xxxx lines in the PI-log file to the GUI |
| zlogs | <not yet used> | |
| sunrisesunset | Send back message with todays sunrise and sunset times | |
| Send back list of all clients connected (IP) and their port | ||
| rebootdaemon | Reboot the LamPI-node daemon | |
| printConfig | Send back the current configuration in the 'config' object | |
| dbase | add_room | Add a room record to the config['rooms'] array and store in 'rooms' database |
| delete_room | Delete a room from the 'config' object and from the mysql database | |
| add_scene | ||
| delete_scene | ||
| store_scene | ||
| add_timer | ||
| delete_timer | ||
| store_timer | ||
| add_handset | ||
| delete_handset | ||
| list_user | send back message with all known users in the database | |
| add_user | ||
| delete_user | ||
| store_user | ||
| add_sensor | ||
| delete_sensor | ||
| add_rule | ||
| store_rule | ||
| delete_rule | ||
| store_setting | Store config['settings'][i] value | |
| add_device | ||
| delete_device | ||
| store_device | ||
| backup_db | ||
| restore_db | ||
| energy | <none> | Only one smart meter device is defined at the moment. The buffer argument contains 10 parameters reported by the smart meter. If the meter is not yet present, we create it first. |
| graphs | energy | |
| sensors OR weather | ||
| gui | <none> | The guiHandler and icsHandler handle incoming device commands received from the user either through the GUI or through a handset message received. |
| handset | see gui handler | |
| login | <none> | When the connection is not trustued, the LamPI-node program asks for additional user credentials. Parameters are buf.login and buf.passwd. As part of the response to client the daemon sends the 'alert' command back as well |
| load_database | <none> | This command is VERY essential to the LamPI.js gui application. It sends the 'config' object to the requesting client upon starting the client page. |
| ping | <none> | This is a keep-alive message to make sure client and server both know that the otehr one is alive. In a mid-size configuration, ping messages are not necessary anymore since there will be multi commands per minute. |
| scene | The buf.message argument contains the name of the scene to run | |
| cancel_scene | Not yet used/implemented. Reserved. | |
| sensor | <none> | Handle incoming sensor messages. So update the config['sensors'] object. |
| store_config | Store the config database file. The buf.message parameter secifies the filename | |
| load_config | Load the config database text file specified by the buf.name argument | |
| Make a list of all configuration files in the ~/config directory and send back to the requesting GUI socket | ||
| user | <none> | Not used at the moment |
| weather | see Sensor | Weather has migrated to sensor (will be obsolete in one of the next releases). |
In the sections below the messages are explained in more detail.
Acknowledge message, telling connected clients that the LamPI-daemon as received its message OK.
var message = {
tcnt; // message transaction counter
type; // type of content part, eg raw or json
action == "ack";
}
Same as Alert message
var message = {
tcnt : |
<Integer number>, |
// Message or transaction counter |
|
type : |
"raw", |
// type of content part, eg raw or json |
|
action : |
"alert" |
|
}
The console message is used to receive and send messages to the GUI client that contain console/management - like information about the system. Messages are a result of user actions taken in the console section (subsetion of the config menu) in the GUI. Examples are: List connected clients to the LamPI-deamon, last 20 lines of the log/LamPI_daemon.log file and restarting the daemon itself.
var rcv = {
rcv.tcnt, // message transaction counter
rcv.type == 'raw' // type of content part, eg raw or json
rcv.action == 'console',
rec.request == 'code'
// One of the sub commands found below (logs, reboot etc.)
TBD
}
And the response to the requesting GUI is as follows:
var buf = {
rcv.tcnt, // message transaction counter
rcv.type = 'raw', // type of content part, eg raw or json
rcv.action = 'console',
rcv.request = '<same as your rcv.request code>',
rcv.list = "whatever response is appropriate for the command"
}
The subcommands used by the console action are as follows:
The log command gives webbrowser GUI users the possibility to see last 30 lines of the log file. Of course for debuggingit is better to log in on the master and use the 'tail -f ~/log/PI-node.log' command, but when logging on to the Raspberry LamPI master is no possible this command is the best alternative.
var buf = {
rcv.tcnt, // message transaction counter
rcv.type = 'raw', // type of content part, eg raw or json
rcv.action = 'console',
rcv.request = 'logs',
rcv.list = "last 30 lines of log file in html format"
}
Not yet implmented because Z-Wave is more difficult in its interface. Alternatively one can inspect the log file with the webbrowser through 'http://<Razberry IP>:8083' and use the Razberry interface to look at device states and log files.
Sometimes we like to check what today's timers for sunrise and sunset are. Especially the latter is used in the timer interface to start the lighting at a certain time interval before or after sunset.
var buf = {
rcv.tcnt, // message transaction counter
rcv.type = 'raw', // type of content part, eg raw or json
rcv.action = 'console',
rcv.request = 'sunrisesunset',
rcv.list = "<br>Sunrise: "+sunriseStr+" Hrs<br>Sunset: "+sunsetStr+" Hrs<br>"
}
// sunriseStr and sunsetStr are the string formats used to send back to the client
var buf = {
rcv.tcnt, // message transaction counter
rcv.type = 'raw', // type of content part, eg raw or json
rcv.action = 'console',
rcv.request = 'clients',
rcv.list = "<br>"+client.name+":"+client.type+"<br>"
}
// rcv.list may contain multiple of these arguments contining client name/IP and type websocket or socket.
//
Lines are separated by "<br>"
Reboot the LamPI-node.js daemon.
The configuration can be output using the webserver as follows: 'http://<Your IP>:8080/config'. This povides the best experience as the width of the outpu will scale as much as possible with the opn browser window. However, it is also quite good possible to to output back to the current LamPI session. However, take into accoun that sensor settings might be too much to fit in the window correctly.
The dbase command arranges load and store of objects to the config object and the database (for persistent storage). There are several sub commands involved, most are initiated by a client GUI by updating the value of a device by the user, or as a result of creating or deleting a new defnition in the GUI.
These database commands handle scene object database for actions that are taken by the GUI user.
This message is used to provide the GUI with a list of authorized user profiles. Used in the config -> users option.
The LamPI-daemon received PING messages from some of its connected clients to tell that they are still alive. This messaging might disappear in future releases of the software as during normal operations it does not add value. It does however for maintenance and debugging purposes.
var message = {
tcnt : |
<Integer number>, |
// Message or transaction counter |
|
type : |
"raw", |
// type of content part, eg raw or json |
|
action : |
"ping" |
|
}
var rcv = {
rcv.tcnt; // message transaction counter
rcv.type; // type of content part, eg raw or json
rcv.action = "energy";
TBD
}
Let's start with the messages between the GUI and the LamPI daemon. The GUI connects to the LamPI-daemon either through Ajax calls (Old way) or over a websocket connection. Wesbockets use the jSon message format and therefore a range of messages is used to get messages accross to the LamPI-daemon. The content of these messages are in the standard ICS-1000 message format which is a simple ASCII coding. However, since the LamPI system supports more devices than the ICS-1000 some additional messages are defined.
var message = {
rcv.tcnt; // message transaction counter
rcv.type == "raw"; // type of content part, eg raw or json
rcv.action == "gui";
rcv.message: STRING of ICS command. e.g. "!R3D2FdP16"
}
var message = {
rcv.tcnt; // message transaction counter
rcv.type == "json"; // type of content part, eg raw or json
rcv.action == "gui";
rcv.gaddr; // Group address of the receiver
rcv.uaddr; // Unit address of the receiver device
rcv.val; // Device value e.g. for switch On, Off and for dimmer 0-31
rcv.brand; // Brand of the receiver device
}
Handsets from klikaanklikuit, Action or other handsets that are defined and recognized can send information about buttons pressed to the LamPI-daemon process.
var rcv = {
rcv.tcnt; // message transaction counter
rcv.type: raw // type of content part, eg raw or json
rcv.action;
}
This message is used to tell the GUI that the LamPI-daemon does or does not trust the client, based on its IP address.
var rcv = {
tcnt: <integer value>, // message transaction counter
type: "raw", // type of content part, eg raw or json
action : "login",
message : "optional text message"
}
Messages received from the LamPI_receiver or any other sensor control program might contain the weather action, which will be interpreted by the LamPI_daemon and its values forwarded to the connected GUI clients.
var rcv = {
tcnt: , // message transaction counter
type: 'raw', // type of content part, eg raw or json
action: 'sensor',
address : ,
channel : ,
temperature: ,
humidity : ,
airpressure: ,
windspeed: ,
winddirection: ,
rainfall:
}
The individual settings as in config['settings'] can be updated. Settings can be updated local to the GUI session in the browser, and some can be stored in persistent storage.
Load the config file requested by the user (in the socket) and make sure that the current 'config' object is replaced by the JSON object found in the file.
List all config files in the config directory and send them to the requesting GUI client.
This is the message that will reset the Mysql database and re-load the ~/config/database.cfg file into the system
var rcv = {
tcnt: <integer value>, // message transaction counter
type: "json", // type of content part, eg raw or json
action : "load_database"
}
The Z-Wave messaging format is described on the separate Z-Wave page. Reason is that this is not so much a programming interface but communication takes place as a URL string that is executed by "curl" in the LamPI-daemon. At the moment the communication is therefore initiated by the LamPI-daemon only.
The Z-Way software contains Javascript library functions to build actions and initiate communication from the Razberry device but this is not implemented (yet), and therefore for example administrative functions for adding Z-Wave devices must be done using the Razberry interface on that machine itself.
http://<raspberry_ip_address>:8083
Then choose the traditional blue interface and then "network" to setup your new Z-Wave device.