ARRIS Enterprises, Inc. Confidential Information

Migration Guide (TOI2→TOI3)

Some effort is required to migrate an existing portal from TOI2 to TOI3. This guide helps you through the major points. While migrating your portal, please keep an eye on the STB log for warnings related to deprecated functionality.

Initialization

TOI3 does not use an NPAPI plugin as in TOI2/JS. Instead, TOI3 uses web technologies for communication with the KreaTV platform. The protocol details are hidden from the application by a JavaScript wrapper API, which is very similar to the TOI2/JS "toi" object. See the bootstrapping page for more details.

Fundamentals

Using web technologies means that each individual function call to TOI3 involves an XmlHttpRequest to the KreaTV platform, so has more overhead than before, but that data structures returned from the platform are now JSON objects. These objects are processed much faster by the browser's JavaScript engine. To optimize on this fact, the APIs in TOI3 make it easier to request more data in one single call, and also provides needed data in notifications from the platform.

For example, the Information Service getObject() and setObject() functions have been replaced by set() and get(). These functions take and return arrays of objects. It is recommended that you batch your calls to Information Service with these functions when possible.

When subscribing to changes on Information Service configuration objects, the ToiInformationObjectsChangedEvent value contains the object you subscribed to. There is no longer a need to call getObject() as a second step to get the value.

In a similar way, when subscribed to changes in media player parameters, the ToiMediaPlayerParameterChangedEvent contains the name and value of the parameter that changed, eliminating a call to getParameter().

Net Service

ToiNetService has been redesigned in TOI3. The biggest change is the introduction of networks, you can read more about it here. While configuration in TOI2 was performed directly on a particular network device/interface, now configuration is performed indirectly by ToiNetService based on the network's settings.

The term interface is used in TOI3 to represent the network interface, not an IP address as it was in TOI2.

When getting the STB's IP address, the var.ip.eth0.addr configuration object is now deprecated. Instead, the IP address used for the boot network (the method the STB used to boot, ie Wi-Fi or ethernet) should be obtained with:

<sdk_root>/examples/example-html-portal/modules/settings/settings.js


// Get the STBs IP address(es)
function updateSTBInfoNetworkIPAddress() {
  var network = toi.netService.getNetwork(
    toi.consts.ToiNetService.BOOT_NETWORK);
  var networkInfo = network.getNetworkInfo();
  var interfaceInfo = networkInfo.interfaceInfo;

  var addressString = "";
  for (var i = 0; i < interfaceInfo.ipAddresses.length; i++) {
    addressString += interfaceInfo.ipAddresses[i].ipAddress;
  }

  framework.emit("NewNetworkIPAddress", addressString);
}

The MAC address is handled in a similar way. ToiNetService allows you to get the IP address, MAC address and other details of the non-active interfaces too.

ToiNetService also reduces and simplifies the number of events, and now also includes Wi-Fi related events.

Wi-Fi Connection

In TOI3 connecting to a Wi-Fi access point requires providing the required information to the service as follows:


var network = NetService.getNetwork(toi.consts.ToiNetService.BOOT_NETWORK);
  network.applySettings({}, {
   wifiSettings: { APINFO.. }
});

Please refer to the ToiNetService API documentation for more information.

Storage Service

The biggest change to the Storage Service is that there no longer is a distinction between internal and external storage. Now, the distinction is made between approved and non approved storage devices. Interfaces in ToiStorageDevice are no longer supported, and ToiStorageService has been extended with new calls to cover for that functionality. For more information about the Storage Service, please refer to here.

Prepare a DVR Storage

The ToiStorageService.prepareDvrStorage() call is introduced, replacing ToiStorageDevice.reformat() and ToiStorageDevice.setEnabledFeatures(). Use this call to prepare a storage device for DVR or Timeshift applications.

<sdk_root>/examples/example-html-portal/modules/storage/setup.js


function issuePrepareDvrStorage(that) {
  var callbacks = {
    onCompleted: function() {
      that.view.progress.setProgress(100);
      that.hidePrepareDvrStorageDialogue();
    },
    onError: function() {
      that.hidePrepareDvrStorageDialogue();
      console.error("Error: prepareDvrStorage failed");
    },
    onProgress: function(operation) {
      that.view.progress.setProgress(operation.progress);
    }
  };
  var device = getFirstStorageDevice();
  toi.storageService.prepareDvrStorage(callbacks, device.id);
}

Calling ToiStorageService.prepareDvrStorage() on a non-approved storage device erases all partitions, leaving a single partition that meets ARRIS requirements for DVR/Timeshift applications.

Unmount/Remove HDD

ToiStorageService.prepareForRemoval() replaces ToiStorageDevice.unMountPartition() for preparing a storage device for clean disconnection.


var callbacks = {
  onResult : function(operation, operationResult) {},
  onError : function(operation) {},
  onCompleted : function(operation) {},
  onProgress : function(operation) {}
};
toi.storageService.prepareForRemoval(callbacks, deviceId); // get deviceId from getDevices()

Please refer to the ToiStorageService API documentation for more information.

Media Player

The media player works much as before, but for efficiency purposes the close(), open() and play() functions are combined together into a single quickPlay(URL) function. There is also a quickPlayFromPosition().

The state machine for the Media Player has been simplified, please see the Media Service documentation.

Asynchronous operations

Asynchronous operations are handled in a way that is more familiar to JavaScript programmers than before. The new AsyncCallback mechanism allows you to pass an object containing callback functions which will be executed once the asynchronous operation completes. As an example:

<sdk_root>/examples/example-html-portal/modules/settings.js


function configureVideoOutput(config) {
  var session = toi.videoOutputService.createSession();
  session.configure(hdmiOutputId, config);
  session.apply({
    onCompleted: function() {
      ...
      session.releaseInstance();
    },
    onError: function() {
      ...
      session.releaseInstance();
    },
    onProgress: function() {
      ...
    },
    onResult: function() {
      ...
      session.releaseInstance();
    }});
}

This is used when scanning for Wi-Fi networks and when applying video configuration changes (shown above).

Video Output Service

The VideoOutput service has had a major overhaul. The new interface shares the philosophy of the old one (session based with incremental configuration steps), but tries to approach output configuration in a modern and more consistent way. Focus has been to improve the ergonomics of the JavaScript interface. The most noticeable change is that you do all output configuration using one method called configure(). Instead of doing


session.setDefaultVideoMode(outputId, VIDEO_MODE_720P50);
session.setColorSpace(outputId, COLOR_SPACE_SRGB);

you do


session.configure(outputId, { mode: VIDEO_MODE_720P50,
                              colorSpace: COLOR_SPACE_SRGB });

or equivalently


session.configure(outputId, { mode: VIDEO_MODE_720P50 });
session.configure(outputId, { colorSpace: COLOR_SPACE_SRGB });

in sequence.

Valid settings

The information about valid settings in the old ToiVideoOutputConfigurationVideoOutputInfo and ToiVideoOutputConfigurationVideoOutputCapabilityInfo (like ToiVideoOutputConfigurationVideoOutputInfo.allowedVideoModes and ToiVideoOutputConfigurationVideoOutputCapabilityInfo.videoModes) are merged and made available in the different ToiVideoOutputInfo members. Here a "supported" prefix indicates that the member contains a lists of all settings supported by the hardware, "configurable" a lists of all settings available using the current configuration and "allowed" all settings available using the current configuration plus the restrictions imposed by the display (where applicable).

Display overrides

The feature of adding exceptions or overrides for HDMI displays with a broken EDID (using setDisplayInfo()) has been removed. Instead you can instruct the interface to ignore all restrictions imposed by the display. This is done using the ignoreDisplayCapabilities attribute.


// Scenario: The connected display signals (using the EDID) that it
// doesn't support 'VIDEO_MODE_720P50' (i.e. the mode is not in
// 'allowedModes'), but we know it does and we want to ignore it.
session.configure(outputId, { mode: VIDEO_MODE_720P50,
                              ignoreDisplayCapabilities: true });

More information about the service and the interface can be found in here: Video Output Service

Content Service

Asset Manager Service is no longer supported and its functionality has been replaced with the new Content Service. The Content Service allows applications to search for and modify content from multiple content sources in a unified way. Content Service interface works in an asynchronous manner, and is implemented using asynchronous operations.

Content IDs

The Content Service identifies each piece of content with a unique Content ID. Thus ToiMediaRecoder.open() has been changed to accept content ID as argument, and ToiMediaRecoderBase.getContentId() has been added for obtaining the content ID for a recorder instance.

Searching for content

The following example shows how a simple search for content can be performed using the new interface. The search will only include content where the title includes the string "movie".


var callbacks = {
  onCompleted: function(operation) {
    for (var content in operation.result) {
      console.log("Content found with ID: " + operation.result[content].id);
    }
  },
  onError: function() {
    console.error("Error: search failed");
  }
};

var searchParameters = {
  contentConditions: { "title": { like: "movie" } }
};

toi.contentService.search(callbacks, searchParameters);

Platform Service

Functions related to components have been removed.

Statics

The TOI2/JS concept of statics has been removed, and instead you can now write JSON objects directly. For example, when connecting to a Wi-Fi network and calling ToiNetwork.applySettings() a ToiSettings object is required:

<sdk_root>/examples/example-html-portal/modules/wifi/setup.js


this.network.applySettings({}, {
  wifiSettings: {
    ssid: apInfo.ssid,
    presharedKey: password
  },
  deviceSelection: toi.consts.ToiNetwork.DEVICE_SELECTION_WIFI
});

Exceptions

Exception handling is now more aligned with standard JavaScript paradigms. See here for more details on exceptions.

Detailed comparison

The following table lists the changes between TOI2/JS and TOI3 where possible. An exhaustive changelog is also provided.

TOI2/JS	TOI3
ToiApplicationService
`activate()`, `activateWithUri()`, `activateWithCommand()`, `deactivate()`, `getApplicationIds()`, `loadUri()`	Removed.
`kill()`	`ToiPrimaryApplication.stop()`
`getOwnApplicationId()`	`ToiPrimaryApplication.getName()`
`getBoolProperty()`, `getIntProperty()`, `getStringProperty()`, `getStringSequenceProperty()`	`ToiPrimaryApplication.getProperties()`
`getInfo()`	Use above `getName()` and `getProperties()` instead
ToiAssetManagerService
`getAssetStorages()`	`ToiContentService.getSources()`
`getProperties()`	`ToiContentService.getContent()`
`removeAsset()`	`ToiContentService.remove()`
`removeProperties()`	`ToiContentService.removeProperties()`
`runQuery()`	`ToiContentService.search()`
`setProperties()`	`ToiContentService.setProperties()`
`ON_ASSET_STORAGE_ADDED`	`ToiContentService.ON_SOURCE_AVAILABLE`
`ON_ASSET_STORAGE_REMOVED`	`ToiContentService.ON_SOURCE_UNAVAILABLE`
`getDefinedProperties()`	Use `ToiContentSource.getInfo` or `ToiContentService.getSources()` and read `supportedContentProperties` from `ToiContentService.ToiSourceInfo.queryCapabilities`.
`ON_ASSETS_ADDED`	`ToiContentSource.ON_CONTENT_ADDED`
`ON_ASSETS_CHANGED`	`ToiContentSource.ON_CONTENT_CHANGED`
`ON_ASSETS_REMOVED`	`ToiContentSource.ON_CONTENT_REMOVED`
`copyAsset()`	`ToiRecordedContentSource.copy()`
`createAsset()`	`ToiRecordedContentSource.create()`
`createDirectory()`, `moveDirectory()`, `setDirectoryProperties()`, `removeDirectoryProperties()`, `removeDirectory()`, `getDirectoryInfo()`, `getDirectories()`, `getPropertyDefinition()`, `createPropertyDefinition()`, `removePropertyDefinition()`, `createAssetFromProperties()`, `importAsset()`, `linkAssets()`, `unlinkAssets()`, `runQueryForDirectory()`, `runCountQuery()`, `getAllProperties()`, `removeMultiValuedPropertyValue()`	Removed.
`ON_DIRECTORIES_ADDED`, `ON_DIRECTORIES_CHANGED`, `ON_DIRECTORIES_REMOVED`	Removed.
ToiAudioOutputConfigurationSession
	Application must call `releaseInstance()` explicitly.
ToiDrmService
`getCurrentOutputControl()`	Removed.
`ON_CCI_CHANGED`	Removed.
ToiHdmiService
`getHdmiSinkInfo()`	`getSinkInfo()`
`HDMI_CONNECTION_STATUS_UNKNOWN`	`CONNECTION_STATUS_UNKNOWN`
`HDMI_CONNECTION_STATUS_CONNECTED`	`CONNECTION_STATUS_CONNECTED`
`HDMI_CONNECTION_STATUS_CONNECTED_CAPABILITIES_UNKNOWN`	`CONNECTION_STATUS_CONNECTED_CAPABILITIES_UNKNOWN`
`HDMI_CONNECTION_STATUS_DISCONNECTED`	`CONNECTION_STATUS_DISCONNECTED`
`ON_HDMI_CONNECTION_STATUS_CHANGED`	`ON_CONNECTION_STATUS_CHANGED`
	`ON_HDCP_STATUS_CHANGED`
ToiInformationService
`getObject()`, `getObjects()`	`get(names)`
`setObject()`, `setObjects()`	`set(objects, type)`
`unsetObject()`, `unsetObjects()`	`unset(names, type)`

ToiMediaService
`createPipPlayerInstance()`, `createProducerInstance()`, `createConsumerInstance()`, `enumerateProducers()`, `cancelTask()`	Not yet supported.
`ON_PRODUCER_STATUS_CHANGED`	Not yet supported.
ToiMediaPlayer
	`quickPlay()`, `quickPlayFromPosition(position)`
`setParameter()`, `unsetParameter()`	`setParameters(parameters)`, `unsetParameters(names)`
ToiMediaRecorder
`open(url, assetId)`	`open(url, contentId)`. Takes a content ID instead of an asset ID as argument.
ToiMediaRecorderBase
`getAssetId()`	`getContentId()`
ToiNetService
ToiNetService has been mostly rewritten. We recommend you consult the Net Service page and the ToiNetService API documentation.
ToiPlatformService
`rebootNow()`, `rebootAtNextStandby()`	`reboot(rebootType)`
`setStandby()`	Removed.
	Use Power Management Service
`getComponentsInfo()`, `getComponentInfo()`, `registerComponentUsage()`, `releaseComponentUsage()`	Removed.
ToiStorageDevice
`getStorageInfo()`, `getPartitionInfo()`	`ToiStorageService.getDevices()`
`mountPartition()`	Removed. Handled automatically.
`unmountPartition()`	`ToiStorageService.prepareForRemoval(callbacks, deviceId)`
`runPerformanceCheck()`, `getPropertyResult()`	Removed.
`setEnabledFeatures()`	`ToiStorageService.prepareDvrStorage(callbacks, deviceId)`
`reformat()`	`ToiStorageService.prepareDvrStorage(callbacks, deviceId)`
`scheduleReformatOnNextReboot()`	`ToiStorageService.prepareDvrStorage(callbacks, deviceId)`
`scheduleFileSystemRepairOnNextReboot()`	`ToiStorageService.repair(callbacks, deviceId)`
ToiStorageFile
	Removed.
ToiStorageService
`getStorageDeviceIds()`, `getStorageDevice()`	`getDevices()`
`createFile()`, `copy()`, `move()`	Removed.
`ON_DEVICE_PARTITIONS_CHANGED`, `ON_DEVICE_PARTITION_MOUNT_CHANGED`, `ON_DEVICE_PARTITION_FEATURES_CHANGED`, `ON_DEVICE_HEALTH_CHANGED`	Removed.
`ON_DEVICE_CONNECTED`	`ON_DEVICE_ADDED`
`ON_DEVICE_DISCONNECTED`	`ON_DEVICE_REMOVED`
`ON_DEVICE_TEMPERATURE_THRESHOLD_REACHED`	`ON_DEVICE_TEMPERATURE_REACHED`
`ON_DEVICE_PARTITION_FULL`	`ON_DEVICE_FULL`
	`ON_DEVICE_STATE_CHANGED`
ToiVideoOutputService
ToiVideoOutputService has received extensive changes. We recommend you consult the Video Output Service page and the actual ToiVideoOutputService API documentation for more details. The example portal also shows some basic usage of this redesigned interface.

Unavailable services

The following services are not yet available:

Service name	Status
Channel Service	Not yet available.
Diagnostics Service	Not yet available.
Dlna Content Directory Service	Not yet available.
Dlna Service	Not yet available.
Dvb Eit Service	Not yet available.
Frontend Service	Not yet available.
Front Panel Service	Removed. Functionality moved to a config file instead.
Operation Manager	Removed. See AsyncCallback for new replacement.
Resource Service	Not yet available.