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 |
関連資料
このライブラリで使用しているAzure IoT Hub APIの詳細については、ドキュメンテーションを参照してください。
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);
}
});
}
}
}