@crestron/ch5-webxpanel NPM

Crestron WebXPanel - Getting Started

IMPORTANT: WebXPanel instance without import statement

Use WebXPanel.default to access the WebXPanel instance if the project doesn't use ES6 import statements.

Installation

Make your package available by running one of the following commands in the root folder of the WebXPanel project:

# NPM
npm link

Add WebXPanel to a CH5 Project by running one of the following commands in the root folder of the CH5 project:

# NPM
npm link "@crestron/ch5-webxpanel"

Please make sure that WebXPanel is the first library that is initialized in the CH5 Project!

All configuration parameters are optional. Only the parameters that need to be overwritten should be defined. Do not pass empty string values for parameters that should not be defined.

Example: (app.module.ts)

import WebXPanel, {WebXPanelConfigParams, isActive} from "@crestron/ch5-webxpanel";

const configuration: Partial<WebXPanelConfigParams> = {
    host: 'ip_address | hostname', // defaults to window.location.host
    ipId: '3|0x03', // string representing a hex value. Might contain "0x" or not. Defaults to "0x03"
    roomId: 'virtual_control_room_id', // defaults to empty string
};
// other rarely used options
//     port: 49200, // port for Secure WebSocket connection. Defaults to 49200
//     tokenUrl: 'https://url/cws/websocket/getWebSocketToken', // defaults to `${location.origin}/cws/websocket/getWebSocketToken`,
//     tokenSource: 'CSSelf|Fusion', // defaults to CSSelf

const webXPanelFactory = () => () => {
  if (isActive) {
    WebXPanel.initialize(configuration);
  }
}
// ...

@NgModule({
  // ...
  providers: [
    { provide: APP_INITIALIZER, useFactory: webXPanelFactory, multi: true },
    // ...
  ],
  // ...
})

// ...

Checking if WebXPanel is active

import {isActive} from "@crestron/ch5-webxpanel";

console.log(`WebXPanel isActive: ${isActive}`);

Checking the WebXPanel version and build date

import {getVersion, getBuildDate} from "@crestron/ch5-webxpanel";

console.log(`WebXPanel version: ${getVersion()}`);
console.log(`WebXPanel build date: ${getBuildDate()}`);

Contract file

The WebXPanel library expects to find a contract file named contract.cse2j at the following path in the CH5 project: ./config/contract.cse2j. If a contract file is not found at the specified path, WebXPanel will fallback to an empty contract file.

WebXPanel logging

The WebXPanel library provides a logger which is enabled by default, with the log level set to WARN. This can be changed from the CH5 project and logs can be seen in the browser console, if needed.

import { 
  getDebuggingState, 
  enableDebugging, 
  disableDebugging,
  getLogLevel,
  setLogLevel,
  LogLevel
} from "@crestron/ch5-webxpanel";

const isLoggingEnabled = getDebuggingState();

// to enable logging
enableDebugging();

// to disable debugging
disableDebugging();

// get current log level
getLogLevel();

// set log level to LOG
setLogLevel(LogLevel.LOG);

Listening to WebXPanel Events

All events dispatched by WebXPanel are CustomEvents. The relevant data within each event can be found in the detail property.

Available events and their descriptions

Event name	Dispatch reason	Other information
CONNECT_WS	A successful WebSocket connection has been established	Similar to `WebSocket.onopen`
DISCONNECT_WS	The WebSocket connection was disconnected	Similar to `WebSocket.onclose`
ERROR_WS	An error occurred over websocket	Similar to `WebSocket.onerror`
FETCH_TOKEN_FAILED	Failed to fetch the fusion token
WEB_WORKER_FAILED	Worker is not supported in the current browser
CONNECT_CIP	Successfully connected to Control System over CIP protocol	Provides information about the current connection. Not the same as `CONNECT_WS`
DISCONNECT_CIP	Disconnected from the Control System over CIP protocol	Not the same as `DISCONNECT_WS`
AUTHENTICATION_FAILED	Failed to authenticate to the Control System
AUTHENTICATION_REQUIRED	Authentication token is required by the Control System
LICENSE_WS	A change occurred in the license (e.g. received license, license/trial period update)
NOT_AUTHORIZED	The `/cws/websocket/getWebSocketToken` endpoint response is a redirect

Listening to the `LICENSE_WS` event from a CH5 project

import WebXPanel, {WebXPanelEvents} from "@crestron/ch5-webxpanel";

WebXPanel.addEventListener(WebXPanelEvents.LICENSE_WS, ({detail}) => {
  const {
    resourceAvailable,
    controlSystemSupportsLicense,
    licenseApplied,
    licenseNotRequired,
    licenseHasExpiry,
    licenseDaysRemaining,
    trialPeriod,
    trialPeriodDaysRemaining,
    licenseNotRequired
  } = detail;

  // other callback code
});

Listening to the `NOT_AUTHORIZED` event from a CH5 project

  WebXPanel.addEventListener(WebXPanelEvents.NOT_AUTHORIZED, ({detail}) => {
    const {redirectTo} = detail;
    console.log(`Received a redirect to: ${redirectTo}`);
    
    // login on the redirectTo page then try authenticating
    WebXPanel.authenticate();
    // or refreshing the page
    window.reload();
  });

Listening to the `CONNECT_CIP` event from a CH5 project

  WebXPanel.addEventListener(WebXPanelEvents.CONNECT_CIP, ({detail}) => {
    const {url, ipId, roomId, tokenSource, tokenUrl} = detail;
    console.log(`Connected to ${{url, ipId, roomId, tokenSource, tokenUrl}}`);
  });

Listening to the `DISCONNECT_CIP` event from a CH5 project

  WebXPanel.addEventListener(WebXPanelEvents.DISCONNECT_CIP, ({detail}) => {
    const {reason} = detail;
    console.log(`Disconnected from CIP. Reason: ${reason}`);
  });