AWS IoT Core v2

This library is a built-in class that provides functions to communicate with AWS IoT Core.

Library usage requirements
Type	Integrations
Name	AWS_IoT_Core_V2
Version	2.1.0
Code size used	3.2KB
Resources used	HTTPS x 1, MQTT x 1, Timers x 1

Abstracts

Methods()/Properties	Summary	Note
new AWS_IOT_CORE()	Creates an AWS_IOT_CORE instance.

{AWS_IOT_CORE} Instance

Methods()/Properties	Summary	Note
.httpPost()	Sends data to AWS IoT Core via HTTPS.
.abortHttpRequest()	Aborts the currently ongoing HTTP request.
.mqttConnect()	Connects to AWS IoT Core with MQTT.
.errors	Array containing invalid key names (string) Generated when an invalid parameter is detected in the constructor or .setConfig().
.CONST.VERSION	Version (string)	v2.1.0+

Details

new AWS_IOT_CORE([config])

Creates an AWS_IOT_CORE instance.

Name	Type	M/O	Description	Note
config	Object	optional	Configuration Refer to config for details.
return	{AWS_IOT_CORE}	-	{AWS_IOT_CORE} : Generated {AWS_IOT_CORE}	If invalid parameters are detected, .errors will be generated.

config

Name	Type	M/O	Description	Note
host	string	mandatory	An AWS IoT Core endpoint
deviceCert	string	mandatory	The X.509 certificate associated with this device Specify a string in PEM format. Use `\n` for line feed code.
devicePrivKey	string	mandatory	The private key associated with this device Specify a string in PEM format. Use `\n` for line feed code.
ca	string	mandatory	Root CA certificate for AWS IoT Core Specify a string in PEM format. Use `\n` for line feed code.
httpTimeout	number	optional	HTTP request timeout value [s] If `0`, the timeout function is disabled. The default value is `0`.	v2.1.0+
timeout	number	-	This parameter is ignored.	Unused

Set the Configuration (config) when creating an AWS_IOT_CORE instance.
If an invalid parameter is detected, an array containing the name of the invalid keys is generated as the .errors property. If the parameters are successful, the .errors property will be deleted.

var iot = new AWS_IOT_CORE({
    host: <value>,
    deviceCert: <value>,
    devicePrivKey: <value>,
    ca: <value>
});
if('errors' in iot) {
    //TODO: Handle errors
}

.setConfig(config)

Set the Configuration (config) after the AWS_IOT_CORE instance is created.
If an invalid parameter is detected, an array containing the name of the invalid keys is generated as the .errors property. If the parameters are successful, the .errors property will be deleted.

var iot = new AWS_IOT_CORE();
iot.setConfig({
    host: <value>,
    deviceCert: <value>,
    devicePrivKey: <value>,
    ca: <value>
});
if('errors' in iot) {
    //TODO: Handle errors
}

Setter Methods

After the AWS_IOT_CORE instance is created, Configuration (config) can be set individually using the following setter methods.
If successful, the own instance is returned. If an invalid parameter is detected, false is returned.

Setter Method	Description	Note
.setHost(value)	Sets the `host`.
.setDeviceCert(value)	Sets the `deviceCert`.
.setDevicePrivKey(value)	Sets the `devicePrivKey`.
.setRootCA(value)	Sets the `ca`.
.setHttpTimeout(value)	Sets the `httpTimeout`.	v2.1.0+
.setTimeout(value)	Sets the `timeout`.	Unused

.httpPost(topic,headers,getBody,callback[[,qos],sockTo])

Sends data to AWS IoT Core via HTTPS.
The destination will be the AWS IoT Core endpoint specified by topic.

Name	Type	M/O	Description	Note
topic	string	mandatory	Specify the MQTT topic. This configuration value is converted to `/topics/${topic}`.
headers	object	mandatory	Specify HTTP request headers. "Content-Length" must be included.
getBody	function	mandatory	Execute callback processing at the timing when this method will accept the data (`body`) to be sent. Returns data in `string` or `ArrayBuffer` chunks of 4KB or less until there is no more data, and finally returns `null`.
callback(err, resp)	function	mandatory	Execute callback processing when this method is completed. Notify the processing result using the argument of the callback function. err: {HttpReqError}, null resp: {HttpResponse}, null If an error occurs in the HTTP request, `err` is set; if an HTTP response could be received, `resp` is set.
qos	number	optional	Specify the MQTT quality of service level. This configuration value is converted to `?qos=${qos}`. The default value is `0`.
sockTo	number	optional	Specify the HTTP session timeout value [ms]. This parameter is the `sockTo` setting value of the `https.request()` method. For details, refer to the HTTPS object specification.	v2.1.0+
return	undefined	-

{HttpReqError}

Name	Type	Description	Note
.errCode	number	The error code of the HTTPS request For details, refer to the error code table of the HTTPS object.

{HttpResponse}

Name	Type	Description
.statusCode	number	The status code of the HTTP response
.statusMessage	string	The status message of the HTTP response
.body	string, null	HTTP response data (`Response-Body`)

.abortHttpRequest()

Aborts the currently ongoing HTTP request.

Name	Type	M/O	Description	Note
return	undefined	-

.mqttConnect([options])

Connects to AWS IoT Core with MQTT.

This method is a wrapper function for the mqtt.connect() method.
Create an MQTT client instance {Client} for MQTT connection to AWS IoT Core.
Refer to MQTT object specification for information on how to use the generated {Client} instance.

Name	Type	M/O	Description	Note
options	object	optional	This parameter is the `options` setting of the `mqtt.connect()` method. For details, refer to the MQTT object specification.
return	{Client}, undefined	-	MQTT client instance for AWS IoT Core

Configuration values related to `mqtt.connect()` that are overridden by this method:

mqtt.set(’ssl.ca’, certificate)
- certificate: config.ca
mqtt.set(’ssl.cert’, certificate)
- certificate: config.deviceCert
mqtt.set(’ssl.key’, clientkey)
- clientkey: config.devicePrivKey
mqtt.connect(url[, options])
- url: mqtts://${config.host}:8883

Usage Examples

The following common code is used in all sample code:

Make sure that the root CA certificate is appropriate for the AWS IoT Core endpoint in advance.
For information on how to obtain a CA certificate, please refer to here.

log.setLevel(0,2); //-1:NONE 0:ERROR 1:WARNING 2:DEBUG 3:TRACE, 0:DISABLE 1:LOG 2:CONSOLE 3:BOTH
log.printLevel(2); //0:DISABLE 1:LOG 2:CONSOLE 3:BOTH

var rootCa = '-----BEGIN CERTIFICATE-----\n...<CA>...\n-----END CERTIFICATE-----';
var deviceCert = '-----BEGIN CERTIFICATE-----\n...<CERT>...\n-----END CERTIFICATE-----';
var deviceKey = '-----BEGIN RSA PRIVATE KEY-----\n...<KEY>...\n-----END RSA PRIVATE KEY-----';

//TODO: Configuration
var iot = new AWS_IOT_CORE({
    host: <value>,
    deviceCert: deviceCert,
    devicePrivKey: deviceKey,
    ca: rootCa
});
if('errors' in iot) {
    //TODO: Handle errors
    throw new Error("Invalid configuration");
}

Sample 1

Send data to AWS IoT Core via HTTPS.

var topic = "testtopic/shadowtopic/dummy";
var body = JSON.stringify({
    "message": "HTTP post"
});
var headers = {
    "Content-Length": body.length.toString()
};

var busy;
var getBody = function() {
    var temp = body;
    body = null;
    return temp;
};
var callback = function(err, resp) {
    if(err) {
        print("Error!", err.errCode);
    } else {
        print("Response:", resp.body);
        print("Status:", resp.statusCode, resp.statusMessage);
    }
    busy = false;
};

busy = true;
iot.httpPost(topic, headers, getBody, callback);
while(busy);
print("Done");

Sample 2

Send data in chunks to AWS IoT Core via HTTPS.

var topic = "testtopic/shadowtopic/dummy";
var body = JSON.stringify({
    "message": "This is a really long string[...]"
});
var headers = {
    "Content-Length": body.length.toString()
};

var busy;
var chunkSize = 8; //4KB or less
var index = 0;
var getBody = function() {
    var chunk = body.substring(index, index + chunkSize);
    if(chunk) {
        index = index + chunkSize;
        return chunk;
    }
    return null;
};
var callback = function(err, resp) {
    if(err) {
        print("Error!", err.errCode);
    } else {
        print("Response:", resp.body);
        print("Status:", resp.statusCode, resp.statusMessage);
    }
    busy = false;
};

busy = true;
iot.httpPost(topic, headers, getBody, callback);
while(busy);
print("Done");

Sample 3

Connect to AWS IoT Core with MQTT.
Use the automatic reconnection feature of the MQTT object.

var mqttConnect = function(onConnected, onDisconnected) {
    var cli = iot.mqttConnect({ reconnectCount: 1855 }); //Enable automatic reconnection
    if(!cli) return undefined;
    cli.on('error', function(err) {
        //TODO: Handle errors
        print("Error!", err.code, `(${cli.get('errnoConnect')})`);
    });
    cli.on('message', function(topic, message) {
        //TODO: Handle messages
        print("Message:", `[${topic}]`, message);
    });
    cli.on('close', function() {
        print("DISCONNECTED");
        if(onDisconnected) {
            onDisconnected();
        }
    });
    cli.on('connect', function() {
        print("CONNECTED");
        if(onConnected) {
            onConnected();
        }
    });
    return cli;
};

var onMqttConnect = function() {
    client.subscribe("testtopic/subtopic/#", { qos: 1 }, function(err) {
        if(err.code != 0) {
            //TODO: Handle errors
            print("Subscribe failed:", err.code);
        }
    });
};

var client = mqttConnect(onMqttConnect);
if(!client) {
    throw new Error("Failed to create mqtt instance");
}

var publishInterval = 5 * 1000;
var publishEvent = false;
var publishCnt = 0;
setInterval(function() {
    publishEvent = true;
}, publishInterval);

while(1) {
    if(client && client.canPublish() && publishEvent) {
        publishEvent = false;
        publishCnt++;
        var message = JSON.stringify({ "message": "publish" + publishCnt });
        client.publish("testtopic/subtopic/dummy", message, { qos: 1 }, function(err) {
            if(err.code == 0) {
                print("Publish OK");
            } else {
                //TODO: Handle errors
                print("Publish failed:", err.code);
            }
        });
    }
}

Sample 4

Connect to AWS IoT Core with MQTT.
Performs manual reconnection not using the automatic reconnection feature of the MQTT object.

var mqttConnect = function(onConnected, onDisconnected) {
    var cli = iot.mqttConnect();
    if(!cli) return undefined;
    cli.on('error', function(err) {
        //TODO: Handle errors
        print("Error!", err.code, `(${cli.get('errnoConnect')})`);
        if(err.code == 1 && onDisconnected) { //Connection failed
            onDisconnected();
            return;
        }
    });
    cli.on('message', function(topic, message) {
        //TODO: Handle messages
        print("Message:", `[${topic}]`, message);
    });
    cli.on('close', function() {
        print("DISCONNECTED");
        if(onDisconnected) {
            onDisconnected();
        }
    });
    cli.on('connect', function() {
        print("CONNECTED");
        if(onConnected) {
            onConnected();
        }
    });
    return cli;
};

var onMqttConnect = function() {
    client.subscribe("testtopic/subtopic/#", { qos: 1 }, function(err) {
        if(err.code != 0) {
            //TODO: Handle errors
            print("Subscribe failed:", err.code);
        }
    });
};
var onMqttDisconnect = function() {
    setTimeout(function() {
        print("Reconnecting...");
        client.reconnect();
    }, 10000);
};

var client = mqttConnect(onMqttConnect, onMqttDisconnect);
if(!client) {
    throw new Error("Failed to create mqtt instance");
}

var publishInterval = 5 * 1000;
var publishEvent = false;
var publishCnt = 0;
setInterval(function() {
    publishEvent = true;
}, publishInterval);

while(1) {
    if(client && client.canPublish() && publishEvent) {
        publishEvent = false;
        publishCnt++;
        var message = JSON.stringify({ "message": "publish" + publishCnt });
        client.publish("testtopic/subtopic/dummy", message, { qos: 1 }, function(err) {
            if(err.code == 0) {
                print("Publish OK");
            } else {
                //TODO: Handle errors
                print("Publish failed:", err.code);
            }
        });
    }
}

The company names and product names mentioned above are registered trademarks or trademarks of their respective companies.

Updated: 2024-03-26

NEQTO Apps

Hardware Specifications

Software Specifications

neqto.js

Hardware Specifications

Software Specifications

neqto.js

Hardware Specifications

Software Specifications

neqto.js

Software Specifications

neqto.js

UART

I2C

Utils

Integration

Related Documents

Abstracts

{AWS_IOT_CORE} Instance

Details

new AWS_IOT_CORE([config])

config

.setConfig(config)

Setter Methods

.httpPost(topic,headers,getBody,callback[[,qos],sockTo])

{HttpReqError}

{HttpResponse}

.abortHttpRequest()

.mqttConnect([options])

Configuration values related to `mqtt.connect()` that are overridden by this method:

Usage Examples

Sample 1

Sample 2

Sample 3

Sample 4

Related Documents

Abstracts

{AWS_IOT_CORE} Instance

Details

new AWS_IOT_CORE([config])

config

.setConfig(config)

Setter Methods

.httpPost(topic,headers,getBody,callback[[,qos],sockTo])

{HttpReqError}

{HttpResponse}

.abortHttpRequest()

.mqttConnect([options])

Configuration values related to mqtt.connect() that are overridden by this method:

Usage Examples

Sample 1

Sample 2

Sample 3

Sample 4

Configuration values related to `mqtt.connect()` that are overridden by this method: