Bureaucrats, editor
1,487
edits
Changes
Jump to navigation
Jump to search
Commands: Functional Specification Openplat1.2 (view source)
Revision as of 12:14, 30 April 2020
, 12:14, 30 April 2020Created page with "=== Commands === Commands will enable TV Open Platform operators to send orders toward selected STBs, ordering them to execute an action from a pre-defined command set. They w..."
=== Commands ===
Commands will enable TV Open Platform operators to send orders toward selected STBs, ordering them to execute an action from a pre-defined command set. They will be a powerful tool for operation and troubleshooting teams.
The following are general requirements that apply to all commands supported by TV Open Platform. In next subsections we provide a description of the logic that must be implemented by each command and its specific parameters.
==== Generic requirements ====
These requirements are described with more detail at the following US:[https://jira.tid.es/browse/OPENPLAT-349 OPENPLAT-349] (Message Manager multi-OB support), [https://jira.tid.es/browse/OPENPLAT-312 OPENPLAT-312] (Message Manager validations), [https://jira.tid.es/browse/OPENPLAT-313 OPENPLAT-313], [https://jira.tid.es/browse/OPENPLAT-457 OPENPLAT-457] (Data transformation through TV Open Platform Enablers components) and [https://jira.tid.es/browse/OPENPLAT-342 OPENPLAT-342] (Command Cancellation).
# Message Manager must support sending toward OpenIPTV STBs the set of commands specified in this [https://docs.google.com/spreadsheets/d/1fcrSNz5TC8DvuRKafJK8NxUlLvNPFxeQggr7_2uy32I/edit#gid=1032626120 xls] sheet (Commands tab).
# OB operators must be able to send commands toward OpenIPTV STBs from the following UIs:
#* E2E diagnosis tool (for CAT operators). Commands will be sent toward Message Manager through GVP DataHub (QoS).
#* QoS - Mariner (for local operation teams). Commands will be sent toward Message Manager through GVP DataHub (QoS).
#* GAL BSS component, for a limited set of commands which are currently published in UNICA API toward the OSS/BSS: ResetPin and ResetDevice, plus ReloadAccountStatus which will be used when the status of an account is changed in the OSS/BSS. GAL BSS is able to send these commands to unique STBs identified through their GUID.
# Each possible origin of commands (GVP DataHuB, MiB, GAL BSS) must identify itself, when creating the request toward TV Open Platform, using a unique SourceID so that the rest of the components involved (Message Manager, STB, DataHub) are able to track from which component the request came and process it accordingly. SourceID will be a single character, excluding special characters.
# When creating a command, all the sources will be able to configure a start and end time for the command (in UTC ISO-8601).
#: Most requests coming from DataHub or GAL-BSS will be targeted to a specific STB and must be executed immediately. However, there are situations in which engineering teams might want to send a command to multiple STBs (eg. to regularize a local variable in the STBs). For these scenarios it might be useful to have an extended end time so that multiple STBs in the platform have time to receive and execute it.
# When creating the request toward Message Manager all sources must inform about the instance (OB) for which the command is configured. This will determine which InfoPush/Sprayer servers are to be used to deliver it.
# When creating the request toward Message Manager, all sources must generate a commandID which must be unique throughout the system. This ID will be used to track this specific command through all the components involved. The commandID will be an alphanumeric string of exactly 24 characters, excluding special characters, with zeros to the left.
# Message manager will return an error if any component tries to create two commands with the same commandID for the same instance and from the same component.
# Message Manager will support sending a command to two different device types (OpenIPTV and Hybrid) with the following limitation:
#* If an operator tries to send a command to an Hybrid STB and the delivery mechanism calculated by Message Manager is InfoPush, an error will be returned (InfoPush is not supported for Hybrid STBs).
#* If an operator tries to send a command to OpenIPTV and Hybrid STBs simultaneously and the delivery mechanisms calculated by Message Manager is InfoPush, the response will be OK '''but''' no Hybrid STB will receive the command.
# Once a command is sent toward Message Manager it won’t be possible to modify it.
# All commands must register, in GVP DataHub, the result of its execution through a BI event. Common data to be registered for all commands are the SourceID, STB ID, command type, command ID, success/error code and time (timestamp when the event happened at the STB; fixed-size;string with ISO 8601 datetime format, with precision up to miliseconds - if available - and time zone information as UTC offset) when the command was executed.
# For commands sent from GVP DataHub it is necessary to receive feedback, in real time, about the command execution. For commands sent from other modules it is not necessary to know their execution result in real time.
#: As a consequence, it must be possible to configure, in the request sent toward Message Manager, whether the result of the command execution is to be stored in the BI event queue in the STB (and uploaded to the GVP DataHub following the usual BI event management process) or if it must be sent immediately toward the GVP DataHub.
# It must be possible to '''cancel''' a command once it is sent. In this scenario:
#* All the STBs that have already executed the command won’t execute it again.
#* All the STBs that are executing the command will finish its execution.
#* STBs that are in stand-by mode and have read the command from Sprayer/InfoPush will execute it (see [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Commands_behavior_depending_on_the_STB.27s_status this section]).
#* STBs that are off won’t execute the command if they are turned on.
# When creating the request toward Message Manager, all parameters must be encoded in '''Form Data'''.
==== MIB BE Tools UI Requirements ====
The tool to manage IPTV Service will be TV QoS Tool; MiB BE Tools will be left to manage commercial offering exclusively. Therefore it is not necessary to provide, in MiB BE Tools, mechanisms to send commands toward OpenIPTV STBs.
MiB currently supports resetting PIN (parental, rental) for OTT devices. This operation is not synchronized with Mediaroom STBs. Operation and engineering teams have requested GVP development team to keep this behavior for OpenIPTV STBs. Pin reset for OpenIPTV STBs can be requested from OSS/BSS (through UNICA API) and TV QoS Tool only.
==== MIB GAL BSS Requirements ====
# MiB must support sending reset device requests from the OSS/BSS toward OpenIPTV STBs. When MiB receives a restartRequest from UNICA API, it must forward the request toward Message Manager. An OK response from Message Manager doesn't imply that the device has been restarted; it will just mean that the request has been forwarded successfully.
# MiB must support sending reset pin requests from the OSS/BSS toward OpenIPTV STBs.
## When MiB receives a rememberPasswordRequest from UNICA API, it must forward the request toward Message Manager.
## rememberPasswordRequests in UNICA API are sent for an account. MiB must obtain the list of active OpenIPTV STBs for the account and send this list in the request toward Message Manager.
## An OK response from Message Manager doesn't imply that the PINs have been reset successfully in all the STBs; it will just mean that the request has been forwarded successfully.
==== [[TVOpen Message Manager API Command - Client Software Upgrade|Client Software Upgrade]] ====
''Command name'': client_software_upgrade
''Command-specific entry parameters'':
* version: information about the client software versions per STB model to be downloaded. Every version must included in token [[OPCHToken_ClientCDNURL|ClientCDNURL]], into fw_list, to find bootcast-id xml file to download binary file. If this value is empty, it means that the STB must download the software version available in OPCH. Optional.
* custom_spread_time: time value (in seconds) that STBs will use to randomly spread in time their download requests. If this value is empty, ClientUpgradeSpreadTime global value configured in OPCH will be used. Optional.
''Command-specific parameters sent to GVP DataHub'': This information depends on the results of the upgrade command.
* In case an upgrade/downgrade of client version is done, no data is sent to DataHub
* In case there is no need to change the client version, in the CMD/* event sent to DataHub the STB will inform about this situation.
* In case an error occurs during the upgrade, in the CMD/* event sent to DataHub the STB will inform about the error.
''Supported targets'': it must be possible to send this command to one STB or to a list of STBs
''Description'': This command triggers the upgrade of the software version running in the STB to the one specified as an entry parameter in the request.
* If the version is included into fw_list field of token [[OPCHToken_ClientCDNURL|ClientCDNURL]] and it's a different version than current in flash, STB will invalidate current flashed client, it will change boot mode to 7363 (download by HTTP) and will program an automatic reboot to allow bootloader to perform the update.
* If the version is not included into fw_list, this command will have no effect.
* If no software version is specified or it is then the STB must download the software version available in OPCH. STB will change boot mode to 7313 (download by OPCH) and will program an automatic reboot to allow bootloader to perform the update.
Detailed description of the upgrade process is to be found in [[TVOpen_STB_Boot_and_Configurations#Functional_requirements._Software_upgrade | STB Boot and Configurations]].
==== [[TVOpen Message Manager API Command - Update Audio for Live Channel|Update Audio for Live Channel]] ====
''Command name'': update_audio_for_live_channel
''Command-specific entry parameters'':
* channel_id: ID of the channel on which to force a specific audio language. Mandatory.
* audio language in ISO 639-1 format. If this value is empty, this channel will return to its default audio language, specified in a local configuration variable; if this local configuration variable doesn’t exist then [[OPCHToken_DefaultAudioLanguage|DefaultAudioLanguage]] will be used. Optional.
''Command-specific parameters sent to GVP DataHub'':
* Audio language established for the channel.
* ChannelID which audio language has been changed.
''Supported targets'': it must be possible to send this command to one STB.
''Description'': This command changes the configuration of the STB enforcing a certain audio language for a certain channel. It overwrites the configuration that might have been eventually set by the end user in the STBs UI. This configuration is stored in /tmp/ChannelSettings.ini internal file, so it is stored in volatile memory and it will be lost in every STB reboot.<br>
Message Manager won’t validate that the channel_id corresponds to a valid id configured in the instance; it is the responsibility of the source of the command to perform this validation.
==== [[TVOpen Message Manager API Command - Update Variable|Update Variable]] ====
''Command name'': update_variable
''Command-specific entry parameters'':
* variable: name of the STB’s local variable to be modified. Mandatory. List of available variables can be found '''[[TVOpen Message Manager - List of Variables|here]]'''.
* scope: remote, local. Mandatory.
* value: new value to be assigned to the variable. Optional.
''Command-specific parameters sent to GVP DataHub'':
* Name of the variable modified.
* Value established for the variable.
''Supported targets'': it must be possible to send this command to one STB or to a list of STBs.
''Description'': This command enables external applications to manage variables in the STB. With a single command it is possible to create, update and/or remove a variable from the STB.
* In case the variable already exists and a value is configured, then the local variable must be updated in the STB. This parameter configuration covers the “modify value” scenario.
* In case the variable already exists and the value configured in the command is left empty, then the local variable must be removed from the STB. In this scenario, when a local variable is removed from the STB, the STB will apply the remote value when available, given the precedence rules defined in [[TVOpen_STB_Boot_and_Configurations#Functional_requirements._Configuration_management| STB Boot and Configurations]]. This parameter configuration covers the “remove variable” scenario.
* In case the variable name specified in the command doesn’t exist, a new local variable must be created with the name specified by the command and its value must be set to the one configured in the command. In this scenario both variable and value must be specified. This parameter configuration covers the “create variable” scenario.
* Message Manager won’t validate that the variable is supported in the system. It is the responsibility of the source of the command to ensure to be managing a supported variable in the OpenIPTV STB. This way we are able to manage new variables that might eventually be added to the STB without having to generate a new version of this component.
==== [[TVOpen Message Manager API Command - Get Variable|Get Variable]] ====
''Command name'': get_variable
''Command-specific entry parameters'':
* variable: name of the STB’s local variable to be retrieved; All. Mandatory. List of available variables can be found '''[[TVOpen Message Manager - List of Variables|here]]'''.
* scope: Remote, Local. Mandatory.
''Command-specific parameters sent to GVP DataHub'':
* List of comma-separated values (name - value - scope).
''Supported targets'': it must be possible to send this command to one STB or to a list of STBs.
''Description'': This command enables TV Open Platform operators to retrieve the values of different variables existing in the STB. It is flexible to enable operators get the value of a single variable under study, or all the variables in the STB. It also enables operators to retrieve the variable’s value for different scopes, getting an snapshot of the STB’s current configuration (which might be useful for troubleshooting). '''Remote''' scope will return variable values contained in the STB file '''/flash/var/OpenSTB/DefaultSettings.ini''' and '''Local''' scope will return variable values contained in the STB file '''/flash/var/OpenSTB/CurrentSettings.ini'''.
<br>Message Manager won’t validate that the variable is supported in the system. It is the responsibility of the source of the command to ensure to be managing a supported variable in the OpenIPTV STB. This way we are able to manage new variables that might eventually be added to the STB without having to generate a new version of this component.
<blockquote style="background:FloralWhite; padding:1em; border:1px solid #999; font-style: italic;">
Pendiente de analizar mecanismos de securización para esta comunicación, ya que puede ser que se envíe información sensible del usuario (p.ej. los valores de los PINes). Para IPTV puede no ser un requisite fuerte por tratarse de una red gestionada, pero para otro tipo de STBs (ej. hybrid) sí.
</blockquote>
==== [[TVOpen Message Manager API Command - Reset Device|Reset Device]] ====
''Command name'': reset_device
''Command-specific entry parameters'': None
''Command-specific parameters sent to GVP DataHub'': None
''Supported targets'': it must be possible to send this command to one STB only.
''Description'':This command allows resetting a specific STB. Detailed description of the reset process is to be found in [[TVOpen_STB_Boot_and_Configurations#Functional_requirements._STB_normal_reset|STB Boot and Configurations]] and [[STB_boot_sequence|STB boot sequence]].
==== [[TVOpen Message Manager API Command - Channel Tune|Channel Tune]] ====
''Command name'': channel_tune.
''Command-specific entry parameters'':
* channel_id: ID of the channel to be tuned.
''Command-specific parameters sent to GVP DataHub'':
* Channel id effectively tuned by the STB after the command execution.
''Supported targets'': it must be possible to send this command to one STB only.
''Description'': This command forces a STB to tune a specific channel. The channel can be specified either by its id. If the channel specified doesn’t exist in the channel map or if the end user doesn’t have playback grants then the command must return and error, and the UI will remain unchanged.
Message Manager won’t validate that the channel_id corresponds to a valid id configured in the instance; it is the responsibility of the source of the command to perform this validation.
==== [[TVOpen Message Manager API Command - Open UI State|Open UI State]] ====
''Command name'': open_ui_state
''Command-specific entry parameters'':
* ui_state: UI state to be loaded by the STB. Mandatory.
* parameter: depends on the state selected (e.g. VoD asset number, category number, interactive app URL, etc). Optional.
''Command-specific parameters sent to GVP DataHub'':
* ui_state and parameter effectively loaded by the STB.
''Supported targets'': it must be possible to send this command to one STB only.
''Description'': This command forces a STB to load a UI state; the page might be an internal page in the STB (list of supported pages to be provided by the STB development team) or a third party application.
<br>Message Manager won’t validate that the ui_state corresponds to a page for which direct launch is supported; it is the responsibility of the source of the command to perform this validation. This way we can decouple this component from the STB evolution and order the opening of new ui states without generating a new version of the Message Manager. Additionally, Message Manager won't perform any validations on parameters; all of them are optional and it is the responsibility of the source of the command to provide them if necessary.
''Available values for ui_state'':
{| class="wikitable"
! UI State !! Description !! Parameter
|-
| WELCOME_STATE || Open Welcome Home page with focus on TV window || N/A
|-
| ACCOUNT_STATE || Open My Account section (former ''Settings'' section) with focus on first left side item (Subscriptions), and its content loaded on right side || MenuIndex: Integer value indicating the left menu index (starting at 0) to be opened. The section this menu item corresponds to is determined by the content in the OPCH token [https://wikis.tid.es/gvp-dev/index.php/OPCHToken_SettingsMenuLayout OPCHToken_SettingsMenuLayout].
|-
| MINIGUIDE_STATE || Open miniguide view with current program and channel selected || N/A
|-
| GUIDE_STATE || Open full guide (Grid view) with current program and channel selected || channelId: MiB ID of the channel that will be focused after navigating to full guide page.
|-
| ONNOWGUIDE_STATE || Open On Now Guide view with current program and channel selected || N/A
|-
| INFO_STATE || Open Information page for LIVE and VOD contents || contentId: ID of the content
|-
| CONTENT_TREE_STATE || Open Content Areas (Tematic Areas, Providers, Rentals, Recommendations) with default focus as defined in the UI || vodCategory: Identifies the MiB channel that contains the content to be shown.
|-
| ISERVICES_STATE || Open Applications main board or load external Third Party applications || applicationUrl: URL for QML application. <br>To open a specific application url, parameter should be sent without ''<nowiki>http://</nowiki>'' prefix (ex. files.paytvlabs.com.br/snake/snake.qml). <br>To open the container, just omit the applicationUrl parameter.
|-
| SEARCH_STATE || Open Search page || N/A
|-
| MYCONTENT_STATE || Open My Content section || MenuIndex: Integer value indicating the left menu index (starting at 0) to be opened. Current supported options are:<br>0: My Rented<br>1: My List<br>2: Recent<br>3: My Recordings<br>4: My Channels<br>5: Adult
|-
| SUBSCRIPTION_DETAIL_STATE || Open Suscription page || SubscriptionPid: String value with SUB prefix as exported by ContentAPI (SUB[ID] see this [http://docs.gvp.mediaibox.com.br/v4.1/docs/GVP_4.1.14_API_CONTENTS_DOCS.html#subscription link])
|-
|}
==== [[TVOpen Message Manager API Command - Remote Certification|Remote Certification]] ====
''Command name'': remote_certification
<br>''Command-specific entry parameters'':
* index: identifies the multicast address, from those configured in OPCH variable ''CertificationConfig'' => testChannels, the STB must use for multicast test. Mandatory.
''Command-specific parameters sent to GVP DataHub'': N/A
<br>''Supported targets'': it must be possible to send this command to one STB only.
<br>''Description'': This command triggers the remote certification process in the STB. This process will execute two actions: tune a multicast channel for a specified time (defined in OPCH variable ''CertificationConfig'' => liveTestTime) and download an image. The purpose of these two actions is to test that both multicast and unicast interfaces work correctly. As a result, a CER/execution event will be sent toward GVP Data Hub with the appropriate data.
==== [[TVOpen Message Manager API Command - PIN Reset|Pin Reset]] ====
''Command name'': pin_reset
<br>''Command-specific entry parameters'':
* Type of PIN to be updated: parental, rental. Mandatory.
* New value for each PIN. If not specified, the corresponding PIN will be set to its default value (which can be retrieved by the STB from MiB using UNIAPI [https://wikis.tid.es/gvp-public/index.php/GetDefaultOBPinNumber GetDefaultOBPinNumber]). Optional.
''Command-specific parameters sent to GVP DataHub'': None
<br>''Supported targets'': it must be possible to send this command to one STB or one account (to reset the PINs from all the STBs in the account)
''Description'':
# Message Manager should validate that the mandatory entry parameters are properly filled. The only mandatory parameter is the type of PIN(s) to be updated. In case it is not filled the request must be rejected with the proper error code.
# In case the request is sent to an account, it must be forwarded to all STBs in the account. This filtering will be done before creating the request toward Message Manager; in any case, Message Manager will receive the list of STBs.
# When the STB receives the command, in case the new value for a PIN is not sent, then the STB must retrieve the default value from UNIAPI using [https://wikis.tid.es/gvp-public/index.php/GetDefaultOBPinNumber GetDefaultOBPinNumber] method.
==== [[TVOpen Message Manager API Command - Flush Event Queue|Flush Event Queue]] ====
''Command name'': flush_event_queue
''Command-specific entry parameters'':
* reset_qos_counters: specifies if the STB has to reset the QoS counters after executing the command. Optional.
* custom_spread_time: time value (in seconds) that STBs will use to randomly spread in time the data push toward GVP Data Hub. If this value is empty data will be sent immediately. Optional.
''Command-specific parameters sent to GVP DataHub'': None
''Supported targets'': it must be possible to send this command to one or many STBs.
''Description'': This command can be used to retrieve, in near-real time, complete information about the status of a STB or a set of STBs. When OpenIPTV STBs receive this command they will send the BI events stored in their local buffer toward GVP Data Hub together with the QoS counters.
Once the BI events are sent, the local BI Event buffer must be emptied and the STB counters related to BI events must be reset (number of events, load period). Regarding QoS counters, depending on the command configuration the STB will reset them or not. If not configured, default behaviour will be not to reset the QoS counters.
It will be possible to configure a spread time to avoid collapsing GVP Data Hub with BI and QoS data from multiple STBs. If spread time is not configured, the STBs will send the information immediately; otherwise they will apply a randomly spread delay before sending data to GVP Data Hub.
==== [[TVOpen Message Manager API Command - Get QOS Status|Get QoS Status]] ====
''Command name'': get_qos_status
''Command-specific entry parameters'':
* counter_type: specifies the set of static data counters to be sent to Data Hub. Mandatory
** '''config''': (STA/device-kpis-config)
{| class="wikitable"
! Event Name !! Description
|-
| parental_pin || Parental PIN configured
|-
| vsa_fcc_prim_server || VSA primary server used for FCC. Empty or zero value disables FCC.
|-
| vsa_ret_prim_server || VSA primary server used for RET. Empty or zero value disables RET.
|-
| vsa_fcc_sec_server || VSA secondary server used for FCC
|-
| vsa_ret_sec_server || VSA secondary server used for RET
|-
| volume || Current volume, in percentage
|-
| Mute || Mute status (true=enable;false=disabled)
|-
| zoom_mode || How to scale content. Possible values are ORIGINAL, ZOOM or FULLSCREEN
|-
| analog_video_mode || Standard used for analog video
|-
| dolby_enabled || Indicates that we should bypass Dolby audio data to HDMI instead of downmixing it
|-
| default_audio || User selection for default audio language
|-
| default_subtitle || User selection for default subtitle
|-
| parental_rating || User selected parental rating
|-
| hdmi_connected || This parameter indicates if HDMI output is in use (true/false).
|-
| rca_connected || This parameter indicates if RCA output is in use (true/false)
|}
** '''state''': (STA/device-kpis-state)
{| class="wikitable"
! Event Name !! Description
|-
| ui_state || Current UI state. Screen currently displayed on TV
|-
| last_channel_tuned || Last channel that has been tuned by the end user (identified by MiB’s channel_id;<br>must be the same id than the one sent in LIV/netw-play event).
|-
| reminders || Number of scheduled reminders
|-
| load_avg || CPU load average for 1, 5 and 10 minutes
|-
| memory_total || System total amount of memory in bytes
|-
| memory_free || System free memory in bytes
|-
| allocated_physycal_memory || Total amount of memory allocated in bytes
|-
| active_network_if || Network interface currently active
|-
| epg_file_id || Last EPG FileID received
|-
| dvbipi_last_notify || Date/time from last DVB-IPI notification
|-
| boot_rom_version || Version number of the boot ROM (bootloader)
|-
| sw_version || Current software version
|-
| uptime || Number of seconds since last boot
|-
| standby || Indicates if the STB is in standby or not (boolean; true = standby on; false = standby off)
|-
| geographic_area || Geographic area the account belongs to. Received from GVP
|}
** '''hdmi''': (STA/device-kpis-hdmi)
{| class="wikitable"
! Event Name !! Description
|-
| format || Current HDMI output format
|-
| hdmi_preferedformat || Prefered format reported by TV
|-
| audio_mode || Indicates how audio is handled by HDMI (downmix or bypass)
|-
| aspect_ratio || Aspect ratio used
|-
| model || Device TV model, as reported by HDMI
|-
| manufacturer || Device TV manufacturer, as reported by HDMI
|}
** '''pvr''': (STA/device-kpis-pvr)
{| class="wikitable"
! Event Name !! Description
|-
| is_local_pvr || If current STB is an enabled PVR, announcing itself in LAN
|-
| pvr_capability || True if STB is connected to the Master DVR of the account
|-
| schedules || Total number of schedule objects in middleware. Includes both series and single events.<br>Episodes are counted as a single entry. Returns data from multiroom PVR
|-
| hdd_usage || HDD usage in percentage. Returns data from multiroom PVR
|-
| hdd_free || Indicates the remaining free space in the hard disk
|-
| hdd_size || Indicates total size of the hard disk
|}
** '''wifi''': (STA/STA/device-kpis-wifi)
{| class="wikitable"
! Event Name !! Description
|-
| rssi|| Router RSSI connection
|-
| channel_interference|| Wifi interferences in the same channel or adjacents
|-
| physical_rate|| Transfer physical rate
|}
** '''all''' (STA/device-kpis-config, STA/device-kpis-state, STA/device-kpis-hdmi, STA/device-kpis-pvr, STA/device-kpis-wifi)
* reset_qos_counters: specifies if the STB has to reset the QoS counters after executing the command. Optional.
* custom_spread_time: time value (in seconds) that STBs will use to randomly spread in time the data push toward GVP Data Hub. If this value is empty data will be sent immediately. Optional.
''Command-specific parameters sent to GVP DataHub'': None
''Supported targets'': it must be possible to send this command to one or many STBs.
''Description'': This command can be used to retrieve, in near-real time, QoS information from a STB or a set of STBs. When OpenIPTV STBs receive this command they will send the requested QoS counters toward GVP Data Hub. Depending on the command configuration (resetQoSCounters) the STB will afterwards reset the affected counters or not. If not specified default behaviour will be not to reset the QoS counters.
It will be possible to configure a spread time to avoid collapsing GVP Data Hub with QoS data from multiple STBs. If spread time is not configured, the STBs will send the information immediately; otherwise they will apply a randomly spread delay before sending data to GVP Data Hub.
Message Manager won’t validate the the counter_type requested belongs to a pre-defined list. This way we enable defining new counters sets without having to evolve this component.
==== [[TVOpen Message Manager API Command - Reload Account Status|Reload Account Status]] ====
''Command name'': reload_account_status
''Command-specific entry parameters'':
* custom_spread_time: time value (in seconds) that STBs will use to randomly spread in time the requests toward UNIAPI. If this value is empty the request will be done immediately. Optional.
''Command-specific parameters sent to GVP DataHub'': None
''Supported targets'': it must be possible to send this command to one or many STBs.
''Description'': This command instructs a STB to refresh its account data (using UNIAPI) and update its behaviour accordingly. It will be possible to configure a spread time to avoid collapsing UNIAPI with multiple requests in case the command is sent to a high number of STBs.
<blockquote style="background:FloralWhite; padding:1em; border:1px solid #999; font-style: italic;">
Pendiente disponer de una lista de parámetros de cuenta que se podrán cambiar en caliente y cuáles no. Lo tiene que proporcionar el equipo de GVT.
</blockquote>
==== [[TVOpen Message Manager API Command - Get Recordings|Get Recordings (from STB R2 onwards)]] ====
''Command name'': get_recordings
''Command-specific entry parameters'': None
''Command-specific parameters sent to GVP DataHub'': List of '''finished''' recordings stored in the STB.
''Supported targets'': it must be possible to send this command to one STB.
''Description'': This command can be used to retrieve the list of finished recordings available in a DVR-enabled STB. When invoked on a diskless STB it won’t send data toward GVP Data Hub but an error code in the command’s result. When invoked on a DVR STB it will send a BI record toward GVP Data Hub containing the list of '''finished''' recordings available in the hard disk. Each recording will be identified by a recording ID and will contain information about its duration.
==== [[TVOpen Message Manager API Command - Delete Recording|Delete Recording (from STB R2 onwards)]] ====
''Command name'': delete_recording
''Command-specific entry parameters'':
* recording_id: unique identifier of the recording to be removed from the STB. Mandatory
''Command-specific parameters sent to GVP DataHub'': None
''Supported targets'': it must be possible to send this command to one STB.
''Description'': This command can be used to remove a recording (identified by a recording ID previously retrieved using GetRecordings command) from a DVR-enabled STB. When invoked on a diskless STB the corresponding error code will be returned.
==== [[TVOpen Message Manager API Command - Schedule Manual Recording|Schedule Manual Recording (from STB R2 onwards)]] ====
''Command name'': schedule_manual_recording
''
<br>''Command-specific entry parameters'':
* channel_id: unique identifier of the channel to be recorded. Mandatory.
* start_recording: start time of the recording in UTC ISO-8601 format (%Y-%m-%dT%H:%M:%S'''Z'''). Mandatory.
* end_recording: end time of the recording in UTC ISO-8601 format (%Y-%m-%dT%H:%M:%S'''Z'''). Mandatory.
''Command-specific parameters sent to GVP DataHub'': None
''Supported targets'': it must be possible to send this command to one STB.
''Description'': This command can be used to instruct a DVR-enabled STB to record a channel during the period specified between start and end time. In case the command is sent to a diskless STB no recording will be scheduled and an error code will be returned; in case the command orders a recording on a channel without DVR grants the corresponding error code will be returned. The command result will be sent as soon as the recording is scheduled; it is not necessary to wait until the recording is finished to send this information.
<br>Message Manager won’t validate that the channel_id is effectively configured for the instance.
<br>Both start and end recording dates are sent in UTC ISO-8601 format. It is the STB's responsibility to translate this UTC time to the local time where the STB is effectively located.
==== [[TVOpen Message Manager API Command - Flush EPG|Flush EPG]] ====
''Command name'': flush_epg
''Command-specific entry parameters'': None
''Command-specific parameters sent to GVP DataHub'': None
''Supported targets'': it must be possible to send this command to one STB or to a small list of STBs. It doesn’t make sense sending this command through multicast (although the platform will support it).
''Description'': This command can be used to instruct a STB to remove all EPG data and retrieve it again from the multicast DVB-IPI channels. The STB will send an event toward DataHub once the EPG data is removed, and other event when new data is loaded again; the second event will carry information about the EPGFileId loaded.
==== Commands behavior depending on the STB's status ====
When receiving a command, the STB might be in one of these statuses: ON, OFF, STBY.
<br>If the STB is ON it will execute the command as soon as possible (this will depend on the tasks the STB might be performing when receiving the request).
<br>If the STB is OFF it won't execute anything. When the STB is turned on, if the command is still active, it will be executed as soon as possible (once the startup process is finished and other might-be more important tasks have been executed).
<br>If the STB is in STBY the proposal is to execute the command without exiting STBY status (i.e. the end user must be unaware of the command being executed). The exceptions to this general rule are the ''channel_tune'' and the ''open_ui_state'' commands. The following table presents the behavior defined for the commands currently supported by Graphene devices.
{| class="wikitable"
|-
! Command!! STB Behavior in STBY
|-
| [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Client_Software_Upgrade client_software_upgrade]|| As requested by product team in [https://gvuproducts.aha.io/features/GTV-84 GTV-84] the upgrade must be executed once the recordings that might be taking place are over, without any warning to the end user.
|-
| [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Update_Audio_for_Live_Channel update_audio_for_live_channel]|| The command is executed without any change in the UI (the STB remains in STBY)
|-
| [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Update_Variable update_variable] || The command is executed without any change in the UI (the STB remains in STBY)
|-
| [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Get_Variable get_variable] || The command is executed without any change in the UI (the STB remains in STBY)
|-
| [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Reset_Device reset_device] || As requested by product team in [https://gvuproducts.aha.io/features/GTV-84 GTV-84] the reset must be done immediately, regardless recording status of the STB, and without any warning to the end user.
|-
| [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Open_UI_State open_ui_state] || The command is not executed if the STB is in STBY.
|-
| [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Remote_Certification remote_certification] || The command is executed without any change in the UI (the STB remains in STBY)
|-
| [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Pin_Reset pin_reset] || The command is executed without any change in the UI (the STB remains in STBY)
|-
| [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Flush_Event_Queue flush_event_queue] || The command is executed without any change in the UI (the STB remains in STBY)
|-
| [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Reload_Account_Status reload_account_status] || The command is executed without any change in the UI (the STB remains in STBY)
|-
| [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Get_QoS_Status get_qos_status] || The command is executed without any change in the UI (the STB remains in STBY)
|-
| [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Flush_EPG flush_epg] || The command is executed without any change in the UI (the STB remains in STBY)
|-
|}
Commands will enable TV Open Platform operators to send orders toward selected STBs, ordering them to execute an action from a pre-defined command set. They will be a powerful tool for operation and troubleshooting teams.
The following are general requirements that apply to all commands supported by TV Open Platform. In next subsections we provide a description of the logic that must be implemented by each command and its specific parameters.
==== Generic requirements ====
These requirements are described with more detail at the following US:[https://jira.tid.es/browse/OPENPLAT-349 OPENPLAT-349] (Message Manager multi-OB support), [https://jira.tid.es/browse/OPENPLAT-312 OPENPLAT-312] (Message Manager validations), [https://jira.tid.es/browse/OPENPLAT-313 OPENPLAT-313], [https://jira.tid.es/browse/OPENPLAT-457 OPENPLAT-457] (Data transformation through TV Open Platform Enablers components) and [https://jira.tid.es/browse/OPENPLAT-342 OPENPLAT-342] (Command Cancellation).
# Message Manager must support sending toward OpenIPTV STBs the set of commands specified in this [https://docs.google.com/spreadsheets/d/1fcrSNz5TC8DvuRKafJK8NxUlLvNPFxeQggr7_2uy32I/edit#gid=1032626120 xls] sheet (Commands tab).
# OB operators must be able to send commands toward OpenIPTV STBs from the following UIs:
#* E2E diagnosis tool (for CAT operators). Commands will be sent toward Message Manager through GVP DataHub (QoS).
#* QoS - Mariner (for local operation teams). Commands will be sent toward Message Manager through GVP DataHub (QoS).
#* GAL BSS component, for a limited set of commands which are currently published in UNICA API toward the OSS/BSS: ResetPin and ResetDevice, plus ReloadAccountStatus which will be used when the status of an account is changed in the OSS/BSS. GAL BSS is able to send these commands to unique STBs identified through their GUID.
# Each possible origin of commands (GVP DataHuB, MiB, GAL BSS) must identify itself, when creating the request toward TV Open Platform, using a unique SourceID so that the rest of the components involved (Message Manager, STB, DataHub) are able to track from which component the request came and process it accordingly. SourceID will be a single character, excluding special characters.
# When creating a command, all the sources will be able to configure a start and end time for the command (in UTC ISO-8601).
#: Most requests coming from DataHub or GAL-BSS will be targeted to a specific STB and must be executed immediately. However, there are situations in which engineering teams might want to send a command to multiple STBs (eg. to regularize a local variable in the STBs). For these scenarios it might be useful to have an extended end time so that multiple STBs in the platform have time to receive and execute it.
# When creating the request toward Message Manager all sources must inform about the instance (OB) for which the command is configured. This will determine which InfoPush/Sprayer servers are to be used to deliver it.
# When creating the request toward Message Manager, all sources must generate a commandID which must be unique throughout the system. This ID will be used to track this specific command through all the components involved. The commandID will be an alphanumeric string of exactly 24 characters, excluding special characters, with zeros to the left.
# Message manager will return an error if any component tries to create two commands with the same commandID for the same instance and from the same component.
# Message Manager will support sending a command to two different device types (OpenIPTV and Hybrid) with the following limitation:
#* If an operator tries to send a command to an Hybrid STB and the delivery mechanism calculated by Message Manager is InfoPush, an error will be returned (InfoPush is not supported for Hybrid STBs).
#* If an operator tries to send a command to OpenIPTV and Hybrid STBs simultaneously and the delivery mechanisms calculated by Message Manager is InfoPush, the response will be OK '''but''' no Hybrid STB will receive the command.
# Once a command is sent toward Message Manager it won’t be possible to modify it.
# All commands must register, in GVP DataHub, the result of its execution through a BI event. Common data to be registered for all commands are the SourceID, STB ID, command type, command ID, success/error code and time (timestamp when the event happened at the STB; fixed-size;string with ISO 8601 datetime format, with precision up to miliseconds - if available - and time zone information as UTC offset) when the command was executed.
# For commands sent from GVP DataHub it is necessary to receive feedback, in real time, about the command execution. For commands sent from other modules it is not necessary to know their execution result in real time.
#: As a consequence, it must be possible to configure, in the request sent toward Message Manager, whether the result of the command execution is to be stored in the BI event queue in the STB (and uploaded to the GVP DataHub following the usual BI event management process) or if it must be sent immediately toward the GVP DataHub.
# It must be possible to '''cancel''' a command once it is sent. In this scenario:
#* All the STBs that have already executed the command won’t execute it again.
#* All the STBs that are executing the command will finish its execution.
#* STBs that are in stand-by mode and have read the command from Sprayer/InfoPush will execute it (see [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Commands_behavior_depending_on_the_STB.27s_status this section]).
#* STBs that are off won’t execute the command if they are turned on.
# When creating the request toward Message Manager, all parameters must be encoded in '''Form Data'''.
==== MIB BE Tools UI Requirements ====
The tool to manage IPTV Service will be TV QoS Tool; MiB BE Tools will be left to manage commercial offering exclusively. Therefore it is not necessary to provide, in MiB BE Tools, mechanisms to send commands toward OpenIPTV STBs.
MiB currently supports resetting PIN (parental, rental) for OTT devices. This operation is not synchronized with Mediaroom STBs. Operation and engineering teams have requested GVP development team to keep this behavior for OpenIPTV STBs. Pin reset for OpenIPTV STBs can be requested from OSS/BSS (through UNICA API) and TV QoS Tool only.
==== MIB GAL BSS Requirements ====
# MiB must support sending reset device requests from the OSS/BSS toward OpenIPTV STBs. When MiB receives a restartRequest from UNICA API, it must forward the request toward Message Manager. An OK response from Message Manager doesn't imply that the device has been restarted; it will just mean that the request has been forwarded successfully.
# MiB must support sending reset pin requests from the OSS/BSS toward OpenIPTV STBs.
## When MiB receives a rememberPasswordRequest from UNICA API, it must forward the request toward Message Manager.
## rememberPasswordRequests in UNICA API are sent for an account. MiB must obtain the list of active OpenIPTV STBs for the account and send this list in the request toward Message Manager.
## An OK response from Message Manager doesn't imply that the PINs have been reset successfully in all the STBs; it will just mean that the request has been forwarded successfully.
==== [[TVOpen Message Manager API Command - Client Software Upgrade|Client Software Upgrade]] ====
''Command name'': client_software_upgrade
''Command-specific entry parameters'':
* version: information about the client software versions per STB model to be downloaded. Every version must included in token [[OPCHToken_ClientCDNURL|ClientCDNURL]], into fw_list, to find bootcast-id xml file to download binary file. If this value is empty, it means that the STB must download the software version available in OPCH. Optional.
* custom_spread_time: time value (in seconds) that STBs will use to randomly spread in time their download requests. If this value is empty, ClientUpgradeSpreadTime global value configured in OPCH will be used. Optional.
''Command-specific parameters sent to GVP DataHub'': This information depends on the results of the upgrade command.
* In case an upgrade/downgrade of client version is done, no data is sent to DataHub
* In case there is no need to change the client version, in the CMD/* event sent to DataHub the STB will inform about this situation.
* In case an error occurs during the upgrade, in the CMD/* event sent to DataHub the STB will inform about the error.
''Supported targets'': it must be possible to send this command to one STB or to a list of STBs
''Description'': This command triggers the upgrade of the software version running in the STB to the one specified as an entry parameter in the request.
* If the version is included into fw_list field of token [[OPCHToken_ClientCDNURL|ClientCDNURL]] and it's a different version than current in flash, STB will invalidate current flashed client, it will change boot mode to 7363 (download by HTTP) and will program an automatic reboot to allow bootloader to perform the update.
* If the version is not included into fw_list, this command will have no effect.
* If no software version is specified or it is then the STB must download the software version available in OPCH. STB will change boot mode to 7313 (download by OPCH) and will program an automatic reboot to allow bootloader to perform the update.
Detailed description of the upgrade process is to be found in [[TVOpen_STB_Boot_and_Configurations#Functional_requirements._Software_upgrade | STB Boot and Configurations]].
==== [[TVOpen Message Manager API Command - Update Audio for Live Channel|Update Audio for Live Channel]] ====
''Command name'': update_audio_for_live_channel
''Command-specific entry parameters'':
* channel_id: ID of the channel on which to force a specific audio language. Mandatory.
* audio language in ISO 639-1 format. If this value is empty, this channel will return to its default audio language, specified in a local configuration variable; if this local configuration variable doesn’t exist then [[OPCHToken_DefaultAudioLanguage|DefaultAudioLanguage]] will be used. Optional.
''Command-specific parameters sent to GVP DataHub'':
* Audio language established for the channel.
* ChannelID which audio language has been changed.
''Supported targets'': it must be possible to send this command to one STB.
''Description'': This command changes the configuration of the STB enforcing a certain audio language for a certain channel. It overwrites the configuration that might have been eventually set by the end user in the STBs UI. This configuration is stored in /tmp/ChannelSettings.ini internal file, so it is stored in volatile memory and it will be lost in every STB reboot.<br>
Message Manager won’t validate that the channel_id corresponds to a valid id configured in the instance; it is the responsibility of the source of the command to perform this validation.
==== [[TVOpen Message Manager API Command - Update Variable|Update Variable]] ====
''Command name'': update_variable
''Command-specific entry parameters'':
* variable: name of the STB’s local variable to be modified. Mandatory. List of available variables can be found '''[[TVOpen Message Manager - List of Variables|here]]'''.
* scope: remote, local. Mandatory.
* value: new value to be assigned to the variable. Optional.
''Command-specific parameters sent to GVP DataHub'':
* Name of the variable modified.
* Value established for the variable.
''Supported targets'': it must be possible to send this command to one STB or to a list of STBs.
''Description'': This command enables external applications to manage variables in the STB. With a single command it is possible to create, update and/or remove a variable from the STB.
* In case the variable already exists and a value is configured, then the local variable must be updated in the STB. This parameter configuration covers the “modify value” scenario.
* In case the variable already exists and the value configured in the command is left empty, then the local variable must be removed from the STB. In this scenario, when a local variable is removed from the STB, the STB will apply the remote value when available, given the precedence rules defined in [[TVOpen_STB_Boot_and_Configurations#Functional_requirements._Configuration_management| STB Boot and Configurations]]. This parameter configuration covers the “remove variable” scenario.
* In case the variable name specified in the command doesn’t exist, a new local variable must be created with the name specified by the command and its value must be set to the one configured in the command. In this scenario both variable and value must be specified. This parameter configuration covers the “create variable” scenario.
* Message Manager won’t validate that the variable is supported in the system. It is the responsibility of the source of the command to ensure to be managing a supported variable in the OpenIPTV STB. This way we are able to manage new variables that might eventually be added to the STB without having to generate a new version of this component.
==== [[TVOpen Message Manager API Command - Get Variable|Get Variable]] ====
''Command name'': get_variable
''Command-specific entry parameters'':
* variable: name of the STB’s local variable to be retrieved; All. Mandatory. List of available variables can be found '''[[TVOpen Message Manager - List of Variables|here]]'''.
* scope: Remote, Local. Mandatory.
''Command-specific parameters sent to GVP DataHub'':
* List of comma-separated values (name - value - scope).
''Supported targets'': it must be possible to send this command to one STB or to a list of STBs.
''Description'': This command enables TV Open Platform operators to retrieve the values of different variables existing in the STB. It is flexible to enable operators get the value of a single variable under study, or all the variables in the STB. It also enables operators to retrieve the variable’s value for different scopes, getting an snapshot of the STB’s current configuration (which might be useful for troubleshooting). '''Remote''' scope will return variable values contained in the STB file '''/flash/var/OpenSTB/DefaultSettings.ini''' and '''Local''' scope will return variable values contained in the STB file '''/flash/var/OpenSTB/CurrentSettings.ini'''.
<br>Message Manager won’t validate that the variable is supported in the system. It is the responsibility of the source of the command to ensure to be managing a supported variable in the OpenIPTV STB. This way we are able to manage new variables that might eventually be added to the STB without having to generate a new version of this component.
<blockquote style="background:FloralWhite; padding:1em; border:1px solid #999; font-style: italic;">
Pendiente de analizar mecanismos de securización para esta comunicación, ya que puede ser que se envíe información sensible del usuario (p.ej. los valores de los PINes). Para IPTV puede no ser un requisite fuerte por tratarse de una red gestionada, pero para otro tipo de STBs (ej. hybrid) sí.
</blockquote>
==== [[TVOpen Message Manager API Command - Reset Device|Reset Device]] ====
''Command name'': reset_device
''Command-specific entry parameters'': None
''Command-specific parameters sent to GVP DataHub'': None
''Supported targets'': it must be possible to send this command to one STB only.
''Description'':This command allows resetting a specific STB. Detailed description of the reset process is to be found in [[TVOpen_STB_Boot_and_Configurations#Functional_requirements._STB_normal_reset|STB Boot and Configurations]] and [[STB_boot_sequence|STB boot sequence]].
==== [[TVOpen Message Manager API Command - Channel Tune|Channel Tune]] ====
''Command name'': channel_tune.
''Command-specific entry parameters'':
* channel_id: ID of the channel to be tuned.
''Command-specific parameters sent to GVP DataHub'':
* Channel id effectively tuned by the STB after the command execution.
''Supported targets'': it must be possible to send this command to one STB only.
''Description'': This command forces a STB to tune a specific channel. The channel can be specified either by its id. If the channel specified doesn’t exist in the channel map or if the end user doesn’t have playback grants then the command must return and error, and the UI will remain unchanged.
Message Manager won’t validate that the channel_id corresponds to a valid id configured in the instance; it is the responsibility of the source of the command to perform this validation.
==== [[TVOpen Message Manager API Command - Open UI State|Open UI State]] ====
''Command name'': open_ui_state
''Command-specific entry parameters'':
* ui_state: UI state to be loaded by the STB. Mandatory.
* parameter: depends on the state selected (e.g. VoD asset number, category number, interactive app URL, etc). Optional.
''Command-specific parameters sent to GVP DataHub'':
* ui_state and parameter effectively loaded by the STB.
''Supported targets'': it must be possible to send this command to one STB only.
''Description'': This command forces a STB to load a UI state; the page might be an internal page in the STB (list of supported pages to be provided by the STB development team) or a third party application.
<br>Message Manager won’t validate that the ui_state corresponds to a page for which direct launch is supported; it is the responsibility of the source of the command to perform this validation. This way we can decouple this component from the STB evolution and order the opening of new ui states without generating a new version of the Message Manager. Additionally, Message Manager won't perform any validations on parameters; all of them are optional and it is the responsibility of the source of the command to provide them if necessary.
''Available values for ui_state'':
{| class="wikitable"
! UI State !! Description !! Parameter
|-
| WELCOME_STATE || Open Welcome Home page with focus on TV window || N/A
|-
| ACCOUNT_STATE || Open My Account section (former ''Settings'' section) with focus on first left side item (Subscriptions), and its content loaded on right side || MenuIndex: Integer value indicating the left menu index (starting at 0) to be opened. The section this menu item corresponds to is determined by the content in the OPCH token [https://wikis.tid.es/gvp-dev/index.php/OPCHToken_SettingsMenuLayout OPCHToken_SettingsMenuLayout].
|-
| MINIGUIDE_STATE || Open miniguide view with current program and channel selected || N/A
|-
| GUIDE_STATE || Open full guide (Grid view) with current program and channel selected || channelId: MiB ID of the channel that will be focused after navigating to full guide page.
|-
| ONNOWGUIDE_STATE || Open On Now Guide view with current program and channel selected || N/A
|-
| INFO_STATE || Open Information page for LIVE and VOD contents || contentId: ID of the content
|-
| CONTENT_TREE_STATE || Open Content Areas (Tematic Areas, Providers, Rentals, Recommendations) with default focus as defined in the UI || vodCategory: Identifies the MiB channel that contains the content to be shown.
|-
| ISERVICES_STATE || Open Applications main board or load external Third Party applications || applicationUrl: URL for QML application. <br>To open a specific application url, parameter should be sent without ''<nowiki>http://</nowiki>'' prefix (ex. files.paytvlabs.com.br/snake/snake.qml). <br>To open the container, just omit the applicationUrl parameter.
|-
| SEARCH_STATE || Open Search page || N/A
|-
| MYCONTENT_STATE || Open My Content section || MenuIndex: Integer value indicating the left menu index (starting at 0) to be opened. Current supported options are:<br>0: My Rented<br>1: My List<br>2: Recent<br>3: My Recordings<br>4: My Channels<br>5: Adult
|-
| SUBSCRIPTION_DETAIL_STATE || Open Suscription page || SubscriptionPid: String value with SUB prefix as exported by ContentAPI (SUB[ID] see this [http://docs.gvp.mediaibox.com.br/v4.1/docs/GVP_4.1.14_API_CONTENTS_DOCS.html#subscription link])
|-
|}
==== [[TVOpen Message Manager API Command - Remote Certification|Remote Certification]] ====
''Command name'': remote_certification
<br>''Command-specific entry parameters'':
* index: identifies the multicast address, from those configured in OPCH variable ''CertificationConfig'' => testChannels, the STB must use for multicast test. Mandatory.
''Command-specific parameters sent to GVP DataHub'': N/A
<br>''Supported targets'': it must be possible to send this command to one STB only.
<br>''Description'': This command triggers the remote certification process in the STB. This process will execute two actions: tune a multicast channel for a specified time (defined in OPCH variable ''CertificationConfig'' => liveTestTime) and download an image. The purpose of these two actions is to test that both multicast and unicast interfaces work correctly. As a result, a CER/execution event will be sent toward GVP Data Hub with the appropriate data.
==== [[TVOpen Message Manager API Command - PIN Reset|Pin Reset]] ====
''Command name'': pin_reset
<br>''Command-specific entry parameters'':
* Type of PIN to be updated: parental, rental. Mandatory.
* New value for each PIN. If not specified, the corresponding PIN will be set to its default value (which can be retrieved by the STB from MiB using UNIAPI [https://wikis.tid.es/gvp-public/index.php/GetDefaultOBPinNumber GetDefaultOBPinNumber]). Optional.
''Command-specific parameters sent to GVP DataHub'': None
<br>''Supported targets'': it must be possible to send this command to one STB or one account (to reset the PINs from all the STBs in the account)
''Description'':
# Message Manager should validate that the mandatory entry parameters are properly filled. The only mandatory parameter is the type of PIN(s) to be updated. In case it is not filled the request must be rejected with the proper error code.
# In case the request is sent to an account, it must be forwarded to all STBs in the account. This filtering will be done before creating the request toward Message Manager; in any case, Message Manager will receive the list of STBs.
# When the STB receives the command, in case the new value for a PIN is not sent, then the STB must retrieve the default value from UNIAPI using [https://wikis.tid.es/gvp-public/index.php/GetDefaultOBPinNumber GetDefaultOBPinNumber] method.
==== [[TVOpen Message Manager API Command - Flush Event Queue|Flush Event Queue]] ====
''Command name'': flush_event_queue
''Command-specific entry parameters'':
* reset_qos_counters: specifies if the STB has to reset the QoS counters after executing the command. Optional.
* custom_spread_time: time value (in seconds) that STBs will use to randomly spread in time the data push toward GVP Data Hub. If this value is empty data will be sent immediately. Optional.
''Command-specific parameters sent to GVP DataHub'': None
''Supported targets'': it must be possible to send this command to one or many STBs.
''Description'': This command can be used to retrieve, in near-real time, complete information about the status of a STB or a set of STBs. When OpenIPTV STBs receive this command they will send the BI events stored in their local buffer toward GVP Data Hub together with the QoS counters.
Once the BI events are sent, the local BI Event buffer must be emptied and the STB counters related to BI events must be reset (number of events, load period). Regarding QoS counters, depending on the command configuration the STB will reset them or not. If not configured, default behaviour will be not to reset the QoS counters.
It will be possible to configure a spread time to avoid collapsing GVP Data Hub with BI and QoS data from multiple STBs. If spread time is not configured, the STBs will send the information immediately; otherwise they will apply a randomly spread delay before sending data to GVP Data Hub.
==== [[TVOpen Message Manager API Command - Get QOS Status|Get QoS Status]] ====
''Command name'': get_qos_status
''Command-specific entry parameters'':
* counter_type: specifies the set of static data counters to be sent to Data Hub. Mandatory
** '''config''': (STA/device-kpis-config)
{| class="wikitable"
! Event Name !! Description
|-
| parental_pin || Parental PIN configured
|-
| vsa_fcc_prim_server || VSA primary server used for FCC. Empty or zero value disables FCC.
|-
| vsa_ret_prim_server || VSA primary server used for RET. Empty or zero value disables RET.
|-
| vsa_fcc_sec_server || VSA secondary server used for FCC
|-
| vsa_ret_sec_server || VSA secondary server used for RET
|-
| volume || Current volume, in percentage
|-
| Mute || Mute status (true=enable;false=disabled)
|-
| zoom_mode || How to scale content. Possible values are ORIGINAL, ZOOM or FULLSCREEN
|-
| analog_video_mode || Standard used for analog video
|-
| dolby_enabled || Indicates that we should bypass Dolby audio data to HDMI instead of downmixing it
|-
| default_audio || User selection for default audio language
|-
| default_subtitle || User selection for default subtitle
|-
| parental_rating || User selected parental rating
|-
| hdmi_connected || This parameter indicates if HDMI output is in use (true/false).
|-
| rca_connected || This parameter indicates if RCA output is in use (true/false)
|}
** '''state''': (STA/device-kpis-state)
{| class="wikitable"
! Event Name !! Description
|-
| ui_state || Current UI state. Screen currently displayed on TV
|-
| last_channel_tuned || Last channel that has been tuned by the end user (identified by MiB’s channel_id;<br>must be the same id than the one sent in LIV/netw-play event).
|-
| reminders || Number of scheduled reminders
|-
| load_avg || CPU load average for 1, 5 and 10 minutes
|-
| memory_total || System total amount of memory in bytes
|-
| memory_free || System free memory in bytes
|-
| allocated_physycal_memory || Total amount of memory allocated in bytes
|-
| active_network_if || Network interface currently active
|-
| epg_file_id || Last EPG FileID received
|-
| dvbipi_last_notify || Date/time from last DVB-IPI notification
|-
| boot_rom_version || Version number of the boot ROM (bootloader)
|-
| sw_version || Current software version
|-
| uptime || Number of seconds since last boot
|-
| standby || Indicates if the STB is in standby or not (boolean; true = standby on; false = standby off)
|-
| geographic_area || Geographic area the account belongs to. Received from GVP
|}
** '''hdmi''': (STA/device-kpis-hdmi)
{| class="wikitable"
! Event Name !! Description
|-
| format || Current HDMI output format
|-
| hdmi_preferedformat || Prefered format reported by TV
|-
| audio_mode || Indicates how audio is handled by HDMI (downmix or bypass)
|-
| aspect_ratio || Aspect ratio used
|-
| model || Device TV model, as reported by HDMI
|-
| manufacturer || Device TV manufacturer, as reported by HDMI
|}
** '''pvr''': (STA/device-kpis-pvr)
{| class="wikitable"
! Event Name !! Description
|-
| is_local_pvr || If current STB is an enabled PVR, announcing itself in LAN
|-
| pvr_capability || True if STB is connected to the Master DVR of the account
|-
| schedules || Total number of schedule objects in middleware. Includes both series and single events.<br>Episodes are counted as a single entry. Returns data from multiroom PVR
|-
| hdd_usage || HDD usage in percentage. Returns data from multiroom PVR
|-
| hdd_free || Indicates the remaining free space in the hard disk
|-
| hdd_size || Indicates total size of the hard disk
|}
** '''wifi''': (STA/STA/device-kpis-wifi)
{| class="wikitable"
! Event Name !! Description
|-
| rssi|| Router RSSI connection
|-
| channel_interference|| Wifi interferences in the same channel or adjacents
|-
| physical_rate|| Transfer physical rate
|}
** '''all''' (STA/device-kpis-config, STA/device-kpis-state, STA/device-kpis-hdmi, STA/device-kpis-pvr, STA/device-kpis-wifi)
* reset_qos_counters: specifies if the STB has to reset the QoS counters after executing the command. Optional.
* custom_spread_time: time value (in seconds) that STBs will use to randomly spread in time the data push toward GVP Data Hub. If this value is empty data will be sent immediately. Optional.
''Command-specific parameters sent to GVP DataHub'': None
''Supported targets'': it must be possible to send this command to one or many STBs.
''Description'': This command can be used to retrieve, in near-real time, QoS information from a STB or a set of STBs. When OpenIPTV STBs receive this command they will send the requested QoS counters toward GVP Data Hub. Depending on the command configuration (resetQoSCounters) the STB will afterwards reset the affected counters or not. If not specified default behaviour will be not to reset the QoS counters.
It will be possible to configure a spread time to avoid collapsing GVP Data Hub with QoS data from multiple STBs. If spread time is not configured, the STBs will send the information immediately; otherwise they will apply a randomly spread delay before sending data to GVP Data Hub.
Message Manager won’t validate the the counter_type requested belongs to a pre-defined list. This way we enable defining new counters sets without having to evolve this component.
==== [[TVOpen Message Manager API Command - Reload Account Status|Reload Account Status]] ====
''Command name'': reload_account_status
''Command-specific entry parameters'':
* custom_spread_time: time value (in seconds) that STBs will use to randomly spread in time the requests toward UNIAPI. If this value is empty the request will be done immediately. Optional.
''Command-specific parameters sent to GVP DataHub'': None
''Supported targets'': it must be possible to send this command to one or many STBs.
''Description'': This command instructs a STB to refresh its account data (using UNIAPI) and update its behaviour accordingly. It will be possible to configure a spread time to avoid collapsing UNIAPI with multiple requests in case the command is sent to a high number of STBs.
<blockquote style="background:FloralWhite; padding:1em; border:1px solid #999; font-style: italic;">
Pendiente disponer de una lista de parámetros de cuenta que se podrán cambiar en caliente y cuáles no. Lo tiene que proporcionar el equipo de GVT.
</blockquote>
==== [[TVOpen Message Manager API Command - Get Recordings|Get Recordings (from STB R2 onwards)]] ====
''Command name'': get_recordings
''Command-specific entry parameters'': None
''Command-specific parameters sent to GVP DataHub'': List of '''finished''' recordings stored in the STB.
''Supported targets'': it must be possible to send this command to one STB.
''Description'': This command can be used to retrieve the list of finished recordings available in a DVR-enabled STB. When invoked on a diskless STB it won’t send data toward GVP Data Hub but an error code in the command’s result. When invoked on a DVR STB it will send a BI record toward GVP Data Hub containing the list of '''finished''' recordings available in the hard disk. Each recording will be identified by a recording ID and will contain information about its duration.
==== [[TVOpen Message Manager API Command - Delete Recording|Delete Recording (from STB R2 onwards)]] ====
''Command name'': delete_recording
''Command-specific entry parameters'':
* recording_id: unique identifier of the recording to be removed from the STB. Mandatory
''Command-specific parameters sent to GVP DataHub'': None
''Supported targets'': it must be possible to send this command to one STB.
''Description'': This command can be used to remove a recording (identified by a recording ID previously retrieved using GetRecordings command) from a DVR-enabled STB. When invoked on a diskless STB the corresponding error code will be returned.
==== [[TVOpen Message Manager API Command - Schedule Manual Recording|Schedule Manual Recording (from STB R2 onwards)]] ====
''Command name'': schedule_manual_recording
''
<br>''Command-specific entry parameters'':
* channel_id: unique identifier of the channel to be recorded. Mandatory.
* start_recording: start time of the recording in UTC ISO-8601 format (%Y-%m-%dT%H:%M:%S'''Z'''). Mandatory.
* end_recording: end time of the recording in UTC ISO-8601 format (%Y-%m-%dT%H:%M:%S'''Z'''). Mandatory.
''Command-specific parameters sent to GVP DataHub'': None
''Supported targets'': it must be possible to send this command to one STB.
''Description'': This command can be used to instruct a DVR-enabled STB to record a channel during the period specified between start and end time. In case the command is sent to a diskless STB no recording will be scheduled and an error code will be returned; in case the command orders a recording on a channel without DVR grants the corresponding error code will be returned. The command result will be sent as soon as the recording is scheduled; it is not necessary to wait until the recording is finished to send this information.
<br>Message Manager won’t validate that the channel_id is effectively configured for the instance.
<br>Both start and end recording dates are sent in UTC ISO-8601 format. It is the STB's responsibility to translate this UTC time to the local time where the STB is effectively located.
==== [[TVOpen Message Manager API Command - Flush EPG|Flush EPG]] ====
''Command name'': flush_epg
''Command-specific entry parameters'': None
''Command-specific parameters sent to GVP DataHub'': None
''Supported targets'': it must be possible to send this command to one STB or to a small list of STBs. It doesn’t make sense sending this command through multicast (although the platform will support it).
''Description'': This command can be used to instruct a STB to remove all EPG data and retrieve it again from the multicast DVB-IPI channels. The STB will send an event toward DataHub once the EPG data is removed, and other event when new data is loaded again; the second event will carry information about the EPGFileId loaded.
==== Commands behavior depending on the STB's status ====
When receiving a command, the STB might be in one of these statuses: ON, OFF, STBY.
<br>If the STB is ON it will execute the command as soon as possible (this will depend on the tasks the STB might be performing when receiving the request).
<br>If the STB is OFF it won't execute anything. When the STB is turned on, if the command is still active, it will be executed as soon as possible (once the startup process is finished and other might-be more important tasks have been executed).
<br>If the STB is in STBY the proposal is to execute the command without exiting STBY status (i.e. the end user must be unaware of the command being executed). The exceptions to this general rule are the ''channel_tune'' and the ''open_ui_state'' commands. The following table presents the behavior defined for the commands currently supported by Graphene devices.
{| class="wikitable"
|-
! Command!! STB Behavior in STBY
|-
| [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Client_Software_Upgrade client_software_upgrade]|| As requested by product team in [https://gvuproducts.aha.io/features/GTV-84 GTV-84] the upgrade must be executed once the recordings that might be taking place are over, without any warning to the end user.
|-
| [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Update_Audio_for_Live_Channel update_audio_for_live_channel]|| The command is executed without any change in the UI (the STB remains in STBY)
|-
| [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Update_Variable update_variable] || The command is executed without any change in the UI (the STB remains in STBY)
|-
| [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Get_Variable get_variable] || The command is executed without any change in the UI (the STB remains in STBY)
|-
| [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Reset_Device reset_device] || As requested by product team in [https://gvuproducts.aha.io/features/GTV-84 GTV-84] the reset must be done immediately, regardless recording status of the STB, and without any warning to the end user.
|-
| [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Open_UI_State open_ui_state] || The command is not executed if the STB is in STBY.
|-
| [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Remote_Certification remote_certification] || The command is executed without any change in the UI (the STB remains in STBY)
|-
| [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Pin_Reset pin_reset] || The command is executed without any change in the UI (the STB remains in STBY)
|-
| [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Flush_Event_Queue flush_event_queue] || The command is executed without any change in the UI (the STB remains in STBY)
|-
| [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Reload_Account_Status reload_account_status] || The command is executed without any change in the UI (the STB remains in STBY)
|-
| [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Get_QoS_Status get_qos_status] || The command is executed without any change in the UI (the STB remains in STBY)
|-
| [https://wikis.tid.es/gvp-dev/index.php/TVOpen_Notifications_and_Commands#Flush_EPG flush_epg] || The command is executed without any change in the UI (the STB remains in STBY)
|-
|}
