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}`);
  });

Test

# NPM
npm test

Build

# NPM
npm build