Data Concepts and Terminology
The AstroPlant stack consists of multiple modules working together. There are some important concepts to understand, in order to know how to use the system, to know what AstroPlant can and can't do, and to know how to interpret the data.
A "kit" corresponds to a single computer that is monitoring and maybe even controlling an environment. Usually, this computer would be a low-power Linux system, such as Raspbian on a Raspberry Pi. To achieve this, the computer has some number of sensors and actuators connected to it—in the case of a Raspberry Pi, probably through using the general-purpose input/output to directly talk to the devices on a hardware level.
The core of the software (source code available here) running on such a kit computer actually does not know much about the sensors and actuators, it only knows about "peripherals."
A "peripheral" corresponds to a device that can be connected to a kit. This will usually be a sensor (such as a thermometer) or an actuator (such as a heating unit). There are many different types of such devices available. The goal of our definition of "Peripheral" is to abstract away all the specific details: as far as the kit is concerned, a peripheral can be executed (and it might produce some measurements or other media like images) and/or it can accept commands (such as "start heating").
To actually be able to use such a device, there is software on the kit computer that knows how to talk with the device. The core of the kit software uses this software. The AstroPlant team provides the software for the sensors and actuators used in the official AstroPlant project (for which the source code is available here). However, anyone with background in programming and hardware can implement the needed software to use a new peripheral device.
A "measurement" is some data that can be produced by a peripheral (such peripherals would usually be called sensors, but note that the system itself does not distinguish between sensors and actuators). For a thermometer, the produced measurements could e.g. be the temperature in degree Celsius, whereas a barometer might produce relative humidity, temperature in degree Celsius and pressure in Pascal.
In terms of data, one measurement is always a simple decimal value (technically, a 64-bit floating-point number) with an associated physical quantity (e.g. "Temperature") and a physical unit (e.g. "Degree Celsius").
Some peripherals might produce many measurements, whereas other peripherals might only make measurements occasionally. To this end, the core kit software collects a peripheral's measurements over a time window and turns them into "aggregate measurements."
An "aggregate measurement" consists of some summary statistics of the measured values, usually made over a time window of tens of minutes. Normally this will be the average, minimum and maximum of the measured values, as well as the count of measurements included in this aggregate. Measurements are aggregated individually for each type of measurement (physical quantity + physical unit) made by each separate peripheral.
For analyzing your data, the aggregated average over the time windows will usually be the most interesting value: the non-aggregate measurements tend to be made very often (e.g. every few seconds) and are usually noisy. On the official AstroPlant back-end, the non-aggregate measurements are only kept for a few months. The aggregate measurement can, for most purposes, be considered to be the raw data.
"Media" are any type of data produced by peripherals that do not fit into the idea of measurements. This could, for example, be an image produced by a camera. These media are stored as binary files and can be downloaded.
The "controller" is a module on the kit that is used to send commands to peripherals, allowing to control e.g. the brightness of the various wavelengths of LEDs of an LED panel. The controller can work on a schedule (LED brightness based on time of day), or can be used to control the environment based on fuzzy-logic (e.g. acting as a thermostat, controlling a heater based on a thermometer's measurements).
Of course, for this to be possible, the kit needs to know the peripherals that are connected and how to user wishes to control them. This is done through "kit configurations".
There are plans to allow the software to use any arbitrary controller, much like it can use arbitrary peripherals. This is not yet implemented, however.
A "kit configuration" consists of the names and parameters of specific peripherals (and in technical terms, the configuration specifies where the kit can find the software required to use those peripherals). The configuration also specifies the rules for the controller. The configuration can be made by users on the front-end. The user interface is generated dynamically based on the peripherals the user has added to the configuration and uses the definitions of those peripherals.
When the kit software starts up, it fetches its current configuration from the back-end, loads the required software for the peripherals, and starts executing the configuration.
At any one time, a kit can only have one active configuration (or none!). The moment a configuration is activated, it can no longer be changed. This ensures that data and measurements produced can always be traced back to the exact configuration that produced it. To change a configuration, it has to be copied, and that copy can be changed and then activated. There's not yet a user-friendly way to copy configurations, and you'll have to do it manually. Solving this is high on our priority list.
A "peripheral definition" is meta-information about peripherals. It includes the location of software needed by the kit to run the peripheral, as well as the configuration parameters the user needs to fill out when adding the peripheral to a configuration (such as a GPIO port number and the measurement interval), and what the command format is (if any). Technically, the format of configuration parameters and the format of commands are specified as JSON Schemas. This allows for dynamic creation of user interfaces. This way, the front-end does not need to know about specific peripheral devices: it only needs to know about the JSON Schema, thereby allowing users to configure any arbitrary device that the back-end has a definition for.
Currently these definitions need to be added to the back-end by administrators. As such, users wishing to add their own peripherals (while using the official AstroPlant-hosted back-end) will need to contacts us to use their devices. It is planned to allow users to add these definitions themselves, without the intervention of back-end administrators.
