livebox:xap_getting_started

Background on xAP

The best way to start understanding xAP is to read the Basic Status and Control message schema.

A tool to help you view the endpoint control hierarchy - xAP Message Viewer

Here you can see all the endpoints on the Livebox Controller that can be directly addressed using the xAP protocol. There are many top level systems being hosted by the Livebox: Controller, CurrentCost, Pachube, SMS

The preferred language for creating scripts to handle xAP messages is Lua. These scripts run in the Plugboard environment on the HAH.

For information about programming the Livebox with xAP and Python see hah_xap_python

Using the xAPBSC.cmd class we can define actions. Turn on RF relay 1.

xAP-header
{
v=12
hop=1
uid=FF123400
class=xAPBSC.cmd
source=acme.my.controller
target=dbzoo.livebox.controller:rf.1
}
output.state.1
{
id=*
state=on
}

Display the string “Hello World” on the LCD display

xAP-header
{
v=12
hop=1
uid=FF123400
class=xAPBSC.cmd
source=acme.my.controller
target=dbzoo.livebox.controller:lcd
}
output.state.1
{
id=*
text=Hello World
}

Messages in xAPBSC.info and .event are sent to indicate the current state of an Input or Output.

This sample message is telling us that Channel 1 of the CurrentCost device is using 576 watts of power.
A .event will be triggered as soon as a data value changes.

xAP-header
{
v=12
hop=1
uid=FF00DC01
class=xAPBSC.event
source=dbzoo.livebox.CurrentCost:ch1.0
}
input.state
{
level=576
}

.info messages are sent every couple of minutes to show the current state of the system. If we waited until events were sent, programs such as the xAP Viewer would not be able to automatically figure out what is out there.

xAP-header
{
v=12
hop=1
uid=FF00DB0E
class=xAPBSC.info
source=dbzoo.livebox.Controller:rf.4
}
output.state
{
state=off
}

To get an immediate .INFO response from an end point we can direct a .query message to an endpoint or set of endpoints. For each target that matches, an .info response will be generated.

xap-header
{
v=12
hop=1
uid=FF00DB00
class=xAPBSC.query
source= ACME.Controller.Central
target= dbzoo.livebox.controller:relay
}
request
{
}
  • livebox/xap_getting_started.txt
  • Last modified: 2012/06/19 15:26
  • by minerva9