20. nqService

nqServiceオブジェクトは、NEQTO専用の各種機能を提供する組み込みオブジェクトです。

機能概要:

NEQTO Consoleへイベント通知する機能を提供します。
NEQTO Consoleへ計測データや任意データを一括送信する機能を提供します。
NEQTOデバイスに割り当てられているサービス固有情報を取得する機能を提供します。
Expressモードの動作を設定する機能を提供します。

制限事項:

使用可能なセッションリソースは1本です。
一度に送信可能なデータサイズは最大128KBまでとなります。
最大サイズを超えたデータを送信した場合、通信が強制的に切断されます。

nqService Global Object

Methods()/Properties	Summary	Version	Note
nqService.eventNotify()	イベント通知を実行します。		※
nqService.batteryNotify()	バッテリイベント通知を実行します。	02.02.00+	※
nqService.cancelNotify()	イベント通知もしくはバッテリイベント通知を中止します。
nqService.startPublish()	一括データ送信するための通信を開始します。		※
nqService.writePublish()	nqService.startPublish()後、送信データを書き込みます。
nqService.endPublish()	nqService.startPublish()で開始された通信を終了します。
nqService.cancelPublish()	nqService.startPublish()で開始された通信を中止します。
nqService.on()	イベントハンドラを登録します。	01.07.00+
nqService.getServiceId()	NEQTOデバイスに割り当てられているサービス固有情報を取得します。	02.00.00+
nqService.setExpressConf()	Expressモードの動作パラメータを設定します。	02.00.00+

※ これらのメソッドは同時使用できません。
いずれかのメソッド実行後は、通信終了を待ってから次のメソッドを使用してください。

Details

nqService.eventNotify(eventType[,content][,callback][,timestamp])

イベント通知を実行します。
本メソッドに関する注意事項を確認してください。

eventType	Summary	Version	Note
`'info'`,`'warn'`,`'error'`,`'fatal'`	ユーザーイベントメッセージをNEQTO Consoleに通知します。
`'time'`	NEQTO Consoleから時刻情報を取得し、デバイス内部の時計を補正します。

eventType : 'info','warn','error','fatal'

ユーザーイベントメッセージをNEQTO Consoleに通知します。

Name	Type	M/O	Summary	Note
eventType	string	mandatory	イベントタイプ所望のイベントメッセージレベルを指定します。 'info','warn','error','fatal'
content	string	mandatory	任意メッセージを指定します。	文字数に制限はありませんが、メモリリソースは有限です。上限に達するとリソースエラーが発生します。目安として最大256文字以下で使用してください。
callback (statusCode)	function	optional	通信終了時にコールバック処理を実行します。 statusCode : {number} HTTPレスポンスのステータスコード 201: 成功以外: 失敗	本コールバック処理が実行され、コールバック処理から抜けた後に、本メソッドを再度実行可能となります。
timestamp	number	optional	タイムスタンプ unixtime[ms]を指定します。指定がない場合は、本メソッドをコールした際の時刻となります。	Version 02.01.00+ (旧バージョンはコールした際の時刻となります)
return	undefined	-	-	異常が発生した時は、例外となります。

eventType : 'time'

NEQTO Consoleから時刻情報を取得し、デバイス内部の時計を補正します。

Name	Type	M/O	Summary	Note
eventType	string	mandatory	イベントタイプ 'time'
callback (statusCode)	function	optional	通信終了時にコールバック処理を実行します。 statusCode : {number} HTTPレスポンスのステータスコード 200: 成功以外: 失敗
return	undefined	-	-	異常が発生した時は、例外となります。

nqService.batteryNotify(eventType,status[,callback][,timestamp])

バッテリイベント通知を実行します。
指定されたバッテリステータスをNEQTO Consoleに通知します。
本メソッドに関する注意事項を確認してください。

尚、スクリプトの再ロードやファームウェア更新等、動作スクリプト外の動作に遷移した場合、バッテリステータスはN/A状態に戻ります。

Name	Type	M/O	Summary	Note
eventType	string	mandatory	イベントタイプ所望のイベントメッセージレベルを指定します。 'info','warn','error','fatal'
status	string, null	mandatory	バッテリステータスバッテリ状態を指定します。 'charging': 充電中 'full': 100%以下 'half': 50%以下 'low': 25%以下 'empty': 低電圧 'malfunction': 故障 null: N/A
callback (statusCode)	function	optional	通信終了時にコールバック処理を実行します。 statusCode : {number} HTTPレスポンスのステータスコード 201: 成功以外: 失敗	本コールバック処理が実行され、コールバック処理から抜けた後に、本メソッドを再度実行可能となります。
timestamp	number	optional	タイムスタンプ unixtime[ms]を指定します。指定がない場合は、本メソッドをコールした際の時刻となります。
return	undefined	-	-	異常が発生した時は、例外となります。

nqService.cancelNotify()

イベント通知もしくはバッテリイベント通知を中止します。

Name	Type	M/O	Summary	Note
return	undefined	-	-

nqService.startPublish(dataLen)

一括データ送信するための通信を開始します。
本メソッドに関する注意事項を確認してください。

尚、一括データはnqMqtt.getメソッドを使ってフォーマットされている必要があります。
又、フォーマットされたデータは','を使用してさらに結合可能です。(サンプルコード参照)

Name	Type	M/O	Summary	Note
dataLen	number	mandatory	総送信データ長[byte]を指定します。
return	undefined	-	-	異常が発生した時は、例外となります。

nqService.writePublish(data[,callback])

nqService.startPublish()後、送信データを書き込みます。
分割送信する場合は、コールバック処理を利用して、複数回実行します。(サンプルコード参照)

Name	Type	M/O	Summary	Note
data	string, ArrayBuffer	mandatory	送信データ	一度に書き込むデータサイズは4KB以下にしてください。エラーが発生した場合は一度に書き込むデータサイズを減らしてください。尚、送信データ長が0の場合、送信処理が行われないため、コールバックは発生しません。 (`ArrayBuffer`対応: Version 02.01.00+)
callback (len)	function	optional	送信完了時にコールバック処理を実行します。 len : {number} (Version 01.06.02+) 送信データ長[byte] 送信処理中に通信エラーが発生した場合、0となります。	通信エラーが発生した場合、本コールバック処理が実行され、コールバック処理を抜けた後に、nqService.startPublish()を再度実行可能となります。
return	undefined	-	-	異常が発生した時は、例外となります。

nqService.endPublish([data][,callback])

nqService.startPublish()で開始された通信を終了します。
送信データを指定した場合は送信後に終了します。

Name	Type	M/O	Summary	Note
data	string, ArrayBuffer	optional	送信データ	書き込むデータサイズは4KB以下にしてください。エラーが発生した場合は書き込むデータサイズを減らし、nqService.writePublish()を使用した分割書き込みを実行してください。 (`ArrayBuffer`対応: Version 02.01.00+)
callback (statusCode)	function	optional	通信終了時にコールバック処理を実行します。 statusCode : {number} HTTPレスポンスのステータスコード 200: 成功以外: 失敗	本コールバック処理が実行され、コールバック処理から抜けた後に、nqService.startPublish()を再度実行可能となります。
return	undefined	-	-	異常が発生した時は、例外となります。

nqService.cancelPublish()

nqService.startPublish()で開始された通信を中止します。

Name	Type	M/O	Summary	Note
return	undefined	-	-

nqService.on(event,callback)

イベントハンドラを登録します。

Name	Type	M/O	Summary
event	string	mandatory	イベント名使用できるイベント名はreloadとなります。
callback()	function	mandatory	イベント発生時にコールバック処理を実行します。
return	undefined	-	-

event : ’reload’

スクリプトの再ロードやファームウェア更新等、NEQTO Console契機のトリガーコマンドによる動作スクリプトの強制終了イベントが発生する前に、コールバック処理を実行します。
最小限の後処理を実行する用途として活用できます。
尚、自発的に動作スクリプトが終了するthrow文やSyntax error等による例外が発生した場合は、本コールバックは発生しません。

コールバック処理の中で、無限ループが発生した場合、NEQTO Console契機のトリガーコマンド制御が機能しなくなる可能性があります。コールバック処理を実装する前にこちらの注意事項を確認してください。

nqService.getServiceId()

NEQTOデバイスに割り当てられているサービス固有情報を取得します。

Name	Type	M/O	Summary	Note
return	{ServiceID}	-	{ServiceID} : サービス固有情報

{ServiceID}

Name	Type	Summary	Note
.region	string	リージョン	`asia-pacific-1`, `north-america-1`
.group	string	グループID
.node	string	ノードID

nqService.setExpressConf(timeout)

Expressモードの動作パラメータを設定します。
本設定はExpressモードが有効の場合のみ適用され、最後に設定した値が不揮発メモリに保存されます。Expressモードが無効の場合は無視されます。尚、Expressモードを無効化した際、全てのパラメータがデフォルト値に戻ります。

Name	Type	M/O	Summary	Note
timeout	number	mandatory	ネットワーク接続待ちタイムアウト値[s]を指定します。設定範囲: -1, 0～3600 デフォルト値は-1となります。	`-1`を指定した場合、システムデフォルト値`30`秒が適用されます。
return	undefined	-	-	異常が発生したときは、例外となります。

オブジェクトの使用例

Sample 1

一定周期で、イベントメッセージ通知を行うサンプルです。

var count = 0;
var notifying = 0;
var INTERVAL = 15000; //ms
var MAX_COUNT = 3;
var cb_done = function(statusCode) {
    count++;
    if(statusCode == 201) {
        print(Date() + ' Success! :' + statusCode);
    } else {
        print(Date() + ' Failure :' + statusCode);
    }
    notifying = 0;
};
var to = setInterval(function() {
    if(count >= MAX_COUNT) {
        clearInterval(to);
        print('try out');
    } else {
        if(notifying == 0) {
            notifying = 1;
            nqService.eventNotify('info', 'userlevel-Notify-' + count, cb_done);
            print('busy');
        }
    }
}, INTERVAL);

Sample 2

一定周期で、時刻補正イベントを行うサンプルです。

var count = 0;
var correcting = 0;
var INTERVAL = 15000; //ms
var MAX_COUNT = 3;
var cb_done = function(statusCode) {
    count++;
    if(statusCode == 200) {
        print(Date() + ' Success! :' + statusCode);
    } else {
        print(Date() + ' Failure :' + statusCode);
    }
    correcting = 0;
};
var to = setInterval(function() {
    if(count >= MAX_COUNT) {
        clearInterval(to);
        print('try out');
    } else {
        if(correcting == 0) {
            correcting = 1;
            nqService.eventNotify('time', cb_done);
            print('busy');
        }
    }
}, INTERVAL);

Sample 3

ストレージに蓄積されたセンサーデータを一括送信するサンプルです。

var mb = storage.open(0);
mb.reset();
var FRAME_TYPE = 'nqSRV';
var w_len;
var allFrameSize;
var readIdx;
var nowUnix = (new Date()).getTime();
var lwM2MStr;
for(n=0; n<5; n++) {
    lwM2MStr = nqMqtt.get('LwM2MString', nowUnix + (n * 10000), 3313, 0, 5702, "Float", "1.0", 5703, "Float", "-1.0", 5704, "Float", "0.0", 5700, "Float", (1.0 + n*0.2).toFixed(1), "G");
    w_len = mb.writeFrame(FRAME_TYPE, (n > 0 ? ',' + lwM2MStr : lwM2MStr));
}
var getFrameData = function(init) {
    var tmpStr;
    var frame = '';
    if(init == 1) {
        readIdx = 0;
    }
    if(allFrameSize > 0) {
        tmpStr = mb.searchFrame(FRAME_TYPE, readIdx++);
        allFrameSize -= tmpStr.length;
        frame += tmpStr;
    }
    return frame;
}
var cb_done = function(statusCode) {
    if(statusCode == 200) {
        print(Date() + ' Success! :' + statusCode);
        mb.reset(); //Delete the data that could be sent
    } else {
        print(Date() + ' Failure :' + statusCode);
    }
};
var cb_w_done = function(len) {
    if(len === 0) {
        print(Date() + ' cb write failure!'); //disconnected
    } else {
        print(Date() + ' cb write success!');
        var frameData = getFrameData(0);
        if(allFrameSize <= 0) {
            nqService.endPublish(frameData, cb_done);
        } else {
            nqService.writePublish(frameData, cb_w_done);
        }
    }
};
allFrameSize = mb.searchAllFrame(FRAME_TYPE);
if(allFrameSize > 0) {
    print('allFrameSize:' + allFrameSize);
    nqService.startPublish(allFrameSize);
    nqService.writePublish(getFrameData(1), cb_w_done);
}

Updated: 2024-01-29

NEQTO Apps

ハードウェア仕様

ソフトウェア仕様

neqto.js

ハードウェア仕様

ソフトウェア仕様

neqto.js

ハードウェア仕様

ソフトウェア仕様

neqto.js

ソフトウェア仕様

neqto.js

UART

I2C

Utils

Integration

nqService Global Object

Details

nqService.eventNotify(eventType[,content][,callback][,timestamp])

eventType : 'info','warn','error','fatal'

eventType : 'time'

nqService.batteryNotify(eventType,status[,callback][,timestamp])

nqService.cancelNotify()

nqService.startPublish(dataLen)

nqService.writePublish(data[,callback])

nqService.endPublish([data][,callback])

nqService.cancelPublish()

nqService.on(event,callback)

event : ’reload’

nqService.getServiceId()

{ServiceID}

nqService.setExpressConf(timeout)

オブジェクトの使用例

Sample 1

Sample 2

Sample 3