MS VTP Commands

User Authorization

U - Username

Provide the Username as a string of ASCII characters. The Username is case sensitive. VTP User names are limited to a maximum of 16 characters and cannot contain spaces.

P - Password

Provide the password as a string of ASCII characters. The password is case sensitive. VTP User passwords are limited to a maximum of 16 characters and cannot contain spaces.

A – Authorization

Request authorization using the username/password pair previously provided.  If the pair is valid the VTP service responds with “SUCCESS” otherwise it will respond with “FAILURE”.

Internal Function

. - Terminate Session

A full-stop will terminate the VTP session and close the socket.

K - Reboot Device

The K Command is used to perform a remote reboot of a device.

• DeviceType is a numerical representation of the device type.  

• DeviceID is the ID of the particular device.

Use the Q D Command to query devices in a World.

The reboot device responses will be as follows:

<?xml version="1.0"?><Status Command=K><Device type="DeviceType" id="DeviceID">DeviceName:DeviceID</Device><State> Reboot device state </State></Status>

DeviceName is a string representation of the device type.

Reboot device state can be :

• REBOOT_SUCCESS :  Device was successfully restarted

• REBOOT_FAIL : Device was unable to be restarted

In this example the Device Query (Q D) command was used to discover hardware on the network. A VO-4 with Device ID 07 was reset. Then Interactive Mode was enabled and a DS-10 with a Device ID of 04 was reset.

Zone Definition

The system will store a list of Zones to be used with subsequent Page requests. This list of Zones remains current for all future Page requests until overridden by a future Zone list definition. All accessible Zones correspond to the Zone ID numbers shown in Vocia software for the connected Vocia system. Remote Zones in a Multi-World system cannot be accessed via this method – access to remote systems must be made through the MS-1 residing in those systems directly.

Z n1 n2 …

Where n1 n2 … is a list of Zones as decimal numbers each separated by a space.

? - Glossary of VTP Commands

Reports all valid VTP commands in English. (Interactive Mode must be enabled for reporting to work)

# ==========================================================================

#  Vocia VTP Help

# ==========================================================================

#

# -------------------------------------

#  Login and Authentication:

# -------------------------------------

#   U username          - Supply the username

#   P password          - Supply the password

#   A                       - Request authorization of the username/password pair

#

#   C h s                  - Set control handle state

#                         h - control handle id

#                         s - control handle state

#

#   Z n1 n2 ...          - Make this the list of active zones. Overrides previous setting

#

#   E n e/z filename data - Message element definition

#                         n - sequence number

#                         e - existing wavefilename

#                         z - end of sequence marker

#

#   K devtype devid  - Reset a device

# -------------------------------------

#  Query Commands:

# -------------------------------------

#   Query system configuration via VTP

#   Q A                   - List available audio files

#   Q B zone            - List available background sources

#   Q C                   - Display the configuration version

#   Q D                   - List the devices in this world

#   Q E                   - Query the emergency paging priority threshold

#   Q H                   - List available control handles

#   Q I                    - List available user inputs

#   Q L                   - List available page codes

#   Q M                  - Query the state of System Mute

#   Q N index           - Query the network link state of a network interface

#   Q P pagecode     - Display page code details

#   Q S zone           - Display zone configuration details

#   Q T Z zone        - Query the page inhibit threshold for a zone

#   Q U                  - Currently active user input events

#   Q X                  - List active and queued announcements

#   Q Z                  - List available zones

#

# -------------------------------------

#  Background Execution Commands:

# -------------------------------------

#   B I ON/OFF            - Set zone page inhibit on or off

#   B L A value            - Set zone background level (value = 0 - 255)

#   B L P value            - Set zone background level (value = 0 - 100)

#   B M ON/OFF           - Set zone background mute on or off

#   B P ON/OFF            - Set allow zone page inhibit on or off

#   B Q zone               - Query the state of the specified zone

#   B S bundle channel  - Set zone background source

#   B Z ON/OFF           - Set zone mute on or off

#

# -------------------------------------

#  Page Execution Commands:

# -------------------------------------

#   X A                        - Cancel all the active, queued and auto repeating announcements

#   X C id                     - Cancel the active, queued or auto repeating announcement #id

#   X D id                     - Delete user input page #id

#   X P pagecode id       - Execute a recorded announcement page code as page #id

#   X U devtype devid chan duration priority mode id - Execute user input page #id, to preselected zones

#   X S Y/N priority id queue - Execute sequence page #id to preselected zones

#

# -------------------------------------

#  Auto Repeat Commands:

# -------------------------------------

#   R N count           - Set the number of repetitions for subsequent announcements

#   R T interval         - Set the time interval in seconds between repeats

#   R I                     - Repeat until cancelled (overrides repeat count)

#   R L                    - List all auto repeating announcements

#   R C id                - Cancel the auto repeating announcement #id

#   R A                   - Cancel all auto repeating announcements

#

# -------------------------------------

#  Session Commands:

# -------------------------------------

#   D ON/OFF            - Enables/disables encapsulating VTP responses with delimeters

#   I ON/OFF            - Toggles interactive mode (enables verbose responses)

#   L ON/OFF            - Enables/disables logging of VTP activity

#   J ON/OFF            - Enables/disables zone states updates

#   J POLL                - Poll the current state of all zones in the local world

#   M ON/OFF           - Enables/disables system mute states updates

#   S ON/OFF           - Enables/disables page status updates

#

#   ?                   - Display this help information

#   .                   - Terminates session

#   # text            - Provide a comment to be ignored. Possibly an error message

# ==========================================================================

Enable Logging and Prompts

D - Enable/Disable VTP Response Encapsulation

The D command is used to enable or disable encapsulation of the responses transmitted by the MS-1 VTP Processor. 

State shall be:

• D ON – Turns on VTP response encapsulation
• D OFF – Turns off VTP response encapsulation

When encapsulation is turned on, VTP responses will be encapsulated with the ASCII control characters STX (0x02) and ETX (0x03). An example of an encapsulated response is shown below with [STX] and [ETX] used to denote where the STX and ETX characters will be:

L - Activity Logging

The VTP service on the MS-1e can be made to log VTP command activity to the MS-1e’s system log.  This can be useful for debugging a third party application or for keeping a record of system activity.

• L ON - Sets activity logging mode on.

• L OFF - Sets activity logging mode off.

I - Interactive Mode

Interactive mode defines whether informative responses are sent back to the consol. It is offered to make the system more human readable. When interactive mode is ON, feedback confirms commands have been successfully accepted and processed by the system. These responses may confuse a computer-based controller, and so are disabled by default. The ? command can be used once interactive mode is turned on to receive a list of valid VTP commands from the VTP service.

• I ON - Sets interactive mode on. A response is issued.

• I OFF - Sets interactive mode off.

S - Show Page Progress

The MS-VTP service will provide progress status for the currently active paging announcement via MS-VTP. Only pages triggered via MS-VTP are reported.  This information can be used to provide the MS-VTP client with feedback as to the progress of the announcement in the paging system. This facility can be turned on and off using the ‘S’ command and is turned off by default.

• S ON - Enable the transmission of paging progress status.

• S OFF - Disable the transmission of paging progress status.

• S ALL - Enable detailed paging progress mode. Sequence element progress will be reported in addition to the standard page progress. See the PAGE_ELEMENT_X for formatting of the Sequence element response. Use the 'S ON' or the 'S OFF' command to disable the detailed paging progress mode.

The page progress responses will be as follows:

<?xml version="1.0"?>

<Status Command=X>

<Id> Page event id </Id>

<State> Page progress state </State>

</Status>

Where

• Page event id is the id number associated with the page when it was executed

• Page progress state will be one of the following paging states.

• • PAGE_NEW_REQ - Page request accepted

  • PAGE_FAILED - Page failed for some reason

  • PAGE_COMPLETE - Page completed normally

  • PAGE_CANCELLED – Page has been cancelled as a result of the X C or X A command.

  • PAGE_DUPLICATE_ID – Event ID provided with the existing X S or X P command is found to be already in use.

  • PAGE_TIMEOUT – Page play-out delayed longer than the store duration

  • PAGE_ACTIVE - Page is currently being played back the first time

  • PAGE_ELEMENT_X ('S ALL' mode only) – The Sequence element X (where X is 0-23) is currently being played back as part of this page. The preamble, if configured, is considered sequence element P.

  • PAGE_AR_WAITING_FOR_REPEAT_INTERVAL – The page is currently waiting to be re-queued for playback once the repeat interval has expired.

  • PAGE_AR_COMPLETE - Indicates that the playback of the auto repeating announcement has completed.

  • PAGE_OVERIDDEN - Page was overridden by a higher priority announcement

  • PAGE_TRUNCATED - Page was truncated because it exceeded the maximum page duration

J - Zone Status Updates

Zone number must be specified before sending this command using the Z n1 n2 n3 command . Where n1 n2 n3 are zone numbers

State shall be

• ON - Turns on Zone status updates (updates occur anytime the status of a Zone changes)

• OFF - Turns off Zone status updates

• POLL - Will provide the status of all of the Zones in the World

The state of a zone can either be IDLE or it will be the numeric priority that is active in that zone in the range 1 to the Emergency Paging Threshold – 1.  For example if the Emergency Paging Threshold is 101, the numeric priority will be in the range 1 to 100.

The response for a Zone Status POLL command will be in the same format as a zone status update above, however it will contain all of the zones configured in a World.

It should be noted that Emergency Paging and/or Emergency Message playback can cause an audio output channel that has been assigned to both a Zone and an Emergency Zone to become unavailable for custom page code playback.  As the relationship between Zone and Emergency Zone assignment is complex (Zone and Emergency Zones can overlap) any emergency activity will not be reflected in the zone status information provided (the emergency system operation is intended to occur at the highest level of priority).

M - Enable System Mute Status Updates

The 'M' command supports turning on/off system mute status updates. System mute status updates will be sent anytime the state of system mute changes.

State shall be

• ON - Turns on system mute status updates

• OFF - Turns off system mute status updates

Background Control Commands

B I - Sets Page Inhibit State for a zone

Zone number must be specified before sending this command using the Z n1 n2 n3 command . Where n1 n2 n3 are zone numbers

State shall be

• ON - Turns Page Inhibit on for the list of zones specified

• OFF - Turns Page Inhibit off for the list of zones specified

This example shows Paging Inhibit being set to ON in Zone 2

B L P - Sets Background level using a percentage level

Zone number must be specified before sending this command using the Z n1 n2 n3 command . Where n1 n2 n3 are zone numbers

Where level determines the Background Audio Level specified as a percentage value from 0 to 100.

This example shows the level set in Zone 2 to 50%.

B L A  – Set Background level using an absolute value

Zone number must be specified before sending this command using the Z n1 n2 n3 command . Where n1 n2 n3 are zone numbers

Sets the Background Audio Level to the level specified as an absolute value from 0 to 255.

This example shows the absolute level being set to 127 in Zone 2.

B M - Background Music Mute

Zone number must be specified before sending this command using the Z n1 n2 n3 command . Where n1 n2 n3 are zone numbers

State shall be

• ON Turns Background Music Mute on for the list of zones specified

• OFF Turns Background Music Mute off for the list of zones specified

This example shows the Background source mute being activated in Zone 2.

B Q zone– Queries current state of specified Zone

This command is only used on a per-zone basis. Therefore it requires the zone to be specified as part of the command. If no zone is specified no response will be given.

Command will respond with the current state of the specified Zone. This includes background level (specified as a percentage value), background source, page inhibit, and mute.

Use of the Q Z command will allow details of the current zone configuration to be confirmed

B P - Controls WR-1 Page Inhibit access

Zone number must be specified before sending this command using the Z n1 n2 n3 command . Where n1 n2 n3 are zone numbers

Controls the access to Page Inhibit for all the WR-1 panels configured for the specified zone.

State shall be

• ON Turns on access to Page Inhibit for the list of zones specified

• OFF Turns off access to Page Inhibit for the list of zones specified

This example shows the Paging Inhibit access being activated in Zones 2,4 & 5.

B S – Background Audio source selection

Request a change to the background audio source for the list of Zones specified. The background source is specified using the CobraNet bundle “bundle” and bundle “channel” carrying the desired audio source. The bundle numbers and channels available for background selection in a given zone can be queried using the Q B zone command (see VTP Query Commands).

Example sequence

1. 1. Connection to the socket

   2. Request client seat (Enter VTP User Name and Password information, which is set in Vocia software under VTP Users). U n=User Name P n1=Password

   3. Authorize the user (Use the A command)

   4. Set Interactive mode to ON (i on). Interactive mode will generally not be used. It has been turned on in this example to show the commands being processed.

   5. Enter the zone required for the background change using the Z command (e.g. to change to Zone 1 enter command Z 1).  Once a zone command has been entered that zone/s will remain selected until a new zone command is issued. This means that multiple changes to the same zone or zones are possible without re-entering the zone information.

   6. Query the list of assignable background channels for the zone. As is shown in the example screenshot below for Zone 1 enter Q B 1 (for more information on the Q B command, see VTP Query Commands). The list of available background channels for Zone 1 will be shown.

   7. Enter and execute the background source change (To change to input channel four, enter the bundle number, and then the input channel number as shown in the example below B S 3008 3)

• If Interactive Mode (I on/off) is turned on, a response should appear. This will say “Background source for 1 zones set to bundle 3008 and channel 3”.

• As the Zone information has been set, you could continue to make changes in Zone 1, or re-enter a different zone or zones using the Z command.

• Terminate session (.) If required.

 B Z - Zone Mute

Zone number must be specified before sending this command using the Z n1 n2 n3 command . Where n1 n2 n3 are zone numbers

Will mute all audio into a specified zone.

State shall be

• ON  Turns Zone Mute on for the list of Zones specified

• OFF Turns Zone Mute off for the list of Zones specified

This example shows the Zone Mute being activated in Zone 2.

MS VTP Query Commands

A third party application using VTP may need to access certain aspects of the MS-1s configuration. For example it may be necessary to render a list of destination zones or Page Codes on a user interface. The VTP Configuration Query commands can be used for this purpose. All responses are made in XML format and are detailed after the relevant command.

Q A - Query Audio File List

List the recorded announcement .WAV files available for playback by the MS-1e.

The response to an audio file list query command will be as follows:

<?xml version="1.0"?>

<Query Command=”A”> <AudioFiles count=”FileCount”>

<AudioFile id=”FileID”> AudioFileName </ AudioFile >

...

<AudioFile id=”FileID”> AudioFileName </ AudioFile >

</AudioFiles> </Query>

• "FileCount" is the number of available audio files

• "FileID" is a 16bit unique identifier for an audio file

• "AudioFileName" contains the path name of the audio file relative to the Vocia MS-1 audio file base directory /vociawavs. There will be FileCount AudioFile tagged sections in the response list.

Note: Audio files uploaded by the FTP service to the MS-1e will not be displayed as part of this list. As FTP is the primary mechanism supported for providing dynamic (ie. post configuration) audio files from a third party system, FTP is the mechanism that will need to be used to determine if a custom audio file is present. This can be done by listing the contents of the FTP folder locations. See the MS-1e FTP Interface section for more information on viewing the files uploaded via FTP.

Q B zone - Query Background Source List

Return a list of the available background sources for the specified destination zone number zone. The response includes a background source label, and the CobraNet bundle and bundle channel carrying the desired background audio.

The response to a background source list query command will be as follows:

<?xml version="1.0"?><Query Command=”B”> <Backgrounds count=”BackgroundCount”>

<Background id=”BackgroundIndex”>

<Bundle>BundleNumber</Bundle>

<Channel>BundleChannel</Channel>

<Name>BackgroundSourceName</Name>

 </ Background >

<Background id=”BackgroundIndex”>

<Bundle>BundleNumber</Bundle>

<Channel>BundleChannel</Channel>

<Name>BackgroundSourceName</Name>

 </ Background >

</AudioFiles> </Query>

• BackgroundCount is the number of available background sources for the specified zone.

• There are BackgroundCount Background section tags in the list.

• BackgroundIndex is an 8 bit decimal background source index.

• BundleNumber is the CobraNet bundle containing the desired audio channel.

• BundleChannel identifies the required channel within the bundle.

• BackgroundSourceName is the label string associated with the background source.

Q C - Query Configuration Version

Query the current configuration ID for the MS-1e and its World. This command can be used to poll for changes to the configuration and to ensure the configuration used by the third party application is synchronized to the MS-1e.

The response to a configuration query command will be as follows:

<?xml version="1.0"?>

<Query Command=”C”>

<ConfigID> WorldID  ConfigurationVersion  CreationTime  BuildSequence </ ConfigID >

</Query>

• WorldID is a 2 digit hexadecimal number identifying the world the MS-1 belongs to,

• ConfigurationVersion is the 8 digit hexadecimal configuration version,

• CreationTime  is the 8 digit hexadecimal creation time of the project and

• BuildSequence is the 8 digit hexadecimal project build sequence. (e.g. 01  249415D4 4B2F98C9  4B334F69)

Q D - Query Device List

This command queries the devices that are included in the current configuration for the MS-1 and its world.  

The Q D command can be used to list the devices that the system has been configured for, for use in commands such as Reset Device.

The response to a device query command will be as follows:

<?xml version="1.0"?><Query Command="D"><Devices count="DeviceCount">

<Device type="DeviceType" id="DeviceID">DeviceName:DeviceID</Device>

…

<Device type="DeviceType" id="DeviceID">DeviceName:DeviceID</Device>

</Devices></Query>

Where:

• DeviceCount is the number of devices in the World.  

• DeviceType is a numerical representation of the device type.

• DeviceID is the ID of the particular device

• DeviceName is a string representation of the device type.

Q E - Query Emergency Paging Priority Threshold

Request the current Emergency Paging Priority Threshold.

The response to a control handle list query command will be as follows:

<?xml version="1.0"?>

<Query Command=”E”>

<EmergencyPagingPriorityThreshold>Priority</EmergencyPagingPriorityThreshold>

</Query>

Where

• Priority is between 5 and 252

Q H - Query Control Handle List

Request a list of the current Control Handles available in the system. This command provides the Control Handle ID and the label.

The response to a control handle list query command will be as follows:

<?xml version="1.0"?>

<Query Command=”H”><Handles count=”HandleCount”>

<Handle id=”HandleID”> HandleLabel </Handle >

<Handle id=”HandleID”> HandleLabel </Handle >

</Handles></Query>

Where

• HandleCount is the number of available control handles.

• There will be HandleCount Handle section tags in the list.

• HandleID is a 32 bit decimal unique identifier for the control handle.

• HandleLabel  is the label string associated with the control handle.

Q I - Query User Audio Input List

Request a list of available User Audio Inputs. In general User Audio Inputs are VI-6 inputs that are available for long term Pages to a set of destination Paging Zones. Each item in the User Audio Input list will consist of a device type, device ID and a channel number.

The response to a user audio input list query command will be as follows:

<?xml version="1.0"?>

<Query Command=”I”><UserInputs count=”InputCount”>

<UserInput id=”InputID”>

<DeviceType>InputDeviceType</DeviceType>

<DeviceID>InputDeviceID<DeviceID>

<Input> InputChannel</Input>

</UserInput >

...

<UserInput id=”InputID”>

<DeviceType>InputDeviceType</DeviceType>

<DeviceID>InputDeviceID<DeviceID>

<Input> InputChannel</Input>

</UserInput >

</UserInputs></Query>

Where

• InputCount is the number of available user inputs.

• There will be InputCount UserInput section tags in the list.

• InputID is a 32 bit decimal unique identifier for the user input.

• InputDeviceType is a decimal representation of the host device for the input. At present this must be a VI-6 (device type = 6).

• InputDeviceID is the specific device’s 8 bit device ID set on the rotary switches.

• InputChannel specifies the device’s input channel used for the user input.

Q L - Query Page Code List

Respond with a list of all the available Page Codes. The list will consist of items comprising a Page Code followed by its label. See Page Code List for details of the response to this command. Details of a particular Page Code can be obtained using the Q P command.

The response to a Page Code list query command will be as follows:

<?xml version="1.0"?>

<Query Command=”L”><Pagecodes count=”PagecodeCount”>

<Pagecode id=”PageCode”> PagecodeLabel </ Pagecode >

...

<Pagecode id=”PageCode”> PagecodeLabel </ Pagecode >

</ Pagecodes ></Query>

Where

• PagecodeCount is the number of available Page Codes.

• There will be PagecodeCount Pagecode section tags in the list.

• PageCode is the three digit decimal Page Code number.

• PagecodeLabel is the label string associated with the Page Code.

Q M - Query System Mute

Respond with the current state of System Mute. See System Mute for response details.

The response to a System Mute Query will be

<?xml version="1.0"?><SystemMute>State string</SystemMute>

State string will be:

• N - When system mute is inactive or not configured.

• Y - When system mute is active

Q N - Query Network Connection State

The Q N command is used to query the state of the MS-1(e)’s network interfaces.  This will only report on the network link status. 

Interface shall be:

• 1 – MS-1(e) Control Network Port
• 2 – MS-1(e) CobraNet Network Port
• 3 – MS-1(e) VoIP Network Port
• 4 – MS-1(e) Live-Interworld Paging Network Port

The response to a Network Connection Query will be:

<?xml version="1.0"?><Query Command="N"><NetworkLink id=”Interface”>State</NetworkLink></Query>

State string will be:

• UP – network link is present
• DOWN – network link is not present
• UNKNOWN – network link is unknown

Q P - Query Page Code Details

Respond with details of the specified Page Code. The information returned includes the Page Code type (live announcement or pre-recorded), the list of destination Zones, the priority of the Page and whether or not it is assigned a Preamble. See Page Code Details List for details of the XML response to this command.

The response to a Page Code details query command will be as follows:

<?xml version="1.0"?>

<Query Command=”P”><PageCodeDetail id=” PageCode”>

<Preamble> Preamble </ Preamble >

<Priority> Priority </ Priority >

<AutoRepeat enabled=Repeatstate>

<Count>

<Min>1</Min>

<Default>1</Default>

<Max>9999</Max>

</Count>

<Interval>

<Min>0</Min>

<Default>0</Default>

<Max>43200</Max>

</Interval>

</AutoRepeat>

<Type> Type </ Type >

<Zones count=” PCZoneCount” >

<Zone> ZoneNumber </ Zone >

...

<Zone> ZoneNumber </ Zone >

</Zones>

</ PageCodeDetail ></Query>

Where

• PageCode is the three digit decimal Page Code number.

• Preamble is

• • N for no preamble

  • Y when a preamble is required.

• Priority defines the priority value of the Page Code.

• Type can be

• • "PAGE_TYPE_LIVE" for a live page from a paging station microphone,

  • "PAGE_TYPE_DELAYED" for a delayed page from a paging station microphone

  • "PAGE_TYPE_PLAYBACK" for initiation of a recorded announcement playback.

• PCZoneCount specifies the number of destination paging zones for the Page Code. There will be PCZoneCount Zone section tags in the list.

• ZoneNumber is the 8 bit decimal zone number for the destination zone.

"RepeatState" can be

• true - auto repeat enabled

• false - auto repeat not enabled

If the "RepeatState" is 'true' then the <Count> and <Interval> values will show the Page Code auto repeat configured values.

• Count - minimum, default and maximum will be integers in the range 1 to 9999, or the word infinite to represent an infinite count.

• Interval - minimum, default and maximum will be integers in the range 1 to 43200 seconds.

Q S zone - Display zone configuration details

The response will be:

<?xml version="1.0"?>

<Query Command=”S”>

<ZoneDetail id="1">

<Name>Zone 1</Name>

<Description>Zone 1</Description>

</ZoneDetail>

</Query>

Q T Z zone – Query Page Inhibit priority threshold

The response will be:

<?xml version="1.0"?>

<Query Command=”Q T Z”>

<Zone>z</Zone>

<PageInhibitPriorityThreshold>Priority</PageInhibitPriorityThreshold>

</Query>

Q U - Query Active User Audio Inputs

Respond with a list of the currently active User Input events.  The information returned includes the User Input Event ID uniquely identifying the event and supplied at the time the User Input was created using the X U command. The device type and device ID of the VI-6 used for the User Input event, and the input channel number are also provided. See Active User Audio Input List for details of the XML response to this command.

The response to an active user input event query command will be as follows:

<?xml version="1.0"?>

<Query Command=”U”><ActiveInputs count=”InputCount”>

<ActiveInput id=" EventId ">

<DeviceType> InputDeviceType </DeviceType>

<DeviceID> InputDeviceID </DeviceID>

<Input> InputChannel </Input>

</ActiveInput>

<ActiveInput id=" EventId ">

<DeviceType> InputDeviceType </DeviceType>

<DeviceID> InputDeviceID </DeviceID>

<Input> InputChannel </Input>

</ActiveInput>

</ActiveInputs></Query>

Where

• InputCount is the number of active User Input events. There will be InputCount ActiveInput section tags in the list.  

• EventId is the 16 bit signed handle uniquely identifying the User Input event supplied at the time of creation via the X U command.

• InputDeviceType is a decimal representation of the host device for the input. At present this must be a VI-6 (device type = 6).  

• InputDeviceID is the specific device’s 8 bit device ID set on the rotary switches.

• InputChannel specifies the device’s input channel used for the User Input.

QX - List All Current and Future Pages

The Q X command is used to list all pages that have been submitted for playback.

An example of the returned response is shown below:

<?xml version="1.0"?><Query Command=”X”><Messages count="MessageCount”>

<Message id="EventId">State</Message>

…

</Messages></Query>

Where

• EventId is the page event ID used when the page is submitted for playback. See X_P and X_S Commands.
• MessageCount is the total number of current and future playbacks.
• State string will be:
• ACTIVE – The page is currently playing.
• QUEUED – The page is in the queue awaiting playback.

Q Z - Query Paging Zone List

Return a list of the available destination paging Zones. Each item in the list consists of a Zone number followed by the Zone label. See Paging Zone List for details of the XML response to this command.

The response to a Page Code list query command will be as follows:

<?xml version="1.0"?>

<Query Command=”Z”><Zones count=”ZoneCount”>

<Zone id=”ZoneID”> ZoneLabel </ Zone >

...

<Zone id=”ZoneID”> ZoneLabel </ Zone >

</Zones ></Query>

Where

• ZoneCount is the number of available paging Zones. There will be ZoneCount Zone section tags in the list.

• ZoneID is the 8 bit decimal zone number.

• ZoneLabel is the label string associated with the paging Zone.

Set and Execute Commands

Page Execute Commands - E, X S and X P

A Page Execute Command can be used by a third party control system that is connected to an MS-1e using MS-VTP. It allows the creation and triggering of a custom Recorded Page Code sequence using the E and X S commands or triggering a specific Recorded Page Code using the X P command. Live Page Codes are not able to be triggered via MS-VTP (see PS-VTP for Live paging).

E and X S Commands

The E and X S Page execute commands are designed to be used together to define and execute a custom Recorded Page Code using VTP commands. Four different commands are used as part of the Page Code creation:

1. Element Sequence and WAV filename definition. E n e filename will define a sequence of Paging Elements which make up the audio content of the Page Code. Up to 24 Paging Elements can be defined before the End of Sequence Marker. The total length of the combined paging Elements must be below two minutes.

2. End of Sequence Marker. E n z will be an end of Sequence Marker that is used to indicate it is the last Element in the sequence.

3. Zone definition. Z n1 n2 will define the Paging Zones. See Zone Definition for more details.

4. Repeat Number - Will define the number of repeats required

5. Repeat time - defines the amount of time the system shall wait before beginning the next repetition

6. Page execution. X S Pre Priority ID will define Preamble, Priority and ID of the Page and execute the Page.
   

E - Set Elements for a Paging Sequence

E n e filename

A VTP custom Recorded Page Code consists of up to 24 Elements per Paging Event. The order of the WAV audio files is defined using an Element number which must be in the range of 0 to 23, and must be in sequential order. An End of Sequence Marker is required to indicate the last Element in the sequence. The total length of the combined Paging Elements must be less than two minutes.

After defining the Element number 'n' as shown above the WAV filename needs to be defined. The WAV file must exist on the MS-1e file system by importing the required audio files using the Audio File Manager tool or uploading them via the MS-1e FTP Interface. Once Imported, the audio files must then be associated to a Recorded Announcement Page Code or VTP Audio File in the project. If an audio file is specified that does not exist on the MS-1e an error will be reported to the logger when the Page is executed.

A list of WAV files available to the project can be queried using the Q A query command. The audio file folder location is specified as part of the VTP command so any audio file names are required to be preceded by the /vociawavs/ directory path (and/or their corresponding sub-directories). The filename should not be put in quotation marks, even if it contains spaces.

E n z - End of Sequence Marker

This Element is the end-of-sequence marker. This will be the next sequential element after the last E n e filename Element.

n = the next sequential Element.

Z - Zone Definition

Where n1 n2 … is a list of zones as decimal numbers each separated by a space.

X S - Execute a request to playback a sequence of announcements

The X S Command is used to execute the custom Recorded Page Code. It specifies the Preamble, Priority and unique ID of the Page which will contain the previously defined Elements.

pre defines what the Page will be preceded by

• pre = Y Page will be preceded by preamble

• pre = N Page will not be preceded by preamble

• pre = P Page will be preceded by preamble (same as above)

priority = This parameter defines the priority of the page (used for resolution of access to zones) and is in the range 1 and the numerical value below the Emergency Priority Threshold specified in the Universe dialog. The Q E command can be used to query the threshold.

Example:

id = This is an id number provided by the client which the system will use to identify individual page requests when informing the client of progress of an individual page. A number range from 0 to 32767 is supported and each ID sequence should be unique.

queue = This is an optional argument and can either be Y to allow the message to be queued if the destination zones are busy, or N if the message should not be queued and should fail immediately if any of the destination zones are busy. It will default to Y when it hasn’t been specified.

This would play at Priority level 1, using the standard Preamble for Priority level 1 (low) as defined in the Vocia software configuration, followed by the announcement "baggagebelt+0.0db.wav" followed by "pleaseleavenow.wav" to zones 1 and 2 with Page Progress ID of 3456 and will be queued. This would be repeated 5 times every 2 minutes (120 seconds). The Repeat time and Repeat Number are then reset to 0.

X P - Execute the specified Page Code

Execute the specified Page Code. If Auto Repeat settings are configured in the Page Code they will be used. Note that this command will replace any previously issued VTP paging commands in memory such as Zone assignment, Auto Repeat, Priority, Preamble etc.

PageCode must refer to a configured Recorded Announcement Page Code.

id = is an id number provided by the client which the system may use to identify individual page requests when informing the client of progress of an individual page. A number range from 0 to 32767 is supported and each ID sequence should be unique.

C - Control Handle State

Make a request to set the state of a control handle. The handle is an ID number that can be queried using the Q H command, the response will be as found under Control Handle List. The term “state” defines an 8 bit scalar value (0-255 dependent on the switching threshold set in the Vocia software for the control handle).

Please note that to adjust a Control Handle state using VTP it must not be assigned to a physical Control Input. Assign the Control Handle in the Vocia software as a Scheduler/VTP driven handle for use with VTP.

Auto Repeat options

If the selected page code has pre-configured auto-repeat parameters these will override those specified using VTP commands.

By default the number of repeats will be set to 0 implying no repetition of announcements.  The repeat count will persist for all subsequent pages.  It would be necessary to set the repeat count back to 0 if repetition was no longer required.

R A - cancel all repeating recorded messages or paging

The “R A” command will be used to cancel all repeating announcements.  Any announcement appearing in the list obtained using the “R L” command will be terminated once the current play-out has finished.

R C - cancel a repeating message or Page.

  Announcements will be identified using the  event ID specified at the time of execution. A list of currently repeating announcements can be obtained using the “R L” command.

R I - request infinite playback of announcements

These announcements can only be stopped using the 'R C id' command or the 'R A' Command.

R L -  List currently repeating announcements 

The “R L” command will list the currently repeating announcements.  Announcements will be identified using the 16 bit event ID specified as part of the X S or X P command.

R N - specify the number of times a particular announcement will be repeated

Quantity can be specified between 1 and 9999.

If the selected page code has pre-configured auto-repeat parameters these will override those specified using VTP commands.

The repeat count will persist for all subsequent pages.  It would be necessary to set the repeat count back to 0 if repetition was no longer required.

R T - specify the time interval in seconds between repetitions for subsequent announcements

The time will be specified in seconds and must be less than or equal to 43200 (12 hours).

X U - Create a User Audio Input Event

A User Audio Input is assigned to a Vocia Input 6 (VI-6) input channel in the Vocia software interface in the VI-6 dialog window.  Once a VI-6 input channel is configured as a user audio input channel then it can be used for a user audio input event.  This user audio input event can be enabled and disabled through the VTP service.

The following parameters are used to create a user audio input event, and an example follows below.

X U device_type  device_id  channel  duration  prio mode id

• device_type and device_id = These parameters specify the device whose audio input will be used to make the page. At present the device type must be a VI-6, so the device type number will always be 6 (device type = 6). The device id number is determined by the hexadecimal Device ID switches found on the back of the VI-6 hardware.

• channel = This parameter defines which of the device’s audio input channels will be used for the user audio input event (This list can be queried using the Q I command).

• duration = This parameter specifies the duration of the user audio input event page in seconds. Enter 0 for an always active event. The maximum allowable value for a user audio input page that is not always active is 59940 seconds.

• prio = This parameter defines the priority of the page (used for resolution of access to zones) and is between 1 and the numerical value below the Emergency Priority Threshold specified in the Universe dialog. The Q E command can be used to query the threshold.

Example:

• mode = Mode that defines what happens to the background audio during the user input event.  

1. • Mute Mode - ( m = 0 )  mutes the background audio

   • Duck Mode - ( m = 1 ) will lower the background audio to a predefined level for the duration of the Audio Input Event.

   • Vox Mode - ( m = 2 ) will lower the background audio but only when paging audio is present and exceeds a predefined threshold.

The Duck and Vox modes share a user configurable threshold which is set on a per audio output channel basis in the Ducker settings in the Vocia software.

• id = nnnn Is an id number provided by the client which the system will use to identify individual page requests when informing the client of progress of an individual page.  The ID is also important when deleting a User Audio Input as it must be entered with the X D command.  Must be a four or more digit number between 2000 & 32767.

 Example sequence

• Connection to the socket

• Request client seat (Enter Username and Password information) U n=User Name P n1=Password

• Authorize the user (Use the A command)

• Set Interactive mode to ON using the I ON Command if required. Interactive mode will generally not be needed to be used. It has been turned on in this example to show the commands being processed.

• Enter the zone/s required to be affected by the user audio input by using the Z command.

• Query the list of assignable user audio input channels for the zone (Using the Q I Command).

• Enter the command formatted as shown in the table above X U device_type  device_id  channel  duration  prio mode id. For this example the command would be X U 6 9 3 100 2 2 2001.

As the Zone information has been set, you could continue to make changes in Zones 1, 2 & 3 or re-enter a different zone or zones using the Z command.

Terminate session (.) If required.

This user audio input event will route the audio from the VI-6 with Device ID 1, from input channel 2 for 100 seconds to zones 1, 2 and 3 at priority level 2. It will also duck the background audio when signal is received (see VOX in the Vocia Software Help File), and report an ID number of 2001.

X A - Cancel All Pages

The X A command is used to cancel all pages submitted to that MS-1(e) by any VTP clients. This will result in any current and future playback (including any auto-repeating) of all pages to be terminated immediately. 

Please see the R A Command if the intention is to cancel only the future playbacks of all auto-repeating announcements.

X C - Cancel an Individual Page

The X C command is used to cancel a page that has been submitted for playback. This will result in any current and future playback (including any auto-repeating) of the page being terminated immediately. 

Please see the R C Command if the intention is to cancel only the future playbacks of all auto-repeating announcements.

id = The id that corresponds to the page being cancelled that was previously provided by the client when triggering the page. A number range from 0 to 32767 is supported and each ID sequence should be unique.

X D - Delete a User Audio Input Event

Once created using VTP a User Audio Input Event can be deleted or terminated using VTP command X D id.

Delete (or terminate) a user input page identified using the id which is the id number provided at the time the X U command was issued (see above for information on the X U command). Must be a number between 2001 & 32767.