21. nqMqtt · NEQTO Docs

The nqMqtt object is a built-in object that provides MQTT communication function with NEQTO Console.

Functional overview:

Provides a function to send LwM2M data to Components on NEQTO Console.
Provides a function to receive push notifications (Custom messages) from NEQTO Console.

nqMqtt Global Object

Methods()/Properties	Summary	Version
nqMqtt.configure()	Sets system parameters.	02.01.00+
nqMqtt.on()	Registers an event handler.	00.00.15+
nqMqtt.publish()	Publishes a message to NEQTO Console.	00.00.15+
nqMqtt.end()	Terminates nqMqtt.	00.00.15+
nqMqtt.isConnected()	Gets MQTT connection status.	00.00.15+
nqMqtt.isReconnecting()	Gets the status of MQTT when reconnecting.	00.00.15+
nqMqtt.canPublish()	Gets the status of whether the MQTT message can be published.	00.00.18+
nqMqtt.get() ⁽¹⁾	Gets LwM2M data in the specified format.	00.00.15+
nqMqtt.get() ⁽²⁾	Gets LwM2M data in the specified format.	01.07.00+

Details

nqMqtt.configure(paramType[,arg[,arg2]])

Sets system parameters.

paramType	Summary	Version	Note
`'keepalive'`	Sets the keep-alive timer.	02.01.00+

paramType : 'keepalive'

Sets the keep-alive timer.
The last set value is saved in non-volatile memory.

Shortening the keep-alive (heart-beat) monitoring interval of MQTT communication quickly detects device-server disconnections and facilitates recovery through reconnection. This minimizes push notification failures, but increases the amount of communication data.

Name	Type	M/O	Summary	Note
paramType	string	mandatory	Parameter Type 'keepalive'
timer	number	optional	Keep-alive timer [s] Range: 30 - 300 The default value is 300.	If the out-of-range setting value is specified, the default value is used.
immediately	boolean	optional	Immediate reflection true: Immediately false: At next reconnection The default value is true.	If "Immediately" is specified and the setting value is changed, the MQTT connection is disconnected once and then reconnected.
return	undefined	-	-

nqMqtt.on(event,callback)

Registers an event handler.

Name	Type	M/O	Summary
event	string	mandatory	Event name Names that can be used are: push, connect, reconnect, close, error
callback()	function	mandatory	Executes callback processing when an event occurs.
return	undefined	-	-

event: ’push’

Executes callback processing when receiving a push notification of a custom message from NEQTO Console. The arguments for the callback are as follows:

Arguments	Type	Summary	Note
message	string	Received message A string of up to 350 bytes. If the maximum number of bytes is exceeded, the message is discarded.

event: ’connect’

Executes callback when MQTT connection and reconnection are successful. MQTT connection may be completed before the script starts. In that case, the callback will not be executed. The arguments for the callback are as follows:

Arguments	Type	Summary	Note
connack	Object	connack is the content of the recieved connack packet. This argument is not mandatory.

event: ’reconnect’

Executes callback when MQTT reconnection is started.

event: ’close’

Executes callback when MQTT is disconnected.

event: ’error’

Executes callback when an error occurs or the MQTT connection fails. The arguments for the callback are as follows:

Arguments	Type	Summary	Note
err	{MqttError}	Error information

nqMqtt.publish(topic,message[,options][,callback])

Publishes a message to NEQTO Console.

Name	Type	M/O	Summary
topic	null	mandatory	Topic Name This value must always be set to `null`.
message	Object, string	mandatory	Message to publish Specify LwM2M data obtained by nqMqtt.get() ⁽¹⁾ ⁽²⁾. Note that the size of a message that can be published at a time must be less than 2460 bytes. If the permitted size is exceeded, an argument error will occur and the .on('error') callback process will be executed.
options	Object	optional	Publish Options Not used. Please omit it.
callback(err)	function	optional	Execute the callback process when the publish process is completed. err : {MqttError} Error information When err.code is 0, it means success.
return	undefined, {MqttError}	-	{MqttError} : If the request is not accepted due to an illegal argument error, disconnection, etc., {MqttError} is returned. (Version 02.00.00+)

Note: While a publish is in progress, if the next publish is performed before the process completion callback is executed, the latter's publish data may be discarded. Before publishing, it is recommended to check if a publish is currently in progress, or use .canPublish() to check if publish is available.

About joining messages to be published

It is possible to join and publish up to 4 LwM2M data retrieved by nqMqtt.get() ⁽¹⁾ ⁽²⁾.
Note that the permitted size of the message in total must not be exceeded.

The following is a sample of joining and publishing LwM2M object data retrieved by nqMqtt.get('LwM2MObject*'). Each LwM2M object data is arrayed and specified in the message.

var utime = Date.now();
var obj1 = nqMqtt.get('LwM2MObject', utime, 3303, 0, 5700, 'Float', '25.0');
var obj2 = nqMqtt.get('LwM2MObject', utime, 3304, 0, 5700, 'Float', '50.0');
var obj3 = nqMqtt.get('LwM2MObject', utime, 3313, 0, 5702, 'Float', '0.01', 5703, 'Float', '0.02', 5704, 'Float', '0.03', 'G');

var pubObj = [obj1, obj2, obj3];

nqMqtt.publish(null, pubObj, function(err) {
    if(err.code == 0) {
        print('Publish OK');
    } else {
        print('Publish failed');
    }
});

The following is a sample of joining and publishing LwM2M string data retrieved by nqMqtt.get('LwM2MArgStr*'). Each LwM2M string data is joined with a ',' separator and specified in the message.

var utime = Date.now();
var str1 = nqMqtt.get('LwM2MArgStr', utime, 3303, 0, 5700, 'Float', '25.0');
var str2 = nqMqtt.get('LwM2MArgStr', utime, 3304, 0, 5700, 'Float', '50.0');
var str3 = nqMqtt.get('LwM2MArgStr', utime, 3313, 0, 5702, 'Float', '0.01', 5703, 'Float', '0.02', 5704, 'Float', '0.03', 'G');

var pubStr = str1 + ',' + str2 + ',' + str3;

nqMqtt.publish(null, pubStr, function(err) {
    if(err.code == 0) {
        print('Publish OK');
    } else {
        print('Publish failed');
    }
});

nqMqtt.end([callback])

Terminates nqMqtt. Use this function only when you need to terminate the script.

Name	Type	M/O	Summary	Note
callback()	function	optional	Executes callback processing when nqMqtt terminates.
return	undefined	-	-

nqMqtt.isConnected()

Gets MQTT connection status.

Name	Type	M/O	Summary	Note
return	boolean	-	MQTT connection status true: MQTT connected false: Not connected

nqMqtt.isReconnecting()

Gets the status of MQTT when reconnecting.

Name	Type	M/O	Summary	Note
return	boolean	-	MQTT reconnecting status true: MQTT reconnecting false: Not reconnecting

nqMqtt.canPublish()

Gets the status of whether the MQTT message can be published.

Name	Type	M/O	Summary	Note
return	boolean	-	Whether the MQTT message can be published true: Can publish false: Cannot publish

nqMqtt.get(format,timestamp,objId,insId,resId,datatype,value[,resId2,datatype2,value2][,resId3,datatype3,value3][,resId4,datatype4,value4][,unit])

Gets LwM2M data in the specified format.

It is possible to create LwM2M data of up to 4 concatenations with the same timestamp, object ID, instance ID, and unit and with different resource ID, data type, and value by specifying the options as necessary.

For Object ID, Instance ID, Resource ID and Data Type, please refer here.
In addition, this setting must match a component's settings on the NEQTO Console.

Name	Type	M/O	Summary
format	string	mandatory	Specify the LwM2M data format name. 'LwM2MObject', 'LwM2MObjectS', 'LwM2MArgStr', 'LwM2MArgStrS', 'LwM2MString', 'LwM2MStringS'
timestamp	number	mandatory	Timestamp Specify unixtime [ms].
objId	number	mandatory	Object ID The object ID uses the number defined by LwM2M.
insId	number	mandatory	Instance ID If there are multiple of the same Resource ID pairs, this is used to differentiate between them.
resId	number	mandatory	Resource ID The resource ID uses the number defined by LwM2M.
datatype	string	mandatory	Data Type The data type uses the number defined by LwM2M. ('Float', 'Integer', 'String', 'Boolean')
value	string	mandatory	Value Specify a `string` type value. When referencing data of type `number`, convert it to a string and specify it.
resId2	number	optional	The second resource ID. Same as `resId`. `resId`, `resId2`, `resId3`, `resId4` must specify different values for each.
datatype2	string	optional	The second data type Same as `datatype`.
value2	string	optional	The second value Same as `value`.
resId3	number	optional	The third resource ID. Same as `resId`. `resId`, `resId2`, `resId3`, `resId4` must specify different values for each.
datatype3	string	optional	The third data type Same as `datatype`.
value3	string	optional	The third value Same as `value`.
resId4	number	optional	The fourth resource ID. Same as `resId`. `resId`, `resId2`, `resId3`, `resId4` must specify different values for each.
datatype4	string	optional	The fourth data type Same as `datatype`.
value4	string	optional	The fourth value Same as `value`.
unit	string	optional	Unit Specify any string indicating the unit. If undefined is specified, unit will not be used. ('G', 'm', 's', 'ms', ...) The default value is undefined.
return	Object, string, undefined	-	The return type is determined by format. If `'LwM2MObject'` is specified, the type is Object; if `'LwM2MArgStr'` is specified, the type is string; if `'LwM2MString*'` is specified, the type is string. If the creation fails, undefined will be returned.

The following is a usage example.

var obj = nqMqtt.get('LwM2MObject', Date.now(), 3303, 0, 5700, 'Float', '23.4');
var arg = nqMqtt.get('LwM2MArgStr', Date.now(), 3303, 0, 5700, 'Float', '23.4');
var str = nqMqtt.get('LwM2MString', Date.now(), 3303, 0, 5700, 'Float', '23.4');

var obj = nqMqtt.get('LwM2MObject', Date.now(), 3313, 0, 5702, 'Float', '0.01', 5703, 'Float', '0.02', 5704, 'Float', '0.03', 'G');
var arg = nqMqtt.get('LwM2MArgStr', Date.now(), 3313, 0, 5702, 'Float', '0.01', 5703, 'Float', '0.02', 5704, 'Float', '0.03', 'G');
var str = nqMqtt.get('LwM2MString', Date.now(), 3313, 0, 5702, 'Float', '0.01', 5703, 'Float', '0.02', 5704, 'Float', '0.03', 'G');

format : ’LwM2MObject’, ’LwM2MObjectS’

Creates a LwM2M object data to be used in the nqMqtt.publish().

’LwM2MObjectS’ is specified when using Privacy Mode.

format : ’LwM2MArgStr’, ’LwM2MArgStrS’

Creates a LwM2M string data to be used in the nqMqtt.publish().
It can be utilized for linking with other object functions that handle strings.

’LwM2MArgStrS’ is specified when using Privacy Mode.

format : ’LwM2MString’, ’LwM2MStringS’

Creates a LwM2M string data to be used in the batch transmission method of nqService.

’LwM2MStringS’ is specified when using Privacy Mode.

About Privacy Mode

If privacy mode is specified, value arguments will be encrypted.
LwM2M data formatted in privacy mode will be sent to the NEQTO Console and then stored in the data storage on the NEQTO Console in an encrypted state and only decrypted when the values are read out.
If using privacy mode, it is also necessary to enable the privacy mode in the corresponding component's settings on the NEQTO Console in advance.

nqMqtt.get(format,timestamp,component1[,component2[,component3[,component4]]])

Gets LwM2M data in the specified format.

It is possible to create LwM2M data of up to 4 concatenations with the same timestamp and with different object ID, instance ID, unit, resource ID, data type, and value by specifying the options as necessary.

Name	Type	M/O	Summary
format	string	mandatory	Specify the LwM2M data format name. 'LwM2MObjectA', 'LwM2MArgStrA', 'LwM2MStringA'
timestamp	number	mandatory	Timestamp Specify unixtime [ms].
component1	Array	mandatory	Component Data Array
component2	Array	optional	Component Data Array
component3	Array	optional	Component Data Array
component4	Array	optional	Component Data Array
return	Object, string, undefined	-	The return type is determined by format. If `'LwM2MObjectA'` is specified, the type is Object; if `'LwM2MArgStrA'` is specified, the type is string; if `'LwM2MStringA'` is specified, the type is string. If the creation fails, undefined will be returned.

The following is an usage example.

var component1 = [3303, 0, 5700, 'Float', '0.1'];
var component2 = [3303, 1, 5700, 'Float', '0.2', 'deg'];
var component3 = [3300, 0, 5700, 'Integer', '123', '%', 1];
var component4 = [3341, 0, 5527, 'String', 'ABC', , 1];
var obj = nqMqtt.get('LwM2MObjectA', Date.now(), component1, component2, component3, component4);
var arg = nqMqtt.get('LwM2MArgStrA', Date.now(), component1, component2, component3, component4);
var str = nqMqtt.get('LwM2MStringA', Date.now(), component1, component2, component3, component4);

format : ’LwM2MObjectA’

Creates a LwM2M object data to be used in the nqMqtt.publish().

format : ’LwM2MArgStrA’

Creates a LwM2M string data to be used in the nqMqtt.publish().
It can be utilized for linking with other object functions that handle strings.

format : ’LwM2MStringA’

Creates a LwM2M string data to be used in the batch transmission method of nqService.

Component Data Array : [objId,insId,resId,datatype,value,unit,privacyMode]

For Object ID, Instance ID, Resource ID and Data Type, please refer here.
In addition, this setting must match a component's settings on the NEQTO Console.

Index	Name	Type	M/O	Summary
0	objId	number	mandatory	Object ID The object ID uses the number defined by LwM2M.
1	insId	number	mandatory	Instance ID If there are multiple of the same Resource ID pairs, this is used to differentiate between them.
2	resId	number	mandatory	Resource ID The resource ID uses the number defined by LwM2M.
3	datatype	string	mandatory	Data Type The data type uses the number defined by LwM2M. ('Float', 'Integer', 'String', 'Boolean')
4	value	string	mandatory	Value Specify a `string` type value. When referencing data of type `number`, convert it to a string and specify it.
5	unit	string	optional	Unit Specify any string indicating the unit. If undefined is specified, unit will not be used. ('G', 'm', 's', 'ms', ...) The default value is undefined.
6	privacyMode	number	optional	Privacy Mode 1: Enabled 0: Disabled The default value is 0.

Appendix

Object ID, Instance ID, Resource ID and Data Type

In NEQTO Console, you can select data display format and graph by resource ID. For the object ID, select any from the available IDs. See the LwM2M specification for examples of object ID and resource ID combinations. The instance ID is used to distinguish between multiple combinations of the same resource ID and object ID. The data type is defined in relation to the resource ID.

The object ID, resource ID and data type supported by NEQTO are as follows;

Name	Object ID
Generic Sensor	3300
Illuminance	3301
Temperature	3303
Humidity	3304
Accelerometer	3313
Magnetometer	3314
Current	3317
Pressure	3323
Acidity(pH)	3326
Conductivity	3327
Distance	3330
Colour	3335
Location	3336
Addressable Text Display	3341
On/Off switch	3342
Multi-state Selector	3348

Name	Resource ID	Data Type
Digital Input State	5500	Boolean
Digital Input Counter	5501	Float, Integer
Latitude	5514	String
Longitude	5515	String
Text	5527	String
Multi-state Input	5547	Float, Integer
Sensor Value	5700	Float, Integer
X Value	5702	Float, Integer
Y Value	5703	Float, Integer
Z Value	5704	Float, Integer
Colour	5706	String
Application Type	5750	Float, Integer

The following are examples of temperature sensor, humidity sensor, and acceleration sensor.

//value,Xvalue,Yvalue,Zvalue: Any numeric character string

var timestamp = Date.now();

//Temperature sensor (ObjectID:Temperature, ResourceID:Sensor Value, DataType:Float)
nqMqtt.get('LwM2MObject', timestamp, 3303, 0, 5700, "Float", value);

//Humidity sensor (ObjectID:Humidity, ResourceID:Sensor Value, DataType:Float)
nqMqtt.get('LwM2MObject', timestamp, 3304, 0, 5700, "Float", value);

//Acceleration sensor (ObjectID:Accelerometer, ResourceID:X/Y/Z Value, DataType:Float)
nqMqtt.get('LwM2MObject', timestamp, 3313, 0, 5702, "Float", Xvalue, 5703, "Float", Yvalue, 5704, "Float", Zvalue);

{MqttError}

Methods()/Properties	Type	Summary	Note
.code	number	Error code Refer to mqtt errors table for error code details.
.message	string	Error contents Refer to mqtt errors table for error content details.

mqtt errors table

The following is the error code table.
"✓" indicates the callback to be notified. (xx.xx.xx) is the supported FW version.

.code	.message	Note	.on('error',cb)	.publish(cb)
0	OK	No error		✓
1	Connection failed	Connection (reconnection) failure	✓
10	Illegal argument	Invalid argument error	✓	✓ (02.00.00+)
11	Disconnected	Disconnect error		✓ *
12	Publish failed	Publish failed	✓ (02.00.00+)	✓
13	Subscribe failed	Subscribe failed	✓ (02.00.00+)
14	Unsubscribe failed	Unsubscribe failed	✓ (02.00.00+)
255	Other error	Other errors	✓

* Obsolete since Version 02.00.00.

Object Usage Examples

Sample 1

This is a sample using nqMqtt.get() ⁽¹⁾.
Publishes 3-axis acceleration data, temperature data, and color data to NEQTO Console.
Additionally, displays custom messages received from NEQTO Console.

//==============================================================
// nqMqtt event handler
//==============================================================
nqMqtt.on('connect', function(connack) {
    print(Date() + ': nqMqtt connect');
});
nqMqtt.on('close',function() {
    print(Date() + ': nqMqtt close');
});
nqMqtt.on('error', function(error) {
    print(Date() + ': nqMqtt error: ' + error.code.toString());
});
nqMqtt.on('push', function(message) {
    print(Date() + ': nqMqtt push: ' + message);
    //TODO: Custom message handling from NEQTO
});

//==============================================================
// Main routine
//==============================================================
//Publish "Acceleration"
while(!nqMqtt.canPublish()) { setTimeout(100).wait(); }
var x = (1.0).toFixed(1); /* dummy X value */
var y = (1.1).toFixed(1); /* dummy Y value */
var z = (1.2).toFixed(1); /* dummy Z value */
var utime = Date.now();
var acceObj = nqMqtt.get('LwM2MArgStr', utime, 3313, 0, 5702, 'Float', x, 5703, 'Float', y, 5704, 'Float', z);
nqMqtt.publish(null, acceObj, function(err) {
    if(err.code == 0) {
        print('publish OK');
    } else {
        print('publish NG');
    }
});

//Publish "Temperature"
while(!nqMqtt.canPublish()) { setTimeout(100).wait(); }
var temp = (20.2).toFixed(1); /* dummy Temperature */
var utime = Date.now();
var tempObj = nqMqtt.get('LwM2MArgStr', utime, 3303, 0, 5700, 'Float', temp);
nqMqtt.publish(null, tempObj, function(err) {
    if(err.code == 0) {
        print('publish OK');
    } else {
        print('publish NG');
    }
});

//Publish "Color"
while(!nqMqtt.canPublish()) { setTimeout(100).wait(); }
var color = '#FFFF99'; /* dummy Color */
var utime = Date.now();
var colorObj = nqMqtt.get('LwM2MArgStr', utime, 3335, 0, 5706, 'String', color);
nqMqtt.publish(null, colorObj, function(err) {
    if(err.code == 0) {
        print('publish OK');
    } else {
        print('publish NG');
    }
});

Sample 2

This is a sample using nqMqtt.get() ⁽²⁾.
Publishes temperature and humidity data with the same timestamp to NEQTO Console at one time.
Additionally, displays custom messages received from NEQTO Console.

//==============================================================
// nqMqtt event handler
//==============================================================
nqMqtt.on('connect', function(connack) {
    print(Date() + ': nqMqtt connect');
});
nqMqtt.on('close',function() {
    print(Date() + ': nqMqtt close');
});
nqMqtt.on('error', function(error) {
    print(Date() + ': nqMqtt error: ' + error.code.toString());
});
nqMqtt.on('push', function(message) {
    print(Date() + ': nqMqtt push: ' + message);
    //TODO: Custom message handling from NEQTO
});

//==============================================================
// Main routine
//==============================================================
//Publish "Temperature" and "Humidity"
while(!nqMqtt.canPublish()) { setTimeout(100).wait(); }
var temp = (20.4).toFixed(1); /* dummy Temperature */
var humi = (52.5).toFixed(1); /* dummy Humidity */
var msg = nqMqtt.get('LwM2MArgStrA', Date.now(), [3303, 0, 5700, 'Float', temp], [3304, 0, 5700, 'Float', humi]);
nqMqtt.publish(null, msg, function(err) {
    if(err.code == 0) {
        print('publish OK');
    } else {
        print('publish NG');
    }
});

Updated: 2023-09-28