farmOS
Demo farmOS

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:

// 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.

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).