The Livebox has an existing, external, serial port exposed on an MMJ 6P6C jack socket. This is the 'missing link' to transforming the Livebox into one of the most capable and affordable Home Automation systems that you might imagine!

The following features were proven to make this project a winner:

• Solid operation - not prone to hangups
• Gets its IP address via DHCP or STATIC
• Remote firmware 'auto-updates'
• Configuration not lost on 'hard' reset
• Easy to control attached relays and remote RF mains sockets
• Prefer no internal hardware modifications (unless very simple)
• Input sensing as well as output driving
• Browser based user interface
• Pre-programmed scheduling via Google Calendar
• Instant control via twitter
• Data logging to Pachube
• Open control protocol (xAP)
• Build new Livebox firmware from scratch.

Want your own to play with? Have some questions about it?
http://www2.dbzoo.com/

Download the file http://hah.dbzoo.com/upgrade/hah-firmware.dwb.
To install you'll need command line access, so you can replace the redboot loader and finally flash the HAH firmware to get this installed.

This firmware replacement is fully functional; PACHUBE, Currentcost, xAP data feeding and SMS will be ok, however without the additional hardware some functionality will not work. This is also a great way to get yourself a new kernel with many more modules installed plus the full command set of BusyBox (v1.12.1)

Useful information about the HAH firmware:

• uses DHCP by default to obtain an IP address. You will have to examine your DHCP server to find out what IP was assigned; with the additional hardware the IP is shown on the LCD at boot up.
• Default root password is admin
• SSH enabled (dropbear 0.51), TELNETD available, initially disabled.
• Console login disabled as this is where the additional hardware attaches.
• Webserver listens on port 80
• pure ftpd v1.0.21

Then perhaps go for a livebox gcc or python! see Native MIPS toolchain or try building your own HAH firmware binary.

Once installed the livebox HAH firmware can be manually updated with the latest version by executing this shell script from the command line prompt. All settings in /etc/ will be preserved.

# /etc/init.d/update
Ramdisk initialisation ...
Connecting to livebox.dbzoo.com (94.76.216.73:80)
build                100% |*******************************|     4  --:--:-- ETA
Connecting to livebox.dbzoo.com (94.76.216.73:80)
fcp                  100% |*******************************| 46216  --:--:-- ETA
Connecting to livebox.dbzoo.com (94.76.216.73:80)
Image.bin            100% |*******************************|  4024k 00:00:00 ETA
killall: kloned: no process killed
Erasing blocks: 63/63 (100%)
Writing data: 4024k/4024k (100%)
Verifying data: 4024k/4024k (100%)
Reboot

It will only download and reflash if the build is a later version.

The 20,000ft view of how the HAH controller fits into a network and the devices that it is able to control with the custom hardware.

Focusing on the software that controls the HAH additional Hardware

• Using the open protocol xAP gives us the flexibility that our project requires
• For the webserver component we use klone. It's a webserver where you build all the web pages using normal HTML but the embedded scripting language is C. Then it compiles all the pages into a BINARY executable which you ship. One binary and that IS your application. No CGI. No interfacing issues, and best of all no possibility that the scripting language can't do it!

A block diagram of how the daemons interact with one another on the livebox.

• xap-HUB - allows multiple xAP devices to be controled from a server. In this case the Livebox.
• xap-adapter - convert the AVR menu interface into an xAP protocol and interfaces with the RS232 port.
• xap-currentcost - USB/Serial interface to the CURRENTCOST electricity monitor
• xap-sms - USB/Serial interface via a DLR-3 cable to a Nokia 7110 mobile phone.
• xap-pachube - Feed xAP BSC data to the PACHUBE data aggregation service
• xap-googlecal - Trigger xAP event from Google calendar
• xap-twitter - Remote control with Twitter.
• xap-plugboard - LUA based scripting engine

All components use the file /etc/xap-livebox.ini as the universal registry for their settings. This is in “windows ini” file format using minini the INI file parser.

We added a small interface board which plugs in to the MMJ socket on the Livebox. This board holds an AVR microcontroller which interprets commands sent from the Livebox. Since the MMJ connection exposes 5V and Gnd, as well as the serial Tx and Rx lines (at 3.3V), connection to the micro UART pins is straightforward.

Features of the add-on board

• 4x relays
• A set of input lines
• An I2C bus
• 1-Wire bus
• RF transmitter
• LCD (1×16)

These consumer grade remote control switches are just RF controlled. By hacking the RF signal and re-encoding into our micro-controller we can control these from the Livebox.

As for a choice of microcontroller, the AVR2313 chip is probably a bit short on codespace, a Mega8 would give room for extra code functions. Currently, the serial relay control software handles outputs to 4 relays. It is able to query input lines too.

Mockup of MEGA-8 development board with an RF transmitter:

The PCB layout below has now been fabricated - we use an RJ11 female to bring in 5V and serial from the Livebox MMJ connector. This PCB is sized to fit inside the Livebox case.

Board layout with a few component populated

Populated and mounted inside the livebox

Externally mounted for easier access

Before starting make sure that you have all of the parts that you require. Components are packaged as per the shop - keep the parts in their separate bags until you are ready to solder them onto the PCB.

You will need a soldering iron, some fine solder and a small pair of wire-cutters.

The order in which you populate the components on the PCB is not critical. We usually start with the RJ11 socket. The socket is a tight fit. Be sure that all six pins align with the holes in the PCB before applying too much pressure. Then fit the zener diode, D6, directly behind the RJ11 socket. Observe polarity - the bar on the component should match the bar on the PCB legend. Now, fit R6, just to the side of the RJ11 socket.

The socket for the microcontroller is next. We use a 20pin socket + an 8pin socket.
Remember to align the notch on the socket with the notch on the PCB legend. Now, fit the caps and the xtal. Solder the caps to pins 1 and 2, 5 and 6 of SV1. the xtal fits to pins 3 and 4. Fit these so that the xtal sits on top of the caps.

Jumper JP1 should be left unfitted. JP3 should be fitted and jumper-ed to short pins 1 and 2. JP4 should be fitted and pins 1 and 2 shorted.

If you have relays to fit, it is easier to fit the diode, resistor and transistor (required to drive the relay) before fitting the relay itself. When fitting the diode, ensure that the band on the component matches the PCB legend. When fitting the transistor, ensure that the flat side on the component matches the PCB legend.

When fitting the RF module, you first fit 3 molex pins to the PCB. Then solder the 3way socket to these pins. The goal is to have the RF module sit at the same height as the top of the RJ11 socket. If you make this stand too high, the Livebox case will not close properly.
Next, fit the voltage regulator (marked as IC1 on the PCB legend).
Ensure that the flat side on the component matches the PCB legend.

Operation of the RF module requires the addition of a wire from the Livebox to the PCB. This supplies 15V from the Livebox to the PCB. The PCB has a solder pad (marked '15V') - solder one end of the red wire to this. The other end should be soldered to the 15V rail on the Livebox PCB (see RF 15v for details).

Temperature sensors connect to the 1-wire bus. Solder the a 3pin header to the PCB. Pin 1 on the PCB is Gnd, pin 2 Data and pin 3 Power. Then attach the molex-to-3.5mm jack socket connector cable. The black wire on the molex connector is ground.

Close-up of the LCD connector on the PCB.
The LCD requires to be wired to the ribbon cable.
See lcd_assembly for details.

LCD Standard pinout description: http://www.epemag.com/lcd1.pdf

The PCB requires 15V to be fed from the main Livebox board. This is used to source the 12V supply for the RF module on the PCB. The image below shows where this can be tapped.

The only 1-Wire device that we currently support is a temperature sensor, up to 15 of these can be chained to the bus. We use a standard 3.5” audio plug as extension leads and Y splitters are cheap and readily available to make our bus connectors.

For sample BASCOM code that can read this device have a look at the ds18b20 page.

By chaining a series of Y splitters and extension cables we can cable up a set of temperature sensors.

The I2C bus can be used to extend the number of controllable devices that the Serial PCB can access. Using the PPE chip for example an additional 8 I/O pins are available. Times this by up to 8 chips on the bus and you have at your disposal 64 I/O channels; all accessible using the xAP protocol.

Driving and configuring I2C is tricky as the PPE chips can be used in a multitude of configurations add to this the fact that 8 PPE chips can be addressed from the i2c bus and suddenly there is lot of complexity.

There are two requirements for being able to address a PPE chip using xAP endpoint.

• A Single endpoint where all pins are used to represent a byte of information
• An endpoint per pin
• The configuration of 4 bits to construct a nibble in the range (0-15) will not be catered for.

In each of these configurations we need to cater for both input and output addressing, that is Read and Read/Write.

Given the dynamic nature of the I2C bus and that its undesirable to hardcode in the adapter how these PPE endpoints will be created a configuration file is needed.

• http://focus.ti.com/docs/prod/folders/print/pcf8574.html

The programming language chosen for writing the micro-controller firmware is BASCOM.

The AVR firmware will run a simple text command line interface as its protocol. Connecting directly to its firmware we can interact directly with the unit. This will make writing and debugging the unit easier as all communication will be text based and via the livebox serial port.

We communicate at 115200 baud as this is the default speed for the Livebox serial interface. This also affects the XTAL we need to choose for the hardware. 7.3728Mhz gives us the most accuracy at this baud rate.

# microcom -s 115200 /dev/ttyS0
+++
debug
>help
Available Commands:
<channel> = 1-8
  HELP
  REPORT
  1WIRERESET
  EEPROM
  REBOOT
  ON <cc/channel>
  OFF <cc/channel>
  LCD <message>
  I2C R
      Maa   - addr
      Baavv - addr/value
      Paapv - addr/port/value
  RF ccpbbbbbbbbbbbb
>

Channels 1-4 map to the internal relays with 5-8 mapping to external RF relays.

Display the current state of the INPUTS and any devices on the I2C or 1-Wire bus - Debugging command.

>report
input 60,0
1wire 1 20
>

During normal operation these values will be emitted when a change occurs. They are polled by the AVR, using an interrupt, every second.

1wire DEVICE-ID VALUE

To the input value, PORTD of the AVR, the following bit mask 00111100 is applied as only ports 2,3,4,5 are being used to give us our 4x input channels.

input 60,0  (in binary 111100,000000  - VALUE,Change Mask )

As the change mask is 0 no bit has been modified from the previous POLL. The inputs float high with a path to GND(0) when “CLOSED”.

The I2C bus will report the following when a delta is detected between the current and previous value or the report command is issued and an I2C device has been configured.

i2c-ppe ADDR PREVIOUS-VALUE CURRENT-VALUE

Dump the contents of the EEPROM used to hold the RF transmission pulse train codes. Up to 12 RF pulse train codes may be stored. - debugging command

>eeprom
0x05(5)OFF:  4D 2A AA AA AA 80
0x05(5)ON :  4D 2A AA AB 2B 00
0x06(6)OFF:  4D 2A AA CA AC 80
0x06(6)ON :  4D 2A AA CB 2D 00
0x07(7)OFF:  4D 2A AA B2 AB 00
0x07(7)ON :  4D 2A AA B3 2A 80
0x08(8)OFF:  4D 2A AA D2 AD 00
0x08(8)ON :  4D 2A AA D3 2C 80
0x09(9)OFF:  01 02 03 04 05 06
0x09(9)ON :  06 05 04 03 02 01
0x0A(10)OFF:  00 00 00 00 00 00
0x0A(10)ON :  00 00 00 00 00 00
0x0B(11)OFF:  00 00 00 00 00 00
0x0B(11)ON :  00 00 00 00 00 00
0x0C(12)OFF:  00 00 00 00 00 00
0x0C(12)ON :  00 00 00 00 00 00
0x0D(13)OFF:  01 02 03 04 05 06
0x0D(13)ON :  00 00 00 00 00 00
0x0E(14)OFF:  00 00 00 00 00 00
0x0E(14)ON :  00 00 00 00 00 00
0x0F(15)OFF:  06 05 04 03 02 01
0x0F(15)ON :  02 03 04 05 06 07
0x10(16)OFF:  4D 2A AA AA AA 80
0x10(16)ON :  4D 2A AA AB 2B 00
>

The 1-Wire bus is only scanned once during micro-controller startup, if additional devices are added to the unit whilst HOT the bus must be reset to pick these up.

Reset the microcontroller. This will be executed when the Livebox is asked to reboot so both sub-systems stay synchronized.

Toggle a relay or RF relay from the on to the off state.

>on 1
>off 1

Send a message to the LCD screen

>lcd hello world

Additional instructions are going to be needed to configure the I2C devices.

• Add a new I2C device at an address
• Send an I2C command

Configuration command

Example configuration for the last entry in the .INI configuration file above is shown first.

i2c MXX
i2c M43
i2c M45

We need the configure command to add this address to the list of PPE chips that should be polled and read. Up to 8 of these PPE chips can be supported.

Control command

There will be TWO commands one for operating in BYTE mode the other for PIN mode.

Pin mode will accept 4 characters

i2c PXXYY
i2c P4300  - PPE chip at 0x43 Pin 0 LOW - ON (Path to ground)
i2c P4371  - PPE chip at 0x43 Pin 7 HIGH - OFF (no path to ground)

Byte mode will also accept four characters

i2c BXXYY
i2c B4410 - PPE chip at 0x44 write byte 0x10

• rf <chnl><on/off><6 bytes in HEX >
• rf ccpbbbbbbbbbbbb - cc HEX Channel, p On/Off indicator, bbb.. RF control

The on/off indicators mark if this RF sequence turns on or off an external relay.

Example: The default for Channel 10 (RF05) OFF. Don't forget the 1st four channels are for the internal relays, so RF-1 maps to Channel 5.

  rf 0504D2AAAAAAA80

The RF command consists of 6 byte/48 bits of those only 42 bits are use for generating the RF command signal.

Looking at one of the RF sequence

rf1.off=4D2AAAAAAA80

This decodes into the following, we have separated off the last 6 bits as these aren't used.

10011010010101010101010101010101010101010 000000

The transmission always begin by sending a HIGH pulse and alternates as we read each bit. The length of the pulse is determined by the “value of the bit” + 1, reading the pulse command from left to right.

The break between all pulses is 680us.

• 1st bit is 1 so we send two high pulses separated by a 680us wait.
• 2nd bit is 0 so we send one low pulse followed by a 680us wait.
• 3rd bit is 0 so we send one high pulse followed by 680us wait.
• 4th bit is 1 so we send two low pulses separated by a 680us wait.
• this sequence carries on.

When an RF signal is transmitted the entire Command is transmitted 8 times with an 80ms break between transmissions.

During transmission, due to timing requirements, the I2C and 1-Wire bus will not be polled.

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

For more 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 message are sent every couple of minutes to show the state of the current system. If we waited until event where sent programs such as the 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
{
}

This is an example of an xAP message that will be generated when the STATE of pin 1 on I2C PPE chip at address 0×43 changes. The UID will be system generated as each endpoint is created. The name of the device will be encoded using the address and pin. In the case where all pins are used this trailing component will simply be dropped.

xap-header
{
v=12
hop=1
uid=FF00DB47
class=xAPBSC.info
source=dbzoo.livebox.controller:i2c.43.1
}
output.state
{
state=on
}

To change the state of the output pins the following xAP would be constructed. This would turn ON PIN5 and OFF PIN6 of the PPE chip at address 0×43. We use the wildcard character > so that the pattern matching will examine all PINS of the PPE chip, the ID= of the xAP body will indicate which pin we require.

xap-header
{
v=12
hop=1
uid=FF00DB47
class=xAPBSC.cmd
source=acme.my.controller
target=dbzoo.livebox.controller:i2c.43.>
}
output.state.1
{
id=5
state=on
}
output.state.2
{
id=6
state=off
}

Alternative if only a single PIN is being modified, in this example PIN 7 of I2C PPE at address 0×43 we can drop the ID and the wildcard match character (>) and direct the message to the endpoint.

xap-header
{
v=12
hop=1
uid=FF00DB47
class=xAPBSC.cmd
source=acme.my.controller
target=dbzoo.livebox.controller:i2c.43.7
}
output.state
{
state=on
}

The webserver is written in C using

• embedded web server from KloneLogic
• minini the INI file parser

The web server listens on PORT 80 from here you can control most of the Home Automation controller features.

To access any other page but info you will need to authenticate. Login in as admin you can enter anything as the password and it will be accepted. Not until the admin user password has been setup will it be validated.

More screenshots

There are several settings in the /etc/xap-livebox.ini file that directly affect the webserver or the livebox itself.

The network section defines what additional services will be enabled and the ports used, whether DHCP or STATIC IP configuration is setup, if the two Ethernet ports should be bridged together into a Switch configuration or addressed individually, the domain name of the Livebox and the NTP time server to stay in sync with.

[network]
lan_proto=dhcp
hostname=hahbox
config_bridge=1
ether_0=00:07:3A:11:22:00
ether_1=00:07:3A:11:22:01
domain=
ntp_host=uk.pool.ntp.org

The power LED indicator although it appear on the SETUP page has it own section. This reduced the amount of ON time that this LED has, useful if you keep the Livebox in a room where this brightness would be annoying.

[hardware]
power=0

These network entries allow in-built services such as SSH, TELNET and FTP to be enabled/disabled.

[network]
telnet_enable=0
telnet_port=23
ssh_enable=1
ssh_port=22

Access to various pages in the HAH controller can be controlled in the [security] section. For example:

[security]
user=demo
passwd=secret
demo=automation,graph,control

Will create a login user called “demo” with a password of “secret” that only has access to the automation, graph, and control pages.

Up to 10 additional user accounts can be created. Simply separate each with a comma

[security]
user=demo,foo
passwd=secret,bar
demo=automation,graph,control
foo=automation,control

The page names are derived from the names of the pages as defined in the URL. For example the page setup.kl1 will be “setup”.

There are two other entries that appear in the security section that are update-able via the webserver

info_protect=0
admin_passwd=21232f297a57a5a743894a0e4a801fc3

Info protect controls where the INFO page is display without needing to authenticate as a valid user. The admin_password is an MD5 hash of the special user “admin” who cannot be deleted from the system; its a hardcoded username much like root in a Linux system.

If you forget the admin user password simply delete the admin_passwd entry and whatever you enter in the login prompt will be accepted as valid.

The xAP Hub allows multiple applications on the same host to share a common xAP infrastructure - fundamental design constraints in the way TCP/IP works would otherwise prevent more than one xAP application being used at a time on a given host.

For more details http://patrick.lidstone.net/haweb/hub.htm

This daemon, also called xap-livebox, interfaces the external HARDWARE on the serial port with the xAP control protocol.

# xap-livebox --help

Livebox Connector for xAP v12
Copyright (C) DBzoo, 2008,2009

xap-livebox: [options]
  -n, --instance NAME    Default Controller
  -i, --interface IF     Default br0
  -p, --port NUM         Default 3639
  -s, --serial DEV       Default /dev/ttyS0
  -d, --debug            0-9
  -h, --help
#

We will use the WINDOWS .ini file format to store all our configuration parameters

• http://www.compuphase.com/minini.htm - minIni - a minimal INI file parser

There are several sections in the /etc/xap-livebox.ini which are use to control and configure its runtime behaviour.

[1-Wire]
# Up to 15x 1-wire devices may be supported increasing the number
# beyond what you have attached simply presents more XAP endpoint than
# you have devices for.
devices=1
sensor1.label=Office

Each sensor can be given a label using the nomenclature “sensor#.label=<your label>”. These are best setup using the WEB interface but can be done manually too.

The RF sections contains the pulse codes that will be loaded into the eeprom of the MEGA8 chip to control the RF transmitter.

Need a section here on how the pulse codes are encoded

[rf]
# Up to 12 RF channels may be defined.
devices=4
rf1.off=4D2AAAAAAA80
rf1.on=4D2AAAAB2B00
rf2.off=4D2AAACAAC80
rf2.on=4D2AAACB2D00
rf3.off=4D2AAAB2AB00
rf3.on=4D2AAAB32A80
rf4.off=4D2AAAD2AD00
rf4.on=4D2AAAD32C80
rf1.label=RF 1
rf2.label=RF 2
rf3.label=RF 3
rf4.label=RF 4

These section allow us to configure user friendly names that will appear on the webserver interface. The xAP protocol does not make use of these labels.

[input]
input1.label=Input 1
input2.label=Input 2
input3.label=Input 3
input4.label=Input 4
 
[relay]
relay1.label=Relay 1
relay2.label=Relay 2
relay3.label=Relay 3
relay4.label=Relay 4

In this example the following definitions can be set up as xAP endpoints. The endpoint number will be dynamically assigned incrementing by 1 from the last hardcoded endpoint defined internally in the adapter.

The section header indicates the type of I2C chip, this allows additional chip types to be added to the definition file.

; All PINS are used together to represent an input / output byte
[ppe1]
address = 0x40
mode = byte
 
; Each pin is xAP endpoint addressable
[ppe2]
address = 0x41
mode = pin

So that the data being collected by the livebox can be graphed, shared or used to trigger other real world event we use pachube - which people in the know pronounce pach-be, but sound much cooler as pa-chu-be.

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

This daemon is configurable via the webserver interface

Once you have a PACHUBE 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. Here is my data collected on pachube: http://www.pachube.com/feeds/5386

The xAP source parameter has the format source:class:message so taking one of the defined strings from the web page you see dbzoo.livebox.Controller:1wire.1:xAPBSC.info:level breaking this down we get

• source - dbzoo.livebox.Controller:1wire.1
• class - xAPBSC.info
• message value label - level

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

xAP-header
{
v=12
hop=1
uid=FF00DB0A
class=xAPBSC.info
source=dbzoo.livebox.Controller:1wire.1
}
input.state
{
level=21
}

The PACHUBE adapter feeds data to the pachube service on a regular basis.

It's internal cache of data to push to PACHUBE can be updated by xAP messages being targeted at this service.

Message sent to it are not immediately forwarded to the PACHUBE service until the next update cycle.

A Pachube update message looks like this:

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

With all this data being aggregated we can now graph it

As this data resides on an external server we can ask it to produce a graph for us too

<img src="http://www.pachube.com/feeds/5386/datastreams/1/history.png?w=320&h=200&t=HAH%20Temperature&b=true&g=true&r=3"/>

The currentcost device is a UK available item that monitors your electricity usage. The datastream is available via USB/RS232 dongle which plugs into the livebox either directly or with a HUB. The xap-currentcost daemon reads this data and turns it into an xAP message which then makes it available for data logging and event attachment.

The configuration of this device can be done using the WEB interface

Both the Classic and the ENVI (CC128) model are supported. The /etc/xap-livebox.ini file contains a currentcost section that contains the configuration parameters.

[currentcost]
enable=1
usbserial=/dev/ttyUSB0
model=CC128

The sensor hystersis is the amount of Watts that must change before a data value is published to the xAP bus. Having this value >0 prevents event jitter.

The xAP message that will be generated by the xap-currentcost daemon is a BSC message where the level is the amount of WATTS of electricity being used.

With the ENVI model up to 3 channels for 3-phase power, or a secondary meter box, can be monitored. These will appear as the endpoints ch1.0,ch2.0 and ch3.0

The xAP endpoint for the CC128 model is ch<channel>.<sensor>

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

For the CLASSIC model the xAP endpoint is ch<channel> as it doesn't support individual sensors.

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

So the pachube source matching string would be dbzoo.livebox.CurrentCost:ch1:xAPBSC.event:level

The CC128 UNIT also has a built-in temperature sensors this too will also generate its own xAP message. The units for the level are in degrees Celsius.

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

The Classic will report as source=dbzoo.livebox.CurrentCost:temp so a pattern matching pachube string would be dbzoo.livebox.CurrentCost:temp:xAPBSC.event:level

By configuring the xap-pachube daemon this data can be recorded and graphed

If you want to do some debugging there is a baud rate difference between the two models:

• CC128 - 57600-n-8-1
• Classic - 9600-n-8-1

Examining the datastream from a current cost unit. Shutdown the xap-currentcost daemon first.

microcom -s 57600 /dev/ttyUSB0

Starting the xap-currentcost daemon in debug mode. There are 9 level of debug. 1 the lower, 9 the highest. You must be at 5 or higher to see the inbound SERIAL data.

xap-currentcost -d5 -s /dev/ttyUSB0 -i br0

Try using xap-snoop to see if any xAP message is being sent on the bus.

The xap-sms daemon allows the Livebox to send and receive SMS message with a Mobile phone.

The SMS messages are converted into xAP for transport on our bus so that other software can deal with them and react. Usage of this hardware requires additional programming to setup the control structures that you require. It doesn't do anything out of the box - see the sample programs section below.

Testing was done using a NOKIA-7110 your mileage vary with other handsets. However if they are compatible to the COMMAND SET then they should just work.

Connecting the phone to the Livebox will requires a DLR-3 cable and a USB/Serial cable.

The command line options:

# xap-sms --help

SMS Connector for xAP v12
Copyright (C) DBzoo, 2009

xap-sms: [options]
  -n, --instance NAME    Default sms
  -i, --interface IF     Default br0
  -p, --port NUM         Default 3639
  -s, --serial DEV       Default /dev/ttyUSB1
  -d, --debug            0-9
  -h, --help

Scheme for the body of outgoing xAP message

outbound
{
msg=(Message text upto 128 characters)
num=(Telephone number to send to)
}

Schema for the body of an incoming SMS message

inbound
{
msg=(message text)
num=(Telephone number of sender)
timestamp=(date time)
}

There are two configuration parameters in /etc/xap-livebox.ini that xap-sms honours. Whether the daemon should be started or not and the USB serial device where the phone can be found. These can also be updated via the WEB interface.

[sms]
enable=1
usbserial=/dev/ttyUSB1

Sample python programs, also see the HAH xAP Python page

• xaplib.zip - Support library
• xap-sms-lcd.zip - Watch out for inbound SMS messages when one if detected broadcast its message to the Livebox LCD
• xap-sms-event.zip - Watch out for an RF or RELAY event when one if detected send an SMS of the change

Google calendar xAP daemon.

This program will monitor a calendar and produce an xAP payload every minute for as long as the activity is running. The password once entered will never be again displayed on the web GUI, this is for security reasons. However it can be reset by simply entering another.

The polling period determines how often google is checked for events. All events within the polling period will be cached on the Livebox. For example if the current time is 1pm and you check every 1hr, when all events to 2pm will be downloaded and cached on the Livebox. This also means that if you schedule an event at say 1:30pm AFTER the xap-googlecal program has refreshed its cache, this event will not fire.

The /etc/xap-livebox.ini file contains a section that holds the configuration parameters. Only user, enable and passwd are needed, the others will default if missing to those values supplied in the example.

[googlecal]
enable=1
uid=00DA
instance=GoogleCal
user=user@gmail.com
passwd=secret
ufreq=60

An entry is setup in the calendar using the following fields. This example will send the text “Hello World” to the LCD.

• What: <Some text defining your event>
• Where: XAP <must be the value xap>
• When: Start-time to Stop-time
• Description: An xAP payload using short form notation.

   xap-header
   {
   target=dbzoo.livebox.controller:lcd
   class=xAPBSC.cmd
   }
   output.state.1
   {
   id=*
   text=Hello World
   }

In the header you only have to specify the xAP message type (class) and the target.
The other fields will be automatically populated for you.

The event will fire every minute for the duration of the start/stop time.
If you require a single message then make the start/stop time the same value.

Another example, this text in the calendar event description will turn on RF module number 2.

xAP-header
{
class=xAPBSC.cmd
target=dbzoo.livebox.Controller:rf.2
}
output.state.1
{
id=*
state=on
}

Notice that there is no automatic generation of an 'off' message at the end of the calendar event. If you want the RF module to switch back off, you must create a separate 'off' event in the calendar.

Leaving out the description of the calendar entry the Google calendar component will interpret the title as an alias.

So now a calendar definition can be as simple as

This will result in a the following xAP message being transmitted.

xap-header
{
v=12
hop=1
uid=FF00D900
class=alias
source=dbzoo.livebox.Twitter
}
command
{
text=relay 1 on
}

It is up to the alias scripts running with xap-plugboard to determine what action to take.

The Google calender daemon can also act as a service. This mean it will accept an xAP payload and create a calendar event.

Header information

• the target will be: target=dbzoo.livebox.GoogleApp
• and the schema is: class=google.calendar

The body has the following elements

event
{
title=
start=
end=
description=
}

• Title is mandatory and contains a brief description of the logged event.
• Start is mandatory and can use a natural language format for its specification.
• End is optional and if not supplied the event is assumed to be 1 min long.
• Description is optional.

Start / End format

1. We always try to parse as ISO8601 first. We don't support week/day numbers (1985-W15-5) because they make me shudder. It wouldn't actually be hard to support them. We support the W3C subset of ISO8601 (see http://www.w3.org/TR/NOTE-datetime) completely.
2. We then try some fancy natural language processing. No ambiguous formats are represented. 4/3/5 is *not* a valid input, regardless of your locale. But most of the phrases accepted by the current getdate *are*. We can also read in RFC822-conformant dates. (“Wed, 22 Aug 2001 19:35:16 -0400”) and relative dates (“next thursday”). All non-ISO8601 dates are in *local* time. Thus, the date specification “8pm” is 8pm for *you*, not 20:00 UTC. You can specify a time zone (“GMT” or “UTC” for example) to force UTC interpretation. I do *NOT* currently support the 'three-letter' time zone codes, like EST, EDT, PST, etc. Time zones in ISO8601 format (”+08:00”, ”-0400”) and military time zone letters (“A”-“Z”, excluding “J”; see http://www.timeanddate.com/library/abbreviations/timezones/military/ ) are accepted. This is not a fundamental limitation; I'm just trying to avoid accepting potentially ambiguous descriptors ('EST' has different meanings in Australia and the US, for example).

Full payload example

xap-header
{
v=12
hop=1
uid=FF123400
class=google.calendar
source=acme.booker.ping
target=dbzoo.livebox.GoogleCal
}
event
{
title=Lunch
start=tomorrow at 12pm
end=tomorrow at 1pm
description=at Benji
}

This component allows you to tweet messages and control any xAP compliant device. The Livebox being such a device.

Due to the way in which Twitter works, you are not able to enter the same tweet twice. To work around this, the xap-twitter daemon will DELETE the tweet once it has processed it.

This means that you lose the audit trail of the commands you have sent. However, it has the benefit of getting active feedback that the command was accepted and processed.

This will result in a the following xAP message being transmitted.

xap-header
{
v=12
hop=1
uid=FF00D900
class=alias
source=dbzoo.livebox.Twitter
}
command
{
text=relay 1 on
}

The commands you enter resolve the same way as the Google Calendar component (See calendar_aliases) and require an alias_interpreter to resolve these into appropriate actions.

The xap-twitter process can also be used to send TWEETs to twitter. This is really useful if you have other scripts or processing running and you wish to record events. Twitter can be that event recording system to notify when something happens. As tweets can be relayed to your phone, this gives you the ability to remotely monitor events.

Sample payload to create the tweet “Hello World”

xAP-header
{
v=12
hop=1
uid=FF00DB01
class=xAPBSC.cmd
source=dbzoo.acme.test
target=dbzoo.livebox.twitter
}
output.state.1
{
id=*
text=Hello World
}

The load on the LIVEBOX is minimal even with this software stack running there is large amount of room for additional xAP control sofware.

login as: root
root@192.168.1.131's password:
# ps
  PID USER       VSZ STAT COMMAND
    1 root      2352 S    init
    2 root         0 SW   [keventd]
    3 root         0 RWN  [ksoftirqd_CPU0]
    4 root         0 SW   [kswapd]
    5 root         0 SW   [bdflush]
    6 root         0 SW   [kupdated]
    7 root         0 SW   [mtdblockd]
    8 root         0 SW   [khubd]
   29 root         0 SWN  [jffs2_gcd_mtd2]
   92 root      2340 S    udhcpc -b -i br0
  107 root      1668 S    dropbear -p 22
  120 root      2336 S    inetd
  126 root      2440 S    /usr/bin/xap-hub br0
  128 root      4472 S    /usr/bin/xap-livebox -s /dev/ttyS0 -i br0
  134 root      2660 S    /usr/bin/kloned
  135 root      2724 S    /usr/bin/kloned
  140 root      4832 S    /usr/bin/xap-currentcost -s /dev/ttyUSB0 -i br0
  147 root      5236 S    /usr/bin/xap-pachube -i br0
  161 root      2672 S    /usr/bin/kloned
  184 root      1740 S    dropbear -p 22
  185 root      2364 S    -ash
  186 root      2340 R    ps
# free
              total         used         free       shared      buffers
  Mem:        13964        10344         3620            0         1720
 Swap:            0            0            0
Total:        13964        10344         3620
#