Using xAP and xPL Displays

Note: If you are new to xAP or xPL, please begin by reading xAP and xPL - Getting Started.

Most users are familiar with using the "speak" command to output speech to one or more devices. There exists a similar capability for sending messages to display devices. These devices may be physical (e.g., a VFD like those used in squeezeboxes) or virtual (like the system pop-up that can run on win32 systems).

Configuration

Begin by declaring "display_rooms" within your local mh.ini file using the syntax: code display_rooms=<room></room> => schema=<schema_name></schema_name> address=<target></target> device=<devicetype></devicetype>[,] code where:

1. <room></room> is any room name that you would like to use (spaces and punctuation are not permitted)
2. <schema_name></schema_name> is a valid schema name. Currently, only message.display (for xAP) and osd.basic (for xPL) are supported.
3. <target></target> is the xAP or xPL target. Examples are: mi4.intranetlaunch.castor (for xAP) and slimdev-slimserv.softsqueeze (for xPL)
4. <devicetype></devicetype> is either xap or xpl (note lowercase)

An example is: code display_rooms=castor => schema=message.display address=mi4.intranetlaunch.castor device=xap,

              family_room => schema=osd.basic address=slimdev-slimserv.squeezebox device=xpl

code This provides declarations for two rooms: castor (a roving laptop display) and family_room (a squeezebox display).

Now that a set of display "rooms" are defined, you use them in a manner very similar to targeting speech to specific devices. Either you (1) manually specify the "display_rooms" argument when calling display or (2) you map one or more display rooms to a display_apps param. The first method allows explicit control (which is occasionally needed) within your user code logic as well as skips any requirement for creating the application to room "mapping". An example looks like: code &display("display_rooms=castor,living_room My message"); code where the "My message" portion is what is sent to the displays. Note that the above command allows a way of embedding display logic that can combine different devices using different schemas and protocols (e.g., both xPL and xAP).

If the second technique is preferred (and, doing so allows changes to configurations to be much easier), then declare a "display_apps" param in mh.ini using the syntax: code display_apps=<app_name></app_name> => display_rooms=<room></room>[|<room2></room2>...] duration=<duration></duration>[,] code where:

1. <app_name></app_name> is any application name that you want to use (excepting punctuation and spaces)
2. <roomx></roomx> is a room name that is already declared. Multiple rooms are delimited by a single pipe "|" character
3. <duration></duration> is the duration to display the message (optional; the default is "10" if not specified)

An example is: code display_apps=cid => display_rooms=castor|family_room, weather => display_rooms=castor duration=30 code When you use the display_apps param, then you can simplify your messages, like: code my $phone_cid = '555-1212'; &display("app=cid Call from $phone_cid"); code

Duplicating Speak Messages

The discussion above provides a path for controlling messages specific to display devices. But, what if you simply want to "echo" what is already being spoken? If this is appealing, then the easiest way is to simply include the "echo" param in your speak call, like: code speak("echo=xap|xpl System is shutting down in 30 seconds"); code This example not only speaks the message but also broadcasts the message to every xAP or xPL device that exists (the display logic picks the standard message.display and osd.basic schemas by default).