Download source PDF Page last generated on 22:11, 27 November 2015 Github 
API
API......................................................................................................................................................................1
Identification...................................................................................................................................................1
Options...........................................................................................................................................................2
Actions...........................................................................................................................................................3
Webserver......................................................................................................................................................6
Heartbeat.......................................................................................................................................................6
Buffer Sizes...................................................................................................................................................7
Identification
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:
1 {
2 "action": "identify"
3 }
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:
1 {
2 "action": "identify",
3 "options": {
4 "core": 1,
5 "receiver": 1,
6 "config": 1,
7 "forward": 0
8 },
9 "uuid": "0000-d0-63-00-000000",
10 "media": "all"
11 }
After each action, the daemon will send either one of the following two status responses indicating a
success or failure:
1 {
2 "status": "success"
3 }
1 {
2 "status": "failure"
3 }
Options
The identification options define what communication is set-up between the daemon and the client.
receiver
When the receiver option is set, the daemon will forward the received or sent codes to the client. An
example:
1 {
2 "origin": "receiver",
3 "protocol": "kaku_switch",
4 "code": {
5 "id": 1234,
6 "unit": 0,
7 "off": 1
8 }
9 }
10 {
11 "origin": "sender",
12 "protocol": "kaku_switch",
13 "code": {
14 "id": 1234,
15 "unit": 0,
16 "off": 1
17 }
18 }
In the received JSON messages, the origin will tell if an externally received message was received
or a code sent by pilight self.
config
When the config option is set, the daemon will communicate all configuration updates. An example:
1 {
2 "origin": "config",
3 "devices": [ "mainlight" ],
4 "values": {
5 "state": "on"
6 }
7 }
core
When the core option is set, the daemon will communicate pilight core information.
stats
When the stats option is set, the daemon will communicate the RAM and CPU statistics.
1 {
2 "origin": "core",
3 "values": {
4 "cpu": 0.07822473698105643,
5 "ram": 0.1535397936955158
6 },
7 "type": -1,
8 "uuid": "0000-d0-63-00-000000"
9 }
forward
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:
1 {
2 "action": "identify",
3 "options": {
4 "stats": 1,
5 "receiver": 1
6 },
7 "uuid": "0000-d0-63-00-000000"
8 }
Actions
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.
send
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 "action": "send",
3 "code": {
4 "protocol": [ "kaku_switch" ],
5 "id": 1234,
6 "unit": 0,
7 "off": 1
8 }
9 }
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.
control
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 "action": "control",
3 "code": {
4 "device": "mainlight",
5 "state": "on",
6 "values": {
7 "dimlevel": 10
8 }
9 }
10 }
registry
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 "action": "registry",
3 "type": "set",
4 "key": "pilight.version",
5 "value": "6.0"
6 }
1 {
2 "action": "registry",
3 "type": "get",
4 "key": "pilight.version"
5 }
1 {
2 "action": "registry",
3 "type": "remove",
4 "key": "pilight.version"
5 }
The response to a get command is as follows:
1 {
2 "action": "registry",
3 "value": "6.0",
4 "key": "pilight.version"
5 }
Please note that the pilight registry can only hold JSON string and number types.
request config
The request config is used to request the full configuration object from the pilight-daemon:
1 {
2 "action": "request config"
3 }
After this command, the pilight-daemon will send the raw JSON configuration as it is used internally.
1 {
2 "devices": {
3 "tv": {
4 "uuid": "0000-00-00-07-646b93",
5 "origin": "0000-d0-63-00-000000",
6 "timestamp": 0,
7 "protocol": [ "relay" ],
8 "id": [{
9 "gpio": 3
10 }],
11 "state": "off",
12 "default": "off"
13 }
14 },
15 "rules": {
16 "tvswitch": {
17 "rule": "IF tv.state IS on THEN switch DEVICE tv TO off",
18 "active": 1
19 }
20 },
21 "gui": {
22 "television": {
23 "type": 4,
24 "order": 1,
25 "name": "tv",
26 "group": [ "Living" ],
27 "media": [ "all" ],
28 "readonly": 0
29 }
30 },
31 "settings": {
32 "log-level": 4,
33 "pid-file": "/var/run/pilight.pid",
34 "log-file": "/var/log/pilight.log",
35 "webserver-enable": 1,
36 "webserver-http-port": 5001,
37 "webserver-cache": 0,
38 "webserver-root": "/usr/local/share/pilight"
39 },
40 "hardware": {
41 "433gpio": {
42 "sender": 0,
43 "receiver": 1
44 }
45 },
46 "registry": {
47 "pilight": {
48 "version": {
49 "current": "6.0"
50 }
51 }
52 }
53 }
request values
1 {
2 "action": "request values"
3 }
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:
1 [{
2 "type": 4,
3 "devices": [ "tv" ],
4 "values": {
5 "timestamp": 0,
6 "state": "off"
7 }
8 },
9 {
10 "type": 1,
11 "devices": [ "bookShelfLight" ],
12 "values": {
13 "timestamp": 0,
14 "state": "off"
15 }
16 }]
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.
Webserver
The webserver has some special pages:
The config page will present the latest configuration JSON object.
The values page will present the latest values of all device.
The send page can be used to control devices. To use this function, call the send page with a URL-
encoded “send” or “registry” JSON object like this:
This will send the object as described earlier.
The values and config page will by default only show the configuration that applies to a web GUI type. To
retrieve the configuration relevant for other GUI types, use the media argument:
Heartbeat
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 "HEART\n" on which the pilight-daemon will respond with a
"BEAT\n". This is the only exception in which not a JSON object is sent.
send%3F%7B%0A%09%22action%22%3A%20%22control%22%2C%0A%09%22code%22%3A%20%7B%0A
%09%09%22device%22%3A%20%22mainlight%22%2C%0A%09%09%22state%22%3A%20%22on%22%2C%0A
%09%09%22values%22%3A%20%7B%0A%09%09%09%22dimlevel%22%3A%20%2210%22%0A%09%09%7D%0A
%09%7D%0A%7D
http://x.x.x.x:5001/config?media=all
Buffer Sizes
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 "\n\n".
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:
{"message":"test"}\n\n
{"message":"test"}\n\n
{"message":"test"}\n\n
{"message":"test"}\n
{"message":"test"}\n
{"message":"test"}\n
Top