global viewer enterprise third-party controllers protocol ... · gve features not supported by...

Protocol Guide

GlobalViewer Enterprise

For Third-Party Controllers

Server-Based AV Resource Management Software

68-1607-01 Rev. G01 19

Copyright© 2019 Extron Electronics. All rights reserved.TrademarksAll trademarks mentioned in this guide are the properties of their respective owners.The following registered trademarks®, registered service marks(SM), and trademarks (TM) are the property of RGB Systems, Inc. or Extron Electronics (see the current list of trademarks on the Terms of Use page at www.extron.com):

Registered Trademarks (®)

Cable Cubby, ControlScript, CrossPoint, DTP, eBUS, EDID Manager, EDID Minder, Extron, Flat Field, FlexOS, Glitch Free, Global Configurator, Global Scripter, GlobalViewer, Hideaway, HyperLane, IP Intercom, IP Link, Key Minder, LinkLicense, LockIt, MediaLink, MediaPort, NetPA, PlenumVault, PoleVault, PowerCage, PURE3, Quantum, Show Me, SoundField, SpeedMount, SpeedSwitch, StudioStation, System INTEGRATOR, TeamWork, TouchLink, V‑Lock, VideoLounge, VN‑Matrix, VoiceLift, WallVault, WindoWall, XTP, XTP Systems, and ZipClip

Registered Service Mark(SM) : S3 Service Support Solutions

Trademarks (™)

AAP, AFL (Accu‑Rate Frame Lock), ADSP (Advanced Digital Sync Processing), Auto‑Image, AVEdge, CableCover, CDRS (Class D Ripple Suppression), Codec Connect, DDSP (Digital Display Sync Processing), DMI (Dynamic Motion Interpolation), Driver Configurator, DSP Configurator, DSVP (Digital Sync Validation Processing), eLink, EQIP, Everlast, FastBite, FOX, FOXBOX, IP Intercom HelpDesk, MAAP, MicroDigital, Opti‑Torque, PendantConnect, ProDSP, QS‑FPC (QuickSwitch Front Panel Controller), Room Agent, Scope‑Trigger, ShareLink, SIS, Simple Instruction Set, Skew‑Free, SpeedNav, Triple‑Action Switching, True4K, Vector™ 4K, WebShare, XTRA, and ZipCaddy

Conventions Used in this Guide

Notifications The following notifications are used in this guide:

NOTE: A note draws attention to important information.

Software CommandsCommands are written in the fonts shown here: ^AR Merge Scene,,Op1 scene 1,1 ̂ B 51 ̂ W^C

[01] R 0004 00300 00400 00800 00600 [02] 35 [17] [03]

E X! *X1&* X2)* X2#* X2! CE}

NOTE: For commands and examples of computer or device responses mentioned in this guide, the character “0” is used for the number zero and “O” represents the capital letter “o.”

Computer responses and directory paths that do not have variables are written in the font shown here: Reply from 208.132.180.48: bytes=32 times=2ms TTL=32

C:\Program Files\Extron

Variables are written in slanted form as shown here:ping xxx.xxx.xxx.xxx —t

SOH R Data STX Command ETB ETX

Selectable items, such as menu names, menu options, buttons, tabs, and field names are written in the font shown here:From the File menu, select New.Click the OK button.

http://www.extron.com/company/article.aspx?id=termsprivacy

http://www.extron.com

iiiTechnical Publications Standards and Styles • IntroductionGlobalViewer Enterprise • Contents iii

Contents

Introduction ................................................... 1

About this Manual............................................... 1About GlobalViewer Enterprise ........................... 1

Features ......................................................... 1For Further Information ................................... 2

Requirements and Setup .................................... 3

Requirements ..................................................... 3Setup Overview .................................................. 4Add a Room and Location .................................. 4

Add a Location ............................................... 5Add a GVE Room ........................................... 5

Add a Third‑Party Controller to GVE ................... 7Add Attached or Controlled Devices ................... 8Add Input Sources ............................................ 10Add Device Statuses ........................................ 11Develop Controller Code................................... 11

Communication ........................................... 12

Communication Overview ................................. 12Message Packet Structure................................ 12

Header ......................................................... 12Body ............................................................ 13Character Escaping ...................................... 15

Messages Between the Controller and GVE .... 15Special Rules ................................................ 15Messages from the Controller ....................... 15Messages to the Controller from GVE ........... 20Special Messages ......................................... 21

Support ................................................................. 22

Necessary Coding Modification ........................ 22

GlobalViewer Enterprise • Contents iv

<Product Name> • <Section Title> 1GlobalViewer Enterprise • Introduction 1

Introduction

This section describes the main features of GlobalViewer Enterprise (GVE) and provides an overview of this protocol guide. Topics that are covered include:

• About this Guide

• About GlobalViewer Enterprise

• GVE Features

• For Further Information

About this GuideThis guide documents the protocol used for third‑party controllers to function with GlobalViewer Enterprise. It is expected that the user of this document is familiar with third‑party software development.

Within this manual, the terms “GlobalViewer Enterprise” and “GVE” refer to the GlobalViewer Enterprise application and are interchangeable.

As GlobalViewer Enterprise is updated, this protocol may change. Future versions of GlobalViewer Enterprise will support more commands. As updates arise, changes to coding for third‑party controllers may be required.

About GlobalViewer EnterpriseGVE is a multi‑user, web‑based, global management application that aids audio/video (AV) network administrators with monitoring and managing all of the devices across their AV networks. This application manages controllers and their display devices, such as projectors or LCD or plasma monitors.

GVE also takes inventory of other devices attached to the controller, such as media players, switchers, lighting devices, and document cameras. With this application, monitoring and managing AV devices can be accomplished from any location with web browser access.

In GVE 2.7, there are three types of controllers:

• Extron Configurable (see GlobalViewer Enterprise Help file)

• Third‑party controllers (described in this protocol guide)

• Extron Programmable (see GlobalViewer Enterprise Protocol Guide for Programmable Controllers)

GVE FeaturesGlobalViewer Enterprise supports most popular browsers, including:

• Microsoft® Internet Explorer®

• Microsoft Edge™

• Mozilla® Firefox®

• Safari®

• Google Chrome™

GlobalViewer Enterprise • Introduction 2

The application runs from an easy‑to‑learn graphical user interface (GUI) and supplies a comprehensive set of reporting capabilities.

GVE enables AV network administrators to:

• Import an existing AV system using one or more Global Configurator configuration files.

• Set user permissions for complete or regional (partial) access to the AV network and GVE tools.

• Set device schedules and monitors.

• Audit and manage AV equipment assets.

• Control devices on the AV network.

• Capture all host‑to‑controller communications in user logs.

• Generate equipment usage reports.

GVE Features Not Supported by Third-party Control Systems

GVE Help Desk room control

• The Room Control tab lists the controller name, model name, MAC address, firmware version, IP address, gateway, subnet mask, and DHCP status. It does not show an image of the controller front panel.

• The Device Status tab displays device name, device type, status, controller port type, lamp cost, connection, power, device status, lamp hours, max lamp hours, operation hours, and filter hours.

For Extron controllers that have been configured with GCP, the Device Status tab allows you to control and view command status. This is not possible for third‑party controllers.

GVE schedule commands

GVE schedule commands for controllers are not executed on third‑party controllers. The Add a Schedule wizard displays a warning stating this.

GVE time sync

GVE time sync schedule commands are not executed on third‑party control systems.

NOTE: This applies only to IP Link controllers.

For Further InformationFor further information regarding GVE, visit www.extron.com/gve

For any questions regarding this protocol or support for GVE, visit www.extron.com/company/contactus.aspx

http://www.extron.com/gve

http://www.extron.com/company/contactus.aspx

GlobalViewer Enterprise • Requirements and Setup 3

Requirements and Setup

This section describes the requirements to communicate with third‑party controllers and how to set up these controllers in GVE. Topics that are covered include:

• Requirements

• Setup Overview

• Add a Room and Location

• Add a Third-Party Controller to GVE

• Add Attached or Controlled Devices

• Add Input Sources

• Add Device Statuses

• Develop Controller Code

Requirements

NOTE: It is expected that the user of this document is familiar with third‑party software development.

GVE communicates with third‑party controllers over UDP and TCP protocols.

• Status messages sent from the controller to the GVE PC or server use UDP port 5555. This cannot be changed.

• Control messages sent from the GVE PC or server to the controller use TCP port 5555. This can be changed in GVE Configurator.

• The user must have access to the Controller Manager option and Location/Room option in GVE to create GVE rooms.

• The user needs to obtain information regarding the controller MAC address, IP address or host name, firmware version, DHCP, subnet mask, gateway address, time zone, and DST mode.

• GVE supports all of the command and status items listed in the Commands Supported Table, starting on page 17. It is preferred that the user provide as much information as possible about the controller in order to maximize GVE capability.


Setup OverviewA third‑party controller and its attached or controlled devices are added manually to GVE. The steps below enable management of these controllers and devices through GVE.

In the setup process, the user does the following:

1. Defines the location of a third‑party controller and any attached devices.

2. Adds a third‑party controller to GVE.

3. Adds attached or controlled devices and places them in user‑specified locations.

4. Develops controller code.

Add a Room and LocationIn order to add a third‑party controller and any managed devices, you must designate their location and room. Create a location if one has not already been created. Then, add a room within that location.

Definitions• Building — A collection of locations and rooms. It can refer to a collection of floors

within a physical building.

• Location — A collection of other locations and rooms. It can refer to a suite of rooms, an individual floor, or a group of floors.

• Room — A place where a controller or other device is located.

NOTE: Controllers and devices must belong to a room and not a location.

Tree ManagerIf a location already exists, skip the Add a Location instructions and proceed to the Add a GVE Room instructions. To begin defining a location:

1. Log in to GlobalViewer Enterprise.

2. Click System Menu on the navigation bar (see figure 1, 1).

3. Click the Tree Manager icon (see the figure to the right).

The Tree Manager screen opens.

Figure 1. Locations and Rooms Screen

4. See Add a Location and Add a GVE Room (on the next page) to add a location or a room.


Add a Location1. In the GVE Location Tree panel, right‑click the parent location where the new room

will be created for the controller and devices. A pop‑up menu opens:

Figure 2. Create Child Location Option

2. Click Create Child Location (1). A new location icon appears in the tree with the text Location highlighted.

Figure 3. Add New Location

3. Replace Location with the name of the new location.

To rename a location, double‑click the location name to highlight it and enter the new name.

To move a location, drag and drop it in a new position within the location tree.

Add a GVE RoomThe organizational structure of the locations and rooms appears similar to this example:

Figure 4. Location Tree Organization

The lowest tier of the location tree is, typically, where the rooms and their controllers and devices are located.


After a location is designated, add a room as follows:

1. In the GVE Location Tree panel, right‑click the parent location where the new room will be created for the controller and devices.

Figure 5. Create a GVE Room

2. Select Create GVE Room (see figure 5, 1).

3. A new GVE room is created with the text GVERoom highlighted (see figure 6, 1). Enter the name of the new GVE room.

11

2

Figure 6. GVE Room Added

NOTE: The icon for a GVE room contains the text GVE to distinguish it from rooms created in Global Configurator.

4. To rename a GVE room, double‑click the room name to highlight it and enter the new name.

5. To move a GVE room, drag and drop it in a new position within the location tree. In figure 6, the GVE room was renamed Classroom5 and moved from Building 1 to Building 2 (2).


Add a Third-Party Controller to GVE1. Click System Menu (1) on the navigation bar.

2. Click the Controller Manager icon (see the image to the right).

3. Select the 3rd Party Controllers tab (2).

Figure 7. Third-Party Controllers Tab

4. Click Add New Controller (3).

The Add New Controller dialog box opens:

Figure 8. Add New Controller Dialog Box

5. Enter the required information about the controller. Some fields (Model and Firmware) are optional. Required fields are:

• Room — Select a room from the drop‑down menu. Only GVE rooms are in this list.

• Name — Enter a name that distinguishes the controller from other devices or items on the network. Use only upper or lower case letters or numbers (no hyphens or other special characters).

• Time Zone — The time zone of the controller. GVE uses the time zone and DST mode to calculate the local time of the controller. By default, this is set to the same time zone as the local server.

• DST Mode — The Daylight Savings Time mode of the controller

• MAC Address — Media Access Control. It is a hex‑based number that uniquely identifies hardware devices that connect to a network.


• Telnet Port — By default this is 23.

• HTTP Port — By default this is 80.

• DHCP — Dynamic Host Configuration Protocol. If this box is checked, the IP Address, Subnet Mask, and Gateway are automatically assigned by the DHCP server and cannot be edited in this dialog box.

• IP Address — Required if DHCP is disabled. A unique 32‑bit binary number (12‑digit decimal number: xxx.xxx.xxx.xxx) that identifies each sender and receiver of information connected to a LAN, WAN, or the Internet. IP address can be static or dynamic.

• Host Name — Required if DHCP is enabled. It identifies a particular host in electronic communication. While same‑domain connections are possible, cross‑domain connections are not.

• Subnet Mask — Required if you are entering an IP address. It defines the boundaries of an IP subnet. Devices on a subnet share contiguous ranges of IP addresses.

• Gateway — Required if you are entering an IP address. It is a device that interconnects networks with different, incompatible communication protocols.

Refer to the glossary in the GlobalViewer Enterprise Help File for information about other fields.

6. If you have created asset tags (see the GlobalViewer Enterprise Help File), they are listed in the Asset Tags Info panel. You can assign a value to any appropriate tag.

7. Click Add.

The controller is now listed in the 3rd Party Controllers tab.

Figure 9. New Controller Added

NOTE: Click on the delete icon ( ) to delete a controller. Click on the Edit icon ( ) to edit the controller properties.


Add Attached or Controlled Devices1. Right‑click in the row containing the controller you wish to add. A popup menu opens.

Figure 10. Controller Popup

2. Click Add Device.

The Add Device box opens:

Figure 11. Add Device Dialog Box

3. Enter as much information as possible. The Controller Web Page field and Bi‑directional check box are optional.

NOTE: GlobalViewer Enterprise can support bidirectional and unidirectional devices. If the device is unidirectional, no status changes are sent to GlobalViewer Enterprise.

Room can be selected from the drop‑down menu. By default it is the same as controller.

The required fields are:

• Device ID — User‑defined ID associated with the added device.

NOTES:

• The ID entered in this field must match the ID used within the third‑party code for the device.

• The ID cannot be 0 (the controller ID is always 0).

• Each device associated with a controller must have a unique ID. An exception appears if an ID is repeated.

• In a system with multiple controllers, devices can only have the same ID when they are associated with different controllers.

• Device Name — Name used to identify the device in GlobalViewer Enterprise.

• Device Type — Select a device type from the drop‑down menu.


• Manufacturer — Name of the device manufacturer that you can enter or select from the drop‑down list.

• Model — Device model name that you can enter or select from the drop‑down list.

• Max Lamp Hours — This is required if the device type is a video projector. It is the maximum number of lamp hours for the projector.

4. If you have created asset tags (see the GlobalViewer Enterprise Help File), they are listed in the Asset Tag section. You can assign a value to any appropriate tag.

5. Click Add.

6. Repeat steps 1 through 5 to add more devices.

Click > next to the controller to display a list of devices associated with that controller.

Add Input SourcesIn order to track input sources usage, you will need to verify that the input sources have been added to the GVE system.

1. Select the System Menu from the main menu bar (1).

2. Click the Consolidate Input Sources icon (see the figure to the right).

The Consolidate All Input Sources window opens:

Figure 12. Consolidate All Input Sources Window

3. Check whether the input source is listed in the table.

4. If not, add the desired input source to GVE from this page:

a. Click Add/Modify/Delete Input Sources (figure 12, 2).


The Input Sources dialog opens:

Figure 13. Input Sources Dialog

b. Enter the Input Source name and click Add New (figure 13, 1).

c. Click the exit icon in the top right corner (2).

Add Device StatusesGVE provides users with a set of default statuses. If you need one or more additional statuses, you must add them as follows:

1. Select the System Menu from the main menu bar (1).

2. Click the Manage Device Statuses icon (see the figure to the right).

The Device Status Manager window opens:

Figure 14. Device Status Manager Window

3. Select the 3rd Party Device Statuses tab (2).


4. Add the required 3rd Party device status. You must have one of the following combinations:

• Normal and Error

• Normal and Warning

• Normal, Error, and Warning

5. Keep a record of the Device Status ID for programming purposes.

Develop Controller CodeDevelop third‑party code based on this protocol. This user‑developed code maintains functionality between the controller, any attached devices, and GlobalViewer Enterprise.

To develop controller code refer to the specific topics in the following Communication sections:

• Sequence number (see page 14) discusses GlobalViewer Enterprise full update requests with regard to messages that are lost or out of order.

• Full update (see page 23) discusses requests for full update, beginning with the initial startup of the controller.

• Status data (see page 15) discusses how a power status change is accompanied by a source status and vice versa. These details are necessary for GlobalViewer Enterprise reports to run properly because the available reports contain information regarding lamp hours, usage, and so on.

• Support (see page 25) discusses changes requiring modification to the third‑party controller code.

GlobalViewer Enterprise • Communication Overview 13

Communication Overview

This section discusses the communication between controllers and GlobalViewer Enterprise. Topics that are covered include:

• Communication Overview

• Security

• Message Packet Structure

• Commands Supported Table

Communication Overview• GVE uses the IP address and TCP port entered by the user in the Add a

Programmable Controller wizard for communication.

• GVE opens a basic TCP socket connection on the port entered by the user to issue commands to the programmable controller.

• For information about the command strings and their format, see Message Packet Structure on the next page.

Any data or commands issued to the controller that do not follow this format are considered external data.

• GVE uses messages in UDP packets sent from a primary controller to collect status information about devices managed by the controller. Messages are sent from the controller when there is a change to a status that is of interest to the server.

• If there is no controller or device status change, a heartbeat message packet is sent every 20 seconds to ensure the controller is online.

Security• GVE does not perform any security (password) checks when a third‑party controller is

added manually to the system. This facilitates the offline addition of controllers to GVE.

• GVE does not perform any security (password) checks while issuing commands to the third‑party controller. This is to avoid saving passwords in the GVE database.

• All security checks to validate the authenticity of the issuer of commands are the responsibility of the third‑party controller programmer. The third‑party controller code should use some logic to ensure that the commands are being sent by GVE.


Message Packet StructureThe following is the format of the third-party controller to GVE UDP packet:ENTR<PrimaryControllerMACAddressNoDashes><SequenceNumber>[DeviceId~ aCmdID=aCmdValue][SecondaryControllerMAC~aCmdID=aCmdValue]<ETX>

The message packet is split into two parts:

• Fixed‑length header that GVE uses to identify the controller

• Variable‑length data section (body) containing zero or more device status sections (see Status data on page 15 and Heartbeat on page 22)

The message packet ends with the ETX (0x03) character. All message packets are sent to UDP port 5555 at the server.

HeaderThe header portion of the packet is further divided into three fixed‑length fields.

Header

ID MAC Address Sequence Number

4 bytes 12 bytes 3 bytes

ID

These 4 bytes are fixed as ENTR.

MAC address

The MAC address is the ASCII‑encoded hexadecimal representation of the controller MAC address, without hyphens.

For example, the MAC address 00-05-A6-00-C1-94 appears as 0005A600C194.

NOTE: The MAC address is included in the header, allowing GVE to authenticate the controller. Unrecognized MAC addresses should be ignored. This ensures GVE receives a message from the appropriate controller and sends a message to the intended controller.

Sequence number

NOTES:

• The sequence number is in ASCII and is automatically generated by the controller, in sequence, from 000 to 255 and is padded with leading zeroes to three places.

• The sequence number increases by an increment of 1 on the controller after sending each message.

• A message with sequence number 255 is followed by a message with sequence number 000.

• There are no reserved sequence numbers.

GlobalViewer Enterprise uses this field to determine if there have been any missed messages. If messages are lost or arrive out of order, GlobalViewer Enterprise requests a full update from the controller. The threshold for requesting a full update is one missed message.


BodyThis portion of the message packet contains status information and device information for a device.

Status data

Status change notifications for each device are grouped inside square brackets. This is the same as communication with IP Link, IP Link Pro, and third party controllers. The format is:

[Device 1 data] [Device 2 data]...[Device n data]

A device data section contains a device ID and at least one status item. The device ID appears first in this section followed by the status item. The format is:

[device_id~command_id=value].

A message does not contain a section for a device unless there is a change to report for it.

Device ID

NOTES:

• The device ID for the controller is always 0.

• The ID for managed devices is determined after adding a device as shown in Add a Third-Party Controller to GVE (see page 7).

• See the Commands Supported Table, starting on page 17, for information regarding the command IDs and values.

When the data packets or full update packets have statuses for devices, the Device ID is the value entered in the Add A New Device wizard (see Add Attached or Controlled Devices on page 9).

Status item

This is the key‑value pair, indicating the numeric command ID and the value to which the command is changed. An equal sign (=) appears between the command ID and value. Status items are separated with a tilde character (ASCII 0x7E). The format for one device with one command is:

[device_id~command_id=value]

For example, a complete device data section indicating a change in the lamp hours of a projector (device ID=1) to 1000 appears as follows:

[1~20=1000]

The device data between brackets can also have multiple command IDs. The message structure for one device with two commands is:

[device_id~command_id=value~command_id=value]

For example, a complete device data section indicating a change in the lamp hours of a projector (device ID=1) to 1000 and a change in device status to a lamp warning level on the same device appears as follows:

[1~20=1000~22=0603]

If a device has more than two commands, this structure is still applicable. A tilde (~) separates each command ID and its respective value.


Multiple devices can be updated in GlobalViewer Enterprise within the same message. The message for two devices with two commands is:



Depending on the devices, multiple status updates can occur simultaneously. In this example, status updates occur for both a laptop (device ID=1) and a second source (device ID=2). The updates include power status and source status for each device. The status string appears as follows:

[1~17=1~18=Laptop][2~17=1~18=S-Video]

Each device ID refers to a new device and the above format is still applicable if there are more than two devices.

A message from the controller appears with a format similar to messages from a device. The controller ID is always 0.

For example, a 3 °C increase in the temperature of a controller (device ID=0) to 46 °C appears as follows:

[0~28=46C]

<ETX> End of transmission character

Every UDP status packet ends with the ETX (0x03) character.

See the Commands Supported Table starting on the next page for information regarding the command IDs and values within this example.

Character EscapingCertain characters must be escaped when they appear in the “value” section of the data. The escape sequence is a backslash ( \ ) followed by the ASCII‑encoded hexadecimal value of the encoded character. Essentially, these escape sequences appear in place of their respective characters if used in the “value” section but are read as the characters.

Characters to be Escaped

Character Escape Sequence

~ \7E

= \3D

\ \5C

[ \5B

] \5D

For example, if command ID 5 is used for a device named “[Apple],” the framing characters of the name are escaped.

It appears as this section marked in bold:

ENTR0005A600C194000[0~5=\5BApple\5D]<ETX>


Commands Supported Table

NOTE: The controller or controlled devices may not support all of these command or status items. If this is the case, disregard that particular item.

Controller MessagesName Command

IDValue Status

(to GVE)Control

(from GVE)Notes

Update Request

0 0 = Stop communication 1 = Full Update/Resume

No Yes

Firmware Version

1 <string> Yes No String similar to 1.12.0010

DHCP 2 0 = Off 1 = On

Yes No If DHCP is on, then GVE uses the host name to communicate with the controller.

Subnet Mask 3 <string> Yes No String similar to 255.255.0.0

Gateway Address

4 <string> Yes No String similar to 10.0.100.1

Host Name 5 <string> Yes No While same‑domain connections are possible, cross‑domain connections are not.

Telnet Port 6 0-65535 Yes No

HTTP Port 7 0-65535 Yes No

Time Zone 8 <signed ASCII digits>

Yes No String appears in GMT format:

For the Pacific time zone, it appears as “-08:00.”

For the Tokyo time zone, it appears as “09.00“

GVE calculates the local time for the controller based on the time zone and the DST mode.

DST Mode 9 0 = Off/Ignore 1 = USA 2 = Europe 3 = Brazil

Yes No

E‑mail Server 10 <string> Yes No IP address of the server used to send e‑mails.

E‑mail Domain

11 <string> Yes No Similar to extron.com

E‑mail User Name

12 <string> Yes No The e‑mail account user name is used if the e‑mail server requires authentication.


Controller MessagesName Command

IDValue Status

(to GVE)Control

(from GVE)Notes

E‑mail Password

13 0 = Unset 1 = Set

Yes No

Power 17 -1 = Unknown 0 = Off 1 = On 2 = Cool Down 3 = Warm Up

Yes Yes Only “On” and “Off” can be used as commands.

Unknown: the controller has not yet determined the power state.

Relay Open 24 # = Relay# No Yes Maximum relay number depends on the product.

Relay Close 25 # = Relay# No Yes

Relay Pulse 26 # = Relay# No Yes Pulse is always 500 ms

Relay Toggle 27 # = Relay# No Yes

Controller Temperature

28 <Temp><F or C> Yes No Limits depend on the device.

Status change appears if there is a temperature change of ±3 °C or ±5 °F

NOTE: When a power command is sent to a controller, a second message must be sent for the same power command for an attached device. For instance, when a Power Off action is desired, a Power Off must be scheduled for the controller and a second Power Off action must be scheduled for any projectors or displays connected to the controller. Powering off each device within a specified location ensures a full power off.


Projector and display devices (LCD, plasma, and so on)

Device MessagesName Command

IDValue Status

(to GVE)Control

(from GVE)Notes

Power 17 -1 = Unknown 0 = Off 1 = On 2 = Cool Down 3 = Warm Up

Yes Yes Only “On” and “Off” can be used as commands.

Unknown: the controller has not yet determined the power state.

Source 18 <string>

“Unknown” may also be sent.

Yes No String represents the source name. Similar to “Laptop.”

Unknown: The controller has not yet determined the source.

Connection 19 -1 = Unknown 0 = Disconnected 1 = Connected

Yes No Disconnected: the controller cannot communicate with the device.

Connected: the driver module on the controller has a communication channel to the controlled device and it is responding correctly.

Unknown: The controller has not yet determined the connection state.

Lamp hours

(primary lamp 1)

20 <ASCII digits> Yes No Minimum = 0

Theoretical maximum = 2^32 ‑1

Lamp hours

(lamp 2)



Lamp hours

(lamp 3)



Lamp hours

(lamp 4)



Filter hours (projectors

only)




Device MessagesName Command

IDValue Status

(to GVE)Control

(from GVE)Notes

Device status

22 Four ASCII digits, where the first pair of ASCII digits represent the category and the second pair represent status.

Category:

00 = Device 01 = Communication 02 = Cover 03 = Fan 04 = Filter 05 = General 06 = Lamp 07 = Power 08 = Temp 09 = Voltage 10 = Lamp

Status:

01 = Normal 02 = Error 03 = Warning

Yes No A communication error appears as “0102,” where “01” refers to the category and “02” refers to the status.

The Device Normal status appears as “0001” and is the default.

NOTE: You can create additional device statuses and their 4‑digit IDs.

GlobalViewer Enterprise • Third Party Controller to GVE Communication 21

Third-party Controller to GVE Communication

This section provides information about third‑party controller to GVE communication in the following section:

• Special Rules

• Messages from the Controller

• Example of a Message from the Controller to GVE

• Special Messages

Special RulesThere are special rules when pushing status to GlobalViewer Enterprise, which enable greater accuracy in reporting on device usage.

• Upon initial power‑up of the controller, push all status messages for the controller and its managed devices.

• When pushing “power on” status, also push the currently selected input source name.

• If the input source changes, push the power status.

• Controller temperature should only be pushed when the temperature changes every ±3 °C (±5 °F) from its last reported value.

Messages from the ControllerMessages are sent to GlobalViewer Enterprise upon controller power‑up and as changes occur to individual command or status items.

Defined command IDs and their associated values are summarized in the Commands Supported Table, starting on page 17.

NOTE: The controller device ID always equals 0.

GlobalViewer Enterprise • Third Party Controller to GVE Communication 22

Example of a Message from the Controller to GVEFor this example and those in Examples of messages to the controller from GVE (on the next page), assume the controller has a MAC address 00‑05‑A6‑00‑C1‑94 and it is controlling a video projector and a display unless otherwise stated.

Status change on multiple devicesIf the status changes on more than one device, GlobalViewer Enterprise is notified of the changes. The message is usually much shorter than a full update.

Here, status has changed for two devices, a projector (device ID=1) and a display (device ID=2). The lamp time of the projector has changed to 501 and the display has been turned off:

ENTR0005A600C194020[1~20=501][2~17=0~18=S-Video]<ETX>

Special Messages

Heartbeat

The heartbeat is a required message. It has no status information and is just a header. When there have been no status changes for 20 seconds, the controller sends a heartbeat. If an item is sent to the controller to collect information about a device, a heartbeat is sent 20 seconds after the last message. Failure to send a heartbeat results in acknowledging that the controller is offline. The sequence number is still incremented and sent to the GlobalViewer Enterprise server.

A heartbeat is the shortest possible message:ENTR0005A600C194022<ETX>

GlobalViewer Enterprise • GVE to Third Party Controller Communication 23

GVE to Third-party Controller Communication

Messages sent to the controller follow a format similar to those sent from the controller to the server. The basic form is:

ENTR<MAC>[device_ID~command_number=value]

Value refers to the corresponding column within the Commands Supported Table, starting on page 17. Each command sent from GlobalViewer Enterprise appears in this format, whereas messages sent to GlobalViewer Enterprise appear in the format of the examples mentioned in Status item (see page 15).

The MAC address must match the controller to which the message is sent; otherwise, the message is ignored. This is important when writing code to ensure the appropriate MAC address is sent to the intended controller.

Examples of messages to the controller from GVEPower a device on or off

Sending a message to the script using command ID 17 can power a device on or off.

For example, a command that powers on a projector (device ID=1) appears as follows:ENTR0005A600C194[1~17=1]

Full update requestA full update request is a message to the controller that causes the controller code to re‑read all settings and send them to the server. If the controller has been inactive, this message resumes the activity of the controller. A full update request is accomplished by sending a message to the controller with command ID 0. This message can be directed only to device 0, which is the controller:

ENTR0005A600C194[0~0=1]

Full update

On start‑up and as requested, the controller fully updates the server. Afterwards, only a partial update occurs when there is a change to the current variables, unless a full update is requested. A full update from a controller with two display devices appears as follows:

ENTR0005A600C194000[0~1=1.2.3~2=0~3=255.255.255.0~4= 192.168.1.25~5=ClassroomAB_Controller~6=23~7=80~8=-08:00~9= 1~10=192.168.1.254~11=example.com~12=username~13=password][1~17=0~18=RGB1~19=1~20=500~21=100~22=0001][2~17=1~18=Video~19=1~22=0001]<ETX>

See the Commands Supported Table, starting on page 17 for information regarding the command IDs and values within this example.

GlobalViewer Enterprise • GVE to Third Party Controller Communication 24

Stop communication requestA stop communication request is issued to the controller when deleting the controller in GlobalViewer Enterprise. This prevents unnecessary status messages within GlobalViewer Enterprise when the controller has already been removed from the system. A stop communication request appears as follows:

ENTR0005A600C194[0~0=0]

NOTE: The GVE communication logic is disabled but not deleted.

Resume communicationIn order to resume controller activity after a stop communication request, a full update must occur. If the controller has been inactive, a full update request resumes the activity of the controller. This message can be directed only to device 0, which is the controller:

ENTR0005A600C194[0~0=1]

Worldwide Headquarters: Extron USA West, 1025 E. Ball Road, Anaheim, CA 92805, 800.633.9876

Support

This section discusses the support needed to maintain functionality between third‑party controllers and GlobalViewer Enterprise.

Necessary Coding ModificationCertain changes or updates may necessitate coding modification for third‑party controllers to maintain functionality with GlobalViewer Enterprise.

Changes to the GlobalViewer Enterprise protocol itself require modification to coding between the third‑party controller and GlobalViewer Enterprise to ensure proper communication. Such protocol modifications may include changes to any of the existing values for status or command items as well as additions to the existing protocol.

If a controller needs to be replaced, coding must be updated. The MAC address of the new controller should replace the old controller within GlobalViewer Enterprise. In addition to the update of GVE, coding must be updated with the new address in order to ensure that the new controller is recognized.

Coding needs to be updated if an attached device is replaced or if a device is added or removed.

global viewer enterprise third-party controllers protocol ... · gve features not supported by...

Documents