AMX CAFE DUET STANDARD NETLINX API (SNAPI) COMPONENTS AND... User manual

Standard NetLinx API
(SNAPI) R 1.8.0
Components/Listeners
instruction manual
last revision: 8-29-06
Document ID: 033-004-2993

AMX Limited Warranty and Disclaimer
AMX Corporation warrants its products to be free of defects in material and workmanship under normal use for three (3) years from the date of purchase from
AMX Corporation, with the following exceptions:
• Electroluminescent and LCD Control Panels are warranted for three (3) years, except for the display and touch overlay components that are warranted for a
period of one (1) year.
• Disk drive mechanisms, pan/tilt heads, power supplies, MX Series products, and KC Series products are warranted for a period of one (1) year.
• Unless otherwise specified, OEM and custom products are warranted for a period of one (1) year.
• Software is warranted for a period of ninety (90) days.
• Batteries and incandescent lamps are not covered under the warranty.
This warranty extends only to products purchased directly from AMX Corporation or an Authorized AMX Dealer.
AMX Corporation is not liable for any damages caused by its products or for the failure of its products to perform. This includes any lost profits, lost savings, inci-
dental damages, or consequential damages. AMX Corporation is not liable for any claim made by a third party or by an AMX Dealer for a third party.
This limitation of liability applies whether damages are sought, or a claim is made, under this warranty or as a tort claim (including negligence and strict product
liability), a contract claim, or any other claim. This limitation of liability cannot be waived or amended by any person. This limitation of liability will be effective
even if AMX Corporation or an authorized representative of AMX Corporation has been advised of the possibility of any such damages. This limitation of liability,
however, will not apply to claims for personal injury.
Some states do not allow a limitation of how long an implied warranty last. Some states do not allow the limitation or exclusion of incidental or consequential dam-
ages for consumer products. In such states, the limitation or exclusion of the Limited Warranty may not apply. This Limited Warranty gives the owner specific legal
rights. The owner may also have other rights that vary from state to state. The owner is advised to consult applicable state laws for full determination of rights.
EXCEPT AS EXPRESSLY SET FORTH IN THIS WARRANTY, AMX CORPORATION MAKES NO OTHER WARRANTIES, EXPRESSED OR
IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. AMX CORPO-
RATION EXPRESSLY DISCLAIMS ALL WARRANTIES NOT STATED IN THIS LIMITED WARRANTY. ANY IMPLIED WARRANTIES THAT
MAY BE IMPOSED BY LAW ARE LIMITED TO THE TERMS OF THIS LIMITED WARRANTY.

1
Standard NetLinx API (SNAPI) R 1.8.0
Table of Contents
Interfacing with Standard NetLinx API (SNAPI) .................................................... 1
Overview ........................................................................................................................... 1
Programming..................................................................................................................... 4
Channel and Level Ranges............................................................................................... 6
Commands and Escape Characters ................................................................................. 7
Amplifier ............................................................................................................................ 9
Audio Conferencer .......................................................................................................... 11
Audio Mixer ..................................................................................................................... 13
Audio Processor.............................................................................................................. 15
Audio Tape...................................................................................................................... 17
Audio Tuner Device......................................................................................................... 19
Camera ........................................................................................................................... 21
Dialer............................................................................................................................... 25
Digital Media Decoder..................................................................................................... 27
Digital Media Encoder ..................................................................................................... 29
Digital Media Server........................................................................................................ 31
Digital Satellite System ................................................................................................... 33
Digital Video Recorder .................................................................................................... 35
Disc Device ..................................................................................................................... 37
Disc Transport................................................................................................................. 41
Display ............................................................................................................................ 45
Document Camera .......................................................................................................... 49
Gain................................................................................................................................. 51
HVAC .............................................................................................................................. 53

2Standard NetLinx API (SNAPI) R 1.8.0
InputOutput Device Component...................................................................................... 59
InputOutput ..................................................................................................................... 61
IO Device ........................................................................................................................ 63
Keypad ............................................................................................................................ 65
Lamp ............................................................................................................................... 67
Light ................................................................................................................................ 69
Media DB ........................................................................................................................ 73
Media Device .................................................................................................................. 75
Menu ............................................................................................................................... 79
Module ............................................................................................................................ 85
Monitor ............................................................................................................................ 87
Motor ............................................................................................................................... 89
Multi Window................................................................................................................... 91
Output Stream................................................................................................................. 93
Phonebook ...................................................................................................................... 95
Pool Spa.......................................................................................................................... 97
Power Device Component ............................................................................................ 103
Power Device ................................................................................................................ 105
Power ............................................................................................................................ 107
Pre Amp ........................................................................................................................ 109
Pre Amp Surround Sound Processor............................................................................ 111
Receiver ........................................................................................................................ 113
Relay Device Component ............................................................................................. 115
Relay Device ................................................................................................................. 117
Security System ............................................................................................................ 119
Sensor........................................................................................................................... 121
Settop Box..................................................................................................................... 123

3
Standard NetLinx API (SNAPI) R 1.8.0
Slide Projector............................................................................................................... 125
Source Select................................................................................................................ 127
Switcher ........................................................................................................................ 129
Tape Transport.............................................................................................................. 131
Text Keypad .................................................................................................................. 135
Tuner Station................................................................................................................. 137
TV.................................................................................................................................. 141
Utility ............................................................................................................................. 143
VCR............................................................................................................................... 145
Video Conferencer ........................................................................................................ 147
Video Processor............................................................................................................ 149
Video Projector.............................................................................................................. 151
Video Wall ..................................................................................................................... 153
Volume Controller ......................................................................................................... 155
Volume .......................................................................................................................... 157
Weather......................................................................................................................... 159
Window ......................................................................................................................... 163

4Standard NetLinx API (SNAPI) R 1.8.0

Interfacing with Standard NetLinx API (SNAPI)
1
Standard NetLinx API (SNAPI) R 1.8.0
Interfacing with Standard NetLinx API (SNAPI)
The Standard NetLinx API (SNAPI) maps function and feedback calls in Duet modules to ICSP channels, levels and commands. SNAPI allows NetLinx
programmers to utilize Duet modules in their NetLinx programs and access the function and feedback of those modules through programming similar to
programming they would use on an AMX device, such as a volume box. While each Duet module may support advanced functions via channels, levels and
commands (see specific module documentation for the channels, levels and commands supported by that module), the SNAPI mappings apply to the Standard API
supported by each module.
Overview
Devices
In Duet, all modules use a Duet virtual device. Duet virtual devices are in the range 41000:1:0 to 42000:1:0. Duet virtual devices are specifically designed for use
with Duet modules. Regular virtual devices will not work properly with Duet modules.
Ports
In Duet, each device may support one or more ports. Multiple ports are used to provide access to different components within the module. For instance, a switcher
may support output volume for each switcher output. In Duet, this is represented by a volume component for each output and in SNAPI, each of these components
is mapped to a Duet virtual device ports. Port 1 will control the volume for output 1, port 2 will control the volume for output 2, etc… Another common use of port
is to control different "zones" of and Audio Receiver, HVAC, Security Systems, etc… It is possible that a single port may offer only a small bit of functionality,
such as volume control.
Port 1 is always the "main" device and supports all functions of the device. For components that have multiple instances, such as volume, port 1 will control the
default component, which is usually component 1.
The documentation for each module will describe what ports are available and what functions they control. See the specific module documentation for a complete
list of ports supported by the module.

Interfacing with Standard NetLinx API (SNAPI)
Standard NetLinx API (SNAPI) R 1.8.0
2
Channels
In SNAPI, there are four kinds of channels: Input Function Channels, Momentary Function Channels, Discrete Function Channels and Feedback Channels.
Input function channels are used for response type functions, such as when a device wants to inform your program of an interesting event, similar to a button push
on a touch panel. For instance, channel 1 is the input function channel for processButtonStateEvent (). When the module has information about the push or release
of a button, the module will send a PUSH or RELEASE.
Momentary function channels are used for momentary type functions and do not provide discrete feedback. For instance, channel 9 is the momentary function
channel for cyclePower(). When pulsed, the channel cycles the state of power on the device and only provides momentary feedback, i.e. the channel is on only
while this function is activated.
Discrete function channels are used for discrete type functions and usually provide discrete feedback. For instance, channel 255 is the discrete function channel for
setPower(); When turned on, this channel sets the state of the power on the device to on. When turned off, this channel sets the state of the power on the device to
off. This channel provides discrete feedback as well; this channel is on if and only if the state of the power on the device is on. In most cases, the channel is listed
as a Discrete function channel next to the function the channel controls and as a Feedback channel next to the feedback function that controls this channel.
Feedback channels provide discrete feedback only. For instance, channel 251 is the feedback channel of Communication Active. This channel is on if and only if
the module is able to communicate to the device.
Levels
Levels in SNAPI are used for both function and feedback. In some cases, a level is only used for feedback, such as temperature, while some levels are used for
function and feedback, such a volume. In most cases, level ranges are from 0-255. All exceptions to this rule are noted, and are only used when the level range is
not bounded by a minimum and a maximum, such as temperature.

Interfacing with Standard NetLinx API (SNAPI)
3
Standard NetLinx API (SNAPI) R 1.8.0
Commands
Commands in SNAPI are used for discrete and momentary functions when the function requires textual information, multiple parameters, or the functions are not
commonly used. For instance, Temperature scale is set via a command because this is usually done only once in a control system program. Other functions, such
as adding and removing lighting and keypad addresses, requires more information than a channel or level alone can convey. All commands start with a command
header, followed by a "-" to separate the command from the data, and data arguments are usually separated by ","s.
Commands used to query for the status of a property start with a "?". Query commands cause the module to respond with a response command.
SNAPI.axi
SNAPI.axi is an include file that defines constants for each channel and level defined by SNAPI. These constants can be used in your programs in place of channel
and level numbers. The constant names are listed in this document alongside every SNAPI function assigned to a channel or level.
SNAPI.axi is located in C:\Program Files\Common Files\AMXShare\AXIs. The file is organized by device type and lists all the standard channels and levels that
may be supported by the module. This list does not contain all the channel or levels supported by a module and may include channels and levels not supported by
a device. See the specific module documentation for a complete list of channels and levels supported by the module.
To include SNAPI.axi in your program, simply add an #INCLUDE statement for it:
#INCLUDE 'SNAPI.axi'
The file does not need to be copied to your project directory. The NetLinx compiler will be able to find this file automatically and include it in your program.

Interfacing with Standard NetLinx API (SNAPI)
Standard NetLinx API (SNAPI) R 1.8.0
4
Programming
Channels
Input function channels are used for response type functions. For instance, channel 1 notifies your program of a button push in the KeypadComponent. When your
program receives a PUSH, the button is pushed. When your program receives a RELEASE, the button is released. You should use BUTTON_EVENT's to capture
the changes of an Input function channel:
BUTTON_EVENT[dvDevice, KEYPAD_BTN]
{
PUSH: // Button was pushed
{
}
RELEASE: // Button was released
{
}
}
Momentary function channels are used to activate functions when the channels change from an OFF state to an ON state. For instance, channel 9 or the constant
POWER cycles the state of the power on the device when it turns on. No change occurs when the channels change from an ON state to an OFF state. You should
activate Momentary function channels using the PULSE, TO or MIN_TO keywords:
PULSE[dvDevice,POWER]// Cycle the state of power
TO[dvDevice,POWER]// Cycle the state of power
MIN_TO[dvDevice,POWER]// Cycle the state of power
Discrete function channels are used to activate functions when the channel changes from an OFF state to an ON state and from an ON to an OFF state. For
instance, channel 255 or the constant POWER_ON sets the state of the power on the device when it turns on and off. You should activate discrete function
channels using the ON and OFF keywords, or any syntax that changes the state of the channel such as a feedback assignment:
ON[dvDevice,POWER_ON] // Turn the power on
OFF[dvDevice,POWER_ON] // Turn the power off
[dvDevice,POWER_ON] = ![dvDevice,POWER_ON] // Cycle the state of power
Feedback channels do not active function and should only be used for feedback. These channels can be used in CHANNEL_EVENTs or feedback assignment
statements to read the status of the channel:
bCommunicationActive = [dvDevce,DEVICE_COMMUNICATING]
CHANNEL_EVENT[dvDevice,DEVICE_COMMUNICATING]
{
ON:
ON[bCommunicationActive]
OFF:
OFF[bCommunicationActive]
}

Interfacing with Standard NetLinx API (SNAPI)
5
Standard NetLinx API (SNAPI) R 1.8.0
Ramping Channels
Some channels in SNAPI provide ramping functionality and some provide adjust "stepping" functionality. Since ramping on a device is only provided if the device
supports ramping, a channel that causes ramping on one device may not cause ramping on another device. The following syntax can be used universally for all
ramping functionality:
BUTTON_EVENT[dvTP,1]
{
PUSH:
TO[dvDevice,VOL_UP]
HOLD[3 , REPEAT]:
ON[dvDevce,VOL_UP]
}
The PUSH: TO part of the button event causes ramping to start and continue until the button is released. If the device does not support ramping, the device adjusts
the desired parameter either up or down one step and stops. The HOLD: ON part of the button event causes the step adjustment to repeat, at a rate specified by the
HOLD repeat time, until the button is released. The HOLD: ON part of the button event has no effect if the device supports ramping.
In a future version of Duet, it is expected that all modules will support ramping natively and that this NetLinx code will not always be required. However, if the
module you are using does not support ramping, this code can be used to achieve ramping functionality.
Levels
Levels in SNAPI are used for both function and feedback. For feedback levels, the level value can be captured in a LEVEL_EVENT, with CREATE_LEVEL or
sent directly to a touch panel display bargraph using DEFINE_CONNECT_LEVEL:
LEVEL_EVENT[dvDevice,1]
{
// LEVEL.VALUE holds the new level value
}
CREATE_LEVEL dvDevice,1,nMyVariable // nMyVariable will hold the
// latest value of the level
DEFINE_CONNECT_LEVEL(dvDevice,1,dvTp,1)
Levels used for functions can be set by calling SEND_LEVEL or by connecting to a touch panel active bargraph using DEFINE_CONNECT_LEVEL:
SEND_LEVEL dvDevice,1,nNewLevelValue
DEFINE_CONNECT_LEVEL(dvDevice,1,dvTp,1)
The CREATE_LEVEL/SEND_LEVEL mechanism is recommended for use with SNAPI. While LEVEL_EVENT will work fine, you may experience problems
when a touch panel falls offline and then reconnects, which happens often with wireless panels. LEVEL_EVENT's will only fire when a change of the level value
occurs. When the panel comes online, the only way to reliably update the level is with a SEND_LEVEL.

Interfacing with Standard NetLinx API (SNAPI)
Standard NetLinx API (SNAPI) R 1.8.0
6
Commands
Commands in SNAPI are sent like commands to other devices, using the SEND_COMMAND keyword:
SEND_COMAND dvDevice,'?VERSION'
Commands used to query for the status of a property start with a "?". Query commands cause the module to respond with a response command. Note that this
response is a command, not a string and can be captured in a DATA_EVENT in the COMMAND sub-section:
DATA_EVENT[dvDevice]
{
COMMAND:
{
// DATA.TEXT holds the response to a query command
}
}
General
The NetLinx program should assume that NetLinx levels are initially 0 and that channels are 'off'. The SNAPI router will notify the NetLinx client upon a change
of state.
All Duet Virtual Devices should be created on port 1, e.g. 41000:1:0 in the following statements:
DEFINE_DEVICE
vdvModule = 41000:1:0
dvDevice = 135:1:0
DEFINE_MODULE 'LightModule' LightModule1 (vdvModule , dvDevice )
While it is possible to create a Duet Virtual Device on a port other than 1 and pass it to the Duet module, the behavior of the module is undefined.
Channel and Level Ranges
SNAPI uses only channels in range 1-299. Some channels are used for multiple functions but these channels belong to components that do not overlap within a
single device. For instance, HVAC and Display both use channel 214 for setFanState and setFreezeOn respectively. Some channels are used for the same function
in multiple components, for instance Video Conference and Display both define channel 191 for cyclePIPPosition. In both cases, this is by design.
Some devices may use custom channels for advanced functions. Channels 67-76 and 300-399 are reserved for modules to use for whatever functions they like. See
specific module documentation for details on the channels used in that module.
SNAPI uses Levels in the range 1-48. Some levels are used for the same function in multiple components, for instance HVAC, Pool/Spa and Weather all define
level 34 for Outdoor Temperature. This is by design.
Some device may use custom levels for advanced functions. Levels 50-80 and above are reserved for modules to use for whatever functions they like. See specific
module documentation for details on the levels used in that module.

Interfacing with Standard NetLinx API (SNAPI)
7
Standard NetLinx API (SNAPI) R 1.8.0
Commands and Escape Characters
SNAPI command uses comma as a parameter separator. If a parameter's value contains a comma, the parameter is escaping using double quotes at the start and end
of the parameter. If a parameter's value contains a double quote character it is escaped with a pair of double quote characters.
The following examples are properly escaped parameter values:
 6
 Hello
 Brown Eyed Girl
 "Morrison, Van"
 "Van ""The Man"" Morrison"
The following examples are improperly escaped parameter values:
 Morrison, Van
 Van "The Man" Morrison
SNAPI.axi includes a few helpful routines to build commands:
 DuetPackCmdHeader(Hdr)
 DuetPackCmdParam(Cmd, Param)
 DuetPackCmdParamArray(Cmd, Params[])
DuetPackCmdHeader is a command using a given command header where Hdr is the command header. DuetPackCmdParam adds a parameter to the command,
escaping the parameter and adding parameter separators as needed; Cmd is the command to which the parameter is added and Param is the parameter to be added.
DuetPackCmdParamArray is similar to DuetPackCmdParam but it takes an array of parameters and adds them to the command. All of these functions return the
updated command.
SNAPI.axi includes a few helpful routines to parse commands as well:
 DuetParseCmdHeader(Cmd)
 DuetParseCmdParam(Cmd)
DuetParseCmdHeader removes and returns the command header from a command. DuetParseCmdParam removes and returns the next parameter from the
command, un-escaping the parameter as needed. Both of these functions return a string containing the command header or the parameter.

Interfacing with Standard NetLinx API (SNAPI)
Standard NetLinx API (SNAPI) R 1.8.0
8
An example program using these routines is shown below:
// Build a command to be stored in cTestCmd
cTestCmd = DuetPackCmdHeader('COMMAND')
cTestCmd = DuetPackCmdParam(cTestCmd,'Morrison,Van')
cTestCmd = DuetPackCmdParam(cTestCmd,'Wild Nights')
cTestCmd = DuetPackCmdParam(cTestCmd,'"The Man"')
cTestCmd = DuetPackCmdParam(cTestCmd,'Tupelo Honey')
// Resulting command is:
// 'COMMAND-"Morrison, Van",Wild Nights,""The Man"",Tupelo Honey'
// Remove the parameters for this command
cCmdheader = DuetParseCmdHeader(cTestCmd)
SWITCH (cCmdheader)
{
CASE 'COMMAND':
{
cParam1 = DuetParseCmdParam(cTestCmd)
cParam2 = DuetParseCmdParam(cTestCmd)
cParam3 = DuetParseCmdParam(cTestCmd)
cParam4 = DuetParseCmdParam(cTestCmd)
// cParam1 = 'Morrison, Van'
// cParam2 = 'Wild Nights'
// cParam3 = '"The Man"'
// cParam4 = 'Tupelo Honey'
}
}

9
Standard NetLinx API (SNAPI) R 1.8.0
Amplifier
Component
Name: Amplifier
Interface: IAmplifierComponent IAmplifierComponent
Component Functions:
Name: Channel: Level: Command: Constant: Notes:
Intentionally left blank
Listener
Name: Amplifier Listener
Interface: IAmplifierComponentListener IAmplifierComponentListener
Listener Functions:
Name: Channel: Level: Command: Constant: Notes:
Intentionally left blank

Standard NetLinx API (SNAPI) R 1.8.0
10

11
Standard NetLinx API (SNAPI) R 1.8.0
Audio Conferencer
Component
Name: Audio Conferencer
Interface: IAudioConferencerComponent IAudioConferencerComponent
Component Functions:
Name: Channel: Level: Command: Constant: Notes:
cyclePrivacy() 145 ACONF_PRIVACY Momentary Function Channel: Cycle privacy when channel is activated
setPrivacyOn(state) 146 ACONF_PRIVACY_ON Discrete Function Channel: Privacy is on while channel is active
train() 147 ACONF_TRAIN Momentary Function Channel: Train is executed when the channel is activated
Listener
Name: Audio Conferencer Listener
Interface: IAudioConferencerComponentListener IAudioConferencerComponentListener
Listener Functions:
Name: Channel: Level: Command: Constant: Notes:
processPrivacyEvent 146 ACONF_PRIVACY_FB Feedback Channel: Privacy is muted if channel is on

Standard NetLinx API (SNAPI) R 1.8.0
12

13
Standard NetLinx API (SNAPI) R 1.8.0
Audio Mixer
Component
Name: Audio Mixer
Interface: IAudioMixerComponent IAudioMixerComponent
Component Functions:
Name: Channel: Level: Command: Constant: Notes:
getAudioMixerCross-
point(input,output)
?XPOINT-<input>,<output> Query for Audio Mixer Crosspoint, responds with XPOINT-<value>,<input>,<output>
where <value> is 0 to 255, <input> is 1 to the maximum supported input and <output> is
the maximum supported output (see specific module documentation)
getAudioMixerPreset() ?MIXERPRESET Query for Audio Mixer Preset, responds with MIXERPRESET-<preset> where <preset>
is 1 to x and x is the maximum supported preset (see specific module documentation)
isAudioMixerCrosspoint-
MuteOn(input,output)
?XPOINTMUTE-<input>,<output> Query for Audio Mixer Crosspoint Mute, responds with XPOINTMUTE-
<state>,<input>,<output> where <state> is 0 (un-muted) or 1 (muted), <input> is 1 to
the maximum supported input and <output> is the maximum supported output (see
specific module documentation)
saveAudioMixerPre-
set(preset)
MIXERPRESETSAVE-<preset> Save Audio Mixer Preset where <preset> is 1 to x and x is the maximum supported pre-
set (see specific module documentation)
setAudioMixerCross-
point(input,out-
put[],value)
XPOINT-<value>,<input>,<out-
put>[,<output>,<output>Ö]
Set Audio Mixer Crosspoint for <input> to one or more <output>s where <value> is 0 to
255. <input> is 1 to the maximum supported input and <output> is 1 to the maximum
supported output (see specific module documentation)
setAudioMixerCross-
pointMuteOn(input,out-
put,state)
XPOINTMUTE-<state>,<input>,<out-
put>
Set Audio Mixer Crosspoint Mute for <input> and <output> where <state> is 0 (un-
muted) or 1 (muted). <input> is 1 to the maximum supported input and <output> is 1 to
the maximum supported output (see specific module documentation)
setAudioMixerPre-
set(preset)
MIXERPRESET-<preset> Recall Audio Mixer Preset where <preset> is 1 to x and x is the maximum supported
preset (see specific module documentation)
Listener
Name: Audio Mixer Listener
Interface: IAudioMixerComponentListener IAudioMixerComponentListener
Listener Functions:
Name: Channel: Level: Command: Constant: Notes:
processAudioMixerCros-
spointEvent
XPOINT-<value>,<input>,<output> Audio Mixer Crosspoint changed for <input> to one or more <output>s where <value>
is 0 to 255. <input> is 1 to the maximum supported input and <output> is 1 to the max-
imum supported output (see specific module documentation)
processAudioMixerCros-
spointMuteOnEvent
XPOINTMUTE-<state>,<input>,<out-
put>
Audio Mixer Crosspoint Mute changed for <input> and <output> where <state> is 0 (un-
muted) or 1 (muted). <input> is 1 to the maximum supported input and <output> is 1 to
the maximum supported output (see specific module documentation)
processAudioMixerPre-
setEvent
MIXERPRESET-<preset> Mixer preset changed, where <preset> is 1 to x and x is the maximum supported preset
(see specific module documentation)

Standard NetLinx API (SNAPI) R 1.8.0
14