20. nqService

The nqService object is a built-in object that provides various functions dedicated to NEQTO.

Functional overview:

• Provides the function to notify events to NEQTO Console.
• Provides a function to send measurement data or arbitrary data to NEQTO Console in batch.
• Provides a function to acquire service specific information assigned to a NEQTO device.
• Provides a function to configure the Express Mode operation.

Limitations:

• The number of session resources that can be used is 1.
• The maximum data size that can be sent at once is up to 128KB.
  If the maximum data size is exceeded, communication will be forcibly disconnected.

---

nqService Global Object

Methods()/Properties	Summary	Version	Note
nqService.eventNotify()	Performs event notification.		*
nqService.batteryNotify()	Performs battery event notification.	02.02.00+	*
nqService.cancelNotify()	Cancels event notification or battery event notification.
nqService.startPublish()	Starts the communication for batch data transmission.		*
nqService.writePublish()	Writes the send data after nqService.startPublish().
nqService.endPublish()	Ends the communication started by nqService.startPublish().
nqService.cancelPublish()	Cancels the communication started by nqService.startPublish().
nqService.on()	Registers an event handler.	01.07.00+
nqService.getServiceId()	Gets the service specific information assigned to the NEQTO device.	02.00.00+
nqService.setExpressConf()	Sets the operating parameters for Express Mode.	02.00.00+

* These methods cannot be used simultaneously.
  After executing one of the methods, wait for the communication to end before using the next method.

---

Details

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

Performs event notification.
Please check the notes regarding this method.

eventType	Summary	Version	Note
'info','warn','error','fatal'	Notifies the user event messages to the NEQTO Console.
'time'	Gets the time information from NEQTO and corrects the device's internal clock.

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

Notifies the user event messages to the NEQTO Console.

Name	Type	M/O	Summary	Note
eventType	string	mandatory	Event Type Specify the desired event message level. 'info','warn','error','fatal'
content	string	mandatory	Specify any message.	There is no limit to the number of characters, but memory resources are finite. Resource error occurs when the limit is reached. As a guide, please use within the maximum of 256 characters.
callback (statusCode)	function	optional	Executes callback processing at the end of communication. statusCode : {number} Status code of the HTTP response 201: Success Other than: Failure	This callback process is executed, and after the callback process exits, this method can be executed again.
timestamp	number	optional	Timestamp Specify unixtime [ms]. If not specified, it is the time when this method is called.	Version 02.01.00+ (In previous versions, it will be the time when this method is called)
return	undefined	-	-	When an error occurs, an exception is raised.

eventType : 'time'

Gets the time information from NEQTO and corrects the device's internal clock.

Name	Type	M/O	Summary	Note
eventType	string	mandatory	Event Type 'time'
callback (statusCode)	function	optional	Executes callback processing at the end of communication. statusCode : {number} Status code of the HTTP response. 200: Success Other than: Failure
return	undefined	-	-	When an error occurs, an exception is raised.

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

Performs battery event notification.
Notifies the specified battery status to the NEQTO Console.
Please check the notes regarding this method.

The battery status will return to the N/A state when the system transitions to behavior other than that of the operating script, such as "Script Reload" or "Firmware Update".

Name	Type	M/O	Summary	Note
eventType	string	mandatory	Event Type Specify the desired event message level. 'info','warn','error','fatal'
status	string, null	mandatory	Battery Status Specify the battery state. 'charging': Now charging 'full': 100% or less 'half': 50% or less 'low': 25% or less 'empty': Under voltage 'malfunction': Fault detected null: N/A
callback (statusCode)	function	optional	Executes callback processing at the end of communication. statusCode : {number} Status code of the HTTP response 201: Success Other than: Failure	This callback process is executed, and after the callback process exits, this method can be executed again.
timestamp	number	optional	Timestamp Specify unixtime [ms]. If not specified, it is the time when this method is called.
return	undefined	-	-	When an error occurs, an exception is raised.

nqService.cancelNotify()

Cancels event notification or battery event notification.

Name	Type	M/O	Summary	Note
return	undefined	-	-

nqService.startPublish(dataLen)

Starts the communication for batch data transmission.
Please check the notes regarding this method.

Note that the batch data needs to be formatted using the nqMqtt.get method.
In addition, the formatted data can be further combined using ','. (See sample code)

Name	Type	M/O	Summary	Note
dataLen	number	mandatory	Specify the total transmission data length [byte].
return	undefined	-	-	When an error occurs, an exception is raised.

nqService.writePublish(data[,callback])

Writes the send data after nqService.startPublish().
When performing divided transmission, use the callback process and execute multiple times. (See sample code)

Name	Type	M/O	Summary	Note
data	string, ArrayBuffer	mandatory	Transmission data	The data size to be written at once should be 4KB or less. If an error occurs, reduce the data size to be written at one time. If the length of the transmission data is 0, no transmission process will be performed and the callback will not be raised. (ArrayBuffer supported: Version 02.01.00+)
callback (len)	function	optional	Executes callback processing when transmission is completed. len : {number} (Version 01.06.02+) Transmission data length [byte] If a communication error occurs during transmission, the value will be 0.	If a communication error occurs, nqService.startPublish() can be executed again after this callback process is executed and the callback process exits.
return	undefined	-	-	When an error occurs, an exception is raised.

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

Ends the communication started by nqService.startPublish().
If transmission data is specified, it will end after transmission is complete.

Name	Type	M/O	Summary	Note
data	string, ArrayBuffer	optional	Transmission data	The data size to be written should be 4KB or less. If an error occurs, reduce the data size to be written and execute divided writing using nqService.writePublish(). (ArrayBuffer supported: Version 02.01.00+)
callback (statusCode)	function	optional	Executes callback processing when transmission is completed. statusCode : {number} Status code of the HTTP response. 200: Success Other than: Failure	This callback process is executed, and after the callback process exits, nqService.startPublish() can be executed again.
return	undefined	-	-	When an error occurs, an exception is raised.

nqService.cancelPublish()

Cancels the communication started by nqService.startPublish().

Name	Type	M/O	Summary	Note
return	undefined	-	-

nqService.on(event,callback)

Registers an event handler.

Name	Type	M/O	Summary	Note
event	string	mandatory	Event name Names that can be used are: reload
callback()	function	mandatory	Executes callback processing when an event occurs.
return	undefined	-	-

event : ’reload’

Executes callback processing before the operation script's forced termination event occurs by a trigger command from the NEQTO Console, such as "Script Reload" or "Firmware Update".
It can be used to execute minimal post-processing.
Note that this callback does not occur when the script terminates spontaneously, such as when a throw statement is executed or when an exception occurs due to syntax error, etc.

If an infinite loop occurs in the callback processing, the trigger command control from the NEQTO Console may become unavailable. Please check the related notes here before implementing the callback process.

nqService.getServiceId()

Gets the service specific information assigned to the NEQTO device.

Name	Type	M/O	Summary	Note
return	{ServiceID}	-	{ServiceID} : Service specific information

{ServiceID}

Name	Type	Summary	Note
.region	string	Region	asia-pacific-1, north-america-1
.group	string	Group ID
.node	string	Node sID

nqService.setExpressConf(timeout)

Sets the operating parameters for Express Mode.
This configuration is only applied when Express Mode is enabled, and the last value set is stored in nonvolatile memory. If Express Mode is disabled, it is ignored. When switching Express Mode to disabled, all parameters will return to default values.

Name	Type	M/O	Summary	Note
timeout	number	mandatory	Specifies the network connection wait timeout value [s]. Range: -1, 0 - 3600 The default value is -1.	If -1 is specified, the system default value of 30 seconds is applied.
return	undefined	-	-	When an error occurs, an exception is raised.

---

Object Usage Examples

Sample 1

This is a sample that notifies event messages at regular intervals.

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

This is a sample that performs a time correction event at regular intervals.

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

This is a sample for batch transmission of sensor data stored in the storage.

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