17. nqFOTA
nqFOTAオブジェクトは、NEQTO Machine Driverを使用してユーザーデバイスのファームウェアを更新する機能を提供する組み込みオブジェクトです。
機能概要:
- ユーザーデバイスのファームウェアイメージファイルのダウンロードとダウンロードデータの読み出し機能を提供します。
- ユーザーデバイスのファームウェア更新結果をNEQTO Consoleへ通知する機能を提供します。
制限事項:
- 本オブジェクトは、Machine Driver専用スクリプト上でのみ使用可能です。
Abstracts
Methods()/Properties | Summary | Version | Note |
---|---|---|---|
new nqFOTA() | nqFOTAインスタンスを生成します。 |
{nqFOTA} Instance
Methods()/Properties | Summary | Version | Note |
---|---|---|---|
.fileDownload() | 指定されたファイルをダウンロードします。 | ||
.binRead() | ダウンロードしたデータを読み出します。 | ||
.reportResult() | NEQTO Consoleへファームウェア更新結果を通知します。 | ||
.setFailsafeTimer() | スクリプトの実行時間監視タイマ値を変更します。 |
Details
new nqFOTA(fileName[,readChunk[,dlTimeout[,dlRetry]]])
nqFOTAインスタンスを生成します。
Name | Type | M/O | Summary | Note |
---|---|---|---|---|
fileName | string | mandatory | ダウンロードするファイル名を指定します。 | |
readChunk | number | optional | ダウンロードデータの読み出し単位[byte]を指定します。 設定範囲: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 デフォルト値は1024となります。 | 規定外の設定値が指定された場合、デフォルト値となります。 |
dlTimeout | number | optional | ダウンロード通信のタイムアウト値[ms]を指定します。 デフォルト値は30000となります。 | |
dlRetry | number | optional | ダウンロード通信のリトライ回数を指定します。 デフォルト値は2となります。 | |
return | {nqFOTA} | - | {nqFOTA} : 生成された{nqFOTA} |
.fileDownload([[dst,]callback])
指定されたファイルをダウンロードします。
このメソッドはブロッキングで処理されます。
一つのnqFOTAインスタンスでダウンロードできるファイルは一つです。
複数のファイルをダウンロードする場合は、新しくnqFOTAインスタンスを作成して、再度ダウンロードを実行してください。
Name | Type | M/O | Summary | Note |
---|---|---|---|---|
dst | number | optional | ダウンロード先を指定します。 0: 暗号化された状態でデーモン管理下の内部ストレージに保存します。 1: /tmp/neqto/user ディレクトリに直接保存します。2: /var/lib/neqto/user ディレクトリに直接保存します。デフォルト値は0となります。 | 0 を指定した場合、前回ダウンロードしたデータは破棄されます。又、データ読み出しには.binRead()メソッドを使用する必要があります。1 ,2 を指定した場合、ダウンロード元ファイルそのものが直接格納されます。.binRead()メソッドを使用してデータを読み出すことも可能です。 |
callback(len,total) | function | optional | ダウンロードの途中経過を通知します。内部ダウンロード処理タイミングに同期して定期的にコールバック処理を実行します。 len: {number} ダウンロード済みサイズ[Byte] total: {number} ダウンロードサイズ[Byte] | Version 00.01.00+ |
return | number | - | ダウンロードしたファイルサイズ[byte] | ダウンロードが失敗した場合、0となります。 |
.binRead()
ダウンロードしたデータを読み出します。
一度に読み出すデータサイズは、nqFOTAインスタンスの作成時にreadChunk
で指定します。
Name | Type | M/O | Summary | Note |
---|---|---|---|---|
return | ArrayBuffer, null | - | ArrayBuffer : 読み出されたデータ null : 読み出すデータなし |
.reportResult(message,version[,eventType])
NEQTO Consoleへファームウェア更新結果を通知します。
このメソッドはブロッキングで処理されます。
Name | Type | M/O | Summary | Note |
---|---|---|---|---|
message | string | mandatory | 結果を示す任意メッセージを指定します。 | 例: 'Success' ,'failure' , ... |
version | string | mandatory | バージョンを示す任意メッセージを指定します。 | 例: 'v1.0.0' ,'001' ,'APP-1.0' ,'APP_1_0_0' , ... |
eventType | string | optional | イベントメッセージタイプを指定します。 'info','warn','error','fatal' デフォルト値は'info'となります。 | |
return | number | - | HTTPレスポンスのステータスコード 200: 成功 以外: 失敗 | 異常が発生したときは、例外となります。 |
.setFailsafeTimer(timeout)
スクリプトの実行時間監視タイマ値を変更します。
NEQTO Machine Driverには、スクリプトが想定通り終了しない場合に備えて実行時間を監視するタイマが存在します。
このタイマは常にスクリプトの開始時に起動され、タイムアウトすると例外を発生させスクリプトを強制終了します。
Name | Type | M/O | Summary | Note |
---|---|---|---|---|
timeout | number | mandatory | タイムアウト値[s]を指定します。 設定範囲: 0~86400 デフォルト値は10800となります。 | 規定外の設定値が指定された場合、デフォルト値となります。0が設定された場合はタイマーが無効となります。 |
return | number | - | 設定された値 | 異常が発生したときは、例外となります。 |
オブジェクトの使用例
以下のサンプルは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: 2024-01-19