clean install

web/profiles/farm/docs/development/module/data_stream.md

@@ -0,0 +1,89 @@
+# Data Stream
+
+The data stream module provides a custom data stream entity for farmOS. Each
+data stream entity represents a time-series stream of data provided by a
+farmOS asset, such as Sensor or Equipment assets. Data streams can also specify
+any assets which their data is describing, such as a Plant, Animal or
+Land assets. Data streams are identified by a `UUID`, and have `private_key` and
+`public` fields to limit access to their data.
+
+Further functionality is provided by data stream types. Each type can provide a
+custom settings form, methods to retrieve and save data, methods for handling
+API requests, and custom display options. This allows custom data stream types
+to save data to the farmOS DB or request data from a third party API.
+
+## Using data stream types
+
+The data stream bundle plugin class can be accessed from a data stream entity
+with the `getPlugin()` method:
+
+```php
+// Load the data stream.
+$data_streams = $this->entityTypeManager()->getStorage('data_stream')->loadByProperties([
+  'uuid' => $uuid,
+]);
+
+// Bail if UUID is not found.
+if (empty($data_streams)) {
+  return;
+}
+
+/** @var \Drupal\data_stream\Entity\DataStreamInterface $data_stream */
+$data_stream = reset($data_streams);
+
+// Get the data stream plugin.
+$plugin = $data_stream->getPlugin();
+
+// Access methods on the plugin.
+// Available methods will vary depending on type.
+$data = $plugin->storageGet();
+```
+
+## Core data stream types
+
+### Basic data stream
+
+The data stream module provides a `basic` data stream type. Basic data streams
+receive data via the farmOS API and save data to the farmOS SQL database. Each
+basic data stream represents a single "value"; a sensor that records
+temperature and humidity would provide two data streams. Data can be accessed
+via the API with the `private_key`, or by anyone if the data stream is set to
+`public`. Basic data streams also provide simple ways to view data in a
+table or graph, and export as CSV.
+
+### Listener (Legacy) data stream
+
+The `farm_sensor_listener` module provides a `legacy_listener` data stream type
+that is compatible with the Listener sensor type from farmOS 1.x. It is
+similar to the `basic` type but has a few differences:
+
+- Each data stream saves multiple values (eg: temperature and humidity are
+  saved to the same data stream)
+- A `public_key` attribute identifies the data stream instead of a `UUID`.
+- It responds to the legacy API endpoint at `/farm/sensor/listener/{public_key}`
+  (to match farmOS 1.x).
+
+## Custom data stream types
+
+Custom data stream types can be created to integrate with data stored outside
+of farmOS (such as time-series databases or 3rd party APIs), provide advanced
+views of data, and other custom behavior.
+
+Data stream types can be provided by adding two files to a module:
+
+1. An entity type config file (YAML), and:
+2. A bundle plugin class (PHP).
+
+For more information see [Entity Types](/development/module/entities).
+
+### Data stream bundle plugin
+
+Data stream bundle plugins must implement the `DataStreamTypeInterface`. The
+`DataStreamTypeBase` class can be used as starting point.
+
+Plugins can optionally implement the `DataStreamStorageInterface` and the
+`DataStreamApiInterface` to adhere to a common interface other data stream
+types might use.
+
+See the "Basic" data stream bundle plugin as an example
+(`Drupal\data_stream\Plugin\DataStream\DataStreamType\Basic`).