Everpass Control API

Description

This driver controls Everpass media players through the cloud-based Everpass Control API. It supports discovering the devices in an organization, discovering entitled live events, monitoring per-device playback state (now playing), retrieving device schedules, and starting or stopping live event playback on a device.

Note: This document is not a replacement for understanding the equipment you're controlling and the documentation that is distributed with the equipment. Please read and understand all documentation before attempting to use this driver.

Everpass Integration Setup *IMPORTANT*

The Everpass organization has certain requirements before this driver can be used. These are needed for the driver to authenticate and to link control and feedback to the correct devices.

Control API Access: The organization must have the control_api_access feature enabled by Everpass.

OAuth Credentials: A Client ID and Client Secret must be issued for the Control API (client credentials flow). These are entered in the driver settings.

Organization ID: The numeric Everpass organization ID must be entered in the driver settings.

Device IDs: Each player to be controlled must have its numeric Everpass Device ID entered in the corresponding Device # Settings. The IDs are found in the Everpass dashboard, and the dev_ prefix is accepted.

Multiple Zones: Everpass entitles playback control at the location (zone) level. When devices span multiple zones, enable Per-Device Organization IDs and give each device the Organization ID of its zone, with the global Organization ID set to the parent organization.

Revision History

v1.0.0 : Initial Release

Known Issues

Connection Settings

All communication between the driver and the Everpass Control API occurs over HTTPS (TCP port 443) to api.everpass.com. The RTI processor must have internet access and working DNS to reach the API. The driver authenticates with the OAuth 2.0 client credentials flow and automatically refreshes its access token before it expires.

Initialization Sequence

Once driver communications have been started and the driver has authenticated, it will automatically sweep the organization device list every 30 seconds and poll the now-playing state of every configured device along with the entitled live event list. Once every configured component has acquired its state, the driver is considered initialized. No playback commands should be sent until this process is complete.

Driver Configuration

Debug Settings

Only visible if "Show Driver Debug Options" has been set in TraceViewer.

Enable Debug Messages

Enables the driver debugging messages. Turn this on when commissioning or troubleshooting.

Debug Level

Determines which debug messages to show. The Debug level is required to see the HTTP trace.

Identifier

Prefix for debug messages to distinguish debug messages from this driver.

Trace HTTP Payloads

Prints a one-line summary of the HTTP request and response for every transaction, including a short body preview. Requires Enable Debug Messages, at the Debug level. Credentials are masked.

API Connection

API Host

The hostname of the Everpass Control API. This should normally be left at the default (api.everpass.com).

API Port

The HTTPS port of the Everpass Control API. Default is 443.

Client ID

OAuth client ID issued when registering the application.

Client Secret

OAuth client secret issued when registering the application.

Organization ID

Numeric Everpass organization ID. The organization must have the control_api_access feature enabled.

Auto Connect

The driver will make a connection attempt to the API once the driver is fully loaded. This means if the processor is rebooted, the driver will make a connection attempt when it is back online.

Live Event Settings

Max Live Events

Maximum number of live events to track. A single instance of the driver supports up to 50 events.

Event Refresh Interval

How often the live event list is refreshed in the background, in minutes. The list is also refreshed on connect and whenever Refresh Live Events is triggered.

Live Event Status Filter

Which event statuses to request from the API: Live Only, Live and Scheduled, or Live, Scheduled and Finished.

Device Configuration

Device Count

Determines the number of Everpass devices to control. A single instance of the driver supports up to 100 devices.

Per-Device Organization IDs

Everpass entitles playback control at the location (zone) level. Leave this off when every device lives in one zone - the global Organization ID is used for everything. Turn it on when devices span multiple zones: each device gets its own Organization ID field, and the global Organization ID should be set to the parent organization so discovery and the live event list still see everything.

Device # Settings

Device # Friendly Name

Defines a friendly name for the device.

Device # Device ID

Numeric Everpass device ID. Found in the Everpass dashboard. The dev_ prefix is accepted.

Device # Organization ID

Organization ID of the location (zone) this device belongs to. Playback control is routed through this organization. Leave blank to use the global Organization ID. Only shown and used when Per-Device Organization IDs is enabled.

Device # Schedule Polling

Periodically poll the upcoming event schedule for this device.

Driver Controls

Communication> Connect:

Triggers the driver to make a connection to the API if not already connected.

Communication> Disconnect:

Triggers the driver to disconnect from the API if currently connected.

Live Events> Refresh Live Events:

Triggers an immediate refresh of the entitled live events list.

{Device #}> Select Target Event:

Selects a live event by its row number in the Live Events list (counting from 0) to be used with Play Target Event. Bind the Event Index parameter to the list selection, or enter a fixed row for a static button. {Device #} will match the friendly name of the device.

{Device #}> Play Target Event:

Starts playback of the event last selected using Select Target Event. Using the two together simplifies list-driven user interfaces.

{Device #}> Play Event By Index:

Starts playback of the live event at the given row number of the Live Events list, counting from 0. Bind the Event Index parameter to the list selection, or enter a fixed row for a static button.

{Device #}> Play Event By ID:

Starts playback of a live event by its numeric Everpass event ID. The evt_ prefix is accepted.

{Device #}> Stop Playback:

Stops live event playback on the device. The device returns to its default content.

{Device #}> Refresh Now Playing:

Triggers an immediate refresh of the device's now-playing state.

{Device #}> Refresh Schedule:

Triggers an immediate refresh of the device's upcoming event schedule.

Driver Feedback

Communications State

Gets the current communications state of the driver. Indicates if communication is enabled or disabled.

Communications State> Disabled

Sets the communication state to disabled. Used to stop communication with the API.

Communications State> Enabled

Sets the communication state to enabled. Used to resume communication with the API.

Connection State

Gets the current connection state of the driver.

Connection State> Disconnected

Indicates the driver is not currently connected to the Everpass Control API.

Connection State> Connected

Indicates the driver is authenticated and communicating with the Everpass Control API.

Initialization State

Reports the current initialization state of the driver.

Initialization State> Not Initialized

Indicates the driver has not yet completed initialization. *IMPORTANT* Make sure the driver is initialized before controlling. If it never initializes, check the Client ID, Client Secret, Organization ID and Device IDs.

Initialization State> Initializing

Indicates the driver is currently acquiring the state of all configured components.

Initialization State> Initialized

Indicates the driver is fully initialized and operational.

Debug State

Indicates the debug state of the driver for diagnostics.

Debug State> Disabled

Indicates that debug output/logging is disabled.

Debug State> Enabled

Indicates that debug output/logging is enabled.

Errors> Last Error

Reports the most recent error reported by the driver or the API, for example invalid_credentials, auth_error or ssl_handshake_failed.

Discovery> Discovered Devices

Indicates all of the devices discovered in the organization as an RTI List, in the form Name [id]. Updated on every heartbeat sweep.

Discovery> Live Events

Indicates the entitled live events as an RTI List. Bind this list to a page and use its selection with Select Target Event / Play Event By Index.

Discovery> Live Event Count

Indicates the number of live events currently in the list.

{Device #}> Name

Returns the configured friendly name for the device.

{Device #}> Device ID

Indicates the Everpass device ID of the device.

{Device #}> Online / Offline / Is Online

Indicates whether the device is currently online, as reported by the organization device sweep. Online and Offline also fire as driver events.

{Device #}> Status / Is Active

Reports the status string of the device and whether it is active.

{Device #}> Model / Serial / Location / Last Seen

Reports the hardware model, serial number, location and last-seen timestamp of the device.

{Device #}> Playback Kind

Reports what the device is currently playing. The matching states Playback Unknown, Playback Off, Playback Default Content and Playback Live Event also fire as driver events.

{Device #}> Now Playing Title / Now Playing Event ID / Now Playing Start / Now Playing End

Reports the title, event ID and start/end times of the live event currently playing on the device.

{Device #}> Schedule

Indicates the device's upcoming event schedule as an RTI List. Requires Schedule Polling to be enabled for the device, or a Refresh Schedule trigger.

{Device #}> Next Event Title / Next Event Start

Reports the title and start time of the next scheduled event for the device.

{Device #}> Target Event Title / Target Event Index / Target Event Selected

Reports the live event currently selected with Select Target Event. If the selected event drops out of the list, the selection is cleared automatically.

{Device #}> Is Event # Selected

Checks whether live event # is the device's currently selected target event. Useful for showing the selection state on list rows.

{Live Event #}> Title / Is Live / Event ID

Reports the title, live state and Everpass event ID of row # of the live event list.

{Live Event #}> Start / End

Reports the scheduled start and end times of the event.

{Live Event #}> Sport / League / Teams

Reports the sport, league and team information for the event, when provided by Everpass.

Further Assistance

If you need more information or assistance, please contact us.

Developer Information

Company: Control Concepts, Inc.

Phone: (201) 797-7900

Email: projects@controlconcepts.net

Website: https://controlconcepts.net/

Developer: Andrew Lockett