This is an old revision of the document!
Identification
All programs communicate with each other by using JSON objects. The normal identification process is as follows:
pilight-daemon
through x.x.x.x:5000
pilight-daemon
waits for the client to identify himself.{ "message": "client sender" }
At this moment, the client can be a: sender
, receiver
, controller
, or gui
. The differences between the four will be explained later on.
pilight-daemon
will send the following JSON object:{ "message": "accept client" }
If the client was not accepted or until the client has not identified himself, the pilight-daemon
will send the following JSON object:
{ "message": "reject client" }
Sender
The pilight-daemon
expects the sender to send the codes of a specific protocol. A sender object can look like this (depending on the protocol used):
{ "message": "send", "protocol": "kaku_switch", "code": { "id": 1234, "unit": 0, "off": 1 } }
These are basically the command like arguments. If a argument requires a value, than the value is added to the argument. If the argument doesn't take a value, than it is defaulted to 1. The pilight-daemon
will check if the code was valid, but doesn't report back if it wasn't. The sender itself should thereby do the first error checking. The pilight-daemon
closes the connection to the sender once it has received a valid code to send.
Receiver
The receiver does nothing more than connecting to the pilight-daemon
, and receiving the same JSON objects that were sent by the sender. The only difference it that the receiver will receive JSON objects that notify if the messages were send or received. An example:
{ "origin": "receiver", "protocol": "kaku_switch", "code": { "id": 1234, "unit": 0, "off": 1 } } { "origin": "sender", "protocol": "kaku_switch", "code": { "id": 1234, "unit": 0, "off": 1 } }
The pilight-daemon
will keep the connection open to the receiver until either the daemon is stopped or the receiver is closed.
Controller
The controller has some additional commands it can send to the pilight-daemon
. The first one is:
{ "message": "request config" }
After this command, the pilight-daemon
will send the raw JSON config file in which all locations and devices are defined. This can help the controller to validate the sent codes.
(development version) Additionally the config can contain a version array. The first number in the array is the currently running version, the second number is the latest upstream version.
{ "config": { "living": { "name": "Living", "bookshelf": { "name": "Book Shelf Light", "protocol": ["kaku_switch"], "id": [{ "id": 1234, "unit": 0 }], "state": "off" }, "television": { "name": "Television", "protocol": ["relay"], "id": [{ "gpio": 3 }], "state": "off" } } }, "version": [ "2.0", "2.0" ] }
The goal of the controller is to send a specific location and device that needs to be controlled. Additionally, a state can be send or else the next value in the values array will be used. Again, the pilight-daemon
does error checking but doesn't report back if it failed. The controller should thereby check everything itself before sending codes. This is an example of the controller JSON object:
{ "message": "send", "code": { "location": "living", "device": "mainlight", "state": "on", "values": { "dimlevel": "10" } } }
The codes send by the controller should match the id's and not the names of the location and device. The pilight-daemon
closes the connection to the controller once it has received a valid code to send. The state
and values
object are optional.
GUI
The GUI behaves just like the controller except the GUI also receives messages. The connection to the GUI is thereby kept open. The received messages look like this:
{ "origin": "config", "devices": { "living": [ "tv", "main" ], "bedroom": [ "headlight"] }, "values": { "state": "on" } }
or
{ "origin": "config", "devices": { "garden": [ "weatherstation" ] }, "values": { "humidity": 800, "battery": 1, "temperature": 3100 } }
The pilight-daemon
will keep the connection open to the receiver until either the daemon is stopped or the receiver is closed. The webgui also acts like a normal gui however all communication is done on the webserver port. The rest is exactly the same.
Webserver
This feature is part of the development version of pilight
The webserver has two special pages.
The config
page will present the latest config json object.
The send
page can be used to control devices. To use this function call the send page with a send object url encoded like this:
send?%7B%0A%09%22message%22%3A%20%22send%22%2C%0A%09%22code%22%3A%20%7B%0A%09%09%22location%22%3A%20%22living%22%2C%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
This will send object as described under the controller.
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 send.
Buffer Sizes
The default buffer size pilight uses is 1024 bytes except in case of the config. The config will be send in 1024000 bytes. This leaves room for massive configurations. Remember that this config will be send as a response to the message request config.