User Tools
lighting:interfaces2.1
Table of Contents
Lighting interfaces v2
Preliminaries
All communications should be done over HTTP/1.1 so as to allow for keepalive.
Timestamp format is ISO 8601, e.g.:
- “2014-03-25T14:03:33+0100” - UTC+1
Interfaces
State interface
Lamp (device) addressing
Devices (lamps, sensors) are addressed using a text-based unique identifier e.g:
PL_KRK_0070034_45_6_01
A device addres, refered to as ADDR later on, has the following properties:
- the address can consist of a comma separated set of identifiers
- parts of the identifier can refer to geographical/other partitioning: PL - country code, KRK - city code, 0070034 - street code etc.
- there could be the following wildcards used in the address:
- '*' matching a string,
- '?' matching a character,
- [] any character specified between the brackets,
- {} any pattern from a comma-separated list between the braces.
Examples
For a single device URI:
/PL_KRK_0070034_45_6_01/...
For a range of devices' URI:
/PL_KRK_0070034_*/...
For a set of devices' URI:
/{PL_KRK_0070034_45_6_01,PL_KRK_0070034_45_6_02,PL_KRK_0070034_45_6_03}/...
Parameters
Device properties are represented as parameters. A parameter is identified by its name. Parameters, referred to as PARAMS later on, are subject to the same wildcards as ADDR.
Examples
A single parameter URI:
/.../status
Multiple parameters URI:
/.../{status,time}
All parameters URI:
/.../*
Get device parameter
GET /ADDR/PARAMS
e.g. getting 'state' parameter:
GET /PL_KRK_0070034_45_6_01/state
Returns:
{
"timestamp": "2014-03-25T14:03Z",
"data": [
{"id": "PL_KRK_0070034_45_6_01", "state": "on" },
...
]
}
Get multiple parameters
e.g.
GET /PL_KRK_0070034_45_6_01/{state,dimming}
Returns:
{
"timestamp": "2014-03-25T14:03Z",
"data": [
{"id": "PL_KRK_0070034_45_6_01", "state": "on", "dimming": 50 }
]
}
Get all parameters
GET /PL_KRK_0070034_45_6_01/*
Returns:
{
timestamp: "2014-03-25T14:03Z",
data: [
{"id": "PL_KRK_0070034_45_6_01", "state": "on", "dimming": 50 }
]
}
Subscribe to parameter changes
This is done by specifying the lasttimestamp GET parameter, which contains the last known timestamp of an update:
GET /*/state?lasttimestamp=2014-03-25T14:03:18+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 addresses or parameters
In case of nonexistant ADDR or PARAMS a null is returned as parameter value
Assuming that foo does not exist the following request:
GET /PL_KRK_0070034_45_6_01/{status,foo}
results in (mind foo is not there):
{
"timestamp":"2014-09-17T11:31:29+0200",
"data": [
{ "id": "PL_KRK_0070034_45_6_01", "status" :0.0 }
]
}
Assuming that ADDR does not exists:
GET /non_existing_addr/something
results in (mind there is no object for the requested address):
{
"timestamp":"2014-09-17T11:31:29+0200",
"data": [
]
}
Control interface
Change lamp parameters:
PUT /
with the following request data:
{
"data" : [
{"id": "PL_KRK_0070034_45_6_01", "dimming" : 50, "state": "on" },
{"id": "PL_KRK_0070034_45_6_02", "state": "off" }
]
}
That will set:
- lamp PL_KRK_0070034_45_6_01 to on with 50% dimming
- lamp PL_KRK_0070034_45_6_02 to off with unspecified dimming
Returns confirmation that particular parameters are set with additional timestamp:
{
"timestamp": "2014-03-25T14:03:22+0200",
"data": [
{"id": "PL_KRK_0070034_45_6_01", "dimming" : 50, "state": "on" },
...
]
}
If the parameter cannot be changed, or if it is nonexistant it is not returned/confirmed:
Request:
{
"data" : [ {"id": "PL_KRK_0070034_45_6_01", "detecdted" :"false", "detected":"false"} ]
}
Reply:
{
"timestamp":"2014-05-30T21:37:39+0200",
"data" : [ {"id": "PL_KRK_0070034_45_6_01", "detected":"false"} ]
}
Non-existant addresses or parameters
If an ADDR does not exist: Request:
{
"data" : [ { "id": "non_existing", "detected":"false" } ]
}
Reply:
{
"timestamp":"2014-05-30T21:37:39+0200",
"data" : [ ]
}
Log interface
TBD
LIMS interface
LIMS Info interface
Main goal:
- device geo location,
- device parameters and their types.
It is provided as GEOJSON, where location is array-encoded [longitude, latitude, elevation]
GET /info
Response:
{ "type": "FeatureCollection",
"features": [
{ "type": "Feature",
"geometry": {"type": "Point", "coordinates": [19.0, 50.0, 118.0]},
"properties": {
"id": "PL_KRK_0070034_45_6_01",
"type": "d",
"class": "traffic",
"attributes": [
{ "name": "detected", "communication": "ro", "type": "atom", "values": [ "true", "false", "unknown" ]},
{ "name": "control", "communication": "rw", "type": "numeric", "ranges": [ {"from": 0.0, "to": 10.0, "precision": 0.1 } ] }
]
}
},
{ "type": "Feature",
"geometry": {"type": "Point", "coordinates": [19.0, 50.0, 118.0]},
"properties": {
"id": "PL_KRK_0070034_45_6_01",
"type": "l",
"class": "light",
"attributes": [
{ "name": "status", "communication": "rw", "type": "numeric", "ranges": [ {"from": 0.0, "to": 100.0, "precision": 1.0 } ] }
]
}
},
...
]
}
where attributes object consists of:
- an 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.
In the example above a single address acts as a two types of device: d and l, by definition they must use disjoint set of properties.
A complete LIMS response example:
{
"features": [
{
"geometry": {"coordinates": [19.972399, 50.066368, 0.0 ], "type":"Point"},
"properties": {
"id":1,
"type":"d",
"class":"done",
"attributes": [
{
"name":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972399, 50.066353, 0.0 ], "type":"Point"},
"properties": {
"id":2,
"type":"d",
"class":"done",
"attributes": [
{
"name":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972534, 50.066368, 0.0 ], "type":"Point"},
"properties": {
"id":3,
"type":"d",
"class":"done",
"attributes": [
{
"name":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972534, 50.066357, 0.0 ], "type":"Point"},
"properties": {
"id":4,
"type":"d",
"class":"done",
"attributes": [
{
"name":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972408, 50.06628, 0.0 ], "type":"Point"},
"properties": {
"id":5,
"type":"d",
"class":"done",
"attributes": [
{
"name":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972408, 50.066265, 0.0 ], "type":"Point"},
"properties": {
"id":6,
"type":"d",
"class":"done",
"attributes": [
{
"name":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972542, 50.066284, 0.0 ], "type":"Point"},
"properties": {
"id":7,
"type":"d",
"class":"done",
"attributes": [
{
"name":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972542, 50.066269, 0.0 ], "type":"Point"},
"properties": {
"id":8,
"type":"d",
"class":"done",
"attributes": [
{
"name":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972359, 50.066387, 0.0 ], "type":"Point"},
"properties": {
"id":1,
"type":"l",
"class":"light",
"attributes": [
{
"name":"status",
"communication":"rw",
"type":"numeric",
"values": [],
"ranges": [ {"from":0.0, "to":100.0, "precision":10.0} ]
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972464, 50.066395, 0.0 ], "type":"Point"},
"properties": {
"id":2,
"type":"l",
"class":"light",
"attributes": [
{
"name":"status",
"communication":"rw",
"type":"numeric",
"values": [],
"ranges": [ {"from":0.0, "to":100.0, "precision":10.0} ]
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972553, 50.066399, 0.0 ], "type":"Point"},
"properties": {
"id":3,
"type":"l",
"class":"light",
"attributes": [
{
"name":"status",
"communication":"rw",
"type":"numeric",
"values": [],
"ranges": [ {"from":0.0, "to":100.0, "precision":10.0} ]
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972368, 50.066322, 0.0 ], "type":"Point"},
"properties": {
"id":4,
"type":"l",
"class":"light",
"attributes": [
{
"name":"status",
"communication":"rw",
"type":"numeric",
"values": [],
"ranges": [ {"from":0.0, "to":100.0, "precision":10.0} ]
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972433, 50.066322, 0.0 ], "type":"Point"},
"properties": {
"id":5,
"type":"l",
"class":"light",
"attributes": [
{
"name":"status",
"communication":"rw",
"type":"numeric",
"values": [],
"ranges": [ {"from":0.0, "to":100.0, "precision":10.0} ]
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972496, 50.066322, 0.0 ], "type":"Point"},
"properties": {
"id":6,
"type":"l",
"class":"light",
"attributes": [
{
"name":"status",
"communication":"rw",
"type":"numeric",
"values": [],
"ranges": [ {"from":0.0, "to":100.0, "precision":10.0} ]
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972559, 50.066326, 0.0 ], "type":"Point"},
"properties": {
"id":7,
"type":"l",
"class":"light",
"attributes": [
{
"name":"status",
"communication":"rw",
"type":"numeric",
"values": [],
"ranges": [ {"from":0.0, "to":100.0, "precision":10.0} ]
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972376, 50.066235, 0.0 ], "type":"Point"},
"properties": {
"id":8,
"type":"l",
"class":"light",
"attributes": [
{
"name":"status",
"communication":"rw",
"type":"numeric",
"values": [],
"ranges": [ {"from":0.0, "to":100.0, "precision":10.0} ]
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972569, 50.066238, 0.0 ], "type":"Point"},
"properties": {
"id":9,
"type":"l",
"class":"light",
"attributes": [
{
"name":"status",
"communication":"rw",
"type":"numeric",
"values": [],
"ranges": [ {"from":0.0, "to":100.0, "precision":10.0} ]
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972492, 50.066177, 0.0 ], "type":"Point"},
"properties": {
"id":10,
"type":"l",
"class":"light",
"attributes": [
{
"name":"status",
"communication":"rw",
"type":"numeric",
"values": [],
"ranges": [ {"from":0.0, "to":100.0, "precision":10.0} ]
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972399, 50.066391, 0.0 ], "type":"Point"},
"properties": {
"id":11,
"type":"d",
"class":"present",
"attributes": [
{
"name":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972528, 50.066395, 0.0 ], "type":"Point"},
"properties": {
"id":12,
"type":"d",
"class":"present",
"attributes": [
{
"name":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972401, 50.066322, 0.0 ], "type":"Point"},
"properties": {
"id":13,
"type":"d",
"class":"present",
"attributes": [
{
"name":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972536, 50.066326, 0.0 ], "type":"Point"},
"properties": {
"id":14,
"type":"d",
"class":"present",
"attributes": [
{
"name":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972406, 50.066235, 0.0 ], "type":"Point"},
"properties": {
"id":15,
"type":"d",
"class":"present",
"attributes": [
{
"name":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972544, 50.066238, 0.0 ], "type":"Point"},
"properties": {
"id":16,
"type":"d",
"class":"present",
"attributes": [
{
"name":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972429, 50.066425, 0.0 ], "type":"Point"},
"properties": {
"id":21,
"type":"d",
"class":"dark",
"attributes": [
{
"name":"detected",
"communication":"ro",
"type":"atom",
"values": ["true", "false" ],
"ranges": []
}
]
},
"type":"Feature"
},
{
"geometry": {"coordinates": [19.972481, 50.066425, 0.0 ], "type":"Point"},
"properties": {
"id":22,
"type":"d",
"class":"hour",
"attributes": [
{
"name":"detected",
"communication":"ro",
"type":"atom",
"values": ["night", "day" ],
"ranges": []
}
]
},
"type":"Feature"
}
],
"type":"FeatureCollection"
}
lighting/interfaces2.1.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
