CWMP Device Operations

This chapter describes the device operations mechanism in Broadband Access Center (BAC). By using this mechanism, you can execute CPE WAN Management Protocol (CWMP) remote procedure calls for a device and perform maintenance tasks such as changing a device's provisioning group.

Overview

You use device operations to execute individual CWMP remote procedure calls (RPCs) against a device immediately, or the next time the device connects to BAC. By using this feature from the provisioning API, you can troubleshoot, collect data, or customize the interaction between a device and BAC.

Device operations are submitted in a batch by using the IPDevice.performOperation() API call. (For details, refer to the API Javadoc.) You can perform some operations from the administrator user interface. This section is focused on describing the concepts behind device operations regardless of whether they are initiated via the API or the administrator user interface.

Note During a BAC installation, several sample files are copied to the BPR_HOME/rdu/samples directory, which contains:

•

The cwmp directory, which features *parameter-list.xml files, which describe parameter lists used to retrieve live device data by using the administrator user interface.

•

The provapi directory, which features CwmpDiagnosticImmediate.java and CwmpDiagnosticOnConnect.java which describe how you can perform device operations by using the API.

Table 14-1 Device Operations Supported in BAC
Operation Name	Description
CreateObjectInstance	Creates object instances within a device's data model
DeleteObjectInstance	Deletes objects from a device's data model
Download	Instructs the device to perform a file download
FactoryReset	Resets a device's settings to its factory default state
Reboot	Instructs the device to reboot
GetParamAttributes	Retrieves attributes for a device's parameters
GetParamNames	Retrieves names of parameters exposed by a device
GetParamValues	Retrieves parameter values from a device's parameter space
GetRPCMethods	Retrieves a device's list of supported RPC methods
SetParamAttributes	Sets the value of device parameter attributes, such as Notification and Access List
SetParamValues	Sets the value of device parameters
ChangeProvGroup	Redirects a device to a new provisioning group
GenerateConfig	Regenerates the instruction set for a device
PassThrough	Sends a generic SOAP message to the device
RemoveOperation	Removes a pending on-connect device operation
RequestConnection	Initiates a connection request to a device

All device operations are executed before other configuration services, such as data synchronization, configuration synchronization, and firmware rules download.

Connection Modes for Device Operations

Immediate Mode

An immediate execution assumes that the device is reachable and is performed by the DPE first issuing a connection request to the device. If the device is not reachable, the operations automatically fail. You can execute multiple operations in the same batch to improve performance, creating a single connection request and, thus, a single management session with the CWMP device.

A client uses a timeout period to post the API batch in immediate mode. If no timeout is set, the duration for immediate operations to time out is, by default, 60 seconds. If a device operation times out or its batch times out, an error is returned.

Note Before attempting to execute immediate operations against a device, ensure that the device is reachable and that BAC is configured to perform connection requests to the device. See Connection Request Service.

When the performOperation() API method is invoked specifying an immediate execution, the RDU constructs and sends corresponding operation instructions to all DPEs in the device's provisioning group. Then, the RDU sends a connection request instruction to a specific DPE within the provisioning group; the DPE, in turn, sends a connection request notification to the device.

When the device establishes a connection with the DPE, the DPE creates a new session and executes the operation upon the device. When the session is closed, the DPE returns the result of the operation to the RDU, which forwards the result to the API client in the Batch's command status.

On-Connect Mode

You can use an on-connect execution to support devices that are not reachable. It is best used in conjunction with periodic Inform RPCs from the CWMP device.

On-connect operations persist at each DPE in the device's provisioning group. They are not removed from the DPEs until the RDU instructs the DPEs to do so (after notifying the client of the execution results via an AsyncOperationEvent).

The API client constructs an IPDeviceOperation specifying an on-connect execution. It registers the appropriate AsyncOperationEvent listeners, then invokes the performOperation() API method. The RDU then constructs and sends corresponding operation instructions to all the DPEs in the device's provisioning group. The DPEs save the operation in their internal database. The RDU batch completes, and the BatchStatus is returned to the API client.

The DPE does not initiate a connection request notification to the device, as it does while executing an immediate operation.

When the device connects to the DPE the next time, the DPE creates a new session with the device and executes the operation upon the device. When the session is closed, the operation result is sent to the RDU, and the RDU sends an AsyncOperationEvent to any registered API client listeners.

Note Immediate operations are always executed before on-connect operations. While you can use BAC to mix modes of operations along with the built-in instructions, you must ensure that the instructions do not override one other. For example, if the device's configuration template specifies false for InternetGatewayDevice.ManagementServer.PeriodicInformEnable and a device operation changes that to true, the configuration template, which runs only after the device operation, overrides it to false.

Conditional Execution

Additionally, immediate and on-connect operations are conditionally executed based on the TR-069 Event Codes in the Inform message from the device. If no intersection occurs between the reported Event Codes in the device's Inform and the list of Event Codes specified in the operation, the operation is not executed.

For example, an operation might be conditional upon the Inform Event Code list including 6 CONNECTION REQUEST. Therefore, the operation only executes if the device reports it is connecting due to an autoconfiguration server (ACS) connection request. If the device reports it is connecting for any other reason, for instance a periodic Inform, the operation does not execute.

Managing a Device's Provisioning Group

The provisioning group for a CWMP device is specified on the device object in the RDU. On the:

•

Administrator user interface, via the Home Provisioning Group drop-down list in the Devices pages.

In managing a device's provisioning group, occasionally, you might need to redirect or correct the provisioning group of a device:

In this scenario, the device communicates with a specific provisioning group, for example PG1, and you want to redirect it to communicate with another provisioning group, PG2.

In this scenario, the device's provisioning group in BAC is incorrect and must be changed only in BAC; for example, the device attempts to contact PG1 but is provisioned for PG2 in BAC.

Note You cannot change a device's provisioning group if the DPE is unable to connect to the RDU.

Redirecting a Device's Provisioning Group

This process involves distributing device instructions to the DPE in the new provisioning group, so it can handle device requests, and instructing the device of its new provisioning group location (ACS URL). You use BAC to make this change in the most efficient manner by using a redirection instruction.

Figure 14-3 depicts the high-level flow when the ChangeProvGroup operation is used in the IPDevice.performOperation() API call.

When the ChangeProvGroup operation is executed in the RDU, the redirection instruction—or the change provisioning group instruction— is included in the device configuration. At this point, the device is still assigned to the existing provisioning group. The new configuration instruction is then forwarded to all the DPEs in the device's provisioning group.

When the device establishes its next session with BAC (for example, from a connection request), the device is authenticated, and the DPE sets the URL of its new DPE is set via the SetParameterValues RPC. (You can configure the ACS URL on the provisioning group from the administrator user interface. See Provisioning Group Configuration Workflow. If the ACS URL is not configured, the discovered URL is used. The discovered URL is the one automatically constructed based on the configuration of the DPE interface.)

Note The configured URL of the provisioning group always takes precedence over its discovered URL.

The RDU is notified of the change, and it then changes the device's provisioning group and generates a new configuration instruction set for the device. The device's configuration is then sent to all DPEs in the device's new provisioning group. The device now connects to its new provisioning group and is managed from that group of DPE servers.

Correcting a Device's Provisioning Group

You can also just reset an incorrect provisioning group specification on the device. In this scenario, you do not need to change the actual device—you only need to update BAC.

To change an incorrect provisioning group from the API, invoke the IPDevice.changeProperties() API and include the IPDeviceKeys.HOME_PROV_GROUP property with the corrected provisioning group. For details, refer to the API Javadoc.

To change an incorrect provisioning group specification from the administrator user interface:

Note If you change the home provisioning group from the administrator user interface, you only correct the provisioning group in BAC; the change does not affect the device.

Step 2

The Manage Devices page appears. Click the Identifier link corresponding to the correct device.

Step 3

The Modify Device page appears. Select your options from the Home Provisioning Group drop-down list.

Table Of Contents