8.2 <mgmtCmd> and <execInstance> resource primitive mappings
8.2.1 Update (Execute) primitive for the <mgmtCmd> resource
8.2.1.0 Introduction
When the Update Request primitive for <mgmtCmd> resource addresses the execEnable attribute of the <mgmtCmd> resource, it effectively triggers an Execute <mgmtCmd> procedure.
The Hosting CSE performs command conversion of its <execInstance> sub-resources. The mapping between the <execInstance> attributes and the TR-069 [4] RPC procedures triggered is based on the value of the cmdType attribute of the <mgmtCmd> resource defined in Table 8.2.1.0-1. The CPE acceptance of the corresponding RPC procedures is indicated by returning a successful Response primitive to the initial Update Request.
The Fault Codes which may be returned by the CPE to the Hosting CSE are mapped onto execResult codes and stored in the corresponding <execInstance> attributes, and are detailed in the following clauses:
Table 8.2.1.0-1 Mapping of Execute <mgmtCmd> primitives to BBF TR-069 RPC
| cmdType value | BBF TR-069 RPCs |
|---|---|
| "DOWNLOAD" | Download RPC (see clause 8.2.1.1) and TransferComplete RPC (clause 8.2.1.3) |
| "UPLOAD" | Upload RPC (clause 8.2.1.2) and TransferComplete RPC (clause 8.2.1.3) |
| "SOFTWAREINSTALL" | ChangeDUState RPC (clause 8.2.1.4) and ChangeDUStateComplete RPC (clause 8.2.1.5) |
| "SOFTWAREUNINSTALL" | ChangeDUState RPC (clause 8.2.1.4) and ChangeDUStateComplete RPC (clause 8.2.1.5) |
| "REBOOT" | Reboot RPC (clause 8.2.1.6) |
| "RESET" | Factory reset RPC (clause 8.2.1.7) |
8.2.1.1 Execute File Download
The download file transfer operation may use the Download mechanism defined in TR-069 [4]. The Download mechanism is an asynchronous command which returns a successful response or one of the following fault codes mapped onto execResult values as detailed in Table 8.2.1.1-1. A successful response to the Update primitive triggering the Execute procedure means that the CPE has accepted the Download RPC.
Table 8.2.1.1-1: Download Fault Code Mapping
| Fault code | Description | execResult Code |
|---|---|---|
| 9000 | Method not supported | STATUS_REQUEST_UNSUPPORTED |
| 9001 | Request denied (no reason specified) | STATUS_REQUEST_DENIED |
| 9002 | Internal error | STATUS_INTERNAL_ERROR |
| 9003 | Invalid arguments | STATUS_INVALID_ARGUMENTS |
| 9004 | Resources exceeded (when used in association with SetParameterValues, this cannot be used to indicate Parameters in error). | STATUS_RESOURCES_EXCEEDED |
| 9010 | File transfer failure (associated with Download, ScheduleDownload, TransferComplete or AutonomousTransferComplete methods). | STATUS_FILE_TRANSFER_FAILED |
| 9012 | File transfer server authentication failure (associated with Upload, Download, TransferComplete, AutonomousTransferComplete, DUStateChangeComplete, or AutonomousDUStateChangeComplete methods, not associated with Scheduled Download method). | STATUS_FILE_TRANSFER_SERVER_AUTHENTICATION_FAILURE |
| 9013 | Unsupported protocol for file transfer (associated with Upload, Download, ScheduleDownload, DUStateChangeComplete, or AutonomousDUStateChangeComplete methods). | STATUS_UNSUPPORTED_PROTOCOL |
8.2.1.2 Execute File Upload Operations
The upload file transfer operation shall use the Upload mechanism defined in TR-069 [4]. The Upload mechanism is an asynchronous command that consists of the synchronous Upload RPC for the Upload and the asynchronous TransferComplete RPC. The Upload RPC returns a successful response or one of the following fault codes mapped onto execResult values as detailed in Table 8.2.1.2-1. A successful response to the Update primitive triggering the execute procedure means that the CPE has accepted the Upload RPC in Table 8.2.1.2-1.
Table 8.2.1.2-1: Upload Fault Code Mapping
| Fault code | Description | execResult Code |
|---|---|---|
| 9000 | Method not supported | STATUS_REQUEST_UNSUPPORTED |
| 9001 | Request denied (no reason specified) | STATUS_REQUEST DENIED |
| 9002 | Internal error | STATUS_INTERNAL_ERROR |
| 9003 | Invalid arguments | STATUS_INVALID_ARGUMENTS |
| 9004 | Resources exceeded (when used in association with SetParameterValues, this cannot be used to indicate Parameters in error) | STATUS_RESOURCES_EXCEEDED |
| 9011 | Upload failure (associated with Upload, TransferComplete or AutonomousTransferComplete methods). | STATUS_UPLOAD_FAILED |
| 9012 | File transfer server authentication failure (associated with Upload, Download, TransferComplete, AutonomousTransferComplete, DUStateChangeComplete, or AutonomousDUStateChangeComplete methods). | STATUS_FILE_TRANSFER_SERVER_AUTHENTICATION_FAILURE |
| 9013 | Unsupported protocol for file transfer (associated with Upload, Download, ScheduleDownload, DUStateChangeComplete, or AutonomousDUStateChangeComplete methods). | STATUS_UNSUPPORTED_PROTOCOL |
8.2.1.3 Report Results using TransferComplete RPC
After a File Download or Upload has been attempted, the result of the operation is reported using the TransferComplete RPC. The TransferComplete RPC indicates a successful operation or one of the following fault codes mapped onto execResult values in Table 8.2.1.3-2.
Table 8.2.1.3-2: TransferComplete Fault Code Mapping
| Fault code | Description | execResult Code |
|---|---|---|
| 9001 | Request denied (no reason specified) | STATUS_REQUEST DENIED |
| 9002 | Internal error | STATUS_INTERNAL_ERROR |
| 9010 | File transfer failure (associated with Download, ScheduleDownload, TransferComplete or AutonomousTransferComplete methods). | STATUS_FILE_TRANSFER_FAILED |
| 9011 | Upload failure (associated with Upload, TransferComplete or AutonomousTransferComplete methods). | STATUS_UPLOAD_FAILED |
| 9012 | File transfer server authentication failure (associated with Upload, Download, TransferComplete, AutonomousTransferComplete, DUStateChangeComplete, or AutonomousDUStateChangeComplete methods). | STATUS_FILE_TRANSFER_SERVER_AUTHENTICATION_FAILURE |
| 9014 | File transfer failure: unable to join multicast group (associated with Download, TransferComplete or AutonomousTransferComplete methods). | STATUS_FILE_TRANSFER_FAILED_MULTICAST_GROUP_UNABLE_JOIN |
| 9015 | File transfer failure: unable to contact file server (associated with Download, TransferComplete, AutonomousTransferComplete, DUStateChangeComplete, or AutonomousDUStateChangeComplete methods). | STATUS_FILE_TRANSFER_FAILED_SERVER_CONTACT_FAILED |
| 9016 | File transfer failure: unable to access file (associated with Download, TransferComplete, AutonomousTransferComplete, DUStateChangeComplete, or AutonomousDUStateChangeComplete methods). | STATUS_FILE_TRANSFER_FAILED_FILE_ACCESS_FAILED |
| 9017 | File transfer failure: unable to complete download (associated with Download, TransferComplete, AutonomousTransferComplete, DUStateChangeComplete, or AutonomousDUStateChangeComplete methods). | STATUS_FILE_TRANSFER_FAILED_DOWNLOAD_INCOMPLETE |
| 9018 | File transfer failure: file corrupted or otherwise unusable (associated with Download, TransferComplete, AutonomousTransferComplete, DUStateChangeComplete, or AutonomousDUStateChangeComplete methods). | STATUS_FILE_TRANSFER_FAILED_FILE_CORRUPTED |
| 9019 | File transfer failure: file authentication failure (associated with Download, TransferComplete or AutonomousTransferComplete methods). | STATUS_FILE_TRANSFER_FILE_AUTHENTICATION_FAILURE |
| 9020 | File transfer failure: unable to complete download within specified time windows (associated with TransferComplete method). | STATUS_FILE_TRANSFER_WINDOW_EXCEEDED |
8.2.1.4 Execute Software Operations with ChangeDUState RPC
The software installation and uninstall operations shall use the ChangeDUState mechanism defined in TR-069 [4]. The ChangeDUState mechanism is an asynchronous command that consists of the synchronous ChangeDUState RPC and returns a successful response or one of the fault codes mapped onto execResult values as detailed in Table 8.2.1.4.-1. A successful response to the Update primitive triggering the Execute procedure means that the CPE has accepted the ChangeDUState RPC.
Table 8.2.1.4-1: ChangeDUState Fault Code Mapping
| Fault code | Description | execResult Code |
|---|---|---|
| 9000 | Method not supported | STATUS_REQUEST_UNSUPPORTED |
| 9001 | Request denied (no reason specified) | STATUS_REQUEST DENIED |
| 9002 | Internal error | STATUS_INTERNAL_ERROR |
| 9004 | Resources exceeded (when used in association with SetParameterValues, this cannot be used to indicate Parameters in error) | STATUS_RESOURCES_EXCEEDED |
8.2.1.5 Report Results with ChangeDUStateComplete RPC
After software installation and uninstall operations using a ChangeDUState mechanism as defined in TR-069 [4], the result of the state change operation is retrieved using the ChangeDUStateComplete RPC. The ChangeDUStateComplete RPC indicates a successful operation or one of the fault codes mapped onto execResult values as detailed in Table 8.2.1.5.-1.
Table 8.2.1.5-1: ChangeDUStateComplete Fault Code Mapping
| Fault code | Description | execResult Code |
|---|---|---|
| 9001 | Request denied (no reason specified) | STATUS_REQUEST_DENIED |
| 9003 | Invalid arguments | STATUS_INVALID_ARGUMENTS |
| 9012 | File transfer server authentication failure (associated with Upload, Download, TransferComplete, AutonomousTransferComplete, DUStateChangeComplete, or AutonomousDUStateChangeComplete methods). | STATUS_FILE_TRANSFER_SERVER_AUTHENTICATION_FAILURE |
| 9013 | Unsupported protocol for file transfer (associated with Upload, Download, ScheduleDownload, DUStateChangeComplete, or AutonomousDUStateChangeComplete methods). | STATUS_UNSUPPORTED_PROTOCOL |
| 9015 | File transfer failure: unable to contact file server (associated with Download, TransferComplete, AutonomousTransferComplete, DUStateChangeComplete, or AutonomousDUStateChangeComplete methods). | STATUS_FILE_TRANSFER_FAILED_SERVER_CONTACT_FAILED |
| 9016 | File transfer failure: unable to access file (associated with Download, TransferComplete, AutonomousTransferComplete, DUStateChangeComplete, or AutonomousDUStateChangeComplete methods). | STATUS_FILE_TRANSFER_FAILED_FILE_ACCESS_FAILED |
| 9017 | File transfer failure: unable to complete download (associated with Download, TransferComplete, AutonomousTransferComplete, DUStateChangeComplete, or AutonomousDUStateChangeComplete methods). | STATUS_FILE_TRANSFER_FAILED_DOWNLOAD_INCOMPLETE |
| 9018 | File transfer failure: file corrupted or otherwise unusable (associated with Download, TransferComplete, AutonomousTransferComplete, DUStateChangeComplete, or AutonomousDUStateChangeComplete methods). | STATUS_FILE_TRANSFER_FAILED_FILE_CORRUPTED |
| 9022 | Invalid UUID Format (associated with DUStateChangeComplete or AutonomousDUStateChangeComplete methods: Install, Update, and Uninstall) | STATUS_INVALID_UUID_FORMAT |
| 9023 | Unknown Execution Environment (associated with DUStateChangeComplete or AutonomousDUStateChangeComplete methods: Install only) | STATUS_UNKNOWN_EXECUTION_ENVIRONMENT |
| 9024 | Disabled Execution Environment (associated with DUStateChangeComplete or AutonomousDUStateChangeComplete methods: Install, Update, and Uninstall) | STATUS_DISABLED_EXECUTION_ENVIRONMENT |
| 9025 | Deployment Unit to Execution Environment Mismatch (associated with DUStateChangeComplete or AutonomousDUStateChangeComplete methods: Install and Update) | STATUS_EXECUTION_ENVIRONMENT_MISMATCH |
| 9026 | Duplicate Deployment Unit (associated with DUStateChangeComplete or AutonomousDUStateChangeComplete methods: Install only) | STATUS_DUPLICATE_DEPLOYMENT_UNIT |
| 9027 | System Resources Exceeded (associated with DUStateChangeComplete or AutonomousDUStateChangeComplete methods: Install and Update) | STATUS_SYSTEM_RESOURCES_EXCEEDED |
| 9028 | Unknown Deployment Unit (associated with DUStateChangeComplete or AutonomousDUStateChangeComplete methods: Update and Uninstall) | STATUS_UNKNOWN_DEPLOYMENT_UNIT |
| 9029 | Invalid Deployment Unit State (associated with DUStateChangeComplete or AutonomousDUStateChangeComplete methods: Install, Update and Uninstall) | STATUS_INVALID_DEPLOYMENT_UNIT_STATE |
| 9030 | Invalid Deployment Unit Update - Downgrade not permitted (associated with DUStateChangeComplete or AutonomousDUStateChangeComplete methods: Update only) | STATUS_INVALID_DEPLOYMENT_UNIT_UPDATE_DOWNGRADE_DISALLOWED |
| 9031 | Invalid Deployment Unit Update - Version not specified (associated with DUStateChangeComplete or AutonomousDUStateChangeComplete methods: Update only) | STATUS_INVALID_DEPLOYMENT_UNIT_UPDATE_UPGRADE_DISALLOWED |
| 9032 | Invalid Deployment Unit Update - Version already exists (associated with DUStateChangeComplete or AutonomousDUStateChangeComplete methods: Update only) | STATUS_INVALID_DEPLOYMENT_UNIT_UPDATE_VERSION_EXISTS |
8.2.1.6 Execute Reboot operation
The reboot operation shall use the Reboot RPC defined in TR-069 [4]. The Reboot RPC is a synchronous command. A successful response to the Update primitive triggering the Execute procedure means that the CPE has accepted the Reboot RPC. The Reboot RPC returns a successful response or one of the fault codes mapped onto execResult values as detailed in Table 8.2.1.6-1.
Table 8.2.1.6-1: Reboot Fault Code Mapping
| Fault code | Description | execResult Code |
|---|---|---|
| 9001 | Request denied (no reason specified) | STATUS_REQUEST_DENIED |
| 9002 | Internal error | STATUS_INTERNAL_ERROR |
| 9003 | Invalid arguments | STATUS_INVALID_ARGUMENTS |
8.2.1.7 Execute Factory Reset operation
The factory reset operation shall use the FactoryReset RPC defined in TR-069 [4]. The FactoryReset RPC is a synchronous command. A successful response to the Update primitive triggering the Execute procedure means that the CPE has accepted the FactoryReset RPC. The FactoryReset RPC returns a successful response or one of the fault codes mapped onto execResult values as detailed in Table 8.2.1.7-1.
Table 8.2.1.7-1: FactoryReset Fault Code Mapping
| Fault code | Description | execResult Code |
|---|---|---|
| 9000 | Method not supported | STATUS_REQUEST_UNSUPPORTED |
| 9001 | Request denied (no reason specified) | STATUS_REQUEST_DENIED |
| 9002 | Internal error | STATUS_INTERNAL_ERROR |
| 9003 | Invalid arguments | STATUS_INVALID_ARGUMENTS |
8.2.2 Delete <mgmtCmd> resource primitive mapping
The Delete Request primitive for the <mgmtCmd> resource may initiate TR-069 [4] RPC commands for the corresponding <execInstance> sub-resources as follows:
- If there are no <execInstance> sub-resources with RUNNING execStatus, a successful response to the Delete primitive is returned and the <mgmtCmd> resource is deleted without triggering any TR-069 [4] RPCs.
- If there are <execInstance> sub-resources with RUNNING execStatus that resulted in cancellable TR-069 [4] RPCs (e.g. File Upload and File Download RPCs), a TR-069 [4] CancelTransfer RPC shall be initiated for each cancellable operation. Upon completion of all the cancellation operations, if any fault codes are returned by the CPE, an unsuccessful Response to the Delete primitive with status code "Delete mgmtCmd- execInstance cancellation error" is returned, and the <mgmtCmd> resource is not deleted. The execStatus attribute of each specific <execInstance> is set to CANCELLED and the execResult attribute is set to "STATUS_SUCCESS" for successful RPCs. For the unsuccessful case, execResult is determined from the RPC fault codes as detailed in Table 8.2.2-1. If all cancellation operations are successful on the managed entity, a successful Response to the Delete primitive is returned and the <mgmtCmd> resource is deleted.
- If there is at least one <execInstance> sub-resource with RUNNING execStatus that resulted in non-cancellable TR-069 [4] RPCs (e.g. RPCs other than File Upload and File Download RPCs), the execStatus attribute of the specific <execInstance> is changed to STATUS_NON_CANCELLABLE. An unsuccessful Response to the Delete primitive with status code "Delete mgmtCmd- execInstance cancellation error" is returned and the <mgmtCmd> resource is not deleted.
Table 8.2.2-1: CancelTransfer Fault Code Mapping for Delete <mgmtCmd>
| Fault code | Description | execResult Code |
|---|---|---|
| 9000 | Method not supported | STATUS_REQUEST_UNSUPPORTED |
| 9001 | Request denied (no reason specified) | STATUS_REQUEST DENIED |
| 9021 | Cancellation of file transfer not permitted in current transfer state | STATUS_CANCELLATION_DENIED |
8.2.3 Update (Cancel) <execInstance> primitive mapping
When the Update Request primitive for an <execInstance> sub-resource addresses the execDisable attribute of the <execInstance > sub-resource, it effectively triggers a Cancel <execInstance> resource procedure.
The hosting CSE determines whether the <execInstance> resource has a RUNNING execStatus and weather the resulting TR-069 [4] RPCs are cancellable. Currently, only the TR-069 File Upload and File Download RPCs are cancellable using the TR-069 [4] CancelTransfer RPC:
- If the addressed <execInstance> sub-resource has an execStatus other than RUNNING, an un-successful Response to the Update primitive is returned with status code "Cancel execInstance - already complete".
- If the addressed <execInstance> sub-resources has RUNNING execStatus and resulted in cancellable TR-069 [4] RPCs (e.g. File Upload and File Download RPCs), a BBF TR-069 [4] CancelTransfer RPC shall be initiated. For a successful CancelTransfer RPC the execStatus attribute of the specific <execInstance> is set to CANCELLED and a successful Response is sent to the Update primitive. For a successful CancelTransfer RPC the execStatus attribute of the specific <execInstance> is set to CANCELLED, the execResult attribute is set to "STATUS_SUCCESS" and a successful Response is sent to the Update primitive. For an unsuccessful CancelTransfer RPC the execResult attribute is determined from the RPC fault codes as detailed in Table 8.2.3-1 and an unsuccessful Response is sent to the Update primitive with status code "Cancel execInstance - cancellation error".
- If the addressed <execInstance> sub-resources has RUNNING execStatus and resulted non-cancellable TR-069 [4] RPCs (e.g. RPCs other than File Upload and File Download RPCs), the execStatus attribute of the specific <execInstance> is changed to STATUS_NON_CANCELLABLE. An unsuccessful Response is sent to the Update primitive with status code "Cancel execInstance - not cancellable".
Table 8.2.3-1: CancelTransfer Fault Code Mapping for Update (Cancel) <execInstance>
| Fault code | Description | execResult Code |
|---|---|---|
| 9000 | Method not supported | STATUS_REQUEST_UNSUPPORTED |
| 9001 | Request denied (no reason specified) | STATUS_REQUEST DENIED |
| 9021 | Cancellation of file transfer not permitted in current transfer state | STATUS_CANCELLATION_DENIED |
8.2.4 Delete <execInstance> primitive mapping
The Delete Request primitive for an <execInstance> sub-resource may initiate TR-069 [4] RPC commands for the corresponding <execInstance> sub-resources as follows:
- If the addressed <execInstance> sub-resource has an execStatus other than RUNNING, an successful Response to the Delete primitive is returned and the <execInstance> sub-resource is deleted without triggering any TR-069 [4] RPCs.
- If the addressed <execInstance> sub-resource has RUNNING execStatus and resulted in cancellable TR-069 [4] RPCs (e.g. File Upload and File Download RPCs), a BBF TR-069 [4] CancelTransfer RPC shall be initiated. For a successful CancelTransfer RPC a successful response is sent to the Delete primitive and the <execInstance> sub-resource is deleted. For an unsuccessful CancelTransfer RPC the execStatus attribute is determined from the RPC fault codes as detailed in Table 8.2.4-1 and an unsuccessful Response is sent to the Delete primitive with status code "Delete execInstance - cancellation failed".
- If the addressed <execInstance> sub-resource has RUNNING execStatus and resulted non-cancellable TR-069 [4] RPCs (e.g. RPCs other than File Upload and File Download RPCs), the execResult attribute is set to STATUS_NON_CANCELLABLE and an unsuccessful Response is sent to the Update primitive with status code "Delete execInstance - not cancellable".
Table 8.2.4-1: CancelTransfer Fault Code Mapping for Delete <execInstance>
| Fault code | Description | execResult Code |
|---|---|---|
| 9000 | Method not supported | STATUS_REQUEST_UNSUPPORTED |
| 9001 | Request denied (no reason specified) | STATUS_REQUEST DENIED |
| 9021 | Cancellation of file transfer not permitted in current transfer state | STATUS_CANCELLATION_DENIED |