There’s many use cases for TR-069 from a service provider’s perspective. Beyond onboarding, firmware upgrades, and service configuration, however, is the ability to monitor various statistics on devices and network interfaces to help troubleshoot an end-user’s service.
Nearly all of the interfaces in the TR-069 Data Models have statistics on the amount of data sent and received through them, which can be used for this kind of troubleshooting. This is particularly true for the data models that cover Set Top Boxes, which is comprised mostly of this kind of status information.
Using TR-069 Diagnostic Objects
The other way to accomplish this is to use active diagnostics to go through the troubleshooting process. Objects such as Device.IP.Diagnostics.IPPing. or Device.IP.Diagnostics.TraceRoute. can be used when a device is having connectivity problems.
Diagnostic objects are “command” objects, which means they represent additional stateful functionality beyond what is defined in the RPCs of TR-069. Diagnostic objects in particular also use a TR-069 event called “8 DIAGNOSTICS COMPLETE” when the Diagnostic command completes (whether successfully or not).
The order of events when using a Diagnostic object (for example, IPPing) is as follows:
- The ACS uses SetParameterValues (SPV) to set the writeable parameters in the object to reflect the input arguments of the Diagnostic. The ACS also sets the DiagnosticsState parameter to “Requested”.
- The device begins the Diagnostic in accordance with the parameters set in step 1.
- Optionally, the ACS can cancel the diagnostic command by using a SPV call to set the DiagnosticsState parameter to “Cancelled”.
- The device updates the value of DiagnosticsState as the diagnostic is executed.
- When the diagnostic completes (or fails), the device initiates a CWMP Session and includes the “8 DIAGNOSTICS COMPLETE” event.
- The ACS uses GetParameterValues to read the results of the diagnostic.
About command objects
Many objects in the Device:2 Data Model are defined as commands within the data model definition. Command objects usually have a parameter (such as DiagnosticsState in the Diagnostics objects) that allow an ACS to initiate the command by setting the parameter to "Requested". The command executes, and its status is updated in the State object.
The User Services Platform (USP) addresses this differently with a protocol level message called "Operate", used to pass arguments to and initiate data model defined commands.
These commands are considered "asynchronous", so the results are returned to the Controller in a USP Notify message with the type "Event".
TR-143 performance diagnostics
The Broadband Forum defined some additional active diagnostics in TR-143, “Enabling Network Throughput Performance Tests and Statistical Monitoring”. These tests are designed to test the throughput of a given link in real time, using the CWMP Endpoint as a “sink” or test endpoint.
The endpoint connects to a “Network Test Server”, which can be used to do any of the following active diagnostics:
- Download diagnostics using FTP or HTTP
- Upload diagnostics using FTP or HTTP
- Fixed duration (time-based) download/upload diagnostics
These download diagnostics are built to measure the throughput of a link between the network test server and the CWMP Endpoint. There’s a number of use cases for this, but much of it originated from demands by service providers to be able to validate the data rate of a WAN connection. However, it can also be used on a TR-069 device in the LAN to measure the throughput through a gateway, or to troubleshoot in-home network links if the network test server can be located on the gateway or elsewhere.
The full description of all of these tests is covered in Appendix A of TR-143, which explains the Theory of Operations of each test. This includes the proper test sequence and the correct way to calculate the results that are presented by the Endpoint.
Ladder diagram of TR-143 upload diagnostic
Graph of TR-143 conversation and uploaded traffic
TR-143 testing in CDRouter
The tr143_http.tcl test module in CDRouter* ensures that a DUT executes TR-143 based tests correctly as defined in TR-143 and in the IntegetGatewayDevice:1 and Device:2 data models. This includes the performance of HTTP downloads and uploads themselves, the use of DNS versus direct addressing for the network test server, and whether the error conditions are presented correctly. The steps are generally:
- Use CDRouter’s simulated ACS to set the desired parameters for an HTTP download or upload test.
- Initiate the test by setting DiagnosticsState to “Requested”.
- Simulate a network test server, either correctly (to test the actual throughput test), or incorrectly (causing error conditions that should be reported by the DUT).
- Wait for an Inform RPC call containing the “8 DIAGNOSTICS COMPLETE” event.
- Verify the results in the DUT’s data model.
- Use the mechanisms outlined in TR-143 to calculate the download/upload throughput.
Take a look at this capture on CloudShark:
We’ve annotated it so you can see the sequence unfold for an example UploadDiagnostics test.
CDRouter focuses on HTTP download/upload specifically, as this was the most common test scenario we encountered in our own labs when building the test module and verifying the module was ready for our users. If you’re looking for the others, be sure to let our support team know!
Note: the tr143_http.tcl module requires the TR-069 or USP add-on and the Performance add-on for CDRouter.