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()/PropertiesSummaryVersionNote
nqService.eventNotify()Performs event notification.01.00.00+
nqService.cancelNotify()Cancels event notification.01.00.00+
nqService.startPublish()Starts the communication for batch data transmission.01.00.00+
nqService.writePublish()Writes the send data after nqService.startPublish().01.00.00+
nqService.endPublish()Ends the communication started by nqService.startPublish().01.00.00+
nqService.cancelPublish()Cancels the communication started by nqService.startPublish().01.00.00+
nqService.on()Registers an event handler.02.00.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+


Details

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

Performs event notification. The event names that can be used are info, warn, error, fatal, and time.

This method does not allow multiple simultaneous uses. Also includes nqService.startPublish(). If the event has already been executed, you need to wait for the end of communication.

event : 'info','warn','error','fatal'

Notify the user event message to the NEQTO Console.

NameTypeM/OSummary                            Note
eventTypestringmandatorySpecify the user event message type.
'info','warn','error','fatal'
contentstringmandatorySpecify 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)functionoptionalExecutes 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.
returnundefined--When an error occurs, an exception is raised.

event : 'time'

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

NameTypeM/OSummary                            Note
eventTypestringmandatoryTime correction event
'time'
callback(statusCode)functionoptionalExecutes callback processing at the end of communication.
statusCode : {number}
Status code of the HTTP response.
200: Success
Other than: Failure
returnundefined--When an error occurs, an exception is raised.

nqService.cancelNotify()

Cancels event notification.

NameTypeM/OSummaryNote
returnundefined--

nqService.startPublish(dataLen)

Starts the communication for batch data transmission.

This method does not allow multiple simultaneous uses. Also includes nqService.eventNotify(). If the event has already been executed, you need to wait for the end of communication.

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)

NameTypeM/OSummaryNote
dataLennumbermandatorySpecify the total transmission data length [byte].
returnundefined--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.

NameTypeM/OSummary                                       Note
datastringmandatoryTransmission dataIf the length of the transmission data is 0, no transmission process will be performed and the callback will not be raised.
callback(len)functionoptionalExecutes callback processing when transmission is completed.
len : {number} (Version 01.03.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.
returnundefined--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.

NameTypeM/OSummary                            Note
datastringoptionalTransmission data
callback(statusCode)functionoptionalExecutes 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.
returnundefined--When an error occurs, an exception is raised.

nqService.cancelPublish()

Cancels the communication started by nqService.startPublish().

NameTypeM/OSummaryNote
returnundefined--

nqService.on(event,callback)

Registers an event handler.

NameTypeM/OSummaryNote
eventstringmandatoryEvent name
Names that can be used are:reload.
callback()functionmandatoryExecutes callback processing when an event occurs.
returnundefined--

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.

NameTypeM/OSummaryNote
return{ServiceID}-{ServiceID} : Service specific information

{ServiceID}

NameTypeSummaryNote
.regionstringRegionasia-pacific-1, north-america-1
.groupstringGroup ID
.nodestringNode sID

nqService.setExpressConf()

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.

NameTypeM/OSummaryNote
timeoutnumbermandatorySpecifies 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.
returnundefined--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: 2022-06-03
← 19. nqSpresense21. nqMqtt →