User Tools
lighting:interfaces
Table of Contents
Lighting interfaces
Preliminaries
All communications should be done over HTTP/1.1 so as to allow for keepalive.
Timestamp format
According to ISO 8601, plus microseconds, see examples:
- “2014-03-25T14:03:33.547222” - assumes zulu time (UTC)
- “2014-03-25T14:03:33.547222Z” - zulu time (UTC)
- “2014-03-25T14:03:33.547222+01” - UTC+1
- “2014-03-25T14:03:33.547222+0100” - UTC+1
- “2014-03-25T14:03:33.547222+01:00” - UTC+1
Lamp (device) addressing
Lamps (devices) are addressed using (cabinet id, device id) pairs:
GET /CID/DID/... PUT /
Where:
- CID (Cabinet IDentifier) is:
- an atomic value (e.g. 35), referring to an ID of a single cabinet,
- a set of comma-separated values (e.g. 33,35,40), referring to a set of cabinets,
- a range (e.g. 33-35), referring to a range of cabinet IDs,
- “all”, referring to all cabinets.
- DID (Device IDentifier) is:
- if DID is an atomic value:
- an atomic value (e.g. 2), referring to an ID of a single lamp within that cabinet,
- a set of comma-separated values (e.g. 1,2,5), referring to a set of lamps,
- a range (e.g. 1-4), referring to a range of lamp IDs,
- “all”, referring to all lamps within that cabinet,
- otherwise, only “all” is allowed, which refers to all lamps in specified cabinets.
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.
Examples
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/...
Interfaces
Control interface
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:
- lamp 1 in cabinet 34 to on with 50% dimming
- lamp 5 in cabinet 35 to off with unspecified dimming
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"} ]
}
]
}
State interface
Get device state
GET /CID/DID/state
Returns:
{
"timestamp": "2014-03-25T14:03.547Z",
"data": [
{ "cid": 34, "did": 10, "params": [ {"k": "state", "v": "on" } ] },
...
]
}
Get lamp dimming
GET /CID/DID/dimming
Returns:
{
"timestamp": "2014-03-25T14:03.547Z",
"data": [
{ "cid": 34, "did": 10, "params": [ {"k": "dimming", "v": 50 } ] },
...
]
}
Get multiple parameters
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 all parameters
GET /CID/DID/all
Returns:
{
timestamp: "2014-03-25T14:03.547Z",
data: [
{ "cid": 34, "did": 10, "params": [ { "k": "state", "v": "on" }, ... ] },
...
]
}
Subscribe to parameter changes
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.
Nonexistant CID, DID or parameters
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} ]
}
]
}
Log interface
Subscribe to newly generated logs
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 logs from a certain date and subscribe to new entries
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 logs from a certain period
GET /log/CID/DID?fromtimestamp=XXXXXXX&totimestamp=YYYYYYY
Response:
{
"lastknowntimestamp": XXXXXXX
"logdata": [
{ json obj },
{ json obj },
...
{ json obj }
]
}
connection is then closed.
Logged data
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
payloadcontains complete data sent as the payload (content of the request or reply),type=request | response,method=PUT | GET.
LIMS interface
LIMS Info interface
Main goal:
- device geo location,
- mapping between logical model (type, idx, class, attributes) and physical deployment (cabinet,device).
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 withfrom,toandprecision.
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}
}
]
lighting/interfaces.txt · Last modified: 2021/01/08 14:10 (external edit)
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
