Generalized new structures for Location, Dimensions, Info, and Version.

CommonGarden · Apr 25, 2018 · 9bdc490 · 9bdc490
1 parent caea85d
commit 9bdc490
Showing 1 changed file with 115 additions and 91 deletions.
diff --git a/versions/0.0.1.md b/versions/0.0.1.md
@@ -111,6 +111,41 @@ Here is an example of a properly formatted timestamp…
 
 ```2018-01-25_04-56-05_UTC```
 
+# Common Structures
+Many concepts use the same data structures to report their essential information. Those structures are listed here.  
+
+## Info
+| Name        | Description                                     | Unit |
+| ----------- | ----------------------------------------------- | ---- |
+| id          | ID of the entity                                | uid  |
+| zone        | ID of the zone containing this entity           | uid  |
+| compartment | ID of the compartment that contains this entity | uid  |
+| facility    | ID of the facility that contains this entity    | uid  |
+
+## Version
+| Name    | Description                                | Unit |
+| ------- | ------------------------------------------ | ---- |
+| id      | unique id of the device                    | uid  |
+| make    | Name of the company that makes this device | text |
+| model   | Model number of this device                | text |
+| version | Version number of this device              | text |
+
+## Location
+| Name | Description                                             | Unit |
+| ---- | ------------------------------------------------------- | ---- |
+| id   | Unique id of this entity                                | uid  |
+| x    | x coordinate of this entity within its parent container | m    |
+| y    | y coordinate of this entity within its parent container | m    |
+| z    | z coordinate of this entity within its parent container | m    |
+
+## Dimensions
+| Name   | Description             | Unit |
+| ------ | ----------------------- | ---- |
+| id     | Unique id of the entity | uid  |
+| length | Length of the entity    | m    |
+| width  | Width of the entity     | m    |
+| height | Height of the entity    | m    |
+
 # Plan
 
 The relationship between the common concepts (facilities, compartments, zones, etc) is maintained as part of a Plan that can be interrogated. The following URLs MUST be supported by any service that wishes to contribute to the Plan.
@@ -143,69 +178,71 @@ Returns an array of Compartment IDs
 ```
 GET http://[domain:port]/agroapi/[version]/plan/compartments/info  
 ```
-Returns an array of [Compartment Info](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#compartment-info)  
+Returns an array of [Info](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#info)  
 
 ```
 GET http://[domain:port]/agroapi/[version]/plan/compartments/location  
 ```
-Returns an array of [Compartment Location](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#compartment-location)  
+Returns an array of [Location](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#location)  
+```
+GET http://[domain:port]/agroapi/[version]/plan/compartments/dimensions  
+```
+Returns an array of [Dimensions](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#dimensions)  
+
 
 ### Single compartment
 ```
 GET http://[domain:port]/agroapi/[version]/plan/compartments/[compartmentid]/info  
 ```
-Returns [Compartment Info](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#compartment-info)  
+Returns [Info](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#info)  
 
 ```
 GET http://[domain:port]/agroapi/[version]/plan/compartments/[compartmentid]/location  
 ```
-Returns [Compartment Location](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#compartment-location)  
+Returns [Location](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#location)  
+
+```
+GET http://[domain:port]/agroapi/[version]/plan/compartments/[compartmentid]/dimensions  
+```
+Returns [Dimensions](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#dimensions)  
 
 ```
 GET http://[domain:port]/agroapi/[version]/plan/compartment/[compartmentid]/zones  
 ```
-Returns an array of [Zone Info](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#zone-info)  
-
-### Data Structures
-#### Compartment Info
-| Name      | Description                  | Unit |
-| --------- | ---------------------------- | ---- |
-| id        | Unique id of the compartment | uid  |
-| length    | Length of the compartment    | cm   |
-| width     | Width of the compartment     | cm   |
-| height    | Height of the compartment    | cm   |
-
-#### Compartment Location
-| Name        | Description                                          | Unit |
-| ----------- | ---------------------------------------------------- | ---- |
-| id          | Unique id of the compartment                         | uid  |
-| facility    | ID of the facility that owns this compartment        | uid  |
-| x           | x coordinate of this compartment within the facility | cm   |
-| y           | y coordinate of this compartment within the facility | cm   |
-| z           | z coordinate of this compartment within the facility | cm   |
+Returns an array of [Info](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#info)  
 
 ## Zones
 ### All zones
 ```
 GET http://[domain:port]/agroapi/[version]/plan/zones/info  
 ```
-Returns an array of [Zone Info](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#zone-info)  
+Returns an array of [Info](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#info)  
 
 ```
 GET http://[domain:port]/agroapi/[version]/plan/zones/location  
 ```
-Returns an array of [Zone Location](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#zone-location)  
+Returns an array of [Location](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#location)  
+
+```
+GET http://[domain:port]/agroapi/[version]/plan/zones/dimensions  
+```
+Returns an array of [Dimensions](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#dimensions)  
 
 ### Single zone
 ```
 GET http://[domain:port]/agroapi/[version]/plan/zones/[zoneid]/info  
 ```
-Returns [Zone Info](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#zone-info)  
+Returns [Info](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#info)  
 
 ```
 GET http://[domain:port]/agroapi/[version]/plan/zones/[zoneid]/location  
 ```
-Returns [Zone Location](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#zone-location)  
+Returns [Location](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#location)  
+
+```
+GET http://[domain:port]/agroapi/[version]/plan/zones/[zoneid]/dimensions  
+```
+Returns [Dimensions](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#dimensions)  
 
 ```
 GET http://[domain:port]/agroapi/[version]/plan/zones/[zoneid]/zones  
@@ -217,58 +254,23 @@ GET http://[domain:port]/agroapi/[version]/plan/zones/[zoneid]/crops
 ```
 Returns an array of Crop Variety IDs  
 
-### Data Structures
-#### Zone Info
-| Name      | Description           | Unit |
-| --------- | --------------------- | ---- |
-| id        | Unique id of the zone | uid  |
-| length    | Length of the zone    | cm   |
-| width     | Width of the zone     | cm   |
-| height    | Height of the zone    | cm   |
-
-#### Zone Location
-| Name        | Description                                           | Unit |
-| ----------- | ----------------------------------------------------- | ---- |
-| id          | Unique id of the zone                                 | uid  |
-| compartment | ID of the compartment that contains this zone         | uid  |
-| parent      | ID of the parent zone that contains this zone, if any | uid  |
-| x           | x coordinate of this compartment within the facility  | cm   |
-| y           | y coordinate of this compartment within the facility  | cm   |
-| z           | z coordinate of this compartment within the facility  | cm   |
-
-## Devices
-Every device uses the same data structures to report its essential identify and location. Here are the structures that are returned in those cases.  
-
-#### Device Info
-| Name    | Description                                | Unit |
-| ------- | ------------------------------------------ | ---- |
-| id      | unique id of the device                    | uid  |
-| make    | Name of the company that makes this device | text |
-| model   | Model number of this device                | text |
-| version | Version number of this device              | text |
-
-#### Device Location
-| Name | Description                                 | Unit |
-| ---- | ------------------------------------------- | ---- |
-| id   | Unique id of the device                     | uid  |
-| zone | ID of the zone containing this device       | uid  |
-| x    | x coordinate of this device within the zone | cm   |
-| y    | y coordinate of this device within the zone | cm   |
-| z    | z coordinate of this device within the zone | cm   |
-
 # Light
 ## Sensors
-### URLS
-#### Talking to one sensor
+### Talking to one sensor
 ```
 GET http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/info  
 ```
-Returns [Device Info](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#device-info)  
+Returns [Info](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#info)  
+
+```
+GET http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/version  
+```
+Returns [Version](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#version)  
 
 ```
 GET http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/location  
 ```
-Returns [Device Location](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#device-location)  
+Returns [Location](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#location)  
 
 ```
 GET http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/ppf  
@@ -280,16 +282,21 @@ GET http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/ppfd
 ```
 Returns [Light PPFD](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#light-ppfd)  
 
-#### Talking to all sensors
+### Talking to all sensors
 ```
 GET http://[domain:port]/agroapi/[version]/lights/sensors/info  
 ```
-Returns an array of [Device Info](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#device-info)  
+Returns an array of [Info](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#info)  
+
+```
+GET http://[domain:port]/agroapi/[version]/lights/sensors/version  
+```
+Returns an array of [Version](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#version)  
 
 ```
 GET http://[domain:port]/agroapi/[version]/lights/sensors/location  
 ```
-Returns an array of [Device Location](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#device-location)  
+Returns an array of [Location](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#location)  
 
 ```
 GET http://[domain:port]/agroapi/[version]/lights/sensors/ppf  
@@ -301,16 +308,21 @@ GET http://[domain:port]/agroapi/[version]/lights/sensors/ppfd
 ```
 Returns an array of [Light PPFD](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#light-ppfd)  
 
-#### Talking to all sensors in a zone
+### Talking to all sensors in a zone
 ```
 GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/info  
 ```
-Returns an array of [Device Info](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#device-info)  
+Returns an array of [Info](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#info)  
+
+```
+GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/version  
+```
+Returns an array of [Version](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#version)  
 
 ```
 GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/location  
 ```
-Returns an array of [Device Location](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#device-location)  
+Returns an array of [Location](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#location)  
 
 ```
 GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/ppf  
@@ -322,8 +334,7 @@ GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/ppfd
 ```
 Returns an array of [Light PPFD](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#light-ppfd)  
 
-### Data structures
-#### Light PPF
+### Light PPF
 | Name      | Description                      | Unit     |
 | --------- | -------------------------------- | -------- |
 | id        | Unique id of the device          | uid      |
@@ -336,7 +347,7 @@ Returns an array of [Light PPFD](https://github.com/open-ag-tech/api-spec/blob/m
 | par       | Level of absorbable light        | PPF      |
 | light     | Level of all spectrums of light  | PPF      |
 
-#### Light PPFD
+### Light PPFD
 | Name      | Description                      | Unit     |
 | --------- | -------------------------------- | -------- |
 | id        | Unique id of the device          | uid      |
@@ -350,17 +361,21 @@ Returns an array of [Light PPFD](https://github.com/open-ag-tech/api-spec/blob/m
 | light     | Level of all spectrums of light  | PPFD     |
 
 ## Fixtures
-### URLS
-#### Talking to one fixture
+### Talking to one fixture
 ```
 GET http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/info
 ```
-Returns [Device Info](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#device-info)  
+Returns [Info](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#info)  
+
+```
+GET http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/version  
+```
+Returns [Version](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#version)  
 
 ```
 GET http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/location
 ```
-Returns [Device Location](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#device-location)  
+Returns [Location](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#location)  
 
 ```
 GET http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/config
@@ -372,16 +387,21 @@ GET http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/power
 ```
 Returns [Fixture Power](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#fixture-power)  
 
-#### Talking to all fixtures
+### Talking to all fixtures
 ```
 GET http://[domain:port]/agroapi/[version]/lights/fixtures/info
 ```
-Returns an array of [Device Info](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#device-info)  
+Returns an array of [Info](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#info)  
+
+```
+GET http://[domain:port]/agroapi/[version]/lights/fixtures/version  
+```
+Returns an array of [Version](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#version)  
 
 ```
 GET http://[domain:port]/agroapi/[version]/lights/fixtures/location
 ```
-Returns an array of [Device Location](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#device-location)  
+Returns an array of [Location](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#location)  
 
 ```
 GET http://[domain:port]/agroapi/[version]/lights/fixtures/config
@@ -393,16 +413,21 @@ GET http://[domain:port]/agroapi/[version]/lights/fixtures/power
 ```
 Returns an array of [Fixture Power](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#fixture-power)  
 
-#### Talking to all fixtures in a zone
+### Talking to all fixtures in a zone
 ```
 GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/info
 ```
-Returns an array of [Device Info](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#device-info)  
+Returns an array of [Info](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#info)  
+
+```
+GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixture/[fixtureid]/version  
+```
+Returns an array of [Version](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#version)  
 
 ```
 GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/location
 ```
-Returns an array of [Device Location](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#device-location)  
+Returns an array of [Location](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#location)  
 
 ```
 GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/config
@@ -414,8 +439,7 @@ GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/power
 ```
 Returns an array of [Fixture Power](https://github.com/open-ag-tech/api-spec/blob/master/versions/0.0.1.md#fixture-power)  
 
-### Data structures
-#### Fixture Configuration
+### Fixture Configuration
 | Name     | Description                     | Unit  |
 | -------- | ------------------------------- | ----- |
 | id       | Unique id of the fixture        | uid   |