Interacting with the Device - TR-069 Functions

The TR-069 functions encapsulate the details of TR-069 interactions with the device away from the script writer.

CAUTION: The scripting feature of Device Manager is very resource intensive. If not managed carefully and thoughtfully, serious performance degradation of your Device Manager system can result. See Scripting Guide Appendix D: Scripts and Events - Cautions and Best Practices for more information.

get()

function get (path);
Description Read parameter or object information from the device
Parameters Path information to the object or parameter in the device’s data model. See the Path section for more details.
Returns Resulting parameters with zero or more parameters, at or under the given path Upon any TR-069 errors an exception will NOT be thrown.  Instead, the results parameter object will try to include any successfully obtained results, and indicate erroneous results in two keys in the parameter object under the problematic path - errorCode and errorMessage.  These values are undefined for successful operations on each path.
Required Libraries useLibrary("tr069");
Example

useLibrary("tr069");

//Get a single parameter

var totalbytessent = tr069.get("InternetGatewayDevice.LANDevice.1 .WLANConfiguration.1.TotalBytesSent");

log.info("WiFi Total Bytes Sent : " +totalbytessent);

//Get an object and all subobjects and parameters

output = tr069.get("InternetGatewayDevice.");

log.info(output.toSource());

 

set()

function set (path, value);
Description Write a parameter value to the device
Parameters
  • path - path information to the object or parameter in the device’s data model. See the Path section for more details.
  • value – new parameter value
Returns

Returns a Boolean status where true indicates that the related property change has been applied and false indicates that another operation is required, typically a reboot.

Upon any errors an exception will be thrown.  You can try/catch these exceptions explicitly in your script, or allow the scripting engine to catch and report them.  Exceptions might correspond to TR-069 Fault codes for the SetParameterValues() function, but this depends on which errors are implemented by the device or ACS.
Required Libraries useLibrary("tr069");
Example

useLibrary("tr069");

tr069.set("InternetGatewayDevice.X_BROADCOM_COM_LoginCfg. SupportPassword","newPassword");

 

setMany()

function setMany(object);
Description Write multiple parameter values to the device.
Parameters

A Javascript associative array of path:value pairs

  • path - path information to the object or parameter in the device’s data model. See the Path section for more details.
  • value – new parameter value
Returns Returns a Boolean status where true indicates that the related property change has been applied and false indicates that another operation is required, typically a reboot. Upon any errors an exception will be thrown.  You can try/catch these exceptions explicitly in your script, or allow the scripting engine to catch and report them.  Exceptions might correspond to TR-069 Fault codes for the SetParameterValues() function, but this depends on which errors are implemented by the device or ACS.
Required Libraries useLibrary("tr069");
Example

useLibrary("tr069");

 

var object = {

“InternetGatewayDevice.Time.NTPServer2” : explicitString(“ntp1.tummy.com”),

“InternetGatewayDevice.Time.NTPServer3” : explicitString(“ntp2.tummy.com”) };

tr069.setMany(object); // status is true

 

setNotify()

function setNotify(state, paths);
Description Set the notification state of one or more parameters
Parameters
  • state – notification state to apply to all paths – 0 = Off, 1 = Passive, 2 = Active.
  • paths – Javascript array of paths for which the notification state is to be set.
Returns Upon any errors an exception will be thrown. Exceptions can be processed explicitly using try/catch. The scripting engine will report these errors in the Event Log.  Exceptions might correspond to TR-069 Fault codes.
Required Libraries useLibrary("tr069");
Example

useLibrary("tr069");

 

tr069.setNotify(0, [“InternetGatewayDevice.Time.CurrentLocalTime”]);

 

has()

function has(path);
Description Test for the existence of a path. Useful to check the existence of a device specific property or any property before you try to set a value that might cause a device exception.
Parameters Any kind of Path. A PathSelector might be especially useful here but, if more than one path is selected, only the existence of one path will cause has() to return a true value.
Returns Boolean true/false
Required Libraries useLibrary("tr069");
Example

useLibrary("tr069");

//Check for the existence of a parameter

if ( tr069.has(“InternetGatewayDevice.LANDevice.{}.Hosts.Host.{}.IPAddress”) === false ) {

log.info(“Host IP Address not found”);

}

 

create()

function create(pathObject, [values]);
Description Add a new numbered instance to a pathObject.
Parameters
  • pathObject – A string specifying the pathObject which has numbered indices as children.
  • values – Javascript array of name:value pairs of the parameters to be set in the newly created object. See the example below.
Returns

An array is returned containing three properties:

  • name – The full path of the to the new object ending with the new index and a “.”
  • Index – The index number of the new object
  • Status – “true” if the object was created or “false” if another operation is required; typically a reboot.
Required Libraries useLibrary("tr069");
Example

useLibrary("tr069");

 

var vals = {

“Enable” : eB(false),

“SourceIPAddress” : eS(“192.100.100.100”),

“SourceSubnetMask” : eS(“255.255.255.255”),

“DestIPAddress” : eS(“192.168.100.100”),

“DestSubnetMask” : eS(“255.255.255.255”)

};

var name = “InternetGatewayDevice.Layer3Forwarding.Forwarding.”;

var ret = tr069.create(name, vals);

log.info(“Create “ + ret.name + “ “ + ret.index + “ “ + ret.status);

 

destroy()

function destroy(pathObject);
Description Delete the specified numbered instance
Parameters pathObject – A string specifying the pathObject to be removed.
Returns Status – “true” if the object was deleted or “false” if another operation is required; typically a reboot.
Required Libraries useLibrary("tr069");
Example

useLibrary("tr069");

 

tr069.destroy(“InternetGatewayDevice.Layer3Forwarding.Forwarding.2”);

 

useDownloadCredentials()

function useDownloadCredentials(username, password);
Description Sets the download credentials to use on all subsequent download calls.  By default, no download credentials are used.
Parameters
  • Username – Username to use on subsequent download calls.
  • Password – Password to use on subsequent download calls.
Returns None
Required Libraries useLibrary("tr069");
Example --

 

downloadFirmware()

function downloadFirmware(FileDownloadRef);
Description Queues a request to download a firmware update.
Parameters FileDownloadRef – a new FileDownloadRef object with specific firmware image data. See the example below.
Returns

The returned object contains three properties:

  • started – date/time value showing when the download process started
  • completed – date/time value showing when the download process completed
  • status – “true” if the download process completed otherwise “false” if the download is waiting on some other event (typically the http download to complete followed by a reboot)

Started and completed values may be null and status will typically be “false” as the device requires time to complete the firmware image transfer, burn it into flash memory and reboot.
Required Libraries useLibrary("tr069");
Example

useLibrary(“tr069);

 

var url = “http://myISPName.com/firmware/Smartrg/”;

var fileSize = 10123456;

var targetFileName = “CA_PBCA_2.6.1.3_401ef32_SR515ac_cfe_fs_kernel”;

var delaySeconds = 0;

var successUrl = “http://myISPName.com/firmware/success”;

var failureUrl = “http://myISPName.com/firmware/failure”;

// See the NOTE below regarding the creation of a new FileDownloadRef object

 

var fdr = new FileDownloadRef(url, fileSize, targetFileName, delaySeconds, successUrl, failureUrl);

 

var rsp = downloadFirmware(fdr);

 

log.info(“Status: “ + rsp.status + “ started: “ + rsp.started + “ completed: “ + rsp.completed);

NOTE: File download reference objects can be created in the Device Manager GUI under ADMINISTRATION > Firmware. You can choose to use the name of the file download reference object created there instead of creating a new FileDownloadRef object in your script.

 

downloadConfigFile()

function downloadConfigFile(FileDownloadRef);
Description Queues a request to download a configuration file update.
Parameters FileDownloadRef – a new FileDownloadRef object with specific firmware image data. See the example below.
Returns

The returned object contains three properties:

  • started – date/time value showing when the download process started
  • completed – date/time value showing when the download process completed
  • status – “true” if the download process completed otherwise “false” if the download is waiting on some other event (typically the http download to complete followed by a reboot).

Started and completed values may be null and status will typically be “false” as the device requires time to complete the firmware image transfer, burn it into flash memory and reboot.
Required Libraries useLibrary("tr069");
Example

useLibrary(“tr069);

 

var url = “http://myISPName.com/configs/Smartrg/”;

var fileSize = 64123; var targetFileName = “MyISPName_SR515ac_07262017.conf”;

var delaySeconds = 0; var successUrl = “http://myISPName.com/configs/success”;

var failureUrl = “http://myISPName.com/configs/failure”;

 

var fdr = new FileDownloadRef(url, fileSize, targetFileName, delaySeconds, successUrl, failureUrl);

 

var rsp = downloadConfigFile(fdr);

 

log.info(“Status: “ + rsp.status + “ started: “ + rsp.started + “ completed: “ + rsp.completed);

NOTE: An alternative and possibly simpler approach to performing configuration file downloads can be seen in the Direct Remote Procedure Calls (RPC) section. See that section for examples on downloading running and default configuration files.

 

reboot()

function reboot();
Description Reboot the device after termination of the current session.
Parameters None
Returns None
Required Libraries useLibrary("tr069");
Example

useLibrary("tr069");

//Reboot the device

reboot();

 

rebootNow()

function reboot();
Description Reboot the device immediately and abandon the current session
Parameters None
Returns None
Required Libraries useLibrary("tr069");
Example

useLibrary("tr069");

//Reboot the device immediately

rebootNow();