Igor Wojnicki's WIKI

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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:
<code json>
{ 
  "timestamp": "2014-03-25T14:03Z", 
  "data": [
    {"id": "PL_KRK_0070034_45_6_01", "state": "on" },
    ...
  ]
}
</code>


=== Get multiple parameters ===

e.g.

   GET /PL_KRK_0070034_45_6_01/{state,dimming}
   
Returns:
<code json>
{ 
  "timestamp": "2014-03-25T14:03Z", 
  "data": [
    {"id": "PL_KRK_0070034_45_6_01", "state": "on", "dimming": 50 }
  ]
}
</code>


=== Get all parameters ===

   GET /PL_KRK_0070034_45_6_01/*
   
Returns:
<code json>
{ 
  timestamp: "2014-03-25T14:03Z", 
  data: [
    {"id": "PL_KRK_0070034_45_6_01", "state": "on", "dimming": 50 }
  ]
}
</code>


=== 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):

<code json>
{
  "timestamp":"2014-09-17T11:31:29+0200",
  "data": [
      { "id": "PL_KRK_0070034_45_6_01", "status" :0.0 } 
  ]
}
</code>
 
Assuming that ADDR does not exists:
  GET /non_existing_addr/something

results in (mind there is no object for the requested address):
<code json>
{
  "timestamp":"2014-09-17T11:31:29+0200",
  "data": [ 
  ]
}
</code>

==== Control interface ====

Change lamp parameters:
  PUT /
with the following request data:
<code json>
{
  "data" : [
    {"id": "PL_KRK_0070034_45_6_01", "dimming" : 50,  "state": "on" },
    {"id": "PL_KRK_0070034_45_6_02", "state": "off" }
  ]
}

</code>
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:

<code json>
{ 
  "timestamp": "2014-03-25T14:03:22+0200", 
  "data": [
    {"id": "PL_KRK_0070034_45_6_01", "dimming" : 50,  "state": "on" },
    ...
  ]
}
</code>

If the parameter cannot be changed, or if it is nonexistant it is not returned/confirmed:

Request:
<code json>
{
  "data" : [ {"id": "PL_KRK_0070034_45_6_01", "detecdted" :"false", "detected":"false"} ]
} 
</code>

Reply:
<code json>
{
  "timestamp":"2014-05-30T21:37:39+0200",
  "data" : [ {"id": "PL_KRK_0070034_45_6_01", "detected":"false"} ] 
}
</code>

=== Non-existant addresses or parameters === 
If an ADDR does not exist:
Request:
<code json>
{
  "data" : [ { "id": "non_existing", "detected":"false" } ]
} 
</code>

Reply:
<code json>
{
  "timestamp":"2014-05-30T21:37:39+0200",
  "data" : [ ]
}
</code>


==== Log interface ====

TBD

==== LIMS interface ====

=== LIMS Info interface ===


Main goal:
  * device geo location, 
  * device parameters and their types.

It is provided as [[http://geojson.org|GEOJSON]], where location is array-encoded [longitude, latitude, elevation]


  GET /info
  
Response:

<code json>
{ "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 } ] }
          ]
        }
      },
...
    ]
}
</code>


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 with ''from'', ''to'' and  ''precision''.

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:

<code json>
{
  "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"
}
</code>
Igor Wojnicki's WIKI

User Tools

Site Tools

Page Tools
