livebox:xapflash [DBZoo]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== xAPFlash ======


===== Introduction =====

{{:livebox:xapbutton.png |}} The xAPFlash application, written by Kevin Hawkins et al, is a GUI front-end that allows you to control xAP compliant devices.

As the name suggests this is a FLASH based application targeted primarily at the O2 Joggler by OpenPeak. However, as this is in Flash it will run on many other supported platforms.

The following have been verified
  * Joggler
  * WebOS (HP Touchpad)
  * Android based systems
  * Browsers
  * Flash Player (Linux, Windows)


<box red round|Support>
Something not working?\\
Having problems?\\
A documentation issue?\\ \\
[[http://www.automatedhome.co.uk/vbulletin/forumdisplay.php?f=29|Visit the forum]]
</box>
===== Background =====

** What is xAP? ** 
xAP is a protocol implemented as broadcast UDP datagrams.  Due to restrictions in Flash it cannot place xAP packets on the wire, this disconnect is resolved by the introduction of a TCP/UDP xAP gateway, the 'iServer'.

The Flash application connects to an [[iserver|iServer]] which will relay traffic to and from the application.  The [[iserver|iServer]] also has the following benefits:
  * TCP is a reliable delivery protocol which is beneficial for wireless devices
  * The iServer also performs packet filtering, only providing data to the Flash application for the endpoints it's controlling and monitoring
  * Monitoring of packet count and throughput
  * Enables external connectivity outside of your LAN

The xAP Flash application can easily interact with all your xAP BSC devices providing immediate state synchronization and  real-time status tracking and control.  It also integrates easily with non xAP BSC schema devices and endpoints.

===== Terminology =====

Some words and their meanings may not be obvious, so getting familiar with the terminology will make reading the rest of this article easier.

^ Word ^ Meaning ^
| xAP | [[http://xapautomation.org/index.php?title=Protocol_definition|xAP Protocol]] |
| xAPBSC | [[http://xapautomation.org/index.php?title=Basic_Status_and_Control_Schema|Basic Status and Control Schema]] often abbreviated to BSC |
| endpoint | Any device, physical or logical, on your network that can generate information and/or be controlled though the use of an xAP schema. e.g. dbzoo.livebox.Controller:relay.1 |

====== Installation ======

If you have a firewall make sure the following are allowed

^^ Process ^^ Port ^^ Type ^^  Usage ^^
|| iServer & Flash || 9996 || TCP || Used for connection of the Flash application to the iServer ||
|| iServer || 3639 || UDP || xAP Broadcast port ||
|| iServer & Flash || 843 || TCP || Adobe socket policy server ||

===== Joggler =====

<note warning>The installation assumes that you have command line access to your Joggler.\\ If you haven't done this then you need to consult the following documentation.\\ http://www.jogglerwiki.com/wiki/SSH</note>

Above instructions replicated locally in case they ever disappear! [[livebox/xapflash/ssh|Joggler SSH access]] there is also an alternative method that involves booting into a Ubuntu distribution [[jogglercommandshell]]

{{ :livebox:o2-joggler-tablet.jpg?320}}  

It's advisable that you are familiar with the Linux environment as the Joggler runs Ubuntu under the bonnet.  Instructions will be given to edit files etc and it's assumed you have a working knowledge of [[http://en.wikipedia.org/wiki/Vi|vi]] and associated tools.

==== iServer installation ====

The iServer is a TCP/UDP gateway to work around that fact that FLASH cannot participate in UDP based communication.  You may run it on the following platforms:
  * Joggler
  * HAH -> Preloaded. It just needs to be [[iserver|enabled]]
  * PC running Windows -> [[http://www.ukusa.demon.co.uk/iServer.htm|install instructions]]

You do need run at least one of these, somewhere, for the xAPFlash application to communicate.

{{ :livebox:xfx-iserver-joggler.png|}}

==== Joggler xAP binaries ====

Installation onto the Joggler is straightforward.
<code>
# cd /tmp
# wget http://www.dbzoo.com/public/joggler-xap.run
# sh joggler-xap.run
</code>

This self extracting shell script will install the following onto your Joggler.
<code>
/
|-- etc
|   |-- init.d
|   |   `-- boot.d
|   |       `-- S70boot.xap
|   |-- plugboard
|   |   |-- plugboard.lua
|   |   `-- samples
|   |       |-- airytecSwitchoffApplet.lua
|   |       |-- ...
|   |       `-- xapCacheWebserverApplet.lua
|   `-- xap.d
|       |-- build
|       |-- iserver.ini
|       |-- plugboard.ini
|       `-- xap-serial.ini
|-- setup
`-- usr
    |-- bin
    |   |-- aliasmsg
    |   |-- bscmsg
    |   |-- iServer
    |   |-- ini
    |   |-- iniget -> ini
    |   |-- iniset -> ini
    |   |-- xap-hub
    |   |-- xap-plugboard
    |   `-- xap-serial
    |-- lib
    |   `-- libxap2.so
    `-- share
        `-- lua
            `-- 5.1
                |-- pl
                |   |-- Date.lua
                |   |-- ...
                |   `-- xml.lua
                `-- xap
                    |-- bluenode.lua
                    |-- ...
                    `-- roomnodetwin.lua
</code>

To enable various features you edit the ini files in /etc/xap.d setting enable=1

If you are running your Joggler over wireless you need to edit /etc/init.d/boot.d/S70boot.xap and uncomment the "ra0" network interface usage.
<code>
# Uncomment for WIRELESS
MYDEV="-i ra0"
</code>

Your hostname for the Joggler by default is "atom" you can change this in /etc/hostname it will be used in the triple "dbzoo.atom.XAP-PROGRAM"

Starting the Joggler xAP software
<code>
/etc/init.d/boot.d/S70boot.xap start
</code>

see [[#The 'iserver' parent element]] for configuration of the XML.
==== xAPFlash installation ====

If you already have xAPFlash installed on your Joggler this will perform an upgrade of the graphics and application leaving your XML configuration files intact.  If you don't already have it installed, it will additionally modify a configuration file so that the LAUNCH icon appears on your Joggler dashboard.  A reboot will be required if installing for the first time.  UPDATE: I found that even if just upgrading you needed a reboot for the new version to load.

<code>
# cd /tmp
# wget http://www.dbzoo.com/public/xapflash.run
# sh xapflash.run
</code>

To check what version you are running, look for a version number string in the xap-hbeat generated by the application
<code>
xap-hbeat
{
v=13
hop=1
uid=FF.0739:0000
class=xap-hbeat.alive
interval=60
source=UKUSA.xAPFlash.pc
}
Heartbeat
{
Version=beta 0.5g
Logon=Joggler
IP=192.168.1.4
}
</code>

If you are not running the iServer on the Joggler itself, you need to modify the config.xml and adjust the IP address from 127.0.0.1 to that of wherever your external iServer is running.

The following files/directories are placed onto your Joggler
  * /media/appshop/xAP
  * /media/appshop/applications.xml  (modified)

===== Browser =====

Works with Internet Explorer, Firefox and Safari, it should work in any browser supporting Flash (v10). Flash however imposes various security restrictions that this application violates. Specifically, it accesses your network via TCP (the iServer) whilst also having access to your local filesystem to read the config file.  This combination is forbidden as standard in the Flash security settings and so you will have to relax them by adding the local files folder location as a trusted site.

Navigate to this site to adjust your settings.\\
http://www.macromedia.com/support/documentation/en/flashplayer/help/settings_manager04.html

This site displays a page that show your personalised Flash security settings.  Add the folder containing the xAP Joggler files to Flash's trusted sites. This will allow Flash to both access local files and the iServer.

{{:livebox:flash-settings.png|}}

You may also access these setting this way
  * Control Panel -> Flash Player -> Advanced(tab) -> Trusted Location Settings...(button)

The xAPFlash GUI is now embedded into the HAH firmware.

{{:livebox:flash-in-a-can.jpg?640}}

====== Configuration ======

The file format used for all configuration files is XML.  The configuration of the system is split across two files:
  * config.xml
  * xAPconfig.xml (default and may be changed)

The ordering of pages, buttons and text boxes within the XML is significant as later elements are rendered on top of previous elements.

The system uses a configurable grid (table layout) in which to place an objects starting with position 0,0 as the top left hand corner.  The object grid position snaps the top left corner of the object into a grid cell.

For example a 5x3 grid, the default, would have the following cell coordinates.
<code xml>
		<gridXmax>5</gridXmax> <!-- maximum grid spaces horizontally -->
		<gridYmax>3</gridYmax> <!-- maximum grid spaces vertically -->
</code>

| (0,0) | (1,0) | (2,0) | (3,0) | (4,0) |
| (0,1) | (1,1) | (2,1) | (3,1) | (4,1) |
| (0,2) | (1,2) | (2,2) | (3,2) | (4,2) |

===== config.xml =====

A sample configuration file showing tags and their structure:
<code xml>
<joggler>
	<version>0.5</version>
	<name>joggler</name>
	<xAP>
		<uid>0737</uid>
        	<indicate1wayBSC/>
	        <bscbuttons/>
        	<bscpages/>
        	<bsctextboxes/>
        	<bscinternals/>
	</xAP>
	<usejogglerapi>auto</usejogglerapi>
	<configfilelocation>local</configfilelocation>
	<configfile>xapconfig.xml</configfile>
        <pausescreensaver>true</pausescreensaver>
        <startupvolumelevel>0</startupvolumelevel>
        <startupscreenbrightnesslevel>100</startupscreenbrightnesslevel>
	<iserver>
		<port>9996</port>
		<ip>192.168.1.138</ip>
		<password>Frogstomp</password>
	</iserver>
	<layout>
		<gridXmax>5</gridXmax>
		<gridYmax>3</gridYmax>
		<aspectLock>true</aspectLock>
		<background>
			<image>background.jpg</image>
			<scaleX>800</scaleX>
			<scaleY>420</scaleY>
		</background>
		<defaults>
			<button/>
			<label/>
			<time/>
			<bsctext/>
	  	        <textbox/>
	        </defaults>
	</layout>
</joggler>
</code>

Parent tag: <joggler> 

^^ Tag ^^ Value ^^ Description ^^
|| <version> || String || A indication of the target for this configuration file. Its purpose is informational only - it's not processed! ||
|| <name> || String || A string this is used to construct the xAP source name for the Flash application, this is the xAP instance name to complete the tuple VENDOR.DEVICE.INSTANCE. \\ \\ The VENDOR and DEVICE are hardcoded into the application as UKUSA and xAPFlash respectively. \\ \\ Given the name __joggler__ we would therefore construct the following: UKUSA.xAPFlash.joggler ||
|| <usejogglerapi> || true,false,auto || Activate available API functions.  Recommend you use 'auto' \\ When running on the Joggler, it is possible to take advantage of many of the built-in API functions. ||
|| <startupvolumelevel> || 0-100 || Set the Joggler volume level on starting the application. \\ //Only used when the Joggler API is detected// ||
|| <startupscreenbrightnesslevel>|| 0-100 || Set the Joggler screen brighness level on starting the application \\ //Only used when the Joggler API is detected// ||
|| <pausescreensaver> || Boolean || Will prevent the Joggler screen saver from starting while the application is running \\ //Only used when the Joggler API is detected.// ||

==== The 'configfilelocation' element ====

Parent tag: <joggler> 

This is a string to indicate the location of where to find the user interface.   The default is the local filesystem. It may also be a URL to a local webserver if you have many Jogglers that need to keep their user interfaces in sync.

Note: When using the URL form do no specify the configuration file, simply the location with a trailing /
<code xml>
<configfilelocation>http://webserver.com/configuration/</configfilelocation>
</code>

The system will append the <configfile> to the contents of this tag.

==== The 'configfile' element ====

Parent tag: <joggler>

Specify the configuration file to load that contains the User Interface definition.  Defaults to: xAPconfig.xml

A relative path specification will be from the location of where the xAPFlash application is running.

==== The 'xAP' parent element ====

Configuration via the following locations:
  * config.xml: ''<joggler> <xAP>''
  * xapconfig.xml: ''<joggler> <config> <xAP>''
  * config.xml: ''<joggler> <override> <config> <xAP>''

There are four distinct areas within xAPFlash that implement BSC.  Pages, Buttons, Text Boxes and some inbuilt endpoints that control internal functionality.  Each area is false by default.

^^ Tag ^^ Value ^^ Description ^^
|| <uid> || Number || Each xAP application on your network must have a unique UID.\\ \\ If you have more than one Joggler running xapFlash or are running the Flash application more than once then you __must__ adjust this field. ||
|| <bscbuttons> || Boolean  || Default: false ||
|| <bscpages> || Boolean  || Default: false ||
|| <bsctextboxes> || Boolean  || Default: false ||
|| <bscinternals> || Boolean  || Default: false ||
|| <indicate1wayBSC> || Boolean || Default: false - Used for BSC endpoints that do not respond to query events.\\ Enables usage of the special xapbsc- schema to designate a GUI element as controlling a 1way BSC element, that is a BSC element that does not support xAPBSC.query ||

**Those bsc... tags**

Display elements (pages, text boxes and buttons) are exposed as xAPBSC endpoints in their own right.  This means that they generate 'events' on your network as they change state and can be controlled remotely.  The visibility of each element is reported using the state= parameter within a xAPBSC.info or xAPBSC.event message.  Visibility for any screen element is controllable from xAP using xAPBSC.cmd messages.  You must use a non wildcarded target= line and the correct ID= value within your .cmd  messages.  Buttons also expose their 'pressed' state using an additional level based 'Button.State' endpoint. The actual on/off uses the state= parameter and because buttons can display multiple states they report this using the level=x/10 parameter.  Button.State is an input only xAP endpoint and so cannot be controlled from xAP.

==== The 'iserver' parent element ====

  * config.xml: ''<joggler> <iserver>''
  * xapconfig.xml: ''<joggler> <config> <iserver>''
  * config.xml: ''<joggler> <override> <config> <iserver>''

The contents of this section informs the system where the iServer is located, if you have installed the iServer onto your Joggler then the IP address will be 127.0.0.1 This is what you need to adjust if you have an external iServer.

^^ Tag ^^ Value ^^ Description ^^
|| <port> || number || iServer listening port. Default: 9996 ||
|| <ip> || Dotted quad || IPv4 address of the iServer ||
|| <password> || String || Optional.  Default: Joggler ||

<code xml>
	<iserver>
		<port>9996</port>
		<ip>192.168.1.138</ip>
		<password>Joggler</password>
	</iserver>
</code>

==== The 'layout' section ====

Parent tag locations:
  * config.xml: ''<joggler> <layout>''
  * xapconfig.xml: ''<joggler> <layout>''
  * config.xml: ''<joggler> <override> <layout>''

Configuration tags within this section control Look & Feel of the interface setting up global values and establishing defaults for configurable items; such as labels, buttons and textboxes.

^ Tag ^ Value ^ Description ^
| <gridXmax> | Number | The number of horizontal buttons in the default grid.  Default: 5 |
| <gridYmax> | Number | The number of horizontal buttons in the default grid.  Default: 3 |
| <aspectLock>	| Boolean | Setting this true will ensure that the vertical and horizontal gutter (between button) spacing is the same. This ensures double or treble size buttons remain square and line up |
| <marginLeft>	| Number | The pixel border width at the left of the Joggler screen (usually positive must not be 0 but can be negative) |
| <marginRight> | Number | The pixel border width at the right of the Joggler screen (usually positive must not be 0 but can be negative) |
| <marginTop> | Number | The pixel border width at the top of the Joggler screen (usually positive must not be 0 but can be negative) |
| <marginBottom> | Number | The pixel border width at the bottom of the Joggler screen (usually positive must not be 0 but can be  negative) |

==== the 'background' section ====

Parent tag locations:
  * config.xml: ''%%<joggler> <layout> <background>%%''
  * xapconfig.xml: ''%%<joggler> <layout> <background>%%''
  * xapconfig.xml: ''%%<joggler> <page> <background>%%''
  * xapconfig.xml: ''%%<joggler> <page> <textbox> <background>%%''
  * config.xml: ''%%<joggler> <override> <layout> <background>%%''

Configures a default background image that will appear on each <page> unless override.  See [[#the 'page' tag]]
<code xml>
<joggler>
	<layout>
		<background>
			<image>background.jpg</image>
			<scaleX>800</scaleX>
			<scaleY>420</scaleY>
		</background>
	</layout>
</joggler>
</code>

Remember the Joggler screen size is 800x420.

Key legend
  * L - Usable in the <layout> section
  * P - Usable in a <page> section
  * T - Usable in a %%<textbox>%% section

^ Tag ^ Key ^ Value ^ Description ^
| %%<image>%% | LP | String | The name of the image file to load as the background.\\  The following file formats are accepted: JPG, PNG, GIF, BMP and SWF |
| %%<scaleX>%% | L | Number | set the width of the background image.  Default: 100 |
| %%<scaleY>%% | L | Number | set the height of the background image.  Default: 100 |
| %%<width>%% | P | Number | set the width of the background image.  Default: 0 |
| %%<height>%% | P | Number | set the width of the background image.  Default: 0 |
| %%<visible>%% | PT | Boolean | Background is shown |
| %%<colour>%% | PT | String | 0xRRGGBB colour specification |
| %%<posX>%% | P | Number | Horizontal pixel position for this element\\ If signed eg +20 then is relative to the default grid position of this element. |
| %%<posY>%% | P | Number | Vertical pixel position for this element\\ If signed eg -20 then is relative to the default grid position of this element. |


==== the 'defaults' section ====

Parent tag locations:
  * config.xml: ''%%<joggler> <layout> <defaults>%%''
  * xapconfig.xml: ''%%<joggler> <layout> <defaults>%%''
  * config.xml: ''%%<joggler> <override> <layout> <defaults>%%''

Here we establish the baseline for our visual components to create a common look and feel and to reduce the amount of repetition in their specification.

<note>We use the British English spelling for colour.  Hoo Ra!</note>

^^ Parent tag ^^ Allowed child tags ^^ Description ^^
|| %%<label>%% || %%<font> <fontsize> <fontcolour> <alpha> <offset>%% || ||
|| %%<bsctext>%% || %%<font> <fontsize> <fontcolour> <alpha>%% || ||
|| %%<button>%% || %%<font> <fontsize> <fontcolour> <alpha>%% || ||
|| %%<textBox>%% || %%<font> <fontsize> <fontcolour> <alpha> <align>%% || ||
|| %%<time>%% || %%<font> <fontsize> <fontcolour> <alpha> <show>%% || ||
|| %%<button>%% || %%<style> <height> <width> <alpha>%% || ||

Details about the children
^^ Tag ^^ Description ^^
|| %%<font>%% || The name of a Font available from inside Flash. **Default: Verdana** ||
|| %%<fontsize>%% || the size of the font.  **Default: 14** ||
|| %%<fontcolour>%% || A Hex triple in the format 0xRRGGBB \\ \\ Default: \\ label,textBox: 0xFFFFFF\\ bsctext,time: 0xFFFFCC ||
|| %%<alpha>%% || Floating point number indicating transparency: 0 transparent, 1 Opaque.  **Default 1** ||
|| %%<align>%% || valid values are: left, right, centre, justify. **Default: left** ||
|| %%<show>%% || valid values: true, false. **Default: true** ||
|| %%<offset>%% || This is the vertical offset of the label from its default - just below the button position (positive or negative, you can also use the word 'centre' to auto compute an offset. ||
|| %%<style>%% || Defines the look and feel for the button.  see [[#the 'style' tag]] ||
|| %%<width>%% || Default width ||
|| %%<height>%% || Default height ||

Example:
<code xml>
      	<textBox>
        		<fontsize>28</fontsize>
        		<fontcolour>0xAABBEE</fontcolour>
        		<font>Verdana</font>
                        <align>centre</align>
      	</textBox>
</code>

===== User interface objects =====

The ''%%<button>%%'' object is the primary object which is used in the construction a user interface.  There are 3 primary modes in which a button will be used
  * in a control mode to trigger an xAP event.
  * in a read-only mode to display xAP data.
  * as a user-interface interaction device not taking part in any xAP flow.

The order in which buttons are parsed, top down, is important as this determines their display precedence.  Buttons found later in the configuration file will display over those found before them.

They may be placed at a grid position using ''%%<gridX><gridY>%%'' or can be directly located at an absolute pixel position using ''%%<posX><posY>%%''; these are mutually exclusive if using absolute posX,posY coordinates.

The ''%%<textbox>%%'' object is display only and has some additional properties from a button; its content may be HTML markup for example.

'Text Box' is really a misnomer as these may also contain local or remote images and even animated Flash (SWF) content.  Text boxes differ from buttons in that they display textual/image content rather than on/off status, and they do not control devices. Indeed text boxes do not intercept clicks at all and so can be placed over other elements as required.  You will find text boxes are far more flexible at displaying content from xAPBSC text devices than buttons.  Buttons used for this purpose only have small centered text areas within the button boundaries whereas textbox's can be any size and at any position. 

Text box elements are added to pages after all the button elements and in their XML order so visually they will be on top of any buttons on that page.  They do not prevent clicks being passed to buttons below even if they are opaque

All UI objects must have a unique NAME attribute
<code xml>
  <button name="unique button name"">
  </button>  
  <textbox name="unique textbox name">
  </textbox>
</code>

Those items defined in the [[#the 'defaults' section]] may also be specified inside either UI element to override a value.
<code xml>
<?xml version="1.0" encoding="windows-1252"?>
<joggler>
  <layout> 
    <defaults>
      <bsctext>
          <fontsize>40</fontsize>
      </bsctext>      
    </defaults>
  </layout>

  <page name="XX">
    <button name="unique button name"">
      <bsctext>
        <fontsize>20</fontsize>   <!-- OVERRIDE default of 40 -->
      </bsctext>      
    </button>
  </page>
</joggler>
</code>

They maybe populated with any of the following child tags according to the usage key legend below
  * BT - ''%%<button>%%'' & ''%%<textbox>%%''
  * B - ''%%<button>%%'' only
  * T - ''%%<textbox>%%'' only

^ Tag ^ Key ^ Description ^
| %%<gridX>%%\\ %%<gridY>%% | BT | Fixes the x,y position of the element on the grid . 0,0 is top left |
| %%<posX>%% | BT | Horizontal pixel position for this element.\\ If signed eg +20 then is relative to the default grid position of this element. |
| %%<posY>%% | BT | Vertical pixel position for this element. \\ If signed eg -10 then is relative to the default grid position of this element |
| %%<width>%% | BT | Element width either in pixels or /2 \2 x2 *3 etc\\ *2 will be double size\\ x3 will be triple size plus any gutter width additions (two widths in this case)  to ensure right hand edges align\\ /2 will be half size\\ \2 will be half size less any gutter width additions (one in this case)  to ensure right hand edges align non integer values may be used but do not right align when using \ or x |
| %%<height>%% | BT | Element height either in pixels or /2 \2 x2 *3 etc as for width above |
| %%<text>%% | BT | Default text to display.  Will be replaced when an associated xAP event is received. |
| %%<textPrefix>%% | BT | If %%<mode>%% is text this is prepended to the xAP item. |
| %%<textSuffix>%% | BT | If %%<mode>%% is text this is appended to the xAP item. |
| %%<html>%% | T | boolean, default: false.  If defined allows full HTML inside the %%<textPrefix> <textSuffix>%% and %%<text>%% tags\\ When entering html within CDATA tags the html tags do not need to be paired but must adhere to html standards\\ \\ %%<textPrefix><![CDATA[<FONT FACE="Times New Roman" SIZE="36" COLOR="#BB5566">]]></textPrefix>%%\\ %%<textSuffix><![CDATA[</FONT>]]></textSuffix>%%\\ \\ %%<text><![CDATA[<img height="200" width="200" src="http://www.bbc.co.uk/home/beta/7.2/object/clock/tiny.swf"></img>]]></text>%% |
| %%<font>%% | T | The default font used for display |
| %%<fontcolour>%% | T | RGB hex triple for the colour.  Must be prefix with 0x. i.e. 0xDDFFAA |
| %%<fontsize>%% | T | Default font size of the displayed text |
| %%<multiline>%% | T | Boolean: true/false |
| %%<wordwrap>%% | T | Boolean: true/false |
| %%<hide>%% | B | text,state, default: none.  For a BSC text button (''%%<mode>text</mode>%%'') defines what is hidden |
| %%<style>%% | B | see [[#the 'style' tag]] |
| %%<alpha>%% | BT | Amount of transparency of ALL items contained withing the UI element.\\ Floating point number: 0 transparent, 1 Opaque. Default 1 |
| %%<xAP>%% | BT | see [[#the 'xAP' tag]] this is how you link a GUI object to an xAP endpoint |
| %%<background>%% | T | see [[#the 'background' section]]. |
| %%<border>%% | T | Boolean: true/false.  Default: false |
| <bordercolour> | T | RGB hex triple for the colour. Default 0x888888 |
| %%<group>%% | B | makes a button into a radio button with 'mutually exclusive' style.  Each button in the group must be named with the same group name.  %%<group>myGroup</group>%% |

These items require more clarification so they have been split out from the table above to allow greater explanatory detail.

^ Tag ^ Key ^ Description ^
| %%<mode>%% | BT | Determines the behaviour of the UI interface object.  Maybe one of the following keywords; control, lcontrol, status, secure, memory, pagetoggle, link, pageshow, pagehide, text, displaytext, toggle, config, xap, dimmer, slider, function |

**control**: A button will directly control something when pressed.  Only xAPBSC output endpoints can be controlled. Input endpoints such as PIR's, TEMP, CURRENTCOST obviously can't.  Sends a ''state=toggle'' xAPBSC.cmd to its associated endpoint.

**lcontrol**: (Level control) Almost identical to control except that it also includes a ''level=100%'' key/pair in the message.  This ensures that a level based endpoint, for example a dimmed light, always comes back on at 100% brightness.

**status**: Means that the button will only display the ''status='' value of a BSC device.  Pressing the button does not attempt to control it. i.e. No xAPBSC.cmd message will be sent.

**secure**: This creates a self toggling button that sets a 'secure' mode . This is used in conjunction with a 'memory' device.  When secure mode is set then any memory device will 'bleep' if activated and its button retains a different icon after triggering. So for example you can include PIRs as memory devices, and as you retire for the night  you set secure mode on the bedside Joggler which includes any downstairs PIRs.  If any downstairs PIRs are activated then they will bleep and remain showing the triggered state until cleared.  Turning secure mode off clears all 'secure' icons and disables bleeps. 

**memory**: These are status type devices that react differently when secure mode is set (see above).

**pagetoggle**: This allows the button to reveal/hide a named page - either to superimpose a smaller page (often called a sub page) or to move to a totally new page.  The name of the page is supplied within a ''%%<page name="">%%'' tag.  Maybe deprecated in future releases please use ''%%<mode>link</mode>%%'' instead.

**link**: This allows the button to reveal/hide a named element (page, button or textbox). Often used to superimpose a smaller page (often called a sub page) or to move to a totally new page. The name of the element is supplied within an accompanying ''%%<link>...</link>%%'' tag.  See [[#the 'page' tag]]

**pageshow**: Reveals a named page but can't hide it again.  (NB will be deprecated beta 6)

**pagehide**: Hides a named page but can't reveal it again. (NB will be deprecated beta 6)

**text**: This allows the ''text='' key/value associated with a xAPBSC endpoint to be displayed on the button.

**displaytext**: This allows the ''displaytext='' key/value associated with a xAPBSC endpoint to be displayed on the button. 

**config**: The button toggles an overlaid configuration screen showing grid layout coordinates and information.  Clicking on one of the blue button numbers displays pertinent information for that button.  If you navigate away from this page the setting will revert so each page will need its own CONFIG button if you want to use this debugging feature.

{{ :livebox:config-button.png }}

<code xml>
		<button name="Configure">
			<label>
				<text>Configure</text>
			</label>
			<gridX>3</gridX>
			<gridY>0</gridY>
			<mode>config</mode>
		</button>		
</code>

**toggle**: This creates a self toggling button whose state changes when clicked - useful to set a mode of operation.  see [[#Using <on>/<off> tags]]

**slider**: Allows a SWF slider control to be embedded onto your page, to either control or display BSC [[http://xapautomation.org/index.php?title=Basic_Status_and_Control_Schema#Level|level=]] items.  Note: may also be used with BSC Stream (text=) items in a read-only capacity. 

Additional configuration attributes of the ''%%<mode>slider</mode>%%'' may be specified within a set of ''%%<slider></slider>%%'' group tags.  The following children are allowed:

^ Tag ^ Description ^
| <design> | Currently only two available: o2, sleek. Default: nothing\\ The contents of the tag are use to construct a filename for the slider VALUEslider.swf, where VALUE is the <design> tag contents. |
| %%<style> %%| The name of the underlying SWF file ie "o2volumecontrol.swf" becomes its style; o2volumecontrol, sleekvolumecontrol |
| <rotation> | vertical(-left), vertical-right, horizontal(-left), horizontal-right |
| <min> | Sliders minimal range scaling value |
| <max> | Sliders maximum range scaling value |
| <type> | embedded, popup - popup can only be used with real BSC level endpoints |
| <delay> | type POPUP only - Milliseconds.  Configures the delay before the popup Slider / Dimmer Control will appear when the button is pressed and released |
| <latency> | BSC LEVEL only - Milliseconds.  If the device being controlled by the Slider / Dimmer Control has any latency, it is a good idea to configure an appropriate value in this tag to prevent the device from being flooded with xAP messages.\\ \\ Choosing an appropriate value is key to the smooth behavior of a slider.  When a slider is dragged its’ position is updated locally and then again by the responses (xAPBSC.event) received back from the device.  The time between issuing a xAPBSC.cmd and the xAPBSC.event response being received back confirming the change is the latency. You can determine this fairly accurately using xFX Viewer and the timestamps on the two messages.   It is best to set the latency to just longer than the time between these two messages.  Some controllers just immediately return an event and some may only return an event once the device has reached its new level. The xAP C-Bus lighting controller does the latter and has a round time of about 80mS . Using a latency of 100mS permits 10 update messages per second and so results in a realtime reaction to the slider movements. |

Example of how to display the current temperature as a slider object.  Note: the GridX and GridY are for the BOTTOM,LEFT hand corner of the slider, the object will extend UP from this location when using the "vertical" rotation.

{{ :livebox:temp-slider.png|}}
<code xml>
		<button name="slider-temp1">
			<label>
				<text>1wire 1</text>
			</label>
			<bsctext>
			  	<fontsize>20</fontsize>
			</bsctext>						
			<gridX>1</gridX>
			<gridY>3</gridY>
			<xAP>
				<schema>xAPBSC</schema>
				<uid>FF00DB80</uid>
				<source>dbzoo.livebox.controller:1wire.1</source>
			</xAP>
			<mode>slider</mode>
			<slider>
			   <type>embedded</type>
			   <min>-20</min>
			   <max>50</max>
			   <design>o2</design>
			   <rotation>vertical</rotation>
			</slider>
		</button>
</code>


**function** Various function buttons have now been added to the xAPFlash application.  These can be used by setting a button <mode> to "function", together with including in a ''<Function></Function>'' section containing the following <type> tags

  * **xcclear**: When pressed this will clear any xapconfig.xml file that may be saved in the SharedObject

  * **ssclear**: When pressed this will clear any persisted state information that may be saved in the SharedObject

  * **volumelevel**: (Joggler only) When pressed this will pop-up a volume level control that allows changing of the volume.  Reports volume level over xAP.

{{ :livebox:volumelevel-o2.png }}

<code xml>
		<button name="volume">
			<label>
				<text>Volume</text>
			</label>
			<gridX>1</gridX>
			<gridY>0</gridY>
			<mode>function</mode>
			<Function>
                          <type>volumelevel</type>
                          <slider>
                            <style>o2volumecontrol</style>
                          </slider>
                        </Function>
		</button>
</code>

The style of the pop-up volume level can also be controlled by including a <slider> section using the following as the style type: ''%%<style>sleekvolumecontrol</style>%%'' or ''%%<style>o2volumecontrol</style>%%''.  Default: sleekvolumecontrol

  * **screenbrightnesslevel** (Joggler Only)

When pressed this will pop-up a screen brightness level control that allows changing of the Joggler screen brightness.  Reports screen brightness level over xAP.

{{ :livebox:brightness-slider.png }}

<code xml>
		<button name="Brightness">
			<label>
				<text>Brightness</text>
			</label>
			<gridX>2</gridX>
			<gridY>0</gridY>
			<mode>function</mode>
			<Function>
				<type>screenbrightnesslevel </type>
			</Function>
		</button>
</code>
The style of the pop-up brightness level can also be controlled by including a <slider> section, just like volumelevel, using the following as the style type: ''%%<style>sleekslider</style>%%'' or ''%%<style>o2slider</style>%%''.  Default: sleekslider

  * **screensaverhold** (Joggler Only)

When pressed this will prevent the Joggler screen saver from running when pressed.

  * **update** (Joggler Only) When pressed this will force a new xapconfig.xml to be downloaded and compared with the copy stored in the SharedObject to see if it has changed.

===== The 'style' tag =====

The style tag is used to define the Look and Feel of an object.  

<note warning>The style tag when used with <page><link> must always use a DUAL icon. See [[#the 'page' tag]]</note> 

You may also use this tag to define your own custom buttons using external images or SWF files.  External images file have a naming nomenclature that allows you to have multiple graphics to represent the possible button states.  Currently only the ON and OFF state are handled.  This is done by appending _on_ or _off_ to the basename of the image.

{{ :livebox:black-red-blue-button.png}} There are three styles defined internally
  * black
  * blue
  * red

The above three buttons where produced with the following definition snippet.
<code xml>
		<button NAME="Button One">
			<gridX>0</gridX>
			<gridY>0</gridY>
			<style>black</style>
		</button>
		<button NAME="Button Two">
			<gridX>1</gridX>
			<gridY>0</gridY>
			<style>red</style>
		</button>
		<button NAME="Button Three">
			<gridX>2</gridX>
			<gridY>0</gridY>
			<style>blue</style>
		</button>
</code>

==== Using a Single image ====

{{ :livebox:temp-button.png}} Using a single image would be desirable when no STATE will be associated with a button and its purpose is to display information.  

^ Image ^ Filename ^
| {{:livebox:inside-temp-icon.png|}} | inside-temp-icon.png |
| {{:livebox:outside-temp-icon.png|}} | outside-temp-icon.png |

Snippet for how the Outside button was constructed.  xAP endpoint binding has been omitted from the example.
<code xml>
		<button NAME="temperature">
			<gridX>0</gridX>
			<gridY>0</gridY>
			<label>
				<text>Outside</text>
				<fontcolour>0x000000</fontcolour>
				<offset>-20</offset>
			</label>
			<bsctext>
				<fontcolour>0x000000</fontcolour>
			</bsctext>			
			<style>outside-temp-icon.png</style>
                </button>
</code>

Here we have used two distinct icons as the button image styles to represent the temperature from different sensors.


==== Using a DUAL image ====

In this example the following button images will be displayed on the screen depending on the STATE of the button.
^ State ^ Image ^ Filename ^
| OFF | {{:livebox:glossy_button_off_.png|}} | glossy_button_off_.png |
| ON | {{:livebox:glossy_button_on_.png|}} | glossy_button_on_.png |

When using this DUAL button functionality we must use the _off_ button as the style image. The width and height of the style graphic must also be specified.
<code xml>
		<button NAME="Relay 1">
			<style>glossy_button_off_.png</style>
			<width>80</width>
			<height>80</height>
		</button>
</code>

Without too much effort the three button example from above can be changed into this

{{ :livebox:relay-glossy.png }}


==== Using a SWF file ====

For the ultimate in control, flexibility and scalability, as they are vector based, you can use buttons in Shockwave Flash format.  Button states are based on a timeline position with various frames representing their state.

^ Frame ^ State ^ Description ^
| 1 | blank | OFF / BLANK  no symbol |
| 2 | on | ON with bulb symbol |
| 3 | off | OFF with bulb symbol |
| 4 | dull | dull / pressed blank |
| 5 | error | ERROR with X symbol |
| 6 | unknown | UNKNOWN with ? symbol |
| 7 | dim | DIMMED (between 0 and 100% |
| 8 | backlit | ON / BACKLIT with no symbol |
| 9 | appon | ON with appliance symbol |
|10 | appoff | OFF with appliance symbol |

<note>TBD: Need some examples of how this works.</note>

===== The 'xAP' tag =====

This element allows you to connect a GUI object with a xAP endpoint so that it may be controlled or its value may be displayed.

A simple example of how this tag group is used to connect, in this instance an xAPBSC endpoint, to a controlling button.
<code xml>
		<button NAME="Relay 1">
			<gridX>2</gridX>
			<gridY>0</gridY>
			<xAP>
				<schema>xAPBSC</schema>
				<uid>FF00DB60</uid>
				<source>dbzoo.livebox.controller:relay.1</source>
			</xAP>
			<mode>control</mode>			
		</button>
</code>

More about the xAP tags children

^ Tag ^ Description ^
| <schema> | The name of the xAP schema this element is associated with, normally **xAPBSC**.  If **generic** is used then a named section of <generic> should be included to further define the required schema interpretation.  **xapbsc-** indicates a one way bsc element, that is one that does not support xAPBSC.query, you must also enable this in the xAP config section, see [[#The 'xAP' parent element]]. |
| <uid> | The UID of the xAP endpoint.  Setting of ''<uid>'' tag to * will allow matching of incoming messages on ''<source>'' tag instead. |
| <source> | the source definition of an xAP endpoint. i.e. dbzoo.livebox.controller:relay.1 |
| <on> \\ <off> | These two tags allow you to send any xAP message you wish when a button is clicked or changes state.\\ Paste a complete 'raw' xAP message between these tags and it will be sent verbatim. |
| <generic> | This section will appear if the <schema> is generic, more about this later. |

==== Using <on>/<off> tags ====

This button toggles on and off sending the RAW xAP message when each state is entered.  This is a contrived example to demonstrate functionality, normal livebox RF control messages would be xAPBSC to a directed endpoint such as dbzoo.livebox.Controller:rf.1

No feedback from the endpoint can be rendered as part of the button's state, this is a fire-and-forget xAP message generator.

<note important>The UID and SOURCE tags will be overwritten with the xAPFlash applications values however place holders for them must be present in the RAW xAP message and they cannot be omitted.</note>

<code xml>
		<button name="genericSchema">
			<label>
				<text>xap generic</text>
			</label>
			<gridX>3</gridX>
			<gridY>0</gridY>
			<xAP>
				<on>
xap-header
{
v=12
hop=1
class=rf.xmit
target=dbzoo.livebox.Controller
source=
uid=
}
rf
{
data=010201130A7300130113011304C9011300000A0127100A259A71
}
				</on>
				<off>
xap-header
{
v=12
hop=1
class=rf.xmit
target=dbzoo.livebox.Controller
source=
uid=
}
rf
{
data=010201130A7300130113011304C9011300000A0127100A259A70
}
				</off>
			</xAP>
			<mode>toggle</mode>
		</button>
</code>

==== Using the <generic> tag ====

The generic tag is used to supply additional information about the xAP message for parsing when using the ''<schema>generic</schema>'' mechanism.

The following children are allowed inside the <generic> parent container.

^ Tag ^ Description ^
| <Class> | the xAP schema name ''class='' value |
| %%<body>%% | The name of the message block container. xAP messages may include several message blocks but they each have a unique name. |
| <parameter> | The name of the data value you wish to extract. |

Consider the following definition usage for the generic schema that watches for an inbound SMS message and displays the text into a textbox.  See [[hah#xap_sms]]

Sample inbound xAP packet
<code>
xap-header
{
v=12
hop=1
UID=FF00DD00
source=dbzoo.livebox.SMS
class=SMS.message
}
inbound
{
msg=(Message text up to 128 characters)
num=+44-123-4567-8900
}
</code>

And the textbox we will use for displaying the message.  The value of the <parameter> is assigned as the TEXT for the textbox.

{{ :livebox:sms-in-textbox.png }}

To get the visual style above we first place a semi-translucent textbox onto the page, onto this we place the TEXT making sure the background for this overlay object is invisible.
<code xml>
		<textbox name="sms-in-background">
			<gridX>3</gridX>
			<gridY>0</gridY>
			<width>*4</width>
			<height>/4</height>
			<background>
				<colour>0xFFFFFF</colour>
			</background>			
			<alpha>0.2</alpha>
		</textbox>

		<textbox name="sms-in">
			<gridX>3</gridX>
			<gridY>0</gridY>
			<width>*4</width>
			<height>/4</height>
			<background>
				<visible>false</visible>
			</background>
			<text>No SMS messages</text>
			<xAP>				
				<schema>generic</schema>
				<source>dbzoo.livebox.SMS</source>
				<uid>FF00DD00</uid>
				<generic>
					<Class>SMS.message</Class>
					<body>inbound</body>
					<parameter>msg</parameter>
				</generic>
			</xAP>			
		</textbox>
</code>

If you wanted to also display the phone number, you'd need to create another text box just like the one above and set the <parameter> to be 'num'.
===== The 'page' tag =====

A page container allows UI elements to be group together.  Each page must be uniquely named using a NAME attribute.

^ Tag ^ Description ^
| <password> | Joggler only - Allows a page to be password protected, displays a on screen keyboard for entry of the password.  Each time the page is navigated the password will be required.  For non-Joggler displays this entry will be ignored and access allowed. |
| %%<background>%% | see [[#the 'background' section]]. |
| <alpha> | Alpha blending from 0.0 (transparent) to 1.0 (opaque).  ALL objects on the page will inherit this value. |
| <visible> | Boolean to show or hide the element at startup. Default: true |
| %%<group>%% | Only one member of a group can be active at once (radio group).  If a page in the group is made visible all others will be hidden. |

Empty <layout>, %%<button>%% and %%<textbox>%% tags have been inserted to show their relationship with respect to a <page> tag.

<code xml>
<joggler>
	<layout/>
	<page NAME="Menu">
		<group>Menu</group>		
		<visible>true</visible>
                <button/>
                <textbox/>
        </page>
	<page NAME="Page1">
		<group>panel</group>		
		<visible>true</visible>
                <button/>
                <textbox/>
        </page>
	<page NAME="Page2">
		<group>panel</group>		
		<visible>false</visible>
                <button/>
                <textbox/>
        </page>
</joggler>        
</code>

===== OSD - On Screen Display =====

This allows you to implement POPUP pages that are triggered by messages adhering to the [[http://www.xapautomation.org/index.php?title=On_Screen_Display_%28OSD%29_Schema|xAPOSD schema]]

^ Main screen ^ After arrival of OSD xAP message |
| {{:livebox:before-osd-message.jpg?320}} | {{:livebox:with-osd-message.jpg?320}} |

To implement an OSD you need to have in place the following:
  * a page with its NAME="OSD"
  * a textbox on that page with NAME="OSD"
  * a hidden button that is used to supply a filter to the iServer so that xAPOSD schema originating source will be passed though to the xAPFlash application.

The snippets used in this example can be examined in more detail: {{:livebox:osd.zip|}}

First we will examine the incoming xAP message that will fire our OSD page.
<code>
xap-header
{
v=12
hop=1
uid=FF111300
Class=xAP-OSD.Display
Source=dbzoo.acme.test
}
Display.Text
{
Line1=Incoming : Mobile Phone call
Line2=Telephone, 07887 123456
Duration=10
}
</code>
The key things to examine are the CLASS, SOURCE and BLOCK BODY.   The CLASS which is "xAP-OSD.Display" as per the xAPOSD schema. Also supported and synonymous is "class=message.display".

By default if the ''duration'' key is not supplied the popup will be displayed for 10 seconds.

The SOURCE/UID on the xAP message above becomes the ''<uid> and <source>'' of the invisible button that is created so that messages from this originator are passed by the iServer.
<code xml>
      <!--  this was created just to facilitate messages from xAP being 
	  registered to be passed through iServers filters  -->
		<button>		
			<visible>false</visible>
			<xAP>
				<schema>xAPOSD</schema>
				<uid>FF111300</uid>
				<source>dbzoo.acme.test</source>
			</xAP>
		</button>
</code>

Now we create the OSD definition
<code xml>
<!-- Page must be called OSD -->
	<page NAME="OSD">
		<visible>false</visible>
		<group>Centre</group>
		
<!-- additional elements may be inserted for aesthetic reasons -->
		<textbox NAME="osd-background">
			<alpha>.7</alpha>
			<gridX>1</gridX>
			<gridY>1</gridY>
			<width>x6</width>
			<height>x2</height>
			<background>
				<colour>0xFFFFFF</colour>
			</background>
		</textbox>
		
<!-- One textbox element must be named OSD -->
		<textbox NAME="OSD">
			<background>
				<visible>false</visible>
			</background>
			<gridX>1</gridX>
			<gridY>1</gridY>
			<width>x6</width>
			<height>x2</height>
			<border>true</border>
			<bordercolour>0xFFFFFF</bordercolour>
			<fontsize>24</fontsize>
			<fontcolour>0x000000</fontcolour>
			<visible>true</visible>
			<text>Your telephone calls display here</text>
			<mode>text</mode>
		</textbox>
	</page>
</code>
====== Inheritance ======

This area is a little confusing.

If <tag> is our configuration element then the following precedence model, in increasing priority order, is applied.
  * config.xml: <joggler><tag>
  * xAPconfig.xml: <joggler><SECTION><tag>
  * config.xml: <joggler><override><SECTION><tag> 

We use the <override> tag in the config.xml file to encapsulate the group of tags that are overriding any value configured in the xAPconfig.xml file.

<SECTION> may be the following depending on what we are overriding.
  * config - is used to access the children that are descendants of the <joggler> element.
  * layout

===== Overriding the Main config from the UI file =====

For example, if config.xml contained the following
<code xml>
<joggler>
   <iserver>
      <ip>192.168.1.138</ip>
    </iserver>
</joggler>
</code>

We could override its value in the xapconfig.xml file like this
<code xml>
<joggler>
  <config>
     <iserver>
       <ip>127.0.0.1</ip>
    </iserver>
  </config>
</joggler>
</code>

===== Overriding the UI from the MAIN config file =====

Conversely, if the xapconfig.xml had a configuration like this:
<code xml>
<joggler>
  <config>
     <iserver>
       <ip>192.168.1.138</ip>
    </iserver>
  </config>
</joggler>
</code>

We could override in the main config.xml file like this.
<code xml>
<joggler>
  <override>
    <config>
      <iserver>
        <ip>127.0.0.1</ip>
      </iserver>
    </config>
  </override>
</joggler>
</code>

====== Resources ======

===== Buttons =====

Some buttons of various colours.

| {{:livebox:glossy_yellow_button.png|}} | {{:livebox:glossy_blue_button.png|}} | {{:livebox:glossy_purple_button.png|}} | {{:livebox:glossy_button_dkgreen.png|}} |
| {{:livebox:glossy_button_off_.png| }} | {{:livebox:glossy_button_on_.png| }} | {{:livebox:glossy_pink_button.png|}} |
| {{:livebox:glossy_orange_button.png|}} | {{:livebox:glossy_cyan_button.png|}} | {{:livebox:glossy_gray_button.png|}} |
===== Backgrounds =====

Some sample backgrounds that you might like to use
^ abstract ^ azure ^ black ^ black2 ^
| {{:livebox:abstract-background.jpg?160}} | {{:livebox:azure-background.jpg?160}}| {{:livebox:background.jpg?160}}| {{:livebox:black-background.jpg?160}} | 
^ blue ^ leaf ^ sonata ^ sonata-menubar ^
| {{:livebox:blue-background.jpg?160}}|  {{:livebox:leaf-background.jpg?160}}| {{:livebox:sonata-background.png?160}} |{{:livebox:sonata-background-menubar.jpg?160}} |

===== Sample HAH UI =====

The following file {{:livebox:hah-sample-v2.tar.gz|}} contains the graphics and configuration to produce the User Interface displayed below. The xAP bindings are pre-configured for the HAH so it should do something out of the box.
You'll want to customize the generic labels to indicate what rooms the sensors and controlled devices are in. 

If you want to try this on your Joggler you can do the following.  It will ERASE your current config.xml and xapconfig.xml.  By default the config.xml has the setting for the IP as 127.0.0.1 and assumes you are running an iServer on your Joggler too.
<code>
cd /media/appshop/xAP
wget http://www.dbzoo.com/_media/livebox/hah-sample-v2.tar.gz
tar zxf hah-sample-v2.tar.gz
</code>

{{:livebox:control-hah.png|}}

{{:livebox:monitor-hah.png|}}