Azure IoT v2

このライブラリは、Azure IoT Hubと通信する機能を提供する組み込みクラスです。

Library usage requirements
Type	Integrations
Name	Azure_IoT_V2
Version	2020-11-04
Code size used	2.8KB
Resources used	HTTPS x 1, MQTT x 1, Timers x 1

Abstracts

Methods()/Properties	Summary
`new AZURE_IOT()`	`AZURE_IOT`インスタンスを初期化します。

{AZURE_IOT} Instance

Methods()/Properties	Summary
`.generateSasToken()`	Azure IoT Hubでこのデバイスを認証するために使用するSASトークンを生成します。
`.httpPost()`	HTTPS経由でAzure IoT Hubにデータを送信します。
`.abortHttpRequest()`	現在進行中のHTTPリクエストを中止します。
`.mqttConnect()`	Azure IoT HubにMQTT接続します。
`.errors`	無効なキー名を含む配列。無効な構成が `setConfig`またはコンストラクターに渡された場合にのみ存在します。

Details

`new AZURE_IOT(config)`

AZURE_IOTインスタンスを初期化します。

Configuration

AZURE_IOT オブジェクトのインスタンスを作成する際には、以下の設定が必要です。

Name	Type	Default	Summary
`host`	string	MANDATORY	有効なAzure IoT Hubエンドポイント。デフォルトでは、Azure IoT HubのDNS名は `{IoT Hub 名}.azure-devices.net` のようになります。
`deviceId`	string	MANDATORY	Azure IoT Hub内のデバイスIDです。これは、Azure IoT HubのIDレジストリにデバイスを登録したときに作成されます。
`primaryKey`	string	MANDATORY	Azure IoT Hubのサービスプライマリキーです。これは、ID レジストリからの対称キー、または共有アクセス・ポリシーからの鍵のいずれかになります。
`ca`	string	MANDATORY	Azure IoT HubとHTTP通信する際に使用するルートCA。
`timeout`	number	90000	デフォルトは 90000 ミリ秒 (90 秒)です。HTTPSリクエストの場合、リクエストが自動的にタイムアウトするまでの時間を変更します。
`tokenTimeout`	number	3600	デフォルトは3600秒（1時間）です。生成されたSASトークンが有効な時間 (秒)です。

configは以下の形式のJavaScriptオブジェクトでなければなりません。

var config = {
    host: "<String>",
    deviceId: "<String>",
    primaryKey: "<String>",
    ca: "<String>"
    timeout: "<Number>",
    tokenTimeout: "<Number>"
};

設定オブジェクトが作成されると、インスタンス作成時に AZURE_IOT に渡すことができます。無効な値が渡された場合、setConfigの結果はerrorsプロパティに格納されるため、適切に処理する必要があります。

var iot = new AZURE_IOT(config);
if ('errors' in iot) {
    // TODO: handle errors
}

Setter Methods

AZURE_IOT オブジェクトのインスタンスを作成した後、対応するセッターメソッドを用いて前述の設定を変更することができます。無効な値がいずれかのセッターメソッドに渡されると、 false が返されます。

Setter	Summary
`.setHost(value: String)`	Azure IoT Hubに接続する際に使用する `Host` の値を設定します。Azure IoT Hub コンソールでは、この値はデバイスを表示する際の「Primary Connection String」属性の `HostName` になります。
`.setDeviceId(value: String)`	このデバイスの認証に使用する `deviceId` の値を設定します。`device_id` の値は、Azure IoT Hubコンソールのデバイス詳細に記載されています。
`.setPrimaryKey(value: String)`	このデバイスの認証に使用する `primary_key` の値を設定します。`primary_key` の値は、Azure IoT Hub コンソールのデバイス詳細に記載されています。
`.setRootCA(value: String)`	リクエストを行うIoT HubインスタンスのCAを設定します。
`.setTimeout(value: Number)`	HTTPSリクエストのタイムアウトを設定します。
`.setTokenTimeout(value: Number)`	トークンのタイムアウトを設定します。

`.setConfig(config)`

setConfig メソッドを用いると、複数の設定オプションを同時に設定したり変更したりすることができます。下記のようにJSONフォーマットで指定してください。無効な値が渡された場合、無効なキーの名前を含む配列を返し、その配列にerrorsプロパティを設定します。有効な configがsetConfigに渡され、errorsが存在する場合、それは削除されます。

iot.setConfig({
    host: "value",
    deviceId: "value",
    primaryKey: "value",
    tokenTimeout: "value",
    timeout: "value"
});

Instance Methods

`.generateSasToken([resourceUri][,signingKey][,policyName][,expiresInSecs])`

Azure IoT Hub でこのデバイスを認証するために使用される SAS トークンを生成します。

Name	Type	Default	Summary
`resourceUri`	string	`{host}/devices/{deviceId}`	このデバイスのURIです。
`signingKey`	string	`{primaryKey}`	SASトークンの署名に使用されるキーです。
`policyName`	string	undefined	セキュリティトークンを生成するためのポリシー名(該当する場合)です。これは `primaryKey` として渡される値によって異なる値を持ちます。有効な値は、Azure IoT Hub セキュリティトークンのドキュメントのさまざまなセクションに記載されています。
`expiresInSecs`	string	`tokenTimeout`	トークンのタイムアウトです。
return	string	-	MQTT 接続の確立や HTTPS リクエストに使用される認証トークンです。

`.httpPost(token,length,getBody,callback[,endpoint])`

HTTPS経由でAzure IoT Hubにデータを送信します。

使用する前に、適切な権限が設定されていること、およびこのデバイスの接続がIoT Hubの制限内で許可されていることを確認してください。

Name	Type	Default	Summary
`token`	string	MANDATORY	認証に用いられるトークンで、`generateSasToken` から返されます。
`length`	string	MANDATORY	Azure IoT Hubに送信するデータ量になります。
`getBody`	function	MANDATORY	送信する`body`データを取得するためのコールバック。データがなくなるまで4KB以下の[string/ArrayBuffer]チャンクでデータを返し、最後に`null`を返します。
`callback(err, resp)`	function	MANDATORY	レスポンスを処理するためのユーザのコールバック関数です。エラーを `err`、レスポンスを `resp` として渡します。
`endpoint`	string	`/messages/events?api-version=2018-06-30`	有効なAzure IoT Hub ルーティングエンドポイントです。QoSやその他のプロパティはクエリパラメータで、Azure IoT Documentationでは `{property_bag}` として記述されています。デフォルトでは、テレメトリエンドポイント `/messages/events?api-version=2018-06-30` にPOSTします。
return	undefined	-	-

Responses

このライブラリは、Azure IoT Hubのレスポンスを処理するためにオブジェクトを使用します。これらのレスポンスは、常に以下の形式になっています。

{
    statusCode: <Number>,
    statusMessage: <String>,
    body: <String>
}

statusCode と statusMessage の詳細は、該当するデバイスの HTTPS ドキュメントを参照してください ( NEQTO Bridge | Spresense)。

bodyはHTTPSレスポンスのデータです。

Errors

このライブラリは、HTTPSのエラーから Error オブジェクトをユーザが提供するコールバックに渡します。エラーオブジェクトの形式は以下の通りです。

{
    errCode: <Number>
}

errCode パラメータの詳細はneqto.jsのドキュメントにあります。(NEQTO Bridge | Spresense )

`.abortHttpRequest()`

現在進行中のHTTPS要求を中止します。

Name	Type	Default	Summary
return	undefined	-	-

`.mqttConnect(token[,options])`

MQTT接続ドキュメントに従ってAzure IoT Hubとの接続を確立します。Azure IoT Hubは、デバイスごとにアクティブなMQTT接続を1つしかサポートしていません。

使用する前に、適切な権限が設定されていること、およびこのデバイスの接続がIoT Hubの制限の範囲内で許可されていることを確認してください。

x.509 証明書を使用した認証は現在サポートされていません。

Name	Type	Default	Summary
`token`	string	MANDATORY	認証に用いられるトークンで、`generateSasToken` から返されます。
`options`	object	{}	適切なMQTTのドキュメントにあるMQTTオプション。`clientId`, `username`, `password` は予約語であり、上書きされます。
return	MQTT.Client	-	Azure IoT Hubに接続されたMQTTクライアントです。このオブジェクトの詳細については、デバイスの適切なMQTTページを参照してください。 - NEQTO Bridge - Spresense

Usage Examples

config オプションで使用できる CAの取得方法はこちら。

ルートCAがターゲットのAzure IoT Hubエンドポイントに適切であることを確認してください。

var rootCa = '-----BEGIN CERTIFICATE-----\n...<CA>...\n-----END CERTIFICATE-----';

以下のサンプルコードのセクションでは、すべて以下の設定を使用しています。

// IMPORTED LIBRARIES
// - Azure_IoT_V2

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

// Set config
var config = {
    host: "<String>",
    deviceId: "<String>",
    primaryKey: "<String>",
    tokenTimeout: "<Number>",
    timeout: "<Number>",
    ca: rootCa
};

var iot = new AZURE_IOT(config);

if ('errors' in iot) {
    // TODO: Handle errors
    throw 'Invalid configuration'
}

Sample 1: 基本的なHTTPS通信

var token = iot.generateSasToken();
var body = "sample text to send to Azure IoT Hub"
var getBody = function() {
    var temp = body;
    body = null;
    return temp;
}
var length = body.length.toString();

var callback = function (err, data) {
    if (err) {
        print("Error!", err.errCode, err.message);
    } else {
        print(data.statusCode, data.statusMessage);
        print(data.body);
    }
}
iot.httpPost(token, length, getBody, callback);

Sample 2: トークンの有効期限が切れた場合のMQTTでの再接続

var reconnectAttempts = 0;
var client;

var reconnectSt = 0;    //0: No reconnect, 1: Reconnect backoff, 2: Expired backoff(available reconnect)
var scheduleMqttReconnect = function() {
    if(reconnectSt) {
        return;
    }
    reconnectSt = 1;    // Waiting reconnect
    var backoff = 64 * 1000;    //backoff[msec]
    reconnectAttempts++;
    if(client) {
        client.end(); // close the connection, free resources
        client = undefined; // destroy the current client
    }
    print('Reconnect backoff[ms]:' + backoff);
    setTimeout(function() {
        print('Backoff expired');
        reconnectSt=2;
    }, backoff);
}

var registerEventHandlers = function() {
    if(!client){
        print('skip registerEventHandlers()');
        return; // quit
    }
    client.on('connect', function() {
        reconnectAttempts = 0;
        if(client.isConnected()){
            client.subscribe(`devices/${config.deviceId}/messages/devicebound/#`, { 'qos' : 1 }, function(err) {
                if(err.code != 0){
                    print('subscribe() failed');
                    //TODO: Error Handling. (Reconnect is recommended)
                }
            });
        }
    });
    client.on('error', function(err) {
        print('mqttClientOnError: ' + err.code);
        if(err.code == 1) {     // 1: connection failed
            var errnoConnect = client.get('errnoConnect');
            print('errnoConnect ' + errnoConnect);
            scheduleMqttReconnect();
        } else {
            //TODO: Error Handling.
        }
    });
    client.on('message', function(topic, message) {
        print('TOPIC ' + topic);
        print('MESSAGE ' + message);
        //TODO: Message Handling
    });
    client.on('close', function() {
        print('DISCONNECTED');
        scheduleMqttReconnect();
    });
}

var publishInterval = 60 * 1000;
var publishEvent = 0;
setInterval(function() {
    publishEvent = 1;
}, publishInterval);

//  Main loop
reconnectSt = 2;
while(1) {
    if(reconnectSt == 2) {  //Allow MQTT connection
        reconnectSt = 0;
        if(!client) {
            var token = iot.generateSasToken();  //update JWT each connection. default == 1 hour.
            client = iot.mqttConnect(token);
            if(!client) {
                scheduleMqttReconnect();
            } else {
                registerEventHandlers();
            }
        } else {
            client.reconnect();
        }
    }
    if(client && client.canPublish()) {
        if(publishEvent) {
            publishEvent = 0;
            client.publish(`devices/${config.deviceId}/messages/events/?api-version=2018-06-30`, 'Publishing over MQTT', { 'qos' : 1 }, function(err) {
                if(err.code == 0) {
                    print('publish success');
                } else {
                    print('publish failure ' + err.code);
                }
            });
        }
    }
}

上記に記載されている会社名、製品名は、各社の登録商標または商標です。

Updated: 2023-01-20

NEQTO Apps

ハードウェア仕様

ソフトウェア仕様

neqto.js

ハードウェア仕様

ソフトウェア仕様

neqto.js

ハードウェア仕様

ソフトウェア仕様

neqto.js

ソフトウェア仕様

neqto.js

UART

I2C

Utils

Integration

関連資料

Abstracts

{AZURE_IOT} Instance

Details

`new AZURE_IOT(config)`

Configuration

Setter Methods

`.setConfig(config)`

Instance Methods

`.generateSasToken([resourceUri][,signingKey][,policyName][,expiresInSecs])`

`.httpPost(token,length,getBody,callback[,endpoint])`

Responses

Errors

`.abortHttpRequest()`

`.mqttConnect(token[,options])`

Usage Examples

Sample 1: 基本的なHTTPS通信

Sample 2: トークンの有効期限が切れた場合のMQTTでの再接続