diff --git a/versions/0.0.2/README.md b/versions/0.0.2/README.md new file mode 100644 index 0000000..b4e8c62 --- /dev/null +++ b/versions/0.0.2/README.md @@ -0,0 +1,13 @@ +# API Specification +This directory contains the various parts of the open API specification for exchanging data and operational control in indoor agricultural environments. + +The specification is divided into the following sub-sections to make it easier to follow... + +* **General** - contains all of the essential rules that need to be followed, including common concepts, common data structures, timestamp formats, error handling, and so on. +* **Plan** - specifies the API for interacting with the basic concepts of a well-planned facility (compartments, zones, crop varieties, and so on) +* **Lights** - specifies the API for interacting with lighting systems +* **Air** - specifies the API for interacting with air control systems (heating, cooling, ventilation, humidity, and so on) +* **Soil** - specifies the API for interacting with soil monitoring systems +* **Roots** - specifies the API for interacting with root monitoring systems +* **Reservoirs** - specifies the API for interacting with reservoir control systems +* **Nutrients** - specifies the API for monitoring nutrients diff --git a/versions/0.0.2/air.md b/versions/0.0.2/air.md new file mode 100644 index 0000000..d8660f5 --- /dev/null +++ b/versions/0.0.2/air.md @@ -0,0 +1,22 @@ +# Purpose + +This specification is intended to define a standardized way of communicating with climate control systems for real-time monitoring and control of air quality and to allow data collection between control systems and / or peripheral devices. + +# Scope + +The scope of this document is limited to providing a payload structure and endpoint type definitions to allow basic control and data acquisition. The addition of product specific features is left to the implementer, but to be in compliance the product must support the basic set of features specified below. + +# Definitions + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. + +# Endpoints +## Sensors +### URLS +### Measurements +| Data point | Description | Unit | +| ---------- | -------------------------------- | ------- | +| temp | The temperature of the air | celsius | +| humidity | The level of humidity in the air | % | +| co2 | The level of CO2 in the air | ppm | +| airflow | The speed of the airflow | m3/s | \ No newline at end of file diff --git a/versions/0.0.2/general.md b/versions/0.0.2/general.md new file mode 100644 index 0000000..a6490f2 --- /dev/null +++ b/versions/0.0.2/general.md @@ -0,0 +1,890 @@ +# Purpose + +This specification is intended to define a standardized way of communicating real-time command-and-control data and to allow data collection between control systems and / or peripheral devices. + +# Scope + +The scope of this document is limited to providing a payload structure and endpoint type definitions to allow basic control and data acquisition. This document does not set out to define an API but rather to specify a uniform way to build one. It does not seek to dictate endpoint names, server architecture, or security protocols. The addition of product specific features is left to the implementer, but to be in compliance the product must support the basic set of features specified below. + +# Definitions + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. + +# Common Concepts + +There are specific concepts that all participants in this open API must support in order to make interaction possible. Each of these concepts should be driven by factory configurations or by on-site configurations made by the customer or a professional integrator. +The diagram below captures their essential relationships. + +![Common Concepts](https://docs.google.com/drawings/d/e/2PACX-1vRptSa5X7K6yzOqA95Jpncwwl8rUZgxOo6l13m_VcnCyd5dHmlLZvUyrED-HX2b5Q9YNHiBltB6cY5t/pub?w=982&h=1042) + +## Company + +A company refers to a single entity that owns and operates one or more facilities. Each company makes its own purchasing and planning decisions and has only one set of executives. + +## System + +Every company has one or more systems that are helping to control all activity related to agriculture (e.g., Argus, Lumigrow, Priva, and so on). In order to help identify compatibility levels, each system should be able to report its make and model number as well as a version number related to its embedded software. Each system can own one or more systems and / or devices and must be able to accept calls on behalf of its devices. For example, a large climate control system might own a network of light and air sensors while also controlling lighting, ventilation and irrigation systems. Systems can manage devices across zones and crops. + +## Crop Variety + +A crop refers to one or more types of plants that are being grown in the same environment - i.e., if a single greenhouse is inter-planting strawberries and mint, this would be considered a single crop for the purposes of management and prediction. Crop variety IDs do not need to be standardized, so long as they are consistent within a single company. + +## Facility + +A facility is a single physical site that contains one or more compartments - e.g., a greenhouse. A company can own many facilities and each facility will have one or more Head Growers to oversee its operations. + +## Compartment + +A compartment is a physically isolated space within a facility for the purpose of establishing a unique macro climate. Each compartment is dedicated to one or more crop varieties. Every compartment has a length, width and height. By default, every compartment contains a single zone that is the length, width, and height of the compartment. + +## Zone + +A zone identifies an area within a compartment dedicated to maintaining a micro-climate. For example, a compartment would maintain uniform levels of humidity and air temperature, whereas a zone might alter the light levels or nutrient mix in the irrigation to create unique micro-climates. + +Every zone contains zero or more zones and / or devices. Every device that is deployed should be assigned to the correct zone. Zones are a natural way of grouping devices for control purposes, so that a configuration can be pushed to a zone and affect all relevant devices within the zone at the same time. + +All zones must be able to identify the crop variety they are overseeing. All data produced from a zone must include a crop variety ID for easy identification. + +Each zone must be able to identify its size (in width and height) as well as its relative location within the compartment, since all sensors and controllers within that zone will report their location relative to the zone, not the compartment. + +Zones can be combined into deep hierarchies. For example, a compartment can have multiple rows of plants that are 1 foot off the floor (e.g., lettuce), with an additional layer of plants 4 feet off the floor (e.g., strawberries). The grower would want to create unique zones for the lettuce vs. the strawberries, reflecting their unique feeds for irrigation and supplemental lighting. However, the grower would also want to maintain a general climate zone for the overall compartment for the purposes of controlling heating and ventilation. This means that the compartment would have a global zone containing two sub-zones. + +## Location + +Every device and zone should know its position relative to its container (devices are contained by zones, zones are contained by compartments). Locations are described using x, y, and z co-ordinates (or length, width, and height). + +## Device + +A device refers to any physical mechanism that can either monitor or control the growing environment (lights, pumps, heaters, humidifiers, etc). + +Every device must be related to a zone and a location within that zone. It should be able to report these relationships along with its own unique ID. + +## Sensor + +A sensor refers to any device that is gathering data about the growing environment (light, air, water, nutrients, and so on). + +## Controller + +A controller refers to any device that can affect the growing environment (light fixtures, nutrient dosers, heaters, humidifiers, and so on). + +# Endpoint Structure + +The detailed endpoint structure is outside the scope of this document because it needs to make sense for the overall architecture of the implementation. However, there are a few standards that need to be considered when it comes to endpoint design. + +*Path elements within the URL...* +- The first element of all compliant apis MUST be "agroapi" +- The second element of all compliant apis MUST be the version number +- The third element of all compliant apis MUST be a domain identifier (e.g., "lights", "air", and so on) +- All elements after the third and before the final element are optional and SHOULD describe collections and / or a single member of a collection +- The final element of all compliant apis MUST identify the information or action that is the subject of the call + +*Structure of collections...* +- Collection identifiers MUST be plural +- Endpoints SHOULD NOT nest more than 2 collections deep (e.g., collection/{id}/collection/{id}) + +*Data structures...* +- Individual data points coming from the same device SHOULD be grouped in a structure with other data points that are related to the same topic + +**Example** + +GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?key=yourAPIKey + +# Error Handling + +In principle, a successful API call should return an HTTP status code of 200. An unsuccessful API call will return an HTTP status code of 550 and the body should contain an error code that has been properly documented by the owner of the API. + +The interpretation of error codes, including the text describing the error, will be left up to the API user based on their understanding of the error code documentation provided by the API owner. + +# Validation Handshake + +*TBD* + +Although a data consumer / receiver will have its own limits when it comes to value ranges and so on, there is a perceived need for the consumer / receiver to know what value ranges the data producer / sender might provide. This gives the consumer / receiver a secondary validation check to ensure that the data makes sense. + +# Timestamps + +All monitoring data MUST be accompanied by a timestamp that includes year, month, day, hour, minute, second, and time zone. The format MUST be as follows… + +```[year]-[month]-[day]_[hour]-[min]-[sec]_[timezone]``` + +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 Data +| 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 Data +| 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 Data +| 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 | + +## Dimension Data +| 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 | + +# Data Types +## Boolean +Used to express T/F, Y/N, or ON/OFF values +```json +type: object + required: + - name + - status + properties: + status: + type: bool +``` +## Integer +Used to express whole 4-byte numbers +```json +type: object + required: + - name + - value + properties: + value: + type: integer +``` +## Decimal +Used to express numbers with 8-byte decimal precision +```json +type: object + required: + - name + - value + properties: + value: + type: number + format: double +``` +## String +Used to send alphanumeric strings +```json +type: object + required: + - name + - text + properties: + text: + type: string +``` + +# Primitive Endpoints +The following endpoints provide examples of payloads that would be exchanged for any endpoints that are trying to work with simple primitive values (e.g., a single number, boolean flag, or piece of text). + +Request and response bodies are presented below in JSON as well as YAML (which is compatible with OpenAPI 3.0). +NOTE: proper RESTful URLs should contain the identification of the entities being queries or acted upon (names or IDs) in the URL itself. Therefore, those identifications do not show up in the payloads. + +## Integer +**Operation:** GET +Fetches an integer entry. This will fail if the integer entry does not yet exist. +**Request Body** +None +**Response Body** +YAML +``` +responses: + '200': + description: successful operation + content: + application/json: + schema: + type: object + required: + - value + properties: + value: + type: integer + links: + type: array + items: + type: string + '400': + description: Failure + content: + application/json: + schema: + type: object + required: + - error + properties: + error: + type: integer + links: + type: array + items: + type: string +``` +JSON +```json +200: +{ + "value": "", + "links": [{""},{"..."}] +} +400: +{ + "error": "", + "links": [{""},{"..."}] +} +``` + +**Operation:** POST +Updates an existing integer entry. This will fail if the integer entry does not yet exist. +**Request Body** +YAML +``` +required: true + content: + application/json: + schema: + type: object + required: + - value + properties: + value: + type: integer +``` +JSON +```json +{ + "value": "" +} +``` +**Response Body** +YAML +``` +responses: + '200': + description: Success + content: + application/json: + schema: + type: object + links: + type: array + items: + type: string + '400': + description: Failure + content: + application/json: + schema: + type: object + required: + - error + properties: + error: + type: integer + links: + type: array + items: + type: string +``` +JSON +```json +200: +{ + "links": [{""},{"..."}] +} +400: +{ + "error": "", + "links": [{""},{"..."}] +} +``` +**Operation:** PUT +Creates a new integer entry. This will fail if the integer entry already exists. +**Request Body** +YAML +``` +required: true + content: + application/json: + schema: + type: object + required: + - value + properties: + value: + type: integer +``` +JSON +```json +{ + "value": "" +} +``` +**Response Body** +YAML +``` +responses: + '200': + description: Success + content: + application/json: + schema: + type: object + properties: + links: + type: array + items: + type: string + '400': + description: Failure + content: + application/json: + schema: + type: object + required: + - error + properties: + error: + type: integer + links: + type: array + items: + type: string +``` +JSON +```json +200: +{ + "links": [{""},{"..."}] +} +400: +{ + "error": "", + "links": [{""},{"..."}] +} +``` +**Operation:** DELETE +Deletes an existing integer entry. This will fail if the integer entry does not already exist. +**Request Body** +None +**Response Body** +YAML +``` +responses: + '200': + description: Success + content: + application/json: + schema: + type: object + properties: + links: + type: array + items: + type: string + '400': + description: Failure + content: + application/json: + schema: + type: object + required: + - error + properties: + error: + type: integer + links: + type: array + items: + type: string +``` +JSON +```json +200: +{ + "links": [{""},{"..."}] +} +400: +{ + "error": "", + "links": [{""},{"..."}] +} +``` +## Decimal +**Operation:** GET +Fetches a decimal entry. This will fail if the decimal entry does not yet exist. +**Request Body** +None +**Response Body** +YAML +``` +responses: + '200': + description: successful operation + content: + application/json: + schema: + type: object + required: + - value + properties: + value: + type: double + links: + type: array + items: + type: string + '400': + description: Failure + content: + application/json: + schema: + type: object + required: + - error + properties: + error: + type: integer + links: + type: array + items: + type: string +``` +JSON +```json +200: +{ + "value": "", + "links": [{""},{"..."}] +} +400: +{ + "error": "", + "links": [{""},{"..."}] +} +``` +**Operation:** POST +Updates an existing decimal entry. This will fail if the decimal entry does not yet exist. +**Request Body** +YAML +``` +required: true + content: + application/json: + schema: + type: object + required: + - value + properties: + value: + type: double +``` +JSON +```json +{ + "value": "" +} +``` +**Response Body** +YAML +``` +responses: + '200': + description: Success + content: + application/json: + schema: + type: object + links: + type: array + items: + type: string + '400': + description: Failure + content: + application/json: + schema: + type: object + required: + - error + properties: + error: + type: integer + links: + type: array + items: + type: string +``` +JSON +```json +200: +{ + "links": [{""},{"..."}] +} +400: +{ + "error": "", + "links": [{""},{"..."}] +} +``` +**Operation:** PUT +Creates a new decimal entry. This will fail if the decimal entry already exists. +**Request Body** +YAML +``` +required: true + content: + application/json: + schema: + type: object + required: + - value + properties: + value: + type: double +``` +JSON +```json +{ + "value": "" +} +``` +**Response Body** +YAML +``` +responses: + '200': + description: Success + content: + application/json: + schema: + type: object + properties: + links: + type: array + items: + type: string + '400': + description: Failure + content: + application/json: + schema: + type: object + required: + - error + properties: + error: + type: integer + links: + type: array + items: + type: string +``` +JSON +```json +200: +{ + "links": [{""},{"..."}] +} +400: +{ + "error": "", + "links": [{""},{"..."}] +} +``` +**Operation:** DELETE +Deletes an existing decimal entry. This will fail if the decimal entry does not already exist. +**Request Body** +None +**Response Body** +YAML +``` +responses: + '200': + description: Success + content: + application/json: + schema: + type: object + properties: + links: + type: array + items: + type: string + '400': + description: Failure + content: + application/json: + schema: + type: object + required: + - error + properties: + error: + type: integer + links: + type: array + items: + type: string +``` +JSON +```json +200: +{ + "links": [{""},{"..."}] +} +400: +{ + "error": "", + "links": [{""},{"..."}] +} +``` +## String +**Operation:** GET +Fetches a string entry. This will fail if the string entry does not yet exist +**Request Body** +None +**Response Body** +YAML +``` +responses: + '200': + description: successful operation + content: + application/json: + schema: + type: object + required: + - value + properties: + value: + type: string + links: + type: array + items: + type: string + '400': + description: Failure + content: + application/json: + schema: + type: object + required: + - error + properties: + error: + type: integer + links: + type: array + items: + type: string +``` +JSON +```json +200: +{ + "value": "", + "links": [{""},{"..."}] +} +400: +{ + "error": "", + "links": [{""},{"..."}] +} +``` + +**Operation:** POST +Updates an existing string entry. This will fail if the string entry does not yet exist. +**Request Body** +YAML +``` +required: true + content: + application/json: + schema: + type: object + required: + - value + properties: + value: + type: string +``` +JSON +```json +{ + "value": "" +} +``` +**Response Body** +YAML +``` +responses: + '200': + description: Success + content: + application/json: + schema: + type: object + links: + type: array + items: + type: string + '400': + description: Failure + content: + application/json: + schema: + type: object + required: + - error + properties: + error: + type: integer + links: + type: array + items: + type: string +``` +JSON +```json +200: +{ + "links": [{""},{"..."}] +} +400: +{ + "error": "", + "links": [{""},{"..."}] +} +``` +**Operation:** PUT +Creates a new string entry. This will fail if the string entry already exists. +**Request Body** +YAML +``` +required: true + content: + application/json: + schema: + type: object + required: + - value + properties: + value: + type: string +``` +JSON +```json +{ + "value": "" +} +``` +**Response Body** +YAML +``` +responses: + '200': + description: Success + content: + application/json: + schema: + type: object + properties: + links: + type: array + items: + type: string + '400': + description: Failure + content: + application/json: + schema: + type: object + required: + - error + properties: + error: + type: integer + links: + type: array + items: + type: string +``` +JSON +```json +200: +{ + "links": [{""},{"..."}] +} +400: +{ + "error": "", + "links": [{""},{"..."}] +} +``` +**Operation:** DELETE +Deletes an existing string entry. This will fail if the string entry does not already exist. +**Request Body** +None +**Response Body** +YAML +``` +responses: + '200': + description: Success + content: + application/json: + schema: + type: object + properties: + links: + type: array + items: + type: string + '400': + description: Failure + content: + application/json: + schema: + type: object + required: + - error + properties: + error: + type: integer + links: + type: array + items: + type: string +``` +JSON +```json +200: +{ + "links": [{""},{"..."}] +} +400: +{ + "error": "", + "links": [{""},{"..."}] +} +``` diff --git a/versions/0.0.2/lights.md b/versions/0.0.2/lights.md new file mode 100644 index 0000000..5f94ea8 --- /dev/null +++ b/versions/0.0.2/lights.md @@ -0,0 +1,355 @@ +# Purpose + +This specification is intended to define a standardized way of communicating with lighting systems for real-time monitoring and control and to allow data collection between control systems and / or peripheral devices. + +**NOTE:** need to add API to query last-known update...identify what was done and when (and by whom?) + +# Scope + +The scope of this document is limited to providing a payload structure and endpoint type definitions to allow basic control and data acquisition. The addition of product specific features is left to the implementer, but to be in compliance the product must support the basic set of features specified below. + +# Definitions + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. + +# Endpoints +## Sensors +### Talking to one sensor +**Retrieving ID information** +``` +GET http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/info +``` +Returns [Info](general.md#info-data) + +**Sending ID information** +``` +POST http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/info +``` +Sends [Info](general.md#info-data) + +**Retrieving version information** +``` +GET http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/version +``` +Returns [Version](general.md#version-data) + +**Retrieving location information** +``` +GET http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/location +``` +Returns [Location](general.md#location-data) + +**Sending location information** +``` +POST http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/location +``` +Sends [Location](general.md#location-data) + +**Retrieving spectrum measurements as PPF** +``` +GET http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/ppf +``` +Returns [Light PPF](lights.md#light-ppf) + +**Retrieving spectrum measurements as PPFD** +``` +GET http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/ppfd +``` +Returns [Light PPFD](lights.md#light-ppfd) + +### Talking to all sensors +**Retrieving ID information** +``` +GET http://[domain:port]/agroapi/[version]/lights/sensors/info +``` +Returns an array of [Info](general.md#info-data) + +**Sending ID information** +``` +POST http://[domain:port]/agroapi/[version]/lights/sensors/info +``` +Sends an array of [Info](general.md#info-data) + +**Retrieving version information** +``` +GET http://[domain:port]/agroapi/[version]/lights/sensors/version +``` +Returns an array of [Version](general.md#version-data) + +**Retrieving location information** +``` +GET http://[domain:port]/agroapi/[version]/lights/sensors/location +``` +Returns an array of [Location](general.md#location-data) + +**Sending location information** +``` +POST http://[domain:port]/agroapi/[version]/lights/sensors/location +``` +Sends an array of [Location](general.md#location-data) + +**Retrieving spectrum measurements as PPF** +``` +GET http://[domain:port]/agroapi/[version]/lights/sensors/ppf +``` +Returns an array of [Light PPF](lights.md#light-ppf) + +**Retrieving spectrum measurements as PPFD** +``` +GET http://[domain:port]/agroapi/[version]/lights/sensors/ppfd +``` +Returns an array of [Light PPFD](lights.md#light-ppfd) + +### Talking to all sensors in a zone +**Retrieving ID information** +``` +GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/info +``` +Returns an array of [Info](general.md#info-data) + +**Sending ID information** +``` +POST http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/info +``` +Sends an array of [Info](general.md#info-data) + +**Retrieving version information** +``` +GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/version +``` +Returns an array of [Version](general.md#version-data) + +**Retrieving location information** +``` +GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/location +``` +Returns an array of [Location](general.md#location-data) + +**Sending location information** +``` +POST http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/location +``` +Sends an array of [Location](general.md#location-data) + +**Retrieving spectrum measurements as PPF** +``` +GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/ppf +``` +Returns an array of [Light PPF](lights.md#light-ppf) + +**Retrieving spectrum measurements as PPFD** +``` +GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/ppfd +``` +Returns an array of [Light PPFD](lights.md#light-ppfd) + +### Light PPF +| Name | Description | Unit | +| --------- | -------------------------------- | -------- | +| id | Unique id of the device | uid | +| timestamp | UTC timestamp of the measurement | datetime | +| red | Level of red spectrum light | PPF | +| blue | Level of blue spectrum light | PPF | +| green | Level of green spectrum light | PPF | +| uv | Level of ultraviolet light | PPF | +| infrared | Level of infrared light | PPF | +| par | Level of absorbable light | PPF | +| light | Level of all spectrums of light | PPF | + +### Light PPFD +| Name | Description | Unit | +| --------- | -------------------------------- | -------- | +| id | Unique id of the device | uid | +| timestamp | UTC timestamp of the measurement | datetime | +| red | Level of red spectrum light | PPFD | +| blue | Level of blue spectrum light | PPFD | +| green | Level of green spectrum light | PPFD | +| uv | Level of ultraviolet light | PPFD | +| infrared | Level of infrared light | PPFD | +| par | Level of absorbable light | PPFD | +| light | Level of all spectrums of light | PPFD | + +## Fixtures +### Talking to one fixture +**Retrieving ID information** +``` +GET http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/info +``` +Returns [Info](general.md#info-data) + +**Sending ID information** +``` +POST http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/info +``` +Sends [Info](general.md#info-data) + +**Retrieving version information** +``` +GET http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/version +``` +Returns [Version](general.md#version-data) + +**Retrieving location information** +``` +GET http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/location +``` +Returns [Location](general.md#location-data) + +**Sending location information** +``` +POST http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/location +``` +Sends [Location](general.md#location-data) + +**Retrieving configuration information** +``` +GET http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/config +``` +Returns [Fixture Configuration](lights.md#fixture-configuration) + +**Sending configuration information** +``` +POST http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/config +``` +Sends [Fixture Configuration](lights.md#fixture-configuration) + +**Retrieving power state information** +``` +GET http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/power +``` +Returns [Fixture Power](lights.md#fixture-power) + +**Sending power state information** +``` +POST http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/power +``` +Sends [Fixture Power](lights.md#fixture-power) + +### Talking to all fixtures +**Retrieving ID information** +``` +GET http://[domain:port]/agroapi/[version]/lights/fixtures/info +``` +Returns an array of [Info](general.md#info-data) + +**Sending ID information** +``` +POST http://[domain:port]/agroapi/[version]/lights/fixtures/info +``` +Sends an array of [Info](general.md#info-data) + +**Retrieving version information** +``` +GET http://[domain:port]/agroapi/[version]/lights/fixtures/version +``` +Returns an array of [Version](general.md#version-data) + +**Retrieving location information** +``` +GET http://[domain:port]/agroapi/[version]/lights/fixtures/location +``` +Returns an array of [Location](general.md#location-data) + +**Sending location information** +``` +POST http://[domain:port]/agroapi/[version]/lights/fixtures/location +``` +Sends an array of [Location](general.md#location-data) + +**Retrieving configuration information** +``` +GET http://[domain:port]/agroapi/[version]/lights/fixtures/config +``` +Returns an array of [Fixture Configuration](lights.md#fixture-configuration) + +**Sending configuration information** +``` +POST http://[domain:port]/agroapi/[version]/lights/fixtures/config +``` +Sends an array of [Fixture Configuration](lights.md#fixture-configuration) + +**Retrieving power state information** +``` +GET http://[domain:port]/agroapi/[version]/lights/fixtures/power +``` +Returns an array of [Fixture Power](lights.md#fixture-power) + +**Sending power state information** +``` +POST http://[domain:port]/agroapi/[version]/lights/fixtures/power +``` +Sends an array of [Fixture Power](lights.md#fixture-power) + +### Talking to all fixtures in a zone +**Retrieving ID information** +``` +GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/info +``` +Returns an array of [Info](general.md#info-data) + +**Sending ID information** +``` +POST http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/info +``` +Sends an array of [Info](general.md#info-data) + +**Retrieving version information** +``` +GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixture/[fixtureid]/version +``` +Returns an array of [Version](general.md#version-data) + +**Retrieving location information** +``` +GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/location +``` +Returns an array of [Location](general.md#location-data) + +**Sending location information** +``` +POST http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/location +``` +Sends an array of [Location](general.md#location-data) + +**Retrieving configuration information** +``` +GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/config +``` +Returns an array of [Fixture Configuration](lights.md#fixture-configuration) + +**Sending configuration information** +``` +POST http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/config +``` +Sends an array of [Fixture Configuration](lights.md#fixture-configuration) + +**Retrieving power state information** +``` +GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/power +``` +Returns an array of [Fixture Power](lghts.md#fixture-power) + +**Sending power state information** +``` +POST http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/power +``` +Sends an array of [Fixture Power](lghts.md#fixture-power) + +### Fixture Configuration +| Name | Description | Unit | +| -------- | ------------------------------- | ----- | +| id | Unique id of the fixture | uid | +| channels | array of channel configurations | [Channel Configuration](lights.md#channel-configuration) | +### Channel Configuration +| Name | Description | Unit | +| ----------- | --------------------------------------------------------- | ---------- | +| id | Unique id of the channel | uid | +| lo-color | Lower boundary of the frequency range for a color channel | nm | +| hi-color | Upper boundary of the frequency range for a color channel | nm | +| cct | Color temperature for a white channel | K (Kelvin) | +| intensity | Light intensity | % | +### Fixture Power +| Name | Description | Unit | +| ------ | ------------------------------ | ------------- | +| id | Unique id of the fixture | uid | +| status | The active state of the lights | "on" or "off" | diff --git a/versions/0.0.2/nutrients.md b/versions/0.0.2/nutrients.md new file mode 100644 index 0000000..7757c01 --- /dev/null +++ b/versions/0.0.2/nutrients.md @@ -0,0 +1,31 @@ +# Purpose + +This specification is intended to define a standardized way of communicating with climate control systems for real-time monitoring and control of root systems and to allow data collection between systems and / or peripheral devices. + +# Scope + +The scope of this document is limited to providing a payload structure and endpoint type definitions to allow basic control and data acquisition. The addition of product specific features is left to the implementer, but to be in compliance the product must support the basic set of features specified below. + +# Definitions + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. + +# Endpoints +## Sensors +### URLS +### Measurements +| Data point | Description | Unit | +| ---------- | ----------------------------- | ---- | +| nitrogen | The amount of nitrogen (N) | ppm | +| phosphorus | The amount of phosphorus (P) | ppm | +| potassium | The amount of potassium (K) | ppm | +| sulphur | The amount of sulfur (S) | ppm | +| calcium | The amount of calcium (Ca) | ppm | +| magnesium | The amount of magnesium (Mg) | ppm | +| iron | The amount of iron (Fe) | ppm | +| manganese | The amount of manganese (Mg) | ppm | +| boron | The amount of boron (B) | ppm | +| copper | The amount of copper (Cu) | ppm | +| zinc | The amount of zinc (Zn) | ppm | +| molybdenum | The amount of molybdenum (Mo) | ppm | +| ammonium | The amount of ammonium (NH4+) | ppm | diff --git a/versions/0.0.2/plan.md b/versions/0.0.2/plan.md new file mode 100644 index 0000000..bc0c163 --- /dev/null +++ b/versions/0.0.2/plan.md @@ -0,0 +1,118 @@ +# Purpose + +This specification is intended to define a standardized way of communicating with facility planning systems for planning the layout of a facility and the deployment of monitoring and control systems. + +# Scope + +The scope of this document is limited to providing a payload structure and endpoint type definitions to allow basic control and data acquisition. The addition of product specific features is left to the implementer, but to be in compliance the product must support the basic set of features specified below. + +# Definitions + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. + +# Endpoints +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 interact with a Plan. + +## Facilities +### All facilities +``` +GET http://[domain:port]/agroapi/[version]/plan/facilities +``` +Returns an array of Facility IDs + +### Single facility +``` +GET http://[domain:port]/agroapi/[version]/plan/facilities/[facilityid]/compartments +``` +Returns an array of Compartment IDs + +``` +GET http://[domain:port]/agroapi/[version]/plan/facilities/[facilityid]/zones +``` +Returns an array of Zone IDs + +## Compartments +### All compartments +``` +GET http://[domain:port]/agroapi/[version]/plan/compartments +``` +Returns an array of Compartment IDs + +``` +GET http://[domain:port]/agroapi/[version]/plan/compartments/info +``` +Returns an array of [Info](general.md#info-data) + +``` +GET http://[domain:port]/agroapi/[version]/plan/compartments/location +``` +Returns an array of [Location](general.md#location-data) +``` +GET http://[domain:port]/agroapi/[version]/plan/compartments/dimensions +``` +Returns an array of [Dimensions](general.md#dimension-data) + + +### Single compartment +``` +GET http://[domain:port]/agroapi/[version]/plan/compartments/[compartmentid]/info +``` +Returns [Info](general.md#info-data) + +``` +GET http://[domain:port]/agroapi/[version]/plan/compartments/[compartmentid]/location +``` +Returns [Location](general.md#location-data) + +``` +GET http://[domain:port]/agroapi/[version]/plan/compartments/[compartmentid]/dimensions +``` +Returns [Dimensions](general.md#dimension-data) + +``` +GET http://[domain:port]/agroapi/[version]/plan/compartment/[compartmentid]/zones +``` +Returns an array of [Info](general.md#info-data) + +## Zones +### All zones +``` +GET http://[domain:port]/agroapi/[version]/plan/zones/info +``` +Returns an array of [Info](general.md#info-data) + +``` +GET http://[domain:port]/agroapi/[version]/plan/zones/location +``` +Returns an array of [Location](general.md#location-data) + +``` +GET http://[domain:port]/agroapi/[version]/plan/zones/dimensions +``` +Returns an array of [Dimensions](general.md#dimension-data) + +### Single zone +``` +GET http://[domain:port]/agroapi/[version]/plan/zones/[zoneid]/info +``` +Returns [Info](general.md#info-data) + +``` +GET http://[domain:port]/agroapi/[version]/plan/zones/[zoneid]/location +``` +Returns [Location](general.md#location-data) + +``` +GET http://[domain:port]/agroapi/[version]/plan/zones/[zoneid]/dimensions +``` +Returns [Dimensions](general.md#dimension-data) + +``` +GET http://[domain:port]/agroapi/[version]/plan/zones/[zoneid]/zones +``` +Returns an array of Zone IDs + +``` +GET http://[domain:port]/agroapi/[version]/plan/zones/[zoneid]/crops +``` +Returns an array of Crop Variety IDs diff --git a/versions/0.0.2/reservoirs.md b/versions/0.0.2/reservoirs.md new file mode 100644 index 0000000..5d799f1 --- /dev/null +++ b/versions/0.0.2/reservoirs.md @@ -0,0 +1,24 @@ +# Purpose + +This specification is intended to define a standardized way of communicating with climate control systems for real-time monitoring and control of reservoir systems and to allow data collection between systems and / or peripheral devices. + +# Scope + +The scope of this document is limited to providing a payload structure and endpoint type definitions to allow basic control and data acquisition. The addition of product specific features is left to the implementer, but to be in compliance the product must support the basic set of features specified below. + +# Definitions + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. + +# Endpoints +## Sensors +### URLS +### Measurements +| Data point | Description | Unit | +| ---------- | -------------------------------------------------------------- | ------- | +| water | The amount of the water in the reservoir | % | +| temp | The temperature of the water / air around the roots | celsius | +| turbidity | The level of solids in the water | ntu | +| oxygen | The amount of oxygen dissolved in the water** around the roots | ppm | +| ec | The electrical conductivity of the water | Ds / m | +| ph | The alkalinity of the water | n/a | diff --git a/versions/0.0.2/roots.md b/versions/0.0.2/roots.md new file mode 100644 index 0000000..ad1dba4 --- /dev/null +++ b/versions/0.0.2/roots.md @@ -0,0 +1,27 @@ +# Purpose + +This specification is intended to define a standardized way of communicating with climate control systems for real-time monitoring and control of root systems and to allow data collection between systems and / or peripheral devices. + +# Scope + +The scope of this document is limited to providing a payload structure and endpoint type definitions to allow basic control and data acquisition. The addition of product specific features is left to the implementer, but to be in compliance the product must support the basic set of features specified below. + +# Definitions + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. + +# Endpoints +## Sensors +### URLS +### Measurements +| Data point | Description | Unit | +| ---------- | ------------------------------------------------------------------------ | ------- | +| water | The amount of the water surrounding the roots (aquaponics & hydroponics) | % | +| light | The level of all spectrums of light | µmoles | +| temp | The temperature of the water / air around the roots | celsius | +| humidity | The level of humidity around the roots (for airponics) | % | +| oxygen | The amount of oxygen dissolved in the water** around the roots | ppm | +| ec | The electrical conductivity of the water** around the roots | Ds / m | +| ph | The alkalinity of the water** around the roots | n/a | + +**NOTE:** for airponics, water levels would be measured from the moisture in the air around the roots diff --git a/versions/0.0.2/soil.md b/versions/0.0.2/soil.md new file mode 100644 index 0000000..980da37 --- /dev/null +++ b/versions/0.0.2/soil.md @@ -0,0 +1,25 @@ +# Purpose + +This specification is intended to define a standardized way of communicating with soil systems for real-time monitoring and control and to allow data collection between control systems and / or peripheral devices. + +# Scope + +The scope of this document is limited to providing a payload structure and endpoint type definitions to allow basic control and data acquisition. The addition of product specific features is left to the implementer, but to be in compliance the product must support the basic set of features specified below. + +# Definitions + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. + +# Endpoints +## Sensors +### URLS +### Measurements +| Data point | Description | Unit | +| ------------- | ----------------------------------------------------------------------- | ---------- | +| heatflow | The amount of heat that transfers from one point in the soil to another | watts / m2 | +| h2o-retention | The rate at which water dissipates from the soil | ??? | +| soil-temp | The temperature of the soil | celsius | +| humidity | The amount of humidity in the soil | % | +| oxygen | The amount of oxygen dissolved in the soil | % | +| ec | The electrical conductivity of the soil | Ds / m | +| ph | The alkalinity of the soil | n/a | diff --git a/versions/master/air.md b/versions/master/air.md index 5ef9a20..d8660f5 100644 --- a/versions/master/air.md +++ b/versions/master/air.md @@ -1,4 +1,14 @@ -# Examples: Air +# Purpose + +This specification is intended to define a standardized way of communicating with climate control systems for real-time monitoring and control of air quality and to allow data collection between control systems and / or peripheral devices. + +# Scope + +The scope of this document is limited to providing a payload structure and endpoint type definitions to allow basic control and data acquisition. The addition of product specific features is left to the implementer, but to be in compliance the product must support the basic set of features specified below. + +# Definitions + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. # Endpoints ## Sensors @@ -9,4 +19,4 @@ | temp | The temperature of the air | celsius | | humidity | The level of humidity in the air | % | | co2 | The level of CO2 in the air | ppm | -| airflow | The speed of the airflow | m3/s | +| airflow | The speed of the airflow | m3/s | \ No newline at end of file diff --git a/versions/master/general.md b/versions/master/general.md index 7d6ffb4..a6490f2 100644 --- a/versions/master/general.md +++ b/versions/master/general.md @@ -1,8 +1,21 @@ -# Examples: General +# Purpose -The diagram below captures a common structure of a company with several facilities. This document gives examples on a way in which the API could be implemented within that system. +This specification is intended to define a standardized way of communicating real-time command-and-control data and to allow data collection between control systems and / or peripheral devices. -![Common Structure](https://docs.google.com/drawings/d/e/2PACX-1vRptSa5X7K6yzOqA95Jpncwwl8rUZgxOo6l13m_VcnCyd5dHmlLZvUyrED-HX2b5Q9YNHiBltB6cY5t/pub?w=982&h=1042) +# Scope + +The scope of this document is limited to providing a payload structure and endpoint type definitions to allow basic control and data acquisition. This document does not set out to define an API but rather to specify a uniform way to build one. It does not seek to dictate endpoint names, server architecture, or security protocols. The addition of product specific features is left to the implementer, but to be in compliance the product must support the basic set of features specified below. + +# Definitions + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. + +# Common Concepts + +There are specific concepts that all participants in this open API must support in order to make interaction possible. Each of these concepts should be driven by factory configurations or by on-site configurations made by the customer or a professional integrator. +The diagram below captures their essential relationships. + +![Common Concepts](https://docs.google.com/drawings/d/e/2PACX-1vRptSa5X7K6yzOqA95Jpncwwl8rUZgxOo6l13m_VcnCyd5dHmlLZvUyrED-HX2b5Q9YNHiBltB6cY5t/pub?w=982&h=1042) ## Company @@ -30,9 +43,9 @@ A zone identifies an area within a compartment dedicated to maintaining a micro- Every zone contains zero or more zones and / or devices. Every device that is deployed should be assigned to the correct zone. Zones are a natural way of grouping devices for control purposes, so that a configuration can be pushed to a zone and affect all relevant devices within the zone at the same time. -In this example, zones identify the crop variety they are overseeing, and include a crop variety ID for easy identification. +All zones must be able to identify the crop variety they are overseeing. All data produced from a zone must include a crop variety ID for easy identification. -Each zone identifies its size (in width and height) as well as its relative location within the compartment, since all sensors and controllers within that zone will report their location relative to the zone, not the compartment. +Each zone must be able to identify its size (in width and height) as well as its relative location within the compartment, since all sensors and controllers within that zone will report their location relative to the zone, not the compartment. Zones can be combined into deep hierarchies. For example, a compartment can have multiple rows of plants that are 1 foot off the floor (e.g., lettuce), with an additional layer of plants 4 feet off the floor (e.g., strawberries). The grower would want to create unique zones for the lettuce vs. the strawberries, reflecting their unique feeds for irrigation and supplemental lighting. However, the grower would also want to maintain a general climate zone for the overall compartment for the purposes of controlling heating and ventilation. This means that the compartment would have a global zone containing two sub-zones. @@ -44,7 +57,7 @@ Every device and zone should know its position relative to its container (device A device refers to any physical mechanism that can either monitor or control the growing environment (lights, pumps, heaters, humidifiers, etc). -In the example, every device is related to a zone and a location within that zone. It should be able to report these relationships along with its own unique ID. +Every device must be related to a zone and a location within that zone. It should be able to report these relationships along with its own unique ID. ## Sensor @@ -58,11 +71,128 @@ A controller refers to any device that can affect the growing environment (light The detailed endpoint structure is outside the scope of this document because it needs to make sense for the overall architecture of the implementation. However, there are a few standards that need to be considered when it comes to endpoint design. +*Path elements within the URL...* +- The first element of all compliant apis MUST be "agroapi" +- The second element of all compliant apis MUST be the version number +- The third element of all compliant apis MUST be a domain identifier (e.g., "lights", "air", and so on) +- All elements after the third and before the final element are optional and SHOULD describe collections and / or a single member of a collection +- The final element of all compliant apis MUST identify the information or action that is the subject of the call + +*Structure of collections...* +- Collection identifiers MUST be plural +- Endpoints SHOULD NOT nest more than 2 collections deep (e.g., collection/{id}/collection/{id}) + +*Data structures...* +- Individual data points coming from the same device SHOULD be grouped in a structure with other data points that are related to the same topic **Example** GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?key=yourAPIKey +# Error Handling + +In principle, a successful API call should return an HTTP status code of 200. An unsuccessful API call will return an HTTP status code of 550 and the body should contain an error code that has been properly documented by the owner of the API. + +The interpretation of error codes, including the text describing the error, will be left up to the API user based on their understanding of the error code documentation provided by the API owner. + +# Validation Handshake + +*TBD* + +Although a data consumer / receiver will have its own limits when it comes to value ranges and so on, there is a perceived need for the consumer / receiver to know what value ranges the data producer / sender might provide. This gives the consumer / receiver a secondary validation check to ensure that the data makes sense. + +# Timestamps + +All monitoring data MUST be accompanied by a timestamp that includes year, month, day, hour, minute, second, and time zone. The format MUST be as follows… + +```[year]-[month]-[day]_[hour]-[min]-[sec]_[timezone]``` + +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 Data +| 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 Data +| 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 Data +| 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 | + +## Dimension Data +| 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 | + +# Data Types +## Boolean +Used to express T/F, Y/N, or ON/OFF values +```json +type: object + required: + - name + - status + properties: + status: + type: bool +``` +## Integer +Used to express whole 4-byte numbers +```json +type: object + required: + - name + - value + properties: + value: + type: integer +``` +## Decimal +Used to express numbers with 8-byte decimal precision +```json +type: object + required: + - name + - value + properties: + value: + type: number + format: double +``` +## String +Used to send alphanumeric strings +```json +type: object + required: + - name + - text + properties: + text: + type: string +``` + # Primitive Endpoints The following endpoints provide examples of payloads that would be exchanged for any endpoints that are trying to work with simple primitive values (e.g., a single number, boolean flag, or piece of text). diff --git a/versions/master/lights.md b/versions/master/lights.md index e0587d3..5f94ea8 100644 --- a/versions/master/lights.md +++ b/versions/master/lights.md @@ -1,84 +1,147 @@ -# Examples: Lights +# Purpose + +This specification is intended to define a standardized way of communicating with lighting systems for real-time monitoring and control and to allow data collection between control systems and / or peripheral devices. + +**NOTE:** need to add API to query last-known update...identify what was done and when (and by whom?) + +# Scope + +The scope of this document is limited to providing a payload structure and endpoint type definitions to allow basic control and data acquisition. The addition of product specific features is left to the implementer, but to be in compliance the product must support the basic set of features specified below. + +# Definitions + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. # Endpoints ## Sensors ### Talking to one sensor +**Retrieving ID information** ``` GET http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/info ``` -Returns [Info](README.md#info-data) +Returns [Info](general.md#info-data) +**Sending ID information** +``` +POST http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/info +``` +Sends [Info](general.md#info-data) + +**Retrieving version information** ``` GET http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/version ``` -Returns [Version](README.md#version-data) +Returns [Version](general.md#version-data) +**Retrieving location information** ``` GET http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/location ``` -Returns [Location](README.md#location-data) +Returns [Location](general.md#location-data) + +**Sending location information** +``` +POST http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/location +``` +Sends [Location](general.md#location-data) +**Retrieving spectrum measurements as PPF** ``` GET http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/ppf ``` -Returns [Light PPF](https://github.com/open-ag-tech/api-spec/blob/master/versions/light-0.0.1.md#light-ppf) +Returns [Light PPF](lights.md#light-ppf) +**Retrieving spectrum measurements as PPFD** ``` GET http://[domain:port]/agroapi/[version]/lights/sensors/[sensorid]/ppfd ``` -Returns [Light PPFD](https://github.com/open-ag-tech/api-spec/blob/master/versions/light-0.0.1.md#light-ppfd) +Returns [Light PPFD](lights.md#light-ppfd) ### Talking to all sensors +**Retrieving ID information** ``` GET http://[domain:port]/agroapi/[version]/lights/sensors/info ``` -Returns an array of [Info](README.md#info-data) +Returns an array of [Info](general.md#info-data) + +**Sending ID information** +``` +POST http://[domain:port]/agroapi/[version]/lights/sensors/info +``` +Sends an array of [Info](general.md#info-data) +**Retrieving version information** ``` GET http://[domain:port]/agroapi/[version]/lights/sensors/version ``` -Returns an array of [Version](README.md#version-data) +Returns an array of [Version](general.md#version-data) +**Retrieving location information** ``` GET http://[domain:port]/agroapi/[version]/lights/sensors/location ``` -Returns an array of [Location](README.md#location-data) +Returns an array of [Location](general.md#location-data) +**Sending location information** +``` +POST http://[domain:port]/agroapi/[version]/lights/sensors/location +``` +Sends an array of [Location](general.md#location-data) + +**Retrieving spectrum measurements as PPF** ``` GET http://[domain:port]/agroapi/[version]/lights/sensors/ppf ``` -Returns an array of [Light PPF](https://github.com/open-ag-tech/api-spec/blob/master/versions/light-0.0.1.md#light-ppf) +Returns an array of [Light PPF](lights.md#light-ppf) +**Retrieving spectrum measurements as PPFD** ``` 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/light-0.0.1.md#light-ppfd) +Returns an array of [Light PPFD](lights.md#light-ppfd) ### Talking to all sensors in a zone +**Retrieving ID information** ``` GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/info ``` -Returns an array of [Info](README.md#info-data) +Returns an array of [Info](general.md#info-data) + +**Sending ID information** +``` +POST http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/info +``` +Sends an array of [Info](general.md#info-data) +**Retrieving version information** ``` GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/version ``` -Returns an array of [Version](README.md#version-data) +Returns an array of [Version](general.md#version-data) +**Retrieving location information** ``` GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/location ``` -Returns an array of [Location](README.md#location-data) +Returns an array of [Location](general.md#location-data) +**Sending location information** +``` +POST http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/location +``` +Sends an array of [Location](general.md#location-data) + +**Retrieving spectrum measurements as PPF** ``` GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/sensors/ppf ``` -Returns an array of [Light PPF](https://github.com/open-ag-tech/api-spec/blob/master/versions/light-0.0.1.md#light-ppf) +Returns an array of [Light PPF](lights.md#light-ppf) +**Retrieving spectrum measurements as PPFD** ``` 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/light-0.0.1.md#light-ppfd) +Returns an array of [Light PPFD](lights.md#light-ppfd) ### Light PPF | Name | Description | Unit | @@ -108,95 +171,183 @@ Returns an array of [Light PPFD](https://github.com/open-ag-tech/api-spec/blob/m ## Fixtures ### Talking to one fixture +**Retrieving ID information** ``` GET http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/info ``` -Returns [Info](README.md#info-data) +Returns [Info](general.md#info-data) + +**Sending ID information** +``` +POST http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/info +``` +Sends [Info](general.md#info-data) +**Retrieving version information** ``` GET http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/version ``` -Returns [Version](README.md#version-data) +Returns [Version](general.md#version-data) +**Retrieving location information** ``` GET http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/location ``` -Returns [Location](README.md#location-data) +Returns [Location](general.md#location-data) + +**Sending location information** +``` +POST http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/location +``` +Sends [Location](general.md#location-data) +**Retrieving configuration information** ``` GET http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/config ``` -Returns [Fixture Configuration](https://github.com/open-ag-tech/api-spec/blob/master/versions/light-0.0.1.md#fixture-configuration) +Returns [Fixture Configuration](lights.md#fixture-configuration) +**Sending configuration information** +``` +POST http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/config +``` +Sends [Fixture Configuration](lights.md#fixture-configuration) + +**Retrieving power state information** ``` GET http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/power ``` -Returns [Fixture Power](https://github.com/open-ag-tech/api-spec/blob/master/versions/light-0.0.1.md#fixture-power) +Returns [Fixture Power](lights.md#fixture-power) + +**Sending power state information** +``` +POST http://[domain:port]/agroapi/[version]/lights/fixtures/[fixtureid]/power +``` +Sends [Fixture Power](lights.md#fixture-power) ### Talking to all fixtures +**Retrieving ID information** ``` GET http://[domain:port]/agroapi/[version]/lights/fixtures/info ``` -Returns an array of [Info](README.md#info-data) +Returns an array of [Info](general.md#info-data) +**Sending ID information** +``` +POST http://[domain:port]/agroapi/[version]/lights/fixtures/info +``` +Sends an array of [Info](general.md#info-data) + +**Retrieving version information** ``` GET http://[domain:port]/agroapi/[version]/lights/fixtures/version ``` -Returns an array of [Version](README.md#version-data) +Returns an array of [Version](general.md#version-data) +**Retrieving location information** ``` GET http://[domain:port]/agroapi/[version]/lights/fixtures/location ``` -Returns an array of [Location](README.md#location-data) +Returns an array of [Location](general.md#location-data) + +**Sending location information** +``` +POST http://[domain:port]/agroapi/[version]/lights/fixtures/location +``` +Sends an array of [Location](general.md#location-data) +**Retrieving configuration information** ``` GET http://[domain:port]/agroapi/[version]/lights/fixtures/config ``` -Returns an array of [Fixture Configuration](https://github.com/open-ag-tech/api-spec/blob/master/versions/light-0.0.1.md#fixture-configuration) +Returns an array of [Fixture Configuration](lights.md#fixture-configuration) + +**Sending configuration information** +``` +POST http://[domain:port]/agroapi/[version]/lights/fixtures/config +``` +Sends an array of [Fixture Configuration](lights.md#fixture-configuration) +**Retrieving power state information** ``` 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/light-0.0.1.md#fixture-power) +Returns an array of [Fixture Power](lights.md#fixture-power) + +**Sending power state information** +``` +POST http://[domain:port]/agroapi/[version]/lights/fixtures/power +``` +Sends an array of [Fixture Power](lights.md#fixture-power) ### Talking to all fixtures in a zone +**Retrieving ID information** ``` GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/info ``` -Returns an array of [Info](README.md#info-data) +Returns an array of [Info](general.md#info-data) + +**Sending ID information** +``` +POST http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/info +``` +Sends an array of [Info](general.md#info-data) +**Retrieving version information** ``` GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixture/[fixtureid]/version ``` -Returns an array of [Version](README.md#version-data) +Returns an array of [Version](general.md#version-data) +**Retrieving location information** ``` GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/location ``` -Returns an array of [Location](README.md#location-data) +Returns an array of [Location](general.md#location-data) +**Sending location information** +``` +POST http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/location +``` +Sends an array of [Location](general.md#location-data) + +**Retrieving configuration information** ``` GET http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/config ``` -Returns an array of [Fixture Configuration](https://github.com/open-ag-tech/api-spec/blob/master/versions/light-0.0.1.md#fixture-configuration) +Returns an array of [Fixture Configuration](lights.md#fixture-configuration) + +**Sending configuration information** +``` +POST http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/config +``` +Sends an array of [Fixture Configuration](lights.md#fixture-configuration) +**Retrieving power state information** ``` 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/light-0.0.1.md#fixture-power) +Returns an array of [Fixture Power](lghts.md#fixture-power) + +**Sending power state information** +``` +POST http://[domain:port]/agroapi/[version]/zones/[zoneid]/lights/fixtures/power +``` +Sends an array of [Fixture Power](lghts.md#fixture-power) ### Fixture Configuration | Name | Description | Unit | | -------- | ------------------------------- | ----- | | id | Unique id of the fixture | uid | -| channels | array of channel configurations | [Channel Configuration](https://github.com/open-ag-tech/api-spec/blob/master/versions/light-0.0.1.md#channel-configuration) | +| channels | array of channel configurations | [Channel Configuration](lights.md#channel-configuration) | ### Channel Configuration -| Name | Description | Unit | -| --------- | ------------------------------------- | ----- | -| id | Unique id of the channel | uid | -| lower | Lower boundary of the frequency range | nm | -| upper | Upper boundary of the frequency range | nm | -| intensity | Light intensity | % | +| Name | Description | Unit | +| ----------- | --------------------------------------------------------- | ---------- | +| id | Unique id of the channel | uid | +| lo-color | Lower boundary of the frequency range for a color channel | nm | +| hi-color | Upper boundary of the frequency range for a color channel | nm | +| cct | Color temperature for a white channel | K (Kelvin) | +| intensity | Light intensity | % | ### Fixture Power | Name | Description | Unit | | ------ | ------------------------------ | ------------- | diff --git a/versions/master/nutrients.md b/versions/master/nutrients.md index 8108c64..7757c01 100644 --- a/versions/master/nutrients.md +++ b/versions/master/nutrients.md @@ -1,4 +1,14 @@ -# Examples: Nutrients +# Purpose + +This specification is intended to define a standardized way of communicating with climate control systems for real-time monitoring and control of root systems and to allow data collection between systems and / or peripheral devices. + +# Scope + +The scope of this document is limited to providing a payload structure and endpoint type definitions to allow basic control and data acquisition. The addition of product specific features is left to the implementer, but to be in compliance the product must support the basic set of features specified below. + +# Definitions + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. # Endpoints ## Sensors diff --git a/versions/master/plan.md b/versions/master/plan.md index 553d0fb..bc0c163 100644 --- a/versions/master/plan.md +++ b/versions/master/plan.md @@ -1,7 +1,17 @@ -# Examples: Plan +# Purpose + +This specification is intended to define a standardized way of communicating with facility planning systems for planning the layout of a facility and the deployment of monitoring and control systems. + +# Scope + +The scope of this document is limited to providing a payload structure and endpoint type definitions to allow basic control and data acquisition. The addition of product specific features is left to the implementer, but to be in compliance the product must support the basic set of features specified below. + +# Definitions + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. # Endpoints -The relationship between the common concepts (facilities, compartments, zones, etc) is maintained as part of a Plan that can be interrogated. +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 interact with a Plan. ## Facilities ### All facilities @@ -31,71 +41,71 @@ Returns an array of Compartment IDs ``` GET http://[domain:port]/agroapi/[version]/plan/compartments/info ``` -Returns an array of [Info](README.md#info-data) +Returns an array of [Info](general.md#info-data) ``` GET http://[domain:port]/agroapi/[version]/plan/compartments/location ``` -Returns an array of [Location](README.md#location-data) +Returns an array of [Location](general.md#location-data) ``` GET http://[domain:port]/agroapi/[version]/plan/compartments/dimensions ``` -Returns an array of [Dimensions](README.md#dimension-data) +Returns an array of [Dimensions](general.md#dimension-data) ### Single compartment ``` GET http://[domain:port]/agroapi/[version]/plan/compartments/[compartmentid]/info ``` -Returns [Info](README.md#info-data) +Returns [Info](general.md#info-data) ``` GET http://[domain:port]/agroapi/[version]/plan/compartments/[compartmentid]/location ``` -Returns [Location](README.md#location-data) +Returns [Location](general.md#location-data) ``` GET http://[domain:port]/agroapi/[version]/plan/compartments/[compartmentid]/dimensions ``` -Returns [Dimensions](README.md#dimension-data) +Returns [Dimensions](general.md#dimension-data) ``` GET http://[domain:port]/agroapi/[version]/plan/compartment/[compartmentid]/zones ``` -Returns an array of [Info](README.md#info-data) +Returns an array of [Info](general.md#info-data) ## Zones ### All zones ``` GET http://[domain:port]/agroapi/[version]/plan/zones/info ``` -Returns an array of [Info](README.md#info-data) +Returns an array of [Info](general.md#info-data) ``` GET http://[domain:port]/agroapi/[version]/plan/zones/location ``` -Returns an array of [Location](README.md#location-data) +Returns an array of [Location](general.md#location-data) ``` GET http://[domain:port]/agroapi/[version]/plan/zones/dimensions ``` -Returns an array of [Dimensions](README.md#dimension-data) +Returns an array of [Dimensions](general.md#dimension-data) ### Single zone ``` GET http://[domain:port]/agroapi/[version]/plan/zones/[zoneid]/info ``` -Returns [Info](README.md#info-data) +Returns [Info](general.md#info-data) ``` GET http://[domain:port]/agroapi/[version]/plan/zones/[zoneid]/location ``` -Returns [Location](README.md#location-data) +Returns [Location](general.md#location-data) ``` GET http://[domain:port]/agroapi/[version]/plan/zones/[zoneid]/dimensions ``` -Returns [Dimensions](README.md#dimension-data) +Returns [Dimensions](general.md#dimension-data) ``` GET http://[domain:port]/agroapi/[version]/plan/zones/[zoneid]/zones diff --git a/versions/master/reservoirs.md b/versions/master/reservoirs.md index 0a6358d..5d799f1 100644 --- a/versions/master/reservoirs.md +++ b/versions/master/reservoirs.md @@ -1,4 +1,14 @@ -# Examples: Reservoirs +# Purpose + +This specification is intended to define a standardized way of communicating with climate control systems for real-time monitoring and control of reservoir systems and to allow data collection between systems and / or peripheral devices. + +# Scope + +The scope of this document is limited to providing a payload structure and endpoint type definitions to allow basic control and data acquisition. The addition of product specific features is left to the implementer, but to be in compliance the product must support the basic set of features specified below. + +# Definitions + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. # Endpoints ## Sensors diff --git a/versions/master/roots.md b/versions/master/roots.md index 00eb077..ad1dba4 100644 --- a/versions/master/roots.md +++ b/versions/master/roots.md @@ -1,4 +1,14 @@ -# Examples: Roots +# Purpose + +This specification is intended to define a standardized way of communicating with climate control systems for real-time monitoring and control of root systems and to allow data collection between systems and / or peripheral devices. + +# Scope + +The scope of this document is limited to providing a payload structure and endpoint type definitions to allow basic control and data acquisition. The addition of product specific features is left to the implementer, but to be in compliance the product must support the basic set of features specified below. + +# Definitions + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. # Endpoints ## Sensors diff --git a/versions/master/soil.md b/versions/master/soil.md index 89f87b9..980da37 100644 --- a/versions/master/soil.md +++ b/versions/master/soil.md @@ -1,4 +1,14 @@ -# Examples: Soil +# Purpose + +This specification is intended to define a standardized way of communicating with soil systems for real-time monitoring and control and to allow data collection between control systems and / or peripheral devices. + +# Scope + +The scope of this document is limited to providing a payload structure and endpoint type definitions to allow basic control and data acquisition. The addition of product specific features is left to the implementer, but to be in compliance the product must support the basic set of features specified below. + +# Definitions + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. # Endpoints ## Sensors