RDK Telco Voice Manager

Introduction

RDK Telco Voice Manager is a component that manages the vendor voice stack through TR104 configuration. 
It is responsible for :

• Managing TR104 data model and persistent storage of the VOIP
• Configuring and managing the life cycle of the vendor voice application through JSON HAL
• Monitoring the network events
• Managing voice firewall rule data via pub/sub events
• Generating TelcoVOIP Harvester report (The component supports data model for generating diagnostics report)

Architecture

The RDK Telco Voice Manager consists of

• Data Models : TR104 V1/V2 objects and Custom objects
• Network Monitor : Monitors the network events and manages the lifecycle of vendor voice process
• Persistent storage : Stores the data model object values in JSON format that needs to be persistent across reboot
• JSON HAL : Telco Voice Manager creates JSON HAL client thread and connects with HAL server for exchanging data with vendor stack using JSON RPC messages
• Controller : Subscribe for events to vendor stack
• Diagnostics Report: Generate statistics

Data Model

• RDK Telco Voice Manager owns standard TR-104 DML and additional custom DML objects

• Supports both TR104v1 or TR104v2 version of data model
• By default V1 data model is supported. TR104V2 can be enabled by adding the below distro feature into 
  OEM machine configuration file

DISTRO_FEATURES_append = " rdkb_voice_manager_dmltr104_v2“

Custom Data Models

RDK Telco Voice Manager has a set of custom TR-104 data objects to manage voice service better. Few of them are listed in the below table

JSON HAL

JSON HAL client and server library modules are used to send and receive JSON based RPC requests/responses between the RDK Telco Voice Manager and the Vendor software.

JSON HAL Client

• Integrated and Initialised by Telco Voice Manager
• Connect with HAL server to communicate with vendor stack through json messages

JSON HAL Server

• JSON HAL server library can be used by the vendor application to receive actions from RDK manager application and do necessary platform level stuffs
• The vendor application that has HAL server library integrated will receive the JSON rpc request from the RDK Telco Voice Manager, process the request and sends the JSON based response back to the Manager
• The HAL server also helps to dispatch events to the RDK Manager based on the event subscription

JSON HAL Schema

• JSON HAL Schema should be used as the SLA between RDK and Vendor
• There are 2 versions of HAL schema files “telcovoice_hal_schema_v1.json “ and “telcovoice_hal_schema_v2.json “ available in Telco Voice Manager
• Telco Voice Manager picks the right version of schema file based on the selected TR104 data model version

During Initialisation, Telco Voice Manager sends all default configurations stored in the persistent file “/opt/secure/telcovoice_config_current.json” as a single JSON HAL set request to the voice stack and initialises the data model objects with default values.

Startup Sequence

Voice Manager- Network Monitor

Once all initialisation is complete, Telco Voice Manager creates the network monitor thread to listen to the WAN events. Based on the WAN event received it then controls the vendor voice process.

Voice Manager register for below sysevents and act

• telcovoicemgr_ipaddr_family : Received upon changing IpAddressFamily IPv4 or IPv6
• ipv4_connection_state : Possible value for this event is “up” or “down”. Voice uses this event if IPv4 IpAddressFamily is configured
• ipv6_connection_state : Possible value for this event is “up” or “down”. Voice uses this event if IPv6 IpAddressFamily is configured

RDK Voice Manager sends the following parameters together in one single JSON HAL set request to the SoC voice stack when the WAN connection is successfully established.

• Devices.Services.VoiceService.{i}.X_RDK_Enable : Enable or Disable voice process based on the value
• Device.Services.VoiceService.{i}.X_RDK_IpAddressFamily : IPv4 or IPv6
• Device.Services.VoiceService.{i}.X_RDK_BoundIpAddr: Holds the current IP address of the interface on which the Voice will be running
• Device.Services.VoiceService.{i}.X_RDK_DnsServers: IPv4/IPv6 DNS server addresses based on the IpAddressFamily configured

Voice Manager - Controller

RDK Manager subscribes for events coming from vendor stack. The HAL server publishes the events to the RDK Manager based on the event subscription.

Subscribe Event

• RDK Telco Voice Manager uses the json hal api “json_hal_client_subscribe_event(event_callback callback, char* event_name, char* event_notification_type)” to register for event
• Voice Manager subscribes for firewall data events that are published from voice stack
  • Ex: Subscribe Event Name : Device.Services.VoiceService.{i}.X_RDK_Firewall_Rule_Data

Publish Event

• Vendor Stack publishes the event using json hal server API “json_hal_server_publishevent (char* event_name, char *event_value)”
  • Publish Event Name : Device.Services.VoiceService.{i}.X_RDK_Firewall_Rule_Data
• Telco Voice Manager receives the published event and handles

Subscribe Event Notification Type: onChange, onChangeSync, onChangeSyncTimeout

• There are 2 types of subscribe events, Blocking and NonBlocking event
• When the event is subscribed with "onChangeSync ", the HAL server that publishes the event is blocked until call back response is obtained
• When the event is subscribed with "onChangeSyncTimeout ", the HAL server that publishes the event is blocked until the timeout expires

Subscribe Event Json Message

{
"module":"voicehal",
"version":"0.0.1",
"reqId":"00000104",
"action":"subscribeEvent",
"params":[
{
"name":"Device.Services.VoiceService.1.X_RDK_Firewall_Rule_Data",
"notificationType":"onChange"
}
]
}

Persistent Storage

• Telco Voice Manager uses JSON based persistent storage file stored as “/opt/secure/telcovoice_config_current.json”
• CJSON library is used to manage(read/parse/write) the persistent storage file
• The datamodel “Device.Services.VoiceService.1.X_RDK_FactoryReset” can be used to reset the voice datamodels to default values
• Upon setting this datamodel, Telco Voice Manager replaces the current config file “telcovoice_config_current.json” with default configuration file “telcovoip_config_default.json” and sends 
  json hal message to set the default configuration values down to the vendor stack

Additional Feature

Voice Diagnostics Report

• Telco Voice Manager fetches data from Voice Stack at a regular interval and generate statistics report
• Introduced new datamodel “Device.Services.X_RDK_Report.Voice.” to support voice report feature
• Feature can be enabled by setting “Device.Services.X_RDK_Report.Voice.Enabled” as TRUE
• Interval can be configured using “Device.Services.X_RDK_Report.Voice.ReportingPeriod “
• Report is sent to cloud server through Webpa

Porting

Distro Features

RDK Telco Voice Manager can be enabled by adding the following distro features into OEM machine configuration file,

• rdkb_telcovoice_manager
• rdkb_voice_manager_dmltr104_v2 : Used to enable TR104v2 data model version. 

DISTRO_FEATURES_append = " rdkb_telcovoice_manager "
DISTRO_FEATURES_append = " rdkb_voice_manager_dmltr104_v2"

Global CFLAGS

CFLAGS can be added in OEM machine configuration files as TARGET_CFLAGS, so it will be available across the build system

• FEATURE_RDKB_TELCOVOICE_MANAGER is the global CFLAG used for Telco Voice Manager feature
• FEATURE_RDKB_VOICE_DM_TR104_V2 is the global CFLAG used for TR104 v2 data model support

Package Group

To enable the RDKB Telco Voice Manager in the final build target, add the following section into the packagegroup bb file,

RDEPENDS_packagegroup-rdkb-wanmanager_append = " ${@bb.utils.contains('DISTRO_FEATURES', 
'rdkb_telcovoice_manager', rdktelcovoicemanager', '', d)} "

Yocto Recipes

All the new recipes are available in meta-rdk-broadband layer. 
Path: https://code.rdkcentral.com/r/plugins/gitiles/components/generic/rdk-oe/meta-rdkbroadband/+/refs/heads/rdk-next/recipes-ccsp/ccsp/
Recipe name : rdktelcovoicemanager.bb 

JSON HAL Conf

• Telco Voice manager requires the configuration file [telcovoice_manager_conf.json] to establish the JSON HAL connectivity with server
• This configuration file contains the JSON HAL schema file path and the server port which the vendor software uses to run the HAL server
• The conf file path is passed as a parameter to json_hal_client_init () to initialise json-hal-client library

{
"hal_schema_path": "/etc/rdk/schemas/telcovoice_hal_schema.json",
"server_port":40104
}

1.What does SLA stand for?

SLA stands for “Service Level Agreement”. JSON HAL schema act as an agreement between the RDK and Vendor on defining the data model object path, data model value patterns , datatype of objects etc. JSON HAL lib validates the parameters exchanged between RDK Manager and Vendor against the respective JSON schema field.

2. How is the JSON HAL conf file provided to the JSON HAL server? Here /opt/secure/telcovoice_config_current.json?

JSON HAL Conf file is maintained by RDK Telco Voice Manager in the build folder (RdkTelcoVoiceManager/config/telcovoice_manager_conf.json) and is installed as  “/etc/rdk/conf/telcovoice_manager_conf.json”. “opt/secure/telcovoice_config_current.json” is the persistent storage file.

3. Where does the vendor software registration happen?

Vendor Software Registration happens below HAL. Vendor should implement their own JSON HAL server by using JSON HAL Server library package to receive the json messages from Telco Voice Manager and initiate vendor application registration.

4. How does the Telco manager pick right version of schema file?

Telco Voice Manager depends on the distro feature flag “rdkb_voice_manager_dmltr104_v2” to pick the right version of schema file. It install V2 schema file if “rdkb_voice_manager_dmltr104_v2” DISTRO feature is enabled in OEM machine configuration file, otherwise v1 schema file is installed.