User Tools

Site Tools


api

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

api [2014/09/21 13:09]
pilino1234 Removed "order" as said in forums, and fixed spelling
api [2015/11/27 21:09]
Line 1: Line 1:
-**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: 
-<code js> 
-{ 
- "​message":​ "​client sender"​ 
-} 
-</​code>​ 
-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: 
-<code js> 
-{ 
- "​message":​ "​accept client"​ 
-} 
-</​code>​ 
-If the client was not accepted or until the client has not identified himself, the ''​pilight-daemon''​ will send the following JSON object: 
-<code js> 
-{ 
- "​message":​ "​reject client"​ 
-} 
-</​code>​ 
-  * 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): 
-<code js> 
-{ 
- "​message":​ "​send",​ 
- "​protocol":​ "​kaku_switch",​ 
- "​code":​ { 
- "​id":​ 1234, 
- "​unit":​ 0, 
- "​off":​ 1 
- } 
-} 
-</​code>​ 
-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: 
-<code js> 
-{ 
- "​origin":​ "​receiver",​ 
- "​protocol":​ "​kaku_switch",​ 
- "​code":​ { 
- "​id":​ 1234, 
- "​unit":​ 0, 
- "​off":​ 1 
- } 
-} 
-{ 
- "​origin":​ "​sender",​ 
- "​protocol":​ "​kaku_switch",​ 
- "​code":​ { 
- "​id":​ 1234, 
- "​unit":​ 0, 
- "​off":​ 1 
- } 
-} 
-</​code>​ 
-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: 
-<code js> 
-{ 
- "​message":​ "​request config"​ 
-} 
-</​code>​ 
-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.// 
-<code js> 
-{ 
- "​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"​ ] 
-} 
-</​code>​ 
- 
-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: 
-<code js> 
-{ 
- "​message":​ "​send",​ 
- "​code":​ { 
- "​location":​ "​living",​ 
- "​device":​ "​mainlight",​ 
- "​state":​ "​on",​ 
- "​values":​ { 
- "​dimlevel":​ "​10"​ 
- } 
- } 
-} 
-</​code>​ 
-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: 
-<code js> 
-{ 
- "​origin":​ "​config",​ 
- "​devices":​ { 
- "​living":​ [ "​tv",​ "​main"​ ], 
- "​bedroom":​ [ "​headlight"​] 
- }, 
- "​values":​ { 
- "​state":​ "​on"​ 
- } 
-} 
-</​code>​ 
-or 
-<code js> 
-{ 
- "​origin":​ "​config",​ 
- "​devices":​ { 
- "​garden":​ [ "​weatherstation"​ ] 
- }, 
- "​values":​ { 
- "​humidity":​ 800, 
- "​battery":​ 1, 
- "​temperature":​ 3100 
- } 
-} 
-</​code>​ 
-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: 
-<​code>​ 
-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 
-</​code>​ 
-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//. 
api.txt ยท Last modified: 2015/11/27 21:09 (external edit)