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:

• Connect to pilight-daemon through x.x.x.x:5000
• The pilight-daemon waits for the client to identify himself.
• The client identifies himself by sending the following JSON object:

{
	"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.

• If the client is accepted, the 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"
}

• At this moment, the specific communication between client and server can take place.

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.