diff --git a/docs/model/type/asset.md b/docs/model/type/asset.md index 690c3f0cc..bbb75ddc4 100644 --- a/docs/model/type/asset.md +++ b/docs/model/type/asset.md @@ -260,6 +260,11 @@ Plant Assets have the following additional relationships: - Plant type (references a Term in the "Plant type" vocabulary) - Season (references a Term in the "Season" vocabulary) +#### Sensor Assets + +Sensor Assets have an additional "Data streams" relationship, which is used to +reference [Data Streams](/model/type/data-stream) associated with the sensor. + #### Structure Assets Structure Assets have the following additional attributes: diff --git a/docs/model/type/data_stream.md b/docs/model/type/data_stream.md new file mode 100644 index 000000000..eacccf4f0 --- /dev/null +++ b/docs/model/type/data_stream.md @@ -0,0 +1,101 @@ +# Data Streams + +Data Streams are records that represent sets of data streamed from sensors or +other real-world devices. + +## Type + +Each Data Stream must have a type. All Asset types have a common set of +attributes and relationships. Specific Data Stream types may also add +additional attributes and relationships (collectively referred to as "fields"). +Data Stream types are defined by modules, and are only available if their +module is enabled. The modules included with farmOS define the following Data +Stream types: + +- Basic +- Listener (Legacy) + +## ID + +Each Data Stream will be assigned two unique IDs in the database: a universally +unique identifier (UUID), and an internal numeric ID. + +The UUID will be unique **across** farmOS databases. The internal ID will only +be unique to a **single** farmOS database. Therefore, the farmOS API uses UUIDs +to ensure that IDs pulled from multiple farmOS databases do not conflict. +Internally, farmOS modules use the internal IDs to perform CRUD operations. + +## Attributes + +Data Streams have a number of attributes that serve to describe their meta +information. All Data Stream have the same standard set of attributes. Modules +can add additional attributes. + +### Standard attributes + +Attributes that are common to all Data Stream types include: + +- Name +- Private key +- Public + +#### Name + +Data Streams must have a name that describes them. The name is used in lists of +Data Streams to easily identify them at quick glance. + +#### Private key + +A Data Stream's private key is the password used to post data to (and get data +from) its API endpoint. + +#### Public + +A Data Stream may be marked as "public" to allow read-access from the API +without a private key. This is useful for loading data into public +third-party apps or scripts, for graphing or other purposes. Data Streams +are not public by default. + +## Relationships + +Data Streams can be related to other records in farmOS These relationships are +stored as reference fields on Data Stream records. + +All Data Streams have the same standard set of relationships. Modules can add +additional relationships. + +Relationships that are common to all Data Streams types include: + +- Assets + +#### Assets + +Data Streams can reference one or more Assets to indicate that the data they +collect is directly relevant to them. + +For example, if a soil moisture sensor that is installed in a field can be +represented with a Sensor Asset (for the soil moisture sensor device itself), +with a Data Stream (soil moisture data readings), that reference a Land Asset +(the field it is installed in). This makes it possible for a single device to +be moved/reused for monitoring multiple Assets, by moving the Sensor Asset +and creating new Data Streams. + +## Type-specific fields + +In addition to the fields that are common to all Data Stream types described +above, some types add additional type-specific fields. These include: + +#### Basic Data Streams + +Basic Data Streams do not define any type-specific fields. + +#### Listener (Legacy) Data Streams + +Listener (Legacy) Data Streams have an additional "public key" attribute, +which is used in the Data Stream's API endpoint for posting/getting data. This +was used in farmOS 1.x to provide a unique ID for the sensor, separate from the +Sensor Asset ID that housed the data. This is no longer needed in farmOS 2.x, +because each Data Stream has its own UUID, which is used in the API endpoints +instead. The public key is retained for Legacy (Listener) Data Streams to +ensure that existing sensors can continue to push data without needing to be +reconfigured. diff --git a/mkdocs.yml b/mkdocs.yml index 7c0d8b77a..beb295130 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,6 +6,7 @@ nav: - Assets: model/type/asset.md - Logs: model/type/log.md - Quantities: model/type/quantity.md + - Data streams: model/type/data_stream.md - Terms: model/type/term.md - Plans: model/type/plan.md - Users: model/type/user.md