All communications should be done over HTTP/1.1 so as to allow for keepalive.
According to ISO 8601, plus microseconds, see examples:
Lamps (devices) are addressed using (cabinet id, device id) pairs:
GET /CID/DID/... PUT /
Where:
All keywords (apart from “all”) can be added in the future. Everything that is not one of the reserved keywords is treated as a cabinet ID or lamp ID, respectively.
For a single device:
GET /34/44/...
For a range of device IDs:
GET /34/10-13/...
For a set of device IDs:
GET /34/4,6,13/...
Change lamp parameters:
PUT /
with the following request data:
{
"data": [
{ "cid": 34, "did": 1, "params": [ { "k" : "dimming", "v": 50 }, {"k": "state", "v": "on",} ] },
{ "cid": 34, "did": 5, "params": [ {"k": "state", "v": "off"} ]}
]
}
That will set:
Returns confirmation that particular parameters are set with additional timestamp:
{
"timestamp": "2014-03-25T14:03:22.547342Z",
"data": [
{ "cid": 34, "did": 10, "params": [ {"k": "state", "v": "on" } ] },
...
]
}
If the parameter cannot be changed, or if it is nonexistant a null value is returned:
Request:
{"data":[{"cid":1, "did": 25, "params":[ { "k":"detecdted", "v":"false"}, { "k":"detected", "v":"false"}]}]}
Reply:
{
"timestamp":"2014-05-30T21:37:39.088752+0200",
"data": [
{
"cid":1,
"did":25,
"params": [ {"k":"detecdted", "v":null}, {"k":"detected", "v":"false"} ]
}
]
}
GET /CID/DID/state
Returns:
{
"timestamp": "2014-03-25T14:03.547Z",
"data": [
{ "cid": 34, "did": 10, "params": [ {"k": "state", "v": "on" } ] },
...
]
}
GET /CID/DID/dimming
Returns:
{
"timestamp": "2014-03-25T14:03.547Z",
"data": [
{ "cid": 34, "did": 10, "params": [ {"k": "dimming", "v": 50 } ] },
...
]
}
GET /CID/DID/state,dimming
Returns:
{
"timestamp": "2014-03-25T14:03.547Z",
"data": [
{ "cid": 34, "did": 10, "params": [ {"k": "state", "v": "on" }, {"k": "dimming", "v": 50 } ] },
...
]
}
GET /CID/DID/all
Returns:
{
timestamp: "2014-03-25T14:03.547Z",
data: [
{ "cid": 34, "did": 10, "params": [ { "k": "state", "v": "on" }, ... ] },
...
]
}
This is done by specifying the lasttimestamp GET parameter, which contains the last known timestamp of an update:
GET /34/all/state?lasttimestamp=2014-03-25T14:03:18.547989+0100
If something has changed from that timestamp, the response will be issued immediately with the current data.
If nothing has changed, the connection will hang until an update of any queried parameters occurs.
In case of nonexistant CID, DID or parameters a null is returned as parameter value
Assuming that foo does not exist the following request:
1/9/status,foo
results in:
{
"timestamp":"2014-09-17T11:31:29.804738+0200",
"data": [
{
"cid":1,
"did":9,
"params": [ {"k":"status", "v":0.0}, {"k":"foo", "v":null} ]
}
]
}
GET /log/CID/DID
No response is given initially; connection is kept alive and every time any log entries appear, an object containing a single array object called log data, which in turn contains log entries, is supplied
{
"logdata": [
{ json obj }
]
}
GET /log/CID/DID?fromtimestamp=XXXXXXX
Response:
{
"lastknowntimestamp": XXXXXXX
"logdata": [
{ json obj },
{ json obj },
...
{ json obj }
]
}
connection is then kept alive and every time any new log entries appear, an object containing a single array object called log data, which in turn contains log entries, is supplied
{
"logdata": [
{ json obj }
]
}
GET /log/CID/DID?fromtimestamp=XXXXXXX&totimestamp=YYYYYYY
Response:
{
"lastknowntimestamp": XXXXXXX
"logdata": [
{ json obj },
{ json obj },
...
{ json obj }
]
}
connection is then closed.
Assumming that there is a GET request: http://192.168.20.1/2/3/state,
json obj in the above statements is structured as:
{
"timestamp": TTTTT,
"who": "192.168.20.1",
"type": "request",
"method": "GET",
"origin": "192.168.20.2",
"target": "192.168.20.1",
"cid": 2,
"did": 3,
"resource": "state",
"payload": null
}
where
payload contains complete data sent as the payload (content of the request or reply),type=request | response,method=PUT | GET.Main goal:
GET /info
Response:
[
{
"type": "d",
"class": "dark",
"idx": 1,
"attributes": [
{"key": "detected", "communication": "ro", "type": "atom", "values": [ "true", "false", "unknown" ]},
{"key": "control", "communication": "rw", "type": "numeric", "ranges": [ {"from": 0, to: 10, "precision": 0.1 } ] }
]
"cid": 1,
"did": 22,
"coordinates": { "lat": 45.7811111, "lon": -108.5038888, "alt": 12.223112 }
},
...
]
where attributes object consists of:
key - attribute name, communication - defines if the attribute can be read or written, available values: ro (read only), rw (read/write), wo (write only),type - data type, available values: atom (arbitrary symbol), numeric, values - an array of acceptable values,range - an array of acceptable ranges indicated with from, to and precision.A complete example:
[
{
"type":"d",
"class":"done",
"idx":1,
"attributes": [
{
"key":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
],
"cid":1,
"did":1,
"coordinates": {"lon":19.972399, "lat":50.066368, "alt":0.0}
},
{
"type":"d",
"class":"done",
"idx":2,
"attributes": [
{
"key":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
],
"cid":1,
"did":2,
"coordinates": {"lon":19.972399, "lat":50.066353, "alt":0.0}
},
{
"type":"d",
"class":"done",
"idx":3,
"attributes": [
{
"key":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
],
"cid":1,
"did":3,
"coordinates": {"lon":19.972534, "lat":50.066368, "alt":0.0}
},
{
"type":"d",
"class":"done",
"idx":4,
"attributes": [
{
"key":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
],
"cid":1,
"did":4,
"coordinates": {"lon":19.972534, "lat":50.066357, "alt":0.0}
},
{
"type":"d",
"class":"done",
"idx":5,
"attributes": [
{
"key":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
],
"cid":1,
"did":5,
"coordinates": {"lon":19.972408, "lat":50.06628, "alt":0.0}
},
{
"type":"d",
"class":"done",
"idx":6,
"attributes": [
{
"key":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
],
"cid":1,
"did":6,
"coordinates": {"lon":19.972408, "lat":50.066265, "alt":0.0}
},
{
"type":"d",
"class":"done",
"idx":7,
"attributes": [
{
"key":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
],
"cid":1,
"did":7,
"coordinates": {"lon":19.972542, "lat":50.066284, "alt":0.0}
},
{
"type":"d",
"class":"done",
"idx":8,
"attributes": [
{
"key":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
],
"cid":1,
"did":8,
"coordinates": {"lon":19.972542, "lat":50.066269, "alt":0.0}
},
{
"type":"l",
"class":"light",
"idx":1,
"attributes": [
{
"key":"status",
"communication":"rw",
"type":"numeric",
"values": [],
"ranges": [ {"from":0.0, "to":100.0, "precision":10.0} ]
}
],
"cid":1,
"did":9,
"coordinates": {"lon":19.972359, "lat":50.066387, "alt":0.0}
},
{
"type":"l",
"class":"light",
"idx":2,
"attributes": [
{
"key":"status",
"communication":"rw",
"type":"numeric",
"values": [],
"ranges": [ {"from":0.0, "to":100.0, "precision":10.0} ]
}
],
"cid":1,
"did":10,
"coordinates": {"lon":19.972464, "lat":50.066395, "alt":0.0}
},
{
"type":"l",
"class":"light",
"idx":3,
"attributes": [
{
"key":"status",
"communication":"rw",
"type":"numeric",
"values": [],
"ranges": [ {"from":0.0, "to":100.0, "precision":10.0} ]
}
],
"cid":1,
"did":11,
"coordinates": {"lon":19.972553, "lat":50.066399, "alt":0.0}
},
{
"type":"l",
"class":"light",
"idx":4,
"attributes": [
{
"key":"status",
"communication":"rw",
"type":"numeric",
"values": [],
"ranges": [ {"from":0.0, "to":100.0, "precision":10.0} ]
}
],
"cid":1,
"did":12,
"coordinates": {"lon":19.972368, "lat":50.066322, "alt":0.0}
},
{
"type":"l",
"class":"light",
"idx":5,
"attributes": [
{
"key":"status",
"communication":"rw",
"type":"numeric",
"values": [],
"ranges": [ {"from":0.0, "to":100.0, "precision":10.0} ]
}
],
"cid":1,
"did":13,
"coordinates": {"lon":19.972433, "lat":50.066322, "alt":0.0}
},
{
"type":"l",
"class":"light",
"idx":6,
"attributes": [
{
"key":"status",
"communication":"rw",
"type":"numeric",
"values": [],
"ranges": [ {"from":0.0, "to":100.0, "precision":10.0} ]
}
],
"cid":1,
"did":14,
"coordinates": {"lon":19.972496, "lat":50.066322, "alt":0.0}
},
{
"type":"l",
"class":"light",
"idx":7,
"attributes": [
{
"key":"status",
"communication":"rw",
"type":"numeric",
"values": [],
"ranges": [ {"from":0.0, "to":100.0, "precision":10.0} ]
}
],
"cid":1,
"did":15,
"coordinates": {"lon":19.972559, "lat":50.066326, "alt":0.0}
},
{
"type":"l",
"class":"light",
"idx":8,
"attributes": [
{
"key":"status",
"communication":"rw",
"type":"numeric",
"values": [],
"ranges": [ {"from":0.0, "to":100.0, "precision":10.0} ]
}
],
"cid":1,
"did":16,
"coordinates": {"lon":19.972376, "lat":50.066235, "alt":0.0}
},
{
"type":"l",
"class":"light",
"idx":9,
"attributes": [
{
"key":"status",
"communication":"rw",
"type":"numeric",
"values": [],
"ranges": [ {"from":0.0, "to":100.0, "precision":10.0} ]
}
],
"cid":1,
"did":17,
"coordinates": {"lon":19.972569, "lat":50.066238, "alt":0.0}
},
{
"type":"l",
"class":"light",
"idx":10,
"attributes": [
{
"key":"status",
"communication":"rw",
"type":"numeric",
"values": [],
"ranges": [ {"from":0.0, "to":100.0, "precision":10.0} ]
}
],
"cid":1,
"did":18,
"coordinates": {"lon":19.972492, "lat":50.066177, "alt":0.0}
},
{
"type":"d",
"class":"present",
"idx":11,
"attributes": [
{
"key":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
],
"cid":1,
"did":19,
"coordinates": {"lon":19.972399, "lat":50.066391, "alt":0.0}
},
{
"type":"d",
"class":"present",
"idx":12,
"attributes": [
{
"key":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
],
"cid":1,
"did":20,
"coordinates": {"lon":19.972528, "lat":50.066395, "alt":0.0}
},
{
"type":"d",
"class":"present",
"idx":13,
"attributes": [
{
"key":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
],
"cid":1,
"did":21,
"coordinates": {"lon":19.972401, "lat":50.066322, "alt":0.0}
},
{
"type":"d",
"class":"present",
"idx":14,
"attributes": [
{
"key":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
],
"cid":1,
"did":22,
"coordinates": {"lon":19.972536, "lat":50.066326, "alt":0.0}
},
{
"type":"d",
"class":"present",
"idx":15,
"attributes": [
{
"key":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
],
"cid":1,
"did":23,
"coordinates": {"lon":19.972406, "lat":50.066235, "alt":0.0}
},
{
"type":"d",
"class":"present",
"idx":16,
"attributes": [
{
"key":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
],
"cid":1,
"did":24,
"coordinates": {"lon":19.972544, "lat":50.066238, "alt":0.0}
},
{
"type":"d",
"class":"dark",
"idx":21,
"attributes": [
{
"key":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
],
"cid":1,
"did":25,
"coordinates": {"lon":19.972429, "lat":50.066425, "alt":0.0}
},
{
"type":"d",
"class":"hour",
"idx":22,
"attributes": [
{
"key":"detected",
"communication":"ro",
"type":"atom",
"values": ["night", "day" ],
"ranges": []
}
],
"cid":1,
"did":26,
"coordinates": {"lon":19.972481, "lat":50.066425, "alt":0.0}
}
]