Perhaps the biggest use case for TR-069 is managing a CPE’s firmware, allowing service providers to remotely upgrade their install base without needing to send the firmware to the customer or send an engineer.
TR-069 has several mechanism for doing this - the first is using the Download RPC to directly upload firmware. Optional RPCs that extend this capability include RequestDownload and ScheduleDownload. There is also a newer “firmware bank” mechanism in TR-069 Amendment 6. We’ll focus on using the Download RPC here and go into more detail in other sessions.
While Download RPC is used to transfer several different kinds of files to the CPE, but when transferring firmware, it defines an entire process for completing the upgrade and conveying it to the ACS. This is due to the fact that a successful call of the RPC includes both downloading the file in question AND applying it.
The Download RPC takes thirteen arguments. The first is our familiar command key. Second is the FileType argument, which as enumeration indicating the purpose of the file download. This has a value from 1 to 5:
1 - Firmware Upgrade Image 2 - Web Content 3 - Vendor Configuration File 4 - Tone File 5 - Ringer File
Values 4 and 5 are specific to the VoiceService function of a CPE specified in TR-104. Vendor Configuration File also has its own criteria for being added to the CPE, so we’ll focus here on Firmware Upgrade Image.
Next is the URL argument. While this must at minimum support HTTP and HTTPS transports, other transports such as FTP may be supported.
The next two arguments are the Username and Password, if they are required, to access the file specified at the URL.
Next is FileSize, which is used to allow the CPE to predict whether it will have enough space for the file. If it is set to 0 by the ACS, the CPE must proceed with the download anyway and assume it has enough space, though it may fail and specify this as the failure reason.
Next is TargetFileName. This is used if the ACS wants to specify the name of the file as it is written to the CPE’s memory.
The DelaySeconds argument behaves differently for different kinds of Downloads. For Unicast downloads, this specifies the number of seconds the CPE should wait before initiating the Download. This is used by the ACS to help control the time at which the CPE upgrades its firmware.
For Multicast downloads, however, the CPE must begin the Download immediately, and this number represents the total time the CPE has to initiate, download, and apply the firmware. If it can’t complete the Download within this window, it must consider the Download to be a failure.
Finally, there are two arguments, SuccessURL and FailureURL, that are meant to redirect and end-user’s browser if the upgrade was requested via the CPE’s interface. This is one of the few instances that an end-user is interacting specifically with a TR-069 mechanism. These should be left empty if they are not used.
The DownloadResponse contains three arguments. This first is Status, just like in SetParameterValues. Status in this case is used as one of the mechanisms to indicate a successful upgrade. The second and third arguments are StartTime and CompleteTime, which indicate the window in which the Download was performed and completed - though these should only exist if the Download completes within the session. Otherwise, it should be set to unknown.
The in the case of firmware, CPE MUST only consider the Download complete when it has been downloaded and the upgrade is complete. There are three ways a CPE can indicate this. The first is to set Status to 0 in the DownloadResponse. This is probably unlikely, as it means the Download was completed and the firmware upgrade was committed and applied DURING the CWMP session; which is probably not possible in the event of a reboot. The second method is to set Status to 1 in the DownloadResponse, and make a TransferComplete call on the ACS during the same session. This is also unlikely for the same reasons, but possible.
The third and most common way is to set Status equal to 1 in the DownloadResponse, and then call the TransferComplete RPC in a new session. This is indicated in the Inform RPC of the new session by including the 7 TRANSFER COMPLETE event, to tell the ACS that the CPE intends to make the TransferComplete call during this session, and the M Download event, to tell the ACS that this is because the Download RPC was called earlier.
Once the session is established, the CPE makes the TransferComplete call on the ACS. It contains four arguments. First is CommandKey, which should be set to the CommandKey value that was passed to the CPE in the Download RPC. Second is FaultStruct. If the transfer was successful, this is set to zero. Otherwise, it contains a FaultStruct, which contains the appropriate FaultCode and a FaultString with additional information. Lastly are our familiar start and complete times, which now have appropriate values.
Develop your solution even faster with the industry standard in automated, expert testing.
