CDRouter Support

CDRouter USP User Guide

user-guide version 11.0

Introduction

User Services Platform

The User Services Platform (USP), as defined in Broadband Forum TR-369, is the next generation of the TR-069 protocol. It’s lighter weight, more flexible and adds some powerful new features.

In the TR-069 domain all messages are transported over HTTP or HTTPS. In some cases, XMPP is used for connection requests. In contrast, USP has far more combinations to test. Messages can be transported over WebSockets, CoAP, or STOMP each with optional encryption. Additionally, each exchange between endpoints can optionally use a session context, optionally encrypt the USP payload and optionally segment payloads at the USP layer.

The CDRouter USP add-on adds USP test capabilities to CDRouter, allowing you to test under all the conditions mentioned in a simple easy to configure way.

The full specification for USP can be found at usp.technology.

Terminology

Term Description
Agent An Agent is an Endpoint that exposes Service Elements to one or more Controllers.
Controller A Controller is an Endpoint that manipulates Service Elements through one or more Agents.
Endpoint An Endpoint is a termination point for a Message.
Record The Record is defined as the Message Transfer Protocol (MTP) payload, encapsulating a sequence of datagrams that comprise the Message as well as providing additional metadata needed for providing integrity protection, payload protection and delivery of fragmented Messages.
Endpoint ID A unique identifier assigned to a USP endpoint.
MTP Message Transport Protocol, the protocol used to transport USP records.
Message The payload within the USP record.
Session Context A set of additional fields that are exchanged between USP endpoints which allow either side to reassemble out of order records, request retransmission of missed records, authenticate messages as coming from allowed endpoints and encrypt messages to allow secure communication between endpoints.
Path A MTP specific string which is used in the transportation of USP messages between endpoints.
USP Encryption A method of encrypting the USP payload with TLS that is available when using session contexts.

Requirements and License

CDRouter USP is available for CDRouter 11.0 and newer releases only.

Licensing

CDRouter USP is a licensed add-on that must be purchased from QA Cafe. For information on upgrading a license to include CDRouter USP or any other add- ons, please contact sales@qacafe.com.

CDRouter will report the status of all available add-ons during the installation process and during start-up. To verify that CDRouter USP is enabled on a system, run the command cdrouter-cli -info as root and look for the line USP is enabled, as shown below. If this line is present, CDRouter USP is enabled and ready to use.

$ cdrouter-cli -info

Starting /usr/cdrouter/bin/cdrouter-cli Thu Mar 15 11:12:22 EDT 2018
Copyright (c) 2001-2018 by QA Cafe
Version 11.0 build 0 (b1081f6e0 master), built 2018-03-14 10:51:06 by nightly@cdr-forge6.lan (x86_64)
OS: CentOS Linux 7.4.1708 (4.4.87-1.el7.qacafe.x86_64)
CPU: Intel(R) Core(TM) i5-7600K CPU @ 3.80GHz
Loaded modules from: '/usr/cdrouter/tests'
Start command: /usr/cdrouter/bin/cdrouter-cli -info
System ID: b2d8619a16720c7c3fc0835500badc15
Registered to: qacafe
Maintenance, support and upgrades until: 2085-01-01
Test suite: cdrouter
    Multiport   is enabled
    IPv6        is enabled
    Storage     is enabled
    IKE         is enabled
    TR69        is enabled
    TR69-EDM    is enabled
    Nmap        is enabled
    BBF.069     is enabled
    SNMP        is enabled
    Performance is enabled
    ICS         is enabled
    DOCSIS      is enabled
    USP         is enabled

Test Methodology

Overview

The network topology of USP endpoints is highly flexible by design. In CWMP the only topology is one in which the TR-069 client is either a gateway or behind a gateway on the LAN side of a network and a single ACS sits somewhere on the internet. While this configuration is still valid in USP, it is by no means the only option. The USP standard was designed not only from the perspective of organizations controlling their products remotely but also from consumers controlling the products in their home. For this reason USP is designed to enable the configuration of an agent from one or more controllers that exist within the same network.

CDRouter is capable of testing common USP network topologies. CDRouter’s USP controller will always be configured on CDRouter’s simulated WAN, but a directly connected agent can be tested using any of the MTPs. Additionally with WebSockets and STOMP, an agent can be placed behind a gateway. For all USP testing CDRouter’s full suite of network address provisioning mechanisms are available for use.

The USP add-on supports all MTPs with or without TLS over both IPv4 and IPv6 and with or without USP layer encryption. All the defined message types are supported as well as segmentation of both USP records and TLS records at the USP layer.

The following MTP, MTP encryption, USP encryption, IP version options are testable using the USP CDRouter addon:

MTP Supported MTP Encryption Supported USP Encryption Supported IP Versions Supports USP Segmentation
WebSocket TLS or None TLS v1.2 or None IPv4 or IPv6 Yes
STOMP TLS or None TLS v1.2 or None IPv4 or IPv6 Yes
CoAP DTLS or None TLS v1.2 or None IPv4 or IPv6 Yes

What is not supported:

The record integrity validation fields mac_signature and sender_cert fields will not be populated by CDRouter when sending a record. Additonally, when CDRouter receives a USP record with those fields set they will be silently ignored and no integrity checks will be done.

When using TLS at the USP layer CDRouter uses a certificate that does not include the controller’s endpoint ID in the subjectAltName field. This is because the certificate used by CDRouter’s controller is signed by a trusted CA and the controller’s endpoint ID is configurable. Additionally CDRouter will not validate that the subjectAltName of certificates sent by an agent contains the endpoint ID of the agent. If the agent being tested validates the subjectAltName in the certificate it receives from the controller this can be overcome by providing certs for the controller to use by setting uspControllerUSPCertPath and uspControllerUSPCaCertPath to the path to a certificate/CA certificate pair that the agent will accept (note that this may also require setting uspControllerID to match the endpoint ID in the subjectAltName in the provided certificate).

Initial Setup

CDRouter’s USP controller runs on the WAN interface. This presents three possible setups for testing USP Agents.

Test Setup #1

If the USP Agent is accessible via the WAN connection on a gateway, the setup is the same as the basic CDRouter test setup for CWMP:

Test Setup #2

If the USP Agent is on an end-device, you can use an additional gateway as part of your test setup. Usually, this setup does not involve the use of the CoAP MTP.

Test Setup #3

Alternatively, you can connect a USP Agent directly to CDRouter’s WAN port and run your testing without the LAN port configured.

Configuration

Enabling the Controller

In order to run any of the USP test cases the USP controller must be enabled. This is done by setting supportsUSP to “yes”.

testvar supportsUSP yes

Configuring the Controller

Setting the Controller ID

If the USP agent expects the controller to have a specific endpoint ID this can be configured by setting uspControllerID to the desired ID.

testvar uspControllerID  myControllerID

Setting the Controller’s Address

The USP controller can be configured to run over IPv4 or IPv6. This is done by setting uspControllerIpMode to either “ipv4-only” or “ipv6-only”.

Once a IP version has been selected the controller’s IP address can be configured by setting uspControllerIpv4 for an IPv4 address

testvar uspControllerIpMode ipv4-only
testvar uspControllerIpv4   6.0.0.2

or uspControllerIpv6 for an IPv6 address.

testvar uspControllerIpMode ipv6-only
testvar uspControllerIpv6 6000::2

CDRouter will also add a DNS entry mapping the configured IP address of the controller to a domain name. To specify the domain named used set uspControllerDomain to the desired domain name.

Setting the MTP

CDRouter has support for all three MTPs:

-WebSockets
-CoAP
-STOMP

To configure the specific MTP set uspControllerMTP to “stomp”, “coap” or “websocket”. If using WebSockets or CoAP the path component of the controller’s endpoint URI can be configured using uspControllerPath. The testvar uspControllerPath is also used to configure the destination controller subscribes to on the STOMP server.

MTP Layer Encryption

To enable MTP level TLS set uspControllerMTPEncryption to “yes”. CDRouter will select the correct encryption method for the selected MTP, TLS for WebSockets and STOMP and DTLS for CoAP.

testvar uspControllerMTP           coap
testvar uspControllerMTPEncryption yes
testvar uspControllerPath          /controllerendpoint

By default the USP controller will use wildcard certificates signed by Comodo for MTP layer encryption. If a different set of certificates should be used, it can be configured by setting uspControllerMTPCertPath and uspControllerMTPCaCertPath to the appropriate paths.

testvar uspControllerMTPCertPath     /home/qacafe/mycert.pem
testvar uspControllerMTPCaCertPath   /home/qacafe/mycert-ca.pem

To specify the port the controller should listen on for incoming connections set uspControllerPort to the desired port number. Setting this testvar to “auto” will cause CDRouter to use the default port for the MTP based off the values of uspControllerMTP and uspControllerMTPEncryption.

Additional Configuration for STOMP

When using STOMP as the MTP, CDRouter will configure the login credentials on the STOMP server using uspControllerUsername and uspControllerPassword. Additionally CDRouter’s STOMP server can be configured to only accept specific values in the “host” header of the STOMP frame by setting uspControllerHost to the value the agent will provide.

Setting the Controller’s Default USP Behavior

CDRouter’s default behavior when it starts a new USP session can be configured.

By default the USP controller will wait 30 seconds for an agent to reply to a message. This can be configured by setting uspMessageTimeout.

testvar uspMessageTimeout 90
USP Layer Encryption

By default the USP controller will not use session contexts, nor will it use USP level security. To enable the use of session contexts set uspControllerUseSessionContext to “yes”. If uspControllerUseSessionContext is set to “yes”, it is also possible to configure the controller to use USP level security by setting uspControllerUSPEncryption to “yes”.

testvar uspControllerUseSessionContext   yes
testvar uspControllerUSPEncryption       yes

CDRouter’s USP controller will also use the Comodo signed certs by default for USP layer encryption. If a different set of certificates should be used, it can be configured by setting uspControllerUSPCertPath and uspControllerUSPCaCertPath to the appropriate paths.

testvar uspControllerUSPCertPath      /home/qacafe/mycert.pem
testvar uspControllerUSPCaCertPath    /home/qacafe/mycert.pem

Configuring the Agent

Agent IP Address

The IP address of the agent is needed to allow the controller to connect to the agent. If the agent will be getting an address from CDRouter both uspAgentIp testvars can be set to “auto”.

If the agent already has a IPv4 or IPv6 address, set uspAgentIpv4 and uspAgentIpv6 respectively.

testvar uspAgentIpv4 10.0.0.6
testvar uspAgentIpv6 auto

USP Settings on the Agent

The USP controller will send messages to the agent using the agent ID set in uspAgentID. If the value of this testvar does not match the agent’s endpoint ID the controller will ignore messages from the agent, and packages will not pass start.

The port on which the agent is listening for a connection is set by configuring uspAgentPort to the port number. If the value “auto” is used, the default port for the MTP will be selected the same way it is for uspControllerPort.

The agent resource path is set by configuring uspAgentPath to the URI.

USP Controller Discovery via DHCP

CDRouter supports the DHCPv4 and DHCPv6 USP controller discovery mechanisms defined by: Use of DHCP for Acquiring Controller Information.

When an agent requests information about a controller, a URL for the controller will be returned. The URL for the controller will be constructed from the values of the following testvars:

USP Scenario Testing

Much like CWMP Scenario testing available in the tr-069 add-on, USP scenarios can be used to simplify the process of writing test cases to validate the basic behavior of USP enabled devices.

There are two ways to execute USP scenario files.

  1. uspScenarioPath - This testvar can be set to the location of a USP scenario file which will be loaded into CDRouter at start, and run when using the usp-scenarios.tcl module.

  2. uspScenarioBootstrap - This testvar can be set to the location of a USP scenario file which will loaded and run at start. This is a quick and easy way to configure settings on the USP agent before starting any of the other tests.

Syntax

The syntax of a USP scenario is very similar to a CWMP scenario.

Basic Actions Description
Get Sends a USP Get message to the agent from the configured controller.
Set Sends a USP Set message to the agent from the configured controller.
Add Sends a USP Add message to the agent from the configured controller.
Delete Sends a USP Delete message to the agent from the configured controller.
GetSupportedDM Sends a USP GetSupportedDM message to the agent from the configured controller.
GetInstances Sends a USP GetInstances message to the agent from the configured controller.
GetSupportedProtocol Sends a USP GetSupportedProtocol message to the agent from the configured controller.
Operate Sends a USP Operate message to the agent from the configured controller.
Open Opens a connection to the agent from the configured controller.
Delay Pauses execution of the next action for a specified amount of time.
WaitFor Waits for a Notify message of a specific type from the agent.
MetricEval Controls whether or not the actions will trigger PASS or FAIL metrics.

This is a simple example of a script that sets a value and validates that it was set.

USP myScenario {
    Set {
        parameter Device.LocalAgent.Controller.1.Alias "My Controller" 1
    }

    Get {
        parameter Device.LocalAgent.Controller.1.Alias
        verify Device.LocalAgent.Controller.1.Alias "My Controller"
    }
}

Get

This action sends a USP Get message to the configured USP agent, and optionally validates any response.

  • parameter <param>
    • <param> - Parameter to include in the Get message. This value can be any string including invalid paths and search paths.
  • verify <param> <value>
    • <param> - Validate that this parameter is in the GetResp.
    • <value> - Validate that the specified parameter has this value. Regular expressions are accepted.
  • verify_missing <param>
    • <param> - Validate that the specified parameter is not included in the GetResp.
  • expect_error - Expect the last parameter added to this action to fail, will cause a metric fail if it doesn’t.
  • faultcode <value>
    • <value> - If the last parameter added to this action fails, verify the error code matched this value.

Get Example

Get {
    parameter Device.LocalAgent.Controller.
    verify Device.LocalAgent.Controller.1.Alias "My Controller"
    faultcode 7016

    parameter Device.LocalAgent.ParameterThatDoesNotExist
    expect_error

    parameter Device.LocalAgent.Subsription.\[Enable=="true"\].Alias
    verify_missing Device.LocalAgent.Subscription.5.Alias
}

When using the verify command to validate that a parameter returned by the agent matches an expected value there are several options for specifying the expected value.

  • The exact value can be provided, which will be directly compared to the parameter in the GetResp
  • The value [any] can be used to accept any value
  • The value [accept value1 value2] can be used to to accept any of the values provided (value1 or value2 in this example)
  • The value [regexp {[0-9][1-3].+}] can be used to accept any value that matches the provided regular expression

Set

This action sends a USP Set message to the configured USP agent.

  • parameter <param> <value> <required>
    • <param> - Parameter to be set.
    • <value> - Value to set the parameter to.
    • <required> - Boolean 1 or 0 to specify if setting this parameter is required.
  • allow_partial - Sets the allow partial flag on the Set message to true.
  • faultcode <value>
    • <value> - If the agent send and error message as a response, validate the error code matches this value.
  • expect_param_error <param> <faultcode> - This will cause CDRouter to expect a parameter error.
    • <value> - The parameter on which the error is expected to occur.
    • <faultcode> - The faultcode expected from the parameter error.
  • verify_success <param>
    • <param> - Validates that this parameter was successfully set.
  • expect_error - Expect the agent to send an error message.

Set Example

Set {
    parameter Device.LocalAgent.Controller.1.Alias "My Controller" 1
    parameter Device.LocalAgent.ParameterThatDoesNotExist "Bound to Fail" 1
    faultcode 7015
}

Set {
    parameter Device.LocalAgent.ParameterThatDoesNotExist "Bound to Fail" 0
    expect_param_error Device.LocalAgent.ParameterThatDoesNotExists 7010
}

Add

This action sends a Add message to the configured USP agent.

  • path <partial path>
    • <partial path> - This is the path to the table to which a new instance should be added.
  • parameter <param> <value> <required>
    • <param> - Parameter to be set in the newly added instance. This should be the complete path to the parameter, without the last instance number (see example).
    • <value> - Value of the parameter to set.
    • <required> - Boolean 1 or 0 to specify if setting this parameter is required.
  • allow_partial - Sets the allow partial flag on the Add message to true.
  • instance <variable name>
    • <variable name> - Bind the instance number of the newly created object to a variable with this name. This value can be used later by accessing its value via %<variable name>%.
  • faultcode <value>
    • <value> - If an error code is present in the AddResp, validate that it is this value.
  • expect_error - This will cause this action to fail in the event the message succeeds, and will only pass if one the expected faultcodes is returned.
  • expect_partial_failure <faultcode> - This will cause CDRouter to expect a partial failure on the last path referenced with the specified faultcode.
  • expect_param_error <param> <faultcode>
    • <param> - Expect this parameter of an added object to fail to be set.
    • <faultcode> - The expected error code for the failed parameter.

Example Add

Add {
    path Device.LocalAgent.Subscription.
    parameter ReferenceList "Device.IP.Interface.1.Enable" 1
    instance interfaceSubscription

    path Device.LocalAgent.Subscription.
    parameter BadParam "Bad Value" 1
    expect_partial_failure 7017

    allow_partial
}

Delete {
   path Device.LocalAgent.Subscription.%interfaceSubscription%.
}

Delete

This action sends a Delete message to the configured USP agent.

  • path <object>
    • <object> - The path to the instance to delete.
  • allow_partial - Sets the allow partial flag on the Delete message to true.
  • faultcode <value>
    • <value> - If an error code is present in the DeleteResp, validate that it is this value.
  • expect_error - Except the agent to respond with an error message.
  • expect_partial_failure <faultcode> - Expect the last path references in this action to fail with the specified error code.
  • expect_param_error <param> <code>
    • <param> - Full path to the parameter expected to object expected to fail.
    • <code> - The err_code expected with the associated failure.

See Add example for usage.

GetSupportedDM

  • path <path>
    • <path> - The requested root for the GetSupportedDM.
  • return_commands - This will request that commands are returned in the GetSupportedDMResp.
  • return_events - This will request that events are returned in the GetSupportedDMResp.
  • return_params - This will request that parameters are returned in the GetSupportedDMResp.
  • verify_param <param>
    • <param> - Validate that this parameter is included in the GetSupportedDMResp.
  • verify_event <event>
    • <event> - Validate that this event is included in the GetSupportedDMResp.
  • verify_command <command>
    • <command> - Validate that this command is included in the GetSupportedDMResp.
  • faultcode <faultcode> - If the agent responds with an error message, ensure the error code matches the specified faultcode.
  • expect_error - Expect the agent to send an error message.

Example GetSupportedDM

GetSupportedDM {
    path Device.
    return_commands
    return_params
    return_events

    verify_param Device.DeviceInfo.ModelVersion
    verify_event Device.Boot!
    verify_command Device.Reboot()
}

GetInstances

This action sends a GetInstances message to the configured USP agent

  • path <path>
    • <path> - Requested root for the GetInstances message.
  • first_level_only - This will cause the first_level_only flag in the GetInstances message to be set to ‘true’.
  • faultcode <faultcode> - If the agent responds with an error message, ensure the error code matches the specified faultcode.
  • expect_error - Expect the agent to send an error message.

Example GetInstances

GetInstances {
    path Device.
}

GetSupportedProtocol

This action sends a GetSupportedProtocol message to the configured USP agent

  • expect_error - Expect the agent to send an error message.

Example GetSupportedProtocol

USP myScenario {
    GetSupportedProtocol
}

Operate

This action sends an Operate message to the configured USP agent

  • operation <name>
    • <name> - The full path of the command to be executed.
  • arg <name> <value>
    • <name> - The name of the argument.
    • <value> - The value of the argument.
  • command_key <value>
    • <value> - The command key to use for this Operate message.
  • send_resp <value>
    • <value> - Boolean 0 or 1 controlling the value the send_resp field is set to in the Operate message.
  • faultcode <value>
    • <value> - If an error code is present in the OperateResp, validate that it is this value.
  • expect_error - This will cause this action to fail in the event the message succeeds, and will only pass if one the expected faultcodes is returned.

Example Operate

USP myScenario {
    Operate {
        operation Device.DeviceInfo.VendorLogFile.4.Upload()
        arg URL http://200.23.0.22
        arg Username qacafe
        arg Password qacafe123
        faultcode 7022
    }
}

Delay

Add a delay between actions

Example Delay

USP myScenario {
    Set {
        parameter Device.LocalAgent.Controller.1.Alias "My Controller" 1   
    }

    Delay 10

    Get {
        parameter Device.LocalAgent.Controller.1.
        verify Device.LocalAgent.Controller.1.Alias "My Controller"
    }
}

WaitFor

Wait for a notification from the configured USP agent and validates the values.

  • ValueChange - Waits for a ValueChange notification.
    • verify_path <path> - Ensures this path is included in the notification.
    • verify_value <value> - Validate that the value of specified path matches this.
  • Event - Waits for an Event notification.
    • verify_path <path> - Validate that the event path matches <path>.
    • verify_name <event_name> - Validate that the event name matches <event_name>.
    • verify_arg <name> <value> - Validate that argument <name> is <value>.
  • ObjectCreation - Waits for an ObjectCreation notification.
    • verify_path <path> - Validate that the path in the notification matches <path>.
    • verify_key <name> <value> - Validate that the key value pair <name>,<value> is among the keys.
  • ObjectDeletion - Waits for an ObjectDeletion notification.
    • verify_path <path> - Validates that <path> is in the notification.
  • OperationComplete - Waits for an OperationComplete notification.
    • verify_path <path> - Validates that <path> is in the notification.
    • verify_command_key <name> - Validates the command key in the notification is <name>.
    • verify_command_name <name> - Validates the command name in the notification is <name>.
    • verify_arg <name> <value> - Validated that key value pair <name>, <value> is among the arguments in the notification.
  • OnBoardRequst - Waits for an OnBoardRequst notification.
    • verify_oui <oui> - Validates the OUI in the OnBoadReqest matches <oui>.
    • verify_product_class <product_class> - Validates the product class in the OnBoadReqest matches <product_class>.
    • verify_serial_number <serial_number> - Validates the serial number in the OnBoadReqest matches <serial_number>.
    • verify_protocol_version <version> - Validates the version in the OnBoadReqest matches <version>.

Example WaitFor:

Add {
    path Device.LocalAgent.Subscription.
    parameter ReferenceList Device.DeviceInfo.UpTime
    parameter Enable true
    parameter NotifType ValueChange
}

WaitFor {
    ValueChange {
        path Device.DeviceInfo.UpTime
    }
}

MetricEval

Turns on or off metric evaluations for actions after this command.

MetricEval off

Set {
    parameter Device.SomeParameterThatMightNotExist "My Value"
}

MetricEval on

New Test Case Support for Scenarios

USP scenarios introduces the ability to use scenarios inline in test cases. This can greatly improve the readability of simple operations while still providing the flexibility of more complex actions.

An inline scenario is used by calling USP_scenario_with_stack and giving it a valid USP controller stack. USP_scenario_with_stack <stack> <scenario>

USP_scenario_with_stack uspServer {
    Log {"Starting test setup"}
    Add {
        path Device.LocalAgent.Subscription.
        parameter NotifyRetry false 1
        instance sub1
    }
}

USP Profile Testing

Much like CWMP Profile testing, CDRouter is able to perform USP profile tests to ensure a USP agent has correctly implemented all the required parameters of a data model’s profile.

The following profile test modules are available:

  • USP_Device2_profile.tcl
  • USP_FAPService2_profile.tcl
  • USP_StorageService1_profile.tcl
  • USP_STBService1_profile.tcl
  • USP_VoiceService1_profile.tcl

For each profile, CDRouter defines several generic tests that verify the consistency of the profile:

  1. Verify all required parameter names are returned using Get
  2. Verify all required parameters exist using GetSupportedDM
  3. Verify the read and write status of each parameter using GetSupportedDM
  4. Verify all writable parameters can be set using Set
  5. Verify the creation and deletion of all creatable objects using Add and Delete

Configuring Which Profiles are Tested

CDRouter has the ability to skip unsupported profiles automatically after specifying what the agent supports.

The agent’s supported data model can be configuring using the testvar uspSupportedDataModel, which supports several different options. Setting this testvar to the keyword all indicates that the agent supports every profile from all officially defined USP data models:

testvar uspSupportedDataModel "all"

A list of top level data models can be specified to indicate that all the profiles in only those data models are supported:

testvar uspSupportedDataModel {Device:2.12 VoiceService:2.0}

A DeviceSummary string as defined in Section 3.7 of TR-106 can also be specified:

testvar uspSupportedDataModel {Device:2.12[](Baseline:2),VoiceService:2.0[1](Baseline:1)}

When specifying a supported data model and its version, the profile version tested will be the most recent version which was included in the minor version specified. This means that values like this:

testvar uspSupportedDataModel {Device:2.1[](Baseline:3)}

will skip the baseline profile because the 3rd version of the Baseline profile did not exist in version 2.1 of the Device data model.

Custom USP Profiles

CDRouter supports user defined profiles. To test a user defined profile, set the testvar uspProfileName to the name of the profile you would like to test and uspProfilePath to the unix file path to the XML file containing profile.

Note: in CWMP profile testing, there is support for specifying profiles in XML format as well as QA Cafe’s proprietary format. The proprietary format is not available as a file format for USP profile testing.

To then test this custom profile, after setting the testvars, run the usp_datamodels.tcl test module.

Example config:

testvar_group usp_profile_1 {
    testvar uspProfileName     STOMPHeartbeats:1
    testvar uspProfilePath     /home/qacafe/my-usp-profile.xml
}

It is also possible to not specify a usp_profile in the config file and still run the usp_datamodels.tcl module. In this case, a GetSupportedDM message will be sent to the agent requesting the entire data model. The resulting data model returned by the agent will be used as one large profile for the tests in this module.

Excluding USP Parameters

In some cases, you may wish to exclude a parameter from the USP profile check because it is not supported by the device under test. CDRouter allows you do to this by configuring a list of parameters to skip in the uspSkipParameters testvar. A list of parameters can be specified by enclosing the list members between “{“ and “}”. The list of parameters can be either full instances or generic instances that use “{i}” for each instance index. Note that each individual parameter within the list must be specified using a full instance or partial path, or a fully generic instance using “{i}” for each index. Parameters cannot be specified using a mix of generic and full instances. Here is an example:

testvar uspSkipParameters {
  Device.DeviceInfo.ModelName
  Device.USP.InterfaceNumberOfEntries
}

If you are skipping an entire object path and all parameters contained below it, you only need to specify the top object path. All top object paths (partial paths) must end with a ‘.’ character. For example, if the device under test does not support the Stats object from a PTM link, you could skip the object by configuring the following uspSkipParameters testvar:

testvar uspSkipParameters {
  Device.PTM.Link.{i}.Stats.
}

Modifying USP Parameters

All USP profiles supported by CDRouter and their corresponding objects and parameters are defined in the /usr/share/doc/cdrouter/usp-profiles directory. The type, requirement, or syntax of any of these pre-defined objects and parameters can be modified using the uspModifyParameters testvar. Like the uspSkipParameters testvar uspModifyParameters supports a list.

When modifying parameters we recommend copying the original parameter definition from the /usr/share/doc/cdrouter/usp-profiles directory and then making the required modifications using uspModifyParameters. Here is an example that modifies the enumeration syntax of the Device.DSL.BondingGroup.{i}.Status parameter to support the additional keywords of auto and foo:

testvar uspModifyParameters {
  string R Device.DSL.BondingGroup.{i}.Status {enumeration {Up Down NotPresent LowerLayerDown}}
}

Likewise, here is an example that changes the requirement of the Device.Time.NTPServer1 parameter from write, W, to read- only, R:

testvar uspModifyParameters {
  string R Device.Time.NTPServer1 {size {maxLength 64}}
}

Note that the syntax argument is optional when modifying parameters. If omitted CDRouter will only overwrite the type and requirement for the specified parameter. As a result the above example can be reduced to this:

testvar uspModifyParameters {
  string R Device.Time.NTPServer1
}

Troubleshooting

Controller is not sending messages

Agent IP configuration

Before the controller will send any USP messages, it will ARP for the agent’s IP. If the agent doesn’t have the correct IP address it will never respond to the ARPs being sent. If the agent is configured to use a static IP ensure it matches what is in the config file. If the agent is configured to get an IP via DHCP, ensure the agent IP address in the config file is either set to “auto” or the DHCP pool is configured to allow for one address and that the appropriate agent IP testvar is set to that address.

If STOMP is being used as the MTP and the agent is getting an IP address but the controller is not sending any messages, ensure the agent is correctly connecting to the STOMP server and subscribing to the correct destination. The controller will not attempt to send any messages until the agent has correctly connected and subscribed to the right destination on the STOMP server. If the agent appears to be attempting to connect to the STOMP server ensure the uspControllerUsername and uspControllerPassword are correctly set to the credentials the agent provides.

Agent not responding to USP messages

If the controller is sending USP messages to the agent’s IP address and not getting a response ensure the following are correctly configured:

  • The MTP the controller is using matches what the agent is expected to use.
  • The port used to accept connections on the agent is correctly configured in the config file.
  • uspControllerID matches what the agent expects the controller ID to be
  • uspAgentID matched the endpoint ID configured on the agent
  • uspControllerUseSessionContext is set to “yes” if the agent is expected to use a session context

Agent’s responses are ignored by the controller

If the controller is ignoring the responses the agent is sending ensure:

  • uspControllerID matches the to_id in the agent’s responses
  • uspAgentID matches the from_id in the agent’s responses
  • The message_id of the message sent to the agent matches the message_id in the agent’s response

Other Issues

TLS

If USP payload security is configured it’s possible there is an issue with the certificate exchange or with the fact that there might be more than one TLS record in a single message.

CoAP

CDRouter expects CoAP ACKs after every message it sends. If the agent doesn’t send a ACK CDRouter will treat the message transmission as a failure.

If the agent doesn’t use the “reply-to” in CoAP messages sent by the controller this can cause issue if the agent doesn’t know the correct path to send replies to.

Controller is dropping messages

If the controller cannot properly decode messages it receives from the agent it will issue a warning in the log and drop it. The most likely reason for a message to not decode properly is an issue with the protobuf encoding.

Contents

×

About CDRouter

CDRouter is made by QA Cafe, a technology company based in Portsmouth, NH.

Get in touch via our Contact page or by following us on your favorite service: