22. nqFOTA

The nqFOTA object is a built-in object that provides the functionality to update the firmware of the user device using the NEQTO Machine Driver.

Functional overview:

• Provides the function of downloading the firmware image file of the user device and reading the download data.
• Provides a function to notify the firmware update result of the user device to NEQTO Console.

Limitations:

• This object can only be used on the Machine Driver dedicated scripts.
• The maximum size of one firmware image file is up to 2040KB.

---

Abstracts

Methods()/Properties	Summary	Version	Note
new nqFOTA()	Creates an nqFOTA instance.

{nqFOTA} Instance

Methods()/Properties	Summary	Version	Note
.fileDownload()	Downloads the specified file.
.binRead()	Reads the downloaded data.
.reportResult()	Notifies the firmware update result to NEQTO Console.
.setFailsafeTimer()	Changes the value of the execution time monitoring timer for the script.

---

Details

new nqFOTA(fileName[,readChunk[,dlTimeout[,dlRetry]]])

Creates an nqFOTA instance.

Name	Type	M/O	Summary	Note
fileName	string	mandatory	Specify the file name to download.
readChunk	number	optional	Specify the read unit [byte] of the download data. Range: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 The default value is 1024.	If the out-of-range setting value is specified, the default value is used.
dlTimeout	number	optional	Specify the timeout value [ms] for download communication. The default value is 30000.
dlRetry	number	optional	Specify the number of download communication retries. The default value is 2.
return	{nqFOTA}	-	{nqFOTA} : Generated {nqFOTA}

.fileDownload([callback])

Downloads the specified file.
This method is executed by blocking.

One file can be downloaded by one nqFOTA instance.
If you want to download multiple files, create a new nqFOTA instance and execute the download again. At that time, the previously downloaded file will be discarded.

Name	Type	M/O	Summary	Note
callback(len,total)	function	optional	Notifies the status of download progress. Executes callback processing periodically in synchronization with internal download processing timing. len: {number} Downloaded Size [Byte] total: {number} Download Size [Byte]	Version 02.02.00+
return	number	-	Size of the downloaded file [byte]	If the download fails, it will be 0.

.binRead()

Reads the downloaded data.
The data size to be read at one time is specified by readChunk when creating the nqFOTA instance.

Name	Type	M/O	Summary	Note
return	ArrayBuffer, null	-	ArrayBuffer : Read data null : No data to read

.reportResult(message,version[,eventType])

Notifies the firmware update result to NEQTO Console.
This method is executed by blocking.

Name	Type	M/O	Summary	Note
message	string	mandatory	Specify any message that indicates the result.	Example: 'Success','failure', ...
version	string	mandatory	Specify any message that indicates the version.	Example: 'v1.0.0','001','APP-1.0','APP_1_0_0', ...
eventType	string	optional	Specify the event message type. 'info','warn','error','fatal' The default value is 'info'.	Version 02.00.00+
return	number	-	Status code of the HTTP response 200: Success Other than: Failure	When an error occurs, an exception is raised.

.setFailsafeTimer(timeout)

Changes the value of the execution time monitoring timer for the script.
The NEQTO Machine Driver has a timer that monitors the execution time if the script does not finish as expected.
This timer always starts at the begining of the script.
When timeout occurs, an exception is raised and the script is forcibly ended.

Name	Type	M/O	Summary	Note
timeout	number	mandatory	Specify the timeout value [s]. Range: 0 - 86400 The default value is 10800.	If the out-of-range setting value is specified, the default value is used. If 0 is set, the timer will be disabled.
return	number	-	Set value	When an error occurs, an exception is raised.

---

Object Usage Examples

The following sample is an operating script dedicated to the Machine Driver.

Sample 1

This is a sample for updating the firmware of a user device.
The firmware update part is a dummy.
The execution time monitoring timer value is changed to 5 minutes.

For FW_FILE, specify any file uploaded in the Machine Driver package.

var FW_FILE = 'sample.bin'; //Specify the file to be downloaded
var TARGET_VER = '0.0.1';

//Download parameter
var READ_CHUNK = 1024; //same as default
var DL_TIMEOUT = 30000; //same as default
var DL_RETRY = 2; //same as default

var fota = new nqFOTA(FW_FILE, READ_CHUNK, DL_TIMEOUT, DL_RETRY);

var fsTimer = fota.setFailsafeTimer(300); //5minutes
print('failsafeTimer: ' + fsTimer + 's');

var dlProg = 0;
print('Download start (' + FW_FILE + ')');
var dlFileSize = fota.fileDownload(function(len, total) {
    var percent = Math.round(len/total*100);
    if(dlProg != percent) {
        print('Downloading...' + percent + '%');
        dlProg = percent;
    }
});
print('Download completed!', dlFileSize);

var fwUpdate = function(fwSize) {
    var offset = 0;
    print('Update start');
    while(1) {
        var buf = fota.binRead(); //ArrayBuffer
        if(!buf) break;

        //FW write processing
        print('Updating...' + offset + '/' + fwSize);

        offset += buf.byteLength;
    }
    print('Update completed!', offset + '/' + fwSize);
    return true;
}

var getFwVersion = function() {
    return TARGET_VER; //dummy
}

var sendFotaResult = function(result, message, version) {
    var ret = fota.reportResult(message, version, result ? 'info' : 'error');
    print('reportResult:', result, '[' + version + '][' + message + ']', ret == 200 ? 'sendOK' : 'sendError');
}

if(dlFileSize) {
    if(fwUpdate(dlFileSize)) sendFotaResult(true, 'OK', getFwVersion());
    else sendFotaResult(false, 'Update failed', getFwVersion());
} else sendFotaResult(false, 'Download failed', getFwVersion());

---

Updated: 2024-01-19