======================================================================
DUNE HD STB -- VERIMATRIX DRM SUPPORT
======================================================================

Verimatrix IPTV client
======================

There are several possible ways to configure Verimatrix IPTV client:
   * Global configuration (can be used in all cases).
   * Per-plugin configuration (can be used by applications implemented as
     Dune plugins).
   * In runtime using Dune STB API (can be used by applications based on
     Native GUI SDK).

Verimatrix IPTV client -- Global configuration
----------------------------------------------

In this case Verimatrix IPTV is enabled for playback of all media_urls of
supported types.

Supported media_url types:
   * Multicast UDP/TS.
   * RTSP/TS.

See http://files.dune-hd.com/partners/sdk/media_url.txt for details about
media_urls and their syntax.

How to configure:
   * Enable telnet acccess to the player (see
     http://files.dune-hd.com/partners/sdk/dune_devel_info.txt for
     details).
   * Put Verimatrix configuration file VERIMATRIX.INI to
     /config/verimatrix/VERIMATRIX.INI (see note below).
   * Put Verimatrix root certificate file rootcert.pem to
     /config/verimatrix/rootcert.pem (see note below).
   * Ensure "ROOTCERT" parameter in VERIMATRIX.INI contains full path to
     /config/verimatrix/rootcert.pem (see note below).
   * Perform "sync" command.
   * Reboot the player.

How to test:
   * Assumption: encrypted stream is sent via multicast
     {multicast-address}:{port}.
   * Put "udp://@{multicast-address}:{port}" URL into .m3u file.
   * "Launch" the .m3u file in the player's GUI (i.e. choose the file, and
     press "ENTER" RC button).

When creating a custom firmware, /firmware/config/verimatrix/ directory
(part of the custom firmware image) can be be used instead of
/config/verimatrix/. 

Note: only SERVERADDRESS, SERVERPORT, ERRORLEVEL, TIMEOUT,
CONNECTION_RETRIES, ENABLE_IPV6, STOREPATH are processed from the
VERIMATRIX.INI, other parameters in the INI file and the root certificate
file itself are ignored in firmware versions that implement Verimatrix IPTV
protocol version 3 - INI file and root certificate from VCAS server are
used.

Verimatrix IPTV client -- Per-plugin configuration
--------------------------------------------------

In this case, Verimatrix IPTV is enabled only for playback of specified
media_urls provided by the plugin.

See http://files.dune-hd.com/partners/sdk/sdk.txt, section "Plugins
mechanism" for details about plugins.

Besides of PHP plugins, this possibility can be also used in HTML
application using Dune HD STB JS API and in Native GUI application using
Dune HD STB C API, if such application is a part of plugin.

Supported media_url types:
   - Multicast UDP/TS.
   - HTTP/TS.
   - RTSP/TS.

See http://files.dune-hd.com/partners/sdk/media_url.txt for details about
media_urls and their syntax.

How to configure:
   * Add the following "drm_defs" declaration into plugin's dune_plugin.xml
     file:
        <dune_plugin>
        ...
           <drm_defs>
              <drm_def>
                 <id>{drm-id}</id>
                 <type>verimatrix</type>
                 <params/>
              </drm_def>
           </drm_defs>
         ...
         </dune_plugin>
   * Put Verimatrix configuration file VERIMATRIX.INI to
     {drm-id}_verimatrix.ini file in root directory of the plugin (note
     {drm-id} in the file name, it should be equal to {drm-id} from the
     drm_def declaration in dune_plugin.xml). See note below.
   * Put Verimatrix root certificate file rootcert.pem to
     {drm-id}_rootcert.pem file in root directory of the plugin (note
     {drm-id} in the file name, it should be equal to {drm-id} from the
     drm_def declaration in dune_plugin.xml). See note below.
   * Verimatrix IPTV is enabled for playback of the following media_urls
     provided by the plugin:
     drm://{plugin-name}/{drm-id}/{actual-playback-media-url}.
      * Here: {plugin-name} is a name of the plugin as specified in the
        "name" element in dune_plugin.xml, {drm-id} is an identifier
        specified in the drm_def declaration in dune_plugin.xml.

How to test:
   * Assumption: encrypted stream is sent via multicast
     {multicast-address}:{port}.
   * Implement the plugin in such a way that it provides the following
     media_url as a playback URL for some TV channel:
     drm://{plugin-name}/{drm-id}/udp://@{multicast-address}:{port}"
   * Enter into the plugin in player's GUI, start playing this TV channel.

Note: only SERVERADDRESS, SERVERPORT, ERRORLEVEL, TIMEOUT,
CONNECTION_RETRIES, ENABLE_IPV6, STOREPATH are processed from the
VERIMATRIX.INI, other parameters in the INI file and the root certificate
file itself are ignored in firmware versions that implement Verimatrix IPTV
protocol version 3 - INI file and root certificate from VCAS server are
used.

Verimatrix IPTV client -- Configuration via Dune STB API
--------------------------------------------------------

In this case, an application based on Dune Native SDK can apply the
required configuration in runtime using Dune STB API.

Please see setVMIptv* operations in Dune STB API documentation.

Verimatrix IPTV client -- Log files
-----------------------------------

Logs from Verimatrix IPTV client are put into /tmp/run/shell.log file. Log
file configuration in VERIMATRIX.INI file (if any), is ignored.

Verimatrix Web client
=====================

There are several possible ways to configure Verimatrix IPTV client:
   * Global configuration (can be used in all cases).
   * Per-plugin configuration (can be used by PHP plugins).
   * In runtime using Dune STB API (can be used by applications based on
     Native GUI SDK).

In all cases, Verimatrix Web is supported for media_urls of the following
types:
   * Apple HLS.

See http://files.dune-hd.com/partners/sdk/media_url.txt for details about
media_urls and their syntax.

Verimatrix Web client -- Global configuration
---------------------------------------------

In this case Verimatrix Web is enabled for playback of all media_urls of
supported types.

How to configure:
   * Enable telnet acccess to the player (see
     http://files.dune-hd.com/partners/sdk/dune_devel_info.txt for
     details).
   * Write single character '1' to /config/verimatrix/hls_verimatrix_web
     file.
   * Perform "sync" command.
   * Reboot the player.

How to test:
   * Assumption: encrypted stream is sent via HLS
     http://{host}:{port}/{path}.m3u8.
   * Put "http://{host}:{port}/{path}.m3u8" URL into .m3u file.
   * "Launch" the .m3u file in the player's GUI (i.e. choose the file, and
     press "ENTER" RC button).

When creating a custom firmware, /firmware/config/verimatrix/ directory
(part of the custom firmware image) can be be used instead of
/config/verimatrix/. 

Verimatrix Web client -- Per-plugin configuration
-------------------------------------------------

In this case, Verimatrix Web is enabled only for playback of specified
media_urls provided by the plugin.

See http://files.dune-hd.com/partners/sdk/sdk.txt, section "Plugins
mechanism" for details about plugins.

Besides of PHP plugins, this possibility can be also used in HTML
application using Dune HD STB JS API and in Native GUI application using
Dune HD STB C API, if such application is a part of plugin.

How to configure:
   * Add the following "drm_defs" declaration into plugin's dune_plugin.xml
     file:
        <dune_plugin>
        ...
           <drm_defs>
              <drm_def>
                 <id>{drm-id}</id>
                 <type>verimatrix_web</type>
                 <params/>
              </drm_def>
           </drm_defs>
         ...
         </dune_plugin>
   * Verimatrix Web is enabled for playback of the following media_urls
     provided by the plugin:
     drm://{plugin-name}/{drm-id}/{actual-playback-media-url}.
      * Here: {plugin-name} is a name of the plugin as specified in the
        "name" element in dune_plugin.xml, {drm-id} is an identifier
        specified in the drm_def declaration in dune_plugin.xml.

How to test:
   * Assumption: encrypted stream is sent via HLS
     http://{host}:{port}/{path}.m3u8.
   * Implement the plugin in such a way that it provides the following
     media_url as a playback URL for some TV channel:
     drm://{plugin-name}/{drm-id}/http://{host}:{port}/{path}.m3u8"
   * Enter into the plugin in player's GUI, start playing this TV channel.

Verimatrix Web client -- Configuration via Dune STB API
-------------------------------------------------------

In this case, an application based on Dune Native SDK can apply the
required configuration in runtime using Dune STB API.

Please see setVMWeb* operations in Dune STB API documentation.

Verimatrix Web client -- Configuring additional parameters
----------------------------------------------------------

Verimatrix Web client can be additionally configured to use specific values
of "boot address" and "company name" parameters, when it is required.

When using global configuration:
   Besides of the file
      [/firmware]/config/verimatrix/hls_verimatrix_web
   create also the file
      [/firmware]/config/verimatrix/hls_verimatrix_web.properties
   and put the required parameters into it:
      boot_address = ...
      company_name = ...

When using Dune STB API:
   See the following API operations (currently available only via Dune STB
   C API, but not via Dune STB JS API):
      dunestbapi_setVMWebBootAddress
      dunestbapi_setVMWebCompanyName

In other cases, when it is required to enable/disable Verimatrix Web client
and configure its parameters dynamically:
   Use /tmp/verimatrix directory instead of /config/verimatrix directory.

Mixing encrypted and non-encrypted streams
==========================================

In all cases, if Verimatrix DRM processing is enabled for a particular
media_url, the system automatically recognize whether the stream is
actually encrypted or not. If the stream is not encrypted, it is processed
in the usual way (w/o decryption). In most cases, this automatic processing
has no or very little impact on the overall system performane. So, in most
cases,it is safe to mix encrypted and non-encrypted streams and do not worry about
enabling Verimatrix DRM for encrypted streams only.

Firmware version
================

Depending on the used Dune HD STB model, it may be needed to ensure that
the firmware version with the support of Verimatrix DRM is installed on the
STB, and install such a version if it is not installed yet.

All "SDK" firmware versions, in particular the following ones, include such
a support:
* Firmware specified in the http://files.dune-hd.com/partners/sdk/sdk.txt
  document, section "JS STB SDK".
* Firmware specified in the http://files.dune-hd.com/partners/sdk/sdk.txt
  document, section "Native GUI STB SDK".