21. nqMqtt

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()/PropertiesSummaryVersionNote
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.on(event,callback)

Registers an event handler.

NameTypeM/OSummaryNote
eventstringmandatoryEvent name
Names that can be used are: push, connect, reconnect, close, error
callback()functionmandatoryExecutes callback processing when an event occurs.
returnundefined--

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:

ArgumentsTypeSummaryNote
messagestringReceived message
A string of up to 380 bytes.
If the 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:

ArgumentsTypeSummaryNote
connackObjectconnack 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:

ArgumentsTypeSummaryNote
err{MqttError}Error information

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

Publishes a message to NEQTO Console.

NameTypeM/OSummaryNote
topicnullmandatoryTopic Name
This value must always be set to null.
messageObject, stringmandatoryMessage 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 2500 bytes. If the permitted size is exceeded, an argument error will occur and the .on('error') callback process will be executed.
optionsObjectoptionalPublish Options
Not used. Please omit it.
callback(err)functionoptionalExecute the callback process when the publish process is completed.
err : {MqttError}
Error information
When err.code is 0, it means success.
returnundefined, {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.

NameTypeM/OSummaryNote
callback()functionoptionalExecutes callback processing when nqMqtt terminates.
returnundefined--

nqMqtt.isConnected()

Gets MQTT connection status.

NameTypeM/OSummaryNote
returnboolean-MQTT connection status
true: MQTT connected
false: Not connected

nqMqtt.isReconnecting()

Gets the status of MQTT when reconnecting.

NameTypeM/OSummaryNote
returnboolean-MQTT reconnecting status
true: MQTT reconnecting
false: Not reconnecting

nqMqtt.canPublish()

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

NameTypeM/OSummaryNote
returnboolean-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.

NameTypeM/OSummaryNote
formatstringmandatorySpecify the LwM2M data format name.
'LwM2MObject', 'LwM2MObjectS',
'LwM2MArgStr', 'LwM2MArgStrS',
'LwM2MString', 'LwM2MStringS'
timestampnumbermandatoryTimestamp
Specify unixtime [ms].
objIdnumbermandatoryObject ID
The object ID uses the number defined by LwM2M.
insIdnumbermandatoryInstance ID
If there are multiple of the same Resource ID pairs, this is used to differentiate between them.
resIdnumbermandatoryResource ID
The resource ID uses the number defined by LwM2M.
datatypestringmandatoryData Type
The data type uses the number defined by LwM2M.
('Float', 'Integer', 'String', 'Boolean')
valuestringmandatoryValue
Specify a string type value.
When referencing data of type number, convert it to a string and specify it.
resId2numberoptionalThe second resource ID.
Same as resId.
resId, resId2, resId3, resId4 must specify different values for each.
datatype2stringoptionalThe second data type
Same as datatype.
value2stringoptionalThe second value
Same as value.
resId3numberoptionalThe third resource ID.
Same as resId.
resId, resId2, resId3, resId4 must specify different values for each.
datatype3stringoptionalThe third data type
Same as datatype.
value3stringoptionalThe third value
Same as value.
resId4numberoptionalThe fourth resource ID.
Same as resId.
resId, resId2, resId3, resId4 must specify different values for each.
datatype4stringoptionalThe fourth data type
Same as datatype.
value4stringoptionalThe fourth value
Same as value.
unitstringoptionalUnit
Specify any string indicating the unit.
If undefined is specified, unit will not be used.
('G', 'm', 's', 'ms', ...)
The default value is undefined.
returnObject,
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.

NameTypeM/OSummaryNote
formatstringmandatorySpecify the LwM2M data format name.
'LwM2MObjectA', 'LwM2MArgStrA', 'LwM2MStringA'
timestampnumbermandatoryTimestamp
Specify unixtime [ms].
component1ArraymandatoryComponent Data Array
component2ArrayoptionalComponent Data Array
component3ArrayoptionalComponent Data Array
component4ArrayoptionalComponent Data Array
returnObject,
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.

IndexNameTypeM/OSummaryNote
0objIdnumbermandatoryObject ID
The object ID uses the number defined by LwM2M.
1insIdnumbermandatoryInstance ID
If there are multiple of the same Resource ID pairs, this is used to differentiate between them.
2resIdnumbermandatoryResource ID
The resource ID uses the number defined by LwM2M.
3datatypestringmandatoryData Type
The data type uses the number defined by LwM2M.
('Float', 'Integer', 'String', 'Boolean')
4valuestringmandatoryValue
Specify a string type value.
When referencing data of type number, convert it to a string and specify it.
5unitstringoptionalUnit
Specify any string indicating the unit.
If undefined is specified, unit will not be used.
('G', 'm', 's', 'ms', ...)
The default value is undefined.
6privacyModenumberoptionalPrivacy 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;

NameObject ID
Generic Sensor3300
Illuminance3301
Temperature3303
Humidity3304
Accelerometer3313
Magnetometer3314
Current3317
Pressure3323
Acidity(pH)3326
Conductivity3327
Distance3330
Colour3335
Location3336
Addressable Text Display3341
On/Off switch3342
Multi-state Selector3348
NameResource IDData Display FormatData Type
Digital Input State5500Boolean
Digital Input Counter5501Float,
Integer
Latitude5514String
Longitude5515String
Text5527String
Multi-state Input5547Float,
Integer
Sensor Value5700Float,
Integer
X Value5702Float,
Integer
Y Value5703Float,
Integer
Z Value5704Float,
Integer
Colour5706String
Application Type5750Float,
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()/PropertiesTypeSummaryNote
.codenumberError code
Refer to mqtt errors table for error code details.
.messagestringError 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.messageNote.on('error',cb).publish(cb)
0OKNo error✓
1Connection failedConnection (reconnection) failure✓
10Illegal argumentInvalid argument error✓✓ (02.00.00+)
11DisconnectedDisconnect error✓ *
12Publish failedPublish failed✓ (02.00.00+)✓
13Subscribe failedSubscribe failed✓ (02.00.00+)
14Unsubscribe failedUnsubscribe failed✓ (02.00.00+)
255Other errorOther 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: 2022-06-03
← 20. nqService22. nqFOTA →