Chapter 6 Implementing new sensors

New sensors should be implemented as new packages (i.e, a new GitHub repository). Packages have a standard format, and should be named sensor-<sensor-name> where <sensor-name> is short, descriptive of the sensor (e.g. model number), and unique within the WildlifeSystems ecosystem.

The structure of a basic package is given below.

.
+-- inst
|   +-- files that are not part of the package structure
|       used during installation (e.g. 3rd party scripts 
|       to be copied to /usr/bin/)
|
+-- sensor-<sensor-name>
|     Executable to read sensor and print JSON of readings
|     (copied on install to /usr/bin/)
|
+-- <sensor-name>
|     Configuration file 
|     (copied on install to /var/aao/sensors/)
|
+-- install
|     Bash file run once on install - used to install packaged
|     dependencies, etc.

As many people implement various sensors on the Raspberry Pi, it is likely that some sort of solution is already available, that can be tweaked to output readings in the standard format required. However, you must ensure that any licensing conditions are met. In particular, an open license is required if submitting your sensor package to WildlifeSystems for inclusion in the ecosystem.

6.1 Reading the sensor

File sensor-<sensor-name> provides the functionality to read the protoype JSON, populate the JSON with sensor readings, and print the output.

The file can be written in any programming or scripting language, but to prevent overhead consideration should be given to minimising the number of new packages installed.

6.1.1 In bash

#!/bin/bash

# Read the prototype JSON
JSON=$(sc-prototype)

echo -n "["

# Code to read the sensor value into GPU_TEMP

# Use `jq` to modify JSON
SENSOR=$(echo $JSON | jq ".sensor |= \"onboard_gpu\" | .measures |= \"temperature\" | .unit |= \"Celsius\"| .value |= ${GPU_TEMP}")
echo -n $SENSOR

echo "]"

6.1.2 In Python

#!/
import os
import json

# Read the prototype JSON
stream = os.popen('sc-prototype')
output = stream.read()

# Pre-populate with sensor metadata
temperature = json.loads(output)
temperature["sensor"] = "bme680_temperature"
temperature["measures"] = "temperature"
temperature["unit"] = "Celsius"

# Code to read sensor and output in variable `sensor_reading`
temperature["value"] = sensor_reading

# Output the JSON in an array
print("[",json.dumps(temperature),"]")

6.2 Setting the environment

The file <sensor-name> in the package specifies information that modify the environment of the Raspberry Pi (e.g. if the i2c interface should be enabled) before the sensor-<sensor-name> script is run. This allows sensors with different requirements to run sequentially on the same node.

The file must always be present, even if it is empty. During installation the file is moved to /var/aao/sensors/ and the list of files in this directory indicates to the system which sensors are installed.

TODO: i2c

6.3 Install

The file install in the directory is run once, when the sensor package is installed. This allows for the installation of packages and scripts necessary for the functioning of the package.

The file is executed by bash and the use of sudo is allowed.

6.4 The installation process with si

The sensor install script, si, from sensor-control is used to install sensor packages. For developer reference the installation process is described below.

  1. si clones the Wildlife-Systems/sensor-<sensor-name> repository from GitHub.

  2. The install script is executed.

  3. sensor-<sensor-name is marked as executable and move to /usr/bin/.

  4. <sensor-name> is moved to /var/aao/sensors/.

  5. The cloned repository is removed from the local filesystem.

6.5 Submitting packages to WildlifeSystems

Submitting packages (where licensing allows) to WildlifeSystems allows the ecosystem to be developed and sustained collaboratively by the user community.

Packages can be sent to the administrators as a compressed file, or a request can be sent to fork an existing GitHub repository. Contact details can be found at https://wildlife.systems/contact.html.