xAP Xively

Xively (formerly Cosm and before that Pachube (pronounced Patch bay)) is an online database service.
We use Xively to log data collected from the Sensors attached to the HAH system.

The xap-xively daemon has been designed to feed any xAP event that appears on the bus to Xively. This means the Livebox hardware plus any other xAP compliant software/device that you may have running elsewhere on your network.

This daemon is configurable via the webserver interface

Once you have a XIVELY account you will get a unique KEY. This must entered into the interface so that trust is formed between the Livebox and the service. You will then need to create a FEED ID.

The Max and Min values are used by xively to perform graph scaling along with the Unit field to annotate the datastream.

Let's consider an example of pushing a 1wire temperature sensor data value to Xively.

The temperatures sensors are generating an event on every .1 degree of a change, however data to xively is only pushed, by default, every minute. The way this timing difference is resolved is for xap-xively to monitor all the events and constantly update its internal cache to record the value. When the time comes to push a new reading the last value from the sensor is used.

If your temperature hovers from 15.5→15.8→15.5 its possible that 15.8 won't be see if this wasn't the last value. Your temperatures readings have to change and hold for at least the reporting period before you'll see something different being reported to xively. The reporting period in effect becomes a hysteresis of sorts.

The xively parameters

• source - dbzoo.livebox.Controller:1wire.1
• class - xAPBSC.event
• section - input.state
• key - text

This will match the inbound message and extract the value 21.0 Which is a degree Celsius reading of the 1st 1-Wire DS18b20 device on the bus.

xAP-header
{
v=12
hop=1
uid=FF00DB80
class=xAPBSC.event
source=dbzoo.livebox.Controller:1wire.1
}
input.state
{
state=on
text=21.0
displaytext=Inside 21.0
}

xap-xively can also handle a ON/OFF value and this will be automatically convert to a 1/0 so the numeric value can be logged, this is handy for relays, rf, and other boolean input/output devices.

The xively parameters

• source - dbzoo.livebox.Controller:relay.1
• class - xAPBSC.event
• section - output.state
• key - state

xAP-header
{
v=12
hop=1
uid=FF00DB60
class=xAPBSC.event
source=dbzoo.livebox.Controller:relay.1
}
output.state
{
state=on
}

The XIVELY daemon feeds data to the xively service on a regular basis.

Its internal cache of data to push to XIVELY can be updated by xAP messages being targeted at this service.

Messages sent to it are not immediately forwarded to the XIVELY service. They wait until the next update cycle, unless the now attribute is supplied more on that later.

A Xively update message looks like this:

xap-header
{
v=12
hop=1
uid=FFAADA01
class=xively.update
target=dbzoo.livebox.xively
source=dbzoo.acme.test:1
}
datastream
{
id=3
tag=Outside Temperature
value=10.4
}

In the message above

• The id= key matches that of the ID field in the datastream for the default Feed ID.
• The tag=key updates the tag value of the datastream identified by the ID key/field
• The value= updates the value of the datastream identified by the ID key/field

The attributes; id, tag and value are mandatory and must be supplied with each xAP message.

The configuration page on the HAH xively tab is unaffected

Note that the UID and source in the message above must either both have sub-addresses or neither have sub addresses

This is an optional attribute.

If you require the manual feed to update xively immediately the xively.update is sent supply the attribute “now” with a value 1.

datastream
{
id=4
tag=Outside light on
value=1
now=1
}

The now field was added to solve the use case where by a boolean value needs to be monitored and its state should not be cached as it may toggle before the next xively web service update occurs. It will cause xap-xively to immediately push the value up to the xively web server.

This is an optional attribute.

When feeding xap-xively manually you may supply a feed attribute to override the default feedid= setting obtained from the /etc/xap.d/xap-xively.ini file.

datastream
{
id=4
tag=Humidity
value=60
feed=1234
}

These are optional attributes.

When feeding xap-xively manually you may supply a min/max attribute to specify to the xively backend the range of values to be expected. This assists it with graphing.

datastream
{
id=4
tag=Temperature
value=20
min=-10
max=40
}

This is an optional attribute.

This attribute allows you to supply a textual hint for the unit type of the value. Its purpose is to document the value units when viewing graphs and values through the xively web interface.

datastream
{
id=4
tag=Pressure
value=973
unit=hPa
}

With all this data being aggregated we can now graph it