All programs communicate with each other by using JSON objects. The normal identification process is as follows:
Connect to pilight-daemon by using the pilight IP and port. The port pilight is running at is either a randomly chosen number or a fixed number as configured in the pilight settings.
The pilight-daemon waits for the client to identify itself by sending the following JSON object:
Additionally, a client can send certain options to tell the daemon what level of communication is the client want to set-up. A full identification JSON looks like this:
After each action, the daemon will send either one of the following two status responses indicating a success or failure:
The identification options define what communication is set-up between the daemon and the client.
When the receiver option is set, the daemon will forward the received or sent codes to the client. An example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | {
"origin": "receiver",
"protocol": "kaku_switch",
"code": {
"id": 1234,
"unit": 0,
"off": 1
}
}
{
"origin": "sender",
"protocol": "kaku_switch",
"code": {
"id": 1234,
"unit": 0,
"off": 1
}
}
|
In the received JSON messages, the origin will tell if an externally received message was received or a code sent by pilight self.
When the config option is set, the daemon will communicate all configuration updates. An example:
1 2 3 4 5 6 7 | {
"origin": "config",
"devices": [ "mainlight" ],
"values": {
"state": "on"
}
}
|
When the core option is set, the daemon will communicate pilight core information.
When the stats option is set, the daemon will communicate the RAM and CPU statistics.
1 2 3 4 5 6 7 8 9 | {
"origin": "core",
"values": {
"cpu": 0.07822473698105643,
"ram": 0.1535397936955158
},
"type": -1,
"uuid": "0000-d0-63-00-000000"
}
|
When the forward option is enabled, all incoming (valid) socket data will be forwarded to the client.
The uuid setting is meant for the client to send its unique UUID.
The media setting is used to tell the daemon what information is sent based on the specific media. As can be read in the GUI configuration, a user can create different GUIs based on different devices. The currently supported GUI types are all, web, mobile, and desktop. If you define your client as one of those GUI types, pilight will only send devices, GUI elements, config updates and rules that apply the specific GUI type, leaving the rest out. Therefore, you do not have to do any additional parsing on the client side.
These options can be updated on-the-fly while the client is running. The daemon will start or stop sending specific messages. To update these options, just send another identification request. An example identification object:
As we have seen in the identification process, pilight can handle several actions. The first action we encounter is the identification action. The following list contains all possible actions the daemon can handle. Again, the daemon will respond to all actions with a success and failure so the client can check if the action succeeded.
In case the client wants to send specific protocol codes, the send action is used. A sent action is accompanied by specific additional arguments:
1 2 3 4 5 6 7 8 9 | {
"action": "send",
"code": {
"protocol": [ "kaku_switch" ],
"id": 1234,
"unit": 0,
"off": 1
}
}
|
These are basically the command like arguments. If an argument requires a value, then the value is added to the argument (as with id and unit). If the argument does not take a value, than it is defaulted to 1 (as with off). The pilight-daemon will check if the code was valid, and report back with a failure if it was not.
The control action is used to control registered devices by using their device IDs. The pilight-daemon will check if the values are valid and report back with a failure if they are not. An example control object:
1 2 3 4 5 6 7 8 9 10 | {
"action": "control",
"code": {
"device": "mainlight",
"state": "on",
"values": {
"dimlevel": 10
}
}
}
|
The pilight registry can be managed by the registry API. The registry is a multi-purpose storage solution within pilight. Developers can store any information they want inside it so it is retrievable later on. The registry allows three types of actions: set, get, remove. The syntax for each on of them is:
1 2 3 4 5 6 | {
"action": "registry",
"type": "set",
"key": "pilight.version",
"value": "6.0"
}
|
1 2 3 4 5 | {
"action": "registry",
"type": "get",
"key": "pilight.version"
}
|
1 2 3 4 5 | {
"action": "registry",
"type": "remove",
"key": "pilight.version"
}
|
The response to a get command is as follows:
1 2 3 4 5 | {
"action": "registry",
"value": "6.0",
"key": "pilight.version"
}
|
Please note that the pilight registry can only hold JSON string and number types.
The request config is used to request the full configuration object from the pilight-daemon:
1 2 3 | {
"action": "request config"
}
|
After this command, the pilight-daemon will send the raw JSON configuration as it is used internally.
request values
pilight tries to make app development as easy as possible. This means that GUIs should only have to parse the GUI configuration object. The downside however is that the GUI object does not contain the device values. To solve this issue, the GUIs can request the values for all devices at once. The returned object will have the same information as the daemon communicates with the config option enabled, but now in bulk for all devices. An example:
Please be aware that right after the request values object, the pilight version object is sent. It is up to the GUIs to ignore or parse this information.
One special function of the pilight-daemon is the heartbeat. The heartbeat is meant to check if a connection is still alive. The client has to send a “HEARTn” on which the pilight-daemon will respond with a “BEATn”. This is the only exception in which not a JSON object is sent.
pilight will sends all streams in 1024 bits. If these streams are smaller than 1024 bits, everything was sent at once. If a stream is 1024 bits, then you will know it is a chunk of a bigger stream. In that case, read until you encounter the end of streams delimiter which is currently made up of two new lines “nn”.
If multiple streams were buffered somewhere, you can also distinguish them by the double new line delimiters. An example:
As you can see. pilight wanted to send three messages, but the TCP sockets concatenated them to one.
The pilight socket_read function takes care of these buffered messages to check if we encountered concatenated multiple streams. pilight will then convert these messages back so the output is just one big stream separated by single newlines: