19. nqFOTA

nqFOTAオブジェクトは、NEQTO Machine Driverを使用してユーザーデバイスのファームウェアを更新する機能を提供する組み込みオブジェクトです。

機能概要:

  • ユーザーデバイスのファームウェアイメージファイルのダウンロードとダウンロードデータの読み出し機能を提供します。
  • ユーザーデバイスのファームウェア更新結果をNEQTO Consoleへ通知する機能を提供します。

制限事項:

  • 本オブジェクトは、Machine Driver専用スクリプト上でのみ使用可能です。


Abstracts

Methods()/PropertiesSummaryVersionNote
new nqFOTA()nqFOTAインスタンスを生成します。

{nqFOTA} Instance

Methods()/PropertiesSummaryVersionNote
.fileDownload()指定されたファイルをダウンロードします。
.binRead()ダウンロードしたデータを読み出します。
.reportResult()NEQTO Consoleへファームウェア更新結果を通知します。
.setFailsafeTimer()スクリプトの実行時間監視タイマ値を変更します。


Details

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

nqFOTAインスタンスを生成します。

NameTypeM/OSummary                                        Note
fileNamestringmandatoryダウンロードするファイル名を指定します。
readChunknumberoptionalダウンロードデータの読み出し単位[byte]を指定します。
設定範囲: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024
デフォルト値は1024となります。		規定外の設定値が指定された場合、デフォルト値となります。
dlTimeoutnumberoptionalダウンロード通信のタイムアウト値[ms]を指定します。
デフォルト値は30000となります。
dlMaxTrynumberoptionalダウンロード通信の最大試行回数を指定します。
設定範囲: 1～
デフォルト値は2となります。
return{nqFOTA}-{nqFOTA} : 生成された{nqFOTA}

.fileDownload([[dst,]callback])

指定されたファイルをダウンロードします。
このメソッドはブロッキングで処理されます。

一つのnqFOTAインスタンスでダウンロードできるファイルは一つです。
複数のファイルをダウンロードする場合は、新しくnqFOTAインスタンスを作成して、再度ダウンロードを実行してください。

NameTypeM/OSummaryNote
dstnumberoptionalダウンロード先を指定します。
0: 暗号化された状態でデーモン管理下の内部ストレージに保存します。
1: /tmp/neqto/userディレクトリに直接保存します。
2: /var/lib/neqto/userディレクトリに直接保存します。
デフォルト値は0となります。		0を指定した場合、前回ダウンロードしたデータは破棄されます。又、データ読み出しには.binRead()メソッドを使用する必要があります。

1,2を指定した場合、ダウンロード元ファイルそのものが直接格納されます。.binRead()メソッドを使用してデータを読み出すことも可能です。
callback(len,total)functionoptionalダウンロードの途中経過を通知します。内部ダウンロード処理タイミングに同期して定期的にコールバック処理を実行します。
len: {number}
ダウンロード済みサイズ[Byte]
total: {number}
ダウンロードサイズ[Byte]		Version 00.01.00+
returnnumber, undefined-ダウンロードしたファイルサイズ[byte]ダウンロードが失敗した場合、undefinedとなります。(Version 00.03.00+)
(旧バージョンの場合は0となります)

.binRead()

ダウンロードしたデータを読み出します。
一度に読み出すデータサイズは、nqFOTAインスタンス作成時にreadChunkで指定します。

NameTypeM/OSummaryNote
returnArrayBuffer, null-ArrayBuffer : 読み出されたデータ
null : 読み出すデータなし

.reportResult(message,version[,eventType])

NEQTO Consoleへファームウェア更新結果を通知します。
このメソッドはブロッキングで処理されます。

NameTypeM/OSummary                                        Note
messagestringmandatory結果を示す任意メッセージを指定します。例: 'Success','failure', ...
versionstringmandatoryバージョンを示す任意メッセージを指定します。例: 'v1.0.0','001','APP-1.0','APP_1_0_0', ...
eventTypestringoptionalイベントメッセージタイプを指定します。
'info','warn','error','fatal'
デフォルト値は'info'となります。
returnnumber-HTTPレスポンスのステータスコード
200: 成功
以外: 失敗		異常が発生したときは、例外となります。

.setFailsafeTimer(timeout)

スクリプトの実行時間監視タイマ値を変更します。
NEQTO Machine Driverには、スクリプトが想定通り終了しない場合に備えて実行時間を監視するタイマが存在します。
このタイマは常にスクリプトの開始時に起動され、タイムアウトすると例外を発生させスクリプトを強制終了します。

NameTypeM/OSummary                                        Note
timeoutnumbermandatoryタイムアウト値[s]を指定します。
設定範囲: 0～86400
デフォルト値は10800となります。		規定外の設定値が指定された場合、デフォルト値となります。0が設定された場合はタイマーが無効となります。
returnnumber-設定された値異常が発生したときは、例外となります。


オブジェクトの使用例

以下のサンプルはMachine Driver専用の動作スクリプトです。

Sample 1

ユーザーデバイスのファームウェアを更新するサンプルです。
ファームウェア更新部分はダミーです。
実行時間監視タイマ値を5分に変更しています。

FW_FILEには、Machine Driverのパッケージにアップロードした任意ファイルを指定してください。

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: 2025-03-19
← 前次 →