20. nqMqtt

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

Functional overview:

Provides functions to send measurements and arbitrary data to NEQTO Console.
Provides a function to receive push notifications from NEQTO Console.

nqMqtt Global Object

Methods()/Properties	Summary	Version	Note
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 information related to the given argument.	00.00.15+	The following arguments can be used as of version `00.00.20+`: 'LwM2MObjectS','LwM2MArgStrS','LwM2MString'

Details

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’

Registers a push event handler. 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 380 bytes. If maximum number of bytes is exceeded, the message is discarded.

event: ’connect’

Registers a connect event handler. 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’

Registers a reconnect event handler. Executes callback when MQTT reconnection is started.

event: ’close’

Registers a close event handler. Executes callback when MQTT is disconnected.

event: ’error’

Registers an error event handler. 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	string, Object	mandatory	Message to publish Specify the object returned by nqMqtt.get('LwM2MObject') or nqMqtt.get('LwM2MArgStr'). If the message to be published is more than 2500 bytes, an argument error occurs and the callback process of .on('error') is 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	-	-

Note: If the next publish() is performed before the current publish() callback, the latter pubish() may be discarded. Before performing a publish(), it is recommended to check whether the callback of the previous publish() has been executed, or check whether publishing is possible with canPublish().

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(name[,args...])

Gets information related to the given argument.

Name	Type	M/O	Summary
name	string	mandatory	The name of the data object to be obtained Names that can be used are; LwM2MObject, LwM2MArgStr, LwM2MString, LwM2MObjectS, LwM2MArgStrS, LwM2MStringS Generally, use 'LwM2MObject'. Use 'LwM2MArgStr' when temporarily saving to a memory block. Use 'LwM2MString' when sending sensor data using nqService.
args	string, number	optional	Arguments used when getting the value
return	Object, string, undefined	-	Object : The requested object string : The requested string data undefined : Failure due to request error

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

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

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

Name	Type	M/O	Summary
’LwM2MObject’	string	mandatory	Name to get LwM2M object data
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. ('G', 'm', 's', 'ms', ...)
return	Object, undefined	-	Object : The created object data undefined : If creation fails

Up to 4 objects created by nqMqtt.get(’LwM2MObject’) can be combined and used in nqMqtt.publish(). This sample publishes by combining temperature and humidity.

var utime = new Date().getTime();
var tempObj = nqMqtt.get(   'LwM2MObject',
                            utime,
                            3303,
                            0,
                            5700,'Float','25.0');
var humiObj = nqMqtt.get(   'LwM2MObject',
                            utime,
                            3304,
                            0,
                            5700,'Float','50.0');
var pubObj = [ tempObj , humiObj ];
nqMqtt.publish(null, pubObj, function(err){
    if(0 == err.code){
        print('publish OK');
    }
    else{
        print('publish NG');
    }
});

Note the allowable size of the publish message.

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

Creates a LwM2M string data to be used in the message of nqMqtt.publish().

Name	Type	M/O	Summary
’LwM2MArgStr’	string	mandatory	Name to get LwM2M string data
:	:	:	Subsequent arguments are the same as LwM2MObject.
return	Object undefined	-	string : The created string data undefined : If creation fails

Up to 4 objects created by nqMqtt.get(’LwM2MArgStr’) can be combined and used in nqMqtt.publish(). This sample publishes by combining temperature and humidity.

var utime = new Date().getTime();
var tempObj = nqMqtt.get(   'LwM2MArgStr',
                            utime,
                            3303,
                            0,
                            5700,'Float','25.0');
var humiObj = nqMqtt.get(   'LwM2MArgStr',
                            utime,
                            3304,
                            0,
                            5700,'Float','50.0');
var pubObj = tempObj + ',' + humiObj;
nqMqtt.publish(null, pubObj, function(err){
    if(0 == err.code){
        print('publish OK');
    }
    else{
        print('publish NG');
    }
});

Note the allowable size of the publish message.

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

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

Name	Type	M/O	Summary
’LwM2MString’	string	mandatory	Name to get LwM2M string data
:	:	:	Subsequent arguments are the same as LwM2MObject.
return	Object undefined	-	string : The created string data undefined : If creation fails

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

Creates a LwM2M object data to be used in the message of nqMqtt.publish(). Functionally the same as LwM2MObject, but each of the returned values are encrypted.

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

Creates a LwM2M string data to be used in the message of nqMqtt.publish(). Functionally the same as LwM2MArgStr, but each of the returned values are encrypted.

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

Creates a LwM2M string data to be used in the batch transmission method of nqService. Functionally the same as LwM2MString, but each of the returned values are encrypted.

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 = new Date().getTime();

//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

Error code table.

.code	.message	Note
0	OK	No error
1	Connection failed	Connection (reconnection) failure
10	Illegal argument	Invalid argument error
11	Disconnected	Disconnect error
12	Publish failed	Publish failed
13	Subscribe failed	Subscribe failed
14	Unsubscribe failed	Unsubscribe failed
255	Other error	Other errors
Others	Reserved	Reserved

Object Usage Examples

Sample 1

This is a sample to perform the following processing.

Prints custom messages received from the NEQTO Console.
Create and publish "acceleration", "temperature", and "color" data respectively.

//Register event handler
nqMqtt.on('connect',function(connack){
    print('mqttConnect');
});
nqMqtt.on('close',function(){
    print('nqMqttClose');
});
nqMqtt.on('error',function(err){
    print('mqttError:'+err.code.toString());
});
nqMqtt.on('push',function(message){
    print(message); //Received custom message
});

//Publish "Acceleration"
while(false==nqMqtt.canPublish()){setTimeout(100).wait();}
var valX = 1.0; /* dummy X value */
var valY = 1.1; /* dummy Y value */
var valZ = 1.2; /* dummy Z value */
var strX = valX.toFixed(1);
var strY = valY.toFixed(1);
var strZ = valZ.toFixed(1);
var utime = new Date().getTime();
var acceObj = nqMqtt.get(   'LwM2MObject',
                            utime,
                            3313,
                            0,
                            5702,'Float',strX,
                            5703,'Float',strY,
                            5704,'Float',strZ);
nqMqtt.publish(null,acceObj,function(err){
    if(0==err.code){
        print('publish OK');
    }
    else{
        print('publish NG');
    }
});

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

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

Updated: 2021-02-19

Step 2. Device Setting & Start Service

Hardware Specifications

Software Specifications

neqto.js