UAPI Specification for RS-232

 

Ubiquity Applications Programming Interface (UAPI)

 for Controlling the Destiny Networks' Domain Controller

via RS-232 Interfaces

Version 2.6

Overview

This document describes the basic UAPI protocol used to control the Domain Controller from external displays, keypads, and other controllers (hereafter referred to as the "controlling device") over RS-232.

In this version, commands received can provide the "fully qualified absolute address" of the device to be controlled or the "relative address" of it. The fully qualified absolute address of the device can be used to control any device in the house. The relative address can only control devices located in the room in which the controlling device is located. For example, a display in the Family room can send a "lights on" command without specifying the Family room because the Domain Controller knows that the display is in the Family room. This latter case enables the same display to be used in other rooms (and even other houses) without additional programming.

New in version 2.6 is that a serial port can be both a driver for an AV component (or other system) and a UAPI listener, but UAPI commands must be proceeded with the two characters "@#" and must be followed by the three characters "%^*".

 
Direction of communication

For  communication over RS-232 the direction of communication is from the controlling device to the Domain Controller only. The Domain controller will not reply to or acknowledge the message.

Initialization and Sequencing of Commands

After the serial line is up and running, the controlling device can initiate a command at any time by sending an ASCII string to the Domain 5000. No set up commands are required. Any command may be sent in any order.

Checksum

The ASCII commands do not have a checksum.

Termination Character

The Domain Controller expects the linefeed character at the end of the command. Commands without the linefeed will not be processed. The linefeed character is "0A" in hexadecimal and is often represented as "\n".

 
Leading zeros

Leading zeros are not required. Therefore, values can be represented as 3 and 26, instead of 003 or 026 (however, 003 or 026 are allowed).

 
RS-232 Interface

Standard RS-232 Protocol

Baud Rate

Start Bits

Data Bits

Stop Bits

Parity

9600 bps

1

8

1

None

 

 
Commands:

There are two types of commands:

  • Commands that use an address relative to the room that the controlling device is located in

  • Commands that use a fully qualified absolute address.

 

 

Relative Address Commands

Commands that use the relative addresses of the devices in a room can only control those devices located in the room in which the controlling device is located (whose location is specified to the Domain Controller via the Design Module).

The format of this type of command is:

<device type abbreviation>:<value>\n

where:

<device type abbreviation> is defined in the list below

":" is the colon key

<value> is the value to which all devices of this type will be set

\n is "backslash n" representing a linefeed character

 

Remember that if the serial port is being used both as a driver of some AV component or lighting system AND is receiving UAPI command, the UAPI commands must be proceeded with the two characters "@#" and must be followed by the three characters "%^*"

Room Scene

s:Normal\n

Sets the Room Scene to Normal

s:Reading\n

Sets the Room Scene to Reading

s:Romantic\n

Sets the Room Scene to Romantic

s:TV\n

Sets the Room Scene to TV

s:Path\n

Sets the Room Scene to Path

s:Off\n

Sets the Room Scene to Off

s:Normal/Off\n

Toggles the Room Scene to Normal if the scene is presently Off and to Off if it is any other scene

 

On/Off and Open/Close Devices

all.curtains:r:100\n

Open all curtains in the room

all.curtains:r:0\n

Close all curtains in the room

all.fans:r:100\n

Turn on all fans in the room

all.fans:r:0\n

Turn off all fans in the room

all.fireplaces:r:100\n

Turn on all fireplaces in the room

all.fireplaces:r:0\n

Turn off all fireplaces in the room

all.fountains:r:100\n

Turn on all fountains in the room

all.fountains:r:0\n

Turn off all fountains in the room

all.lights:r:<brightness>\n

Turn on all lights to a brightness level where "<brightness>" is a value form 0 to 100

all.sprinklers:r:100\n

Turn on all sprinklers in the room

all.sprinklers:r:0\n

Turn off all sprinklers in the room

all.windows:r:100\n

Turn on all windows in the room

all.windows:r:0\n

Turn off all windows in the room

 

AV Entertainment

m:<cmd>\n

Sends a general command to control the entertainment equipment where <cmd> is one of: off, volUp, volDown, mute, chUp, chDown

m:s:<source>\n

Sets up the whole path to play a source where <source> is one of:amfm, cable, cable set tip box, cblsat, cd, dvd, game console, microphone, mp3, pvr, satellite, tuner, vcr,

m:t:<transport>\n

Activates one of the transport commands where <transport> is one of: stop, play, pause, prev, next, rew, fwd, rec, rpt, pageup, pagedown, leftright

m:m:<menu>\n

Activates one of the menu commands where <menu> is one of: exit, guide, menu, select, setup, up, down, left, right

m:n:<#>\n

Sends the number # where <#> is a number from 0 to 9

m:n:enter\n

Sends the "enter" command

m:v:<cmd>\n

Sends a command to control the video picture where <cmd> is one of anamorphic, widescreen,standard, VideoMode (which cycles through the video modes)

m:a:<cmd>\n

Sends a command to control the audio picture where <cmd> is one of matrix, stereo-5ch, stereo-2ch, DTS, Dolby-digital, THX, Prologic, Mono, AudioMode (which cycles through the audio modes)

 

HVAC

t:m:Heat\n

Set the thermostat to heating mode

t:m:Cool\n

Set the thermostat to cooling mode

t:m:Off\n

Set the thermostat to off

t:m:Auto\n

Set the thermostat to auto mode

t:a:on\n

Turn HPS automation on for HVAC (only) in this zone

t:a:off\n

Turn HPS automation of for HVAC (only) in this zone

t:f:on\n

Turn the fan On (the fan will be on all of the time)

t:f:Auto\n

Turn the fan to auto (the fan will only be on when needed)

t:t:up\n

Increase temp 1 degree

t:t:down\n

Decrease temp 1 degree

t:t:<#>\n

Set temp to # where # is a number between 30 and 99

 

Security System

a:<cmd>\n

Sends a command to the security system where <cmd> is alarm system dependent and is one of: emergency, police, fire, arm away, arm stay, chime, instant

a:<key>\n

Sends the keypad button <key> to the security system

 

Groups of Actions

g:<name>\n

Sends the name of a Group of Actions where <name> is the name of the Group of Actions that will begin executing immediately. The following Groups of Actions are common, but are not auto generated in this release:

  • All Outdoor Lights On, All Outdoor Lights Off,

  • All Indoor Lights On, All Indoor Lights Off,

  • All Lights On, All Lights Off,

  • All Awake, Good Night

 

Handsfree Automation

s:a:on\n

Enable handsfree automation in this room

s:a:off\n

Disable handsfree automation in this room

s:p:on\n

Turn on Privacy in this room

s:p:off\n

Turn of Privacy in this room

s:s:on\n

Turn Sleeping mode on

s:s:off\n

Turn Sleeping mode off

 

 

Fully Qualified Absolute Address Commands

Commands that use the fully qualified absolute address of a device in the house have access to all of the devices in the house. These commands must provide the room name, device type, and device name of the device to be controlled, and they must provide the value to which the device should be set. The text string of these commands must be derived from the UAPI Action Tree and associated with commands from the controlling device.

In general, these commands are of the format:

<room name>.<device type>.<device name>^<device type abbreviation>:<value>\n

where:

<room name> is the name of the room

"." is a period separating the room name from the device name

<device name> is the name of the device in the room

"^" is the up arrow key (usually shift 6)

<device type abbreviation> is defined in the list below

":" is the colon key

<value> is the value to which the specified device will be set

\n is "backslash n" representing a linefeed character

however, it is safer to obtain the exact value from the UAPI menu.