saal¶ ↑

saal stands for Sensor and Actuator Abstraction Layer, and it aims to handle the mechanics of accessing sensors and actuators and logging their state over time. In its present state it is capable of reading from any set of one wire sensors attached one or more owserver processes from the owfs project. It is also able to read and actuate the DIN mounted IP relay from digital loggers (www.digital-loggers.com/din.html). In the future other forms of sensors as well as actuators can be added.

Based on a single definition of available sensors/actuators several features are available:

• An API to read/write to sensors/actuators

• A daemon that periodically records all sensor values into a MySQL database

• An API to interrogate the database of recorded values

• A graphing API and full program to produce charts from the stored sensor reads

An example of the usage of saal can be seen at www.corujas.net.

After you install the gem:

$ gem install saal

Define your sensors in /etc/saal/sensors.yml.

fake_temp:
  name: "A fake temperature sensor"
  onewire: 
    serial: /10.4AEC29CDBAAB/temperature

This gives you one available sensor:

require 'saal'
SAAL::Sensors.new.each do {|sensor| puts sensor.name} 
# "fake_temp"

Now if you run owserver in test mode:

owserver --fake 1F,10

you can read from the sensor:

SAAL::Sensors.new.fake_temp.read # Returns a random value with owserver --fake
SAAL::Sensors.new.fake_temp.read_uncached # Forces an actual physical read of the sensor instead of using any cache

To store readings you would need to setup an /etc/saal/database.yml. For example:

host: localhost
user: sensor_reads
pass: somepass
db: sensor_reads_production

This sets up access to the ‘sensor_reads_production’ MySQL database on ‘localhost’, using user ‘sensor_reads’ and pass ‘somepass’. With this in place you can now run the daemon to periodically store sensor values:

$ saal_daemon /var/run/saal.pid

And then you can query the stored values:

SAAL::Sensors.new.fake_temp.average(0,Time.now.utc.to_i)

Both arguments to average are unix timestamps in UTC timezone.

After you’ve gotten sensor logging working and some values in the database you can start creating charts based on it. Here’s an example /etc/saal/charts.yml file:

day:
  sensors: [temp_exterior, hum_exterior, pressure]
  last: 24
  periods: hours

week:
  sensors: [temp_exterior, hum_exterior, pressure]
  last: 7
  periods: days

4week:
  sensors: [temp_exterior, hum_exterior, pressure]
  last: 4
  periods: weeks
  alignlabels: left

year:
  sensors: [temp_exterior, hum_exterior, pressure]
  last: 12
  periods: months

4year:
  sensors: [temp_exterior, hum_exterior, pressure]
  last: 4
  periods: years

With this in place you can now run “saal_chart <some_directory>” and get 5 png files produced with the Google charts API that show the data recorded in the database over the given periods. This is almost exactly the config that generates the graphs at www.corujas.net.

The charting code handles range selection and period naming automatically, so all possibilities of number and type of periods are possible.

Pedro Côrte-Real <pedro@pedrocr.net>