プラットフォームドキュメント

/

Bluesデバイスを追加

Blues NotecardからNotehubを経由して、温度と湿度の測定値をNEQTO.aiに送ります。このガイドでは、TLSを使うNotehubのMQTTルートを作成し、各イベントを推奨のneqtoai-stdエンベロープに変換して、測定値がデバイスの属性として表示されることを確認します。

経路の各段階を確認してください。コントローラーがセンサーの測定値をNotecardに書き込みます。NotecardはそれをNotehubにアップロードします。Notehubのルートがそれを変換し、NEQTO.aiのデバイスエンドポイントにパブリッシュします。ルートの結果と、保存されたデバイスの測定値の両方を確認してください。MQTTの送信が成功したからといって、NEQTO.aiへの正常なデータ取り込みが完了したとは限りません。

必要なもの

開始する前に、次のアカウント、権限、デバイスを用意してください。

  • プロジェクトにアクセスでき、ルートを作成する権限を持つNotehubアカウント。
  • Notehubに接続できる、セルラーまたはWi-FiのNotecard。
  • Notecardに接続されたホストマイコン(センサーのファームウェアを実行するコントローラー)。
  • 温度と湿度の値を書き込むセンサーとファームウェア。例ではtempとhumidityを使います。ファームウェアが別のフィールド名を使う場合は、変換を調整してください。
  • デバイスエンドポイントの作成と閲覧の権限があり、デバイス登録枠に空きがあるNEQTO.aiアカウント。

始める前に

まず、NotecardがセンサーのイベントをNotehubに送っていることを確認します。すでに動作している場合は、ルートの設定に進んでください。

1. NotecardをNotehubにプロビジョニングする

  • 1
    Notehubのプロジェクトを作成するか開き、そのProductUIDをコピーします。
  • 2
    ブラウザー内のターミナルまたはホストコントローラーからNotecardに接続します。hub.setでProductUIDを設定します。下の例のProductUIDは、ご自身の環境の値に置き換えてください。
    {"req":"hub.set","product":"com.your-co.you:project"}
  • 3
    {"req":"hub.sync"}を実行します。NotehubのプロジェクトのDevicesにNotecardが表示されることを確認します。プロビジョニングや同期に失敗する場合は、Notehubのウォークスルーを参照してください。

2. センサーのデータをNotefileに書き込む

次のBlues Notecard APIのリクエストを、ターミナルまたはホストコントローラーからNotecardに送ります。note.addは、Notehubへアップロードするための送信キューファイルであるsensor.qoにノートを保存します。bodyにはセンサーの測定値が入ります。この例では、温度を摂氏、湿度をパーセントで表します。

{
  "req": "note.add",
  "file": "sensor.qo",
  "body": {
    "temp": 22.4,
    "humidity": 47.1
  }
}

ノートを書き込んだ後、{"req":"hub.sync"}を送信して、Notehubとの同期を要求します。NotehubでEventsを開き、イベントにbody.tempとbody.humidityがあり、期待どおりの数値が入っていることを確認します。ここで指定したNotefile名は、後述のルートのフィルター設定でも使用します。

NEQTO.aiのペイロードは、あとでNotehubのルートで作成されます。後述のJSONata式が、イベントのセンサー値、タイムスタンプ、デバイス識別子を読み取り、推奨のneqtoai-stdエンベロープを組み立てます。イベントをNEQTO.aiのMQTTエンドポイントに送る前に、この変換を設定してください。

手順の概要

NotecardがNotehubにイベントを送るようになったら、このチェックリストを使います。詳しい手順はその後に続きます。

  • 1
    NEQTO.aiで「MQTT(TLSあり・推奨)」のデバイスエンドポイントを作成し、その接続情報を安全に保管します。
  • 2
    NotehubのプロジェクトでMQTTルートを作成します。
  • 3
    エンドポイントのブローカー、ポート、トピック、ユーザー名、パスワードをルートにコピーします。ブローカーのURLにはmqtts://を使い、TLSが失敗する場合は証明書の信頼を確認してください。
  • 4
    ルートの対象を、sensor.qoなどのセンサーのNotefileに限定します。
  • 5
    JSONata ExpressionをData > Transform Dataで選択します。後述の式を貼り付けてテストします。
  • 6
    ルートを有効にして保存します。新しいセンサーのイベントを送り、Notehubのルートログを確認して、NEQTO.aiで作成されたデバイスの測定値を確認します。

動画での説明

概要は動画で確認できます。現在のペイロードの例、認証情報の再取得、確認の手順は、本文の手順に従ってください。

詳しい手順

受信側のエンドポイントを作成し、Notehubのイベントを1つ確認して、そのフィールドを使ってルートを設定します。

パートA:NEQTO.aiでデバイスエンドポイントを作成する

  • 1
    アカウントまたはアプリケーションのレベルでデバイス > デバイスエンドポイントを開きます。
  • 2
    デバイスエンドポイントを追加 > デバイスエンドポイント作成を選択します。エンドポイント名を入力し、「MQTT(TLSあり・推奨)」を選択して次へで進みます。このガイドのルートでは、ユーザー名とパスワードの接続情報を使います。
  • 3
    接続情報の画面で、ブローカーURL、ポート、トピック、ユーザー名、パスワードと証明書の情報を確認します。値をコピーするか、詳細をダウンロードをクリックします。ダウンロードしたファイルは安全に保管してください。
「デバイスエンドポイント作成」ダイアログ。デバイスエンドポイント名にBlues Notecardと入力され、接続タイプは作成後に変更できないという注意書きの下に、MQTT(TLS対応)、HTTPS、WebSocketの3つのタイプが並んでいます。MQTT(TLS対応)が選択され、その中の「MQTT(TLSあり・推奨)」と「MQTT(TLSなし)」のうち、「MQTT(TLSあり・推奨)」がオンになっています。下部に戻る、キャンセル、次へがあります。
エンドポイントの接続情報に進む前に、「MQTT(TLSあり・推奨)」を選択します。

パスワードはあとから再取得できます。設定を閉じた後、エンドポイントの「操作」列の3点メニュー > 詳細を表示を開きます。パスワードはそこでもマスクされたままですが、必要な権限があればコピーしたり、詳細を再度ダウンロードしたりできます。ダイアログを閉じても、エンドポイントを作り直したり認証情報を再生成したりする必要はありません。

Blues Notecardのデバイスエンドポイントの詳細ダイアログ。ストリームID、ブローカーURL(mqtt.neqto.ai)、ポート(8883)、トピック、ユーザー名が表示され、各行にコピーボタンがあります。パスワードの行のラベルが赤枠で囲まれ、値はマスクされたままです。その下のCA証明書の行には有効期限と証明書の本文、コピーとダウンロードがあります。完了の横にある詳細をダウンロードも赤枠で囲まれています。
「詳細を表示」を再度開くと、接続情報のコピーや再ダウンロードができます。

パートB:Notehubでセンサーのイベントを確認する

  • 1
    NotehubでプロジェクトのEventsページを開き、センサーのNotefileからの最近のイベントを選択します。
  • 2
    イベントの本文を確認します。tempとhumidityに期待どおりの測定値と単位が入っていることを確認します。ファームウェアが別の名前を使っている場合は、変換に使う正確なパスを控えておきます。
  • 3
    Notefile名、イベントのwhenタイムスタンプ、best_idを記録します。送信ごとに変化しない、恒久的なデバイス識別子を使用してください。

Notehubは、デバイスのシリアル番号が設定されていればそこから、なければNotecardのデバイスUIDからbest_idを決めます。取り込み後にこの識別子を変更すると、NEQTO.aiはその後の測定値を別のデバイスとして扱うことがあります。本番のデータを送る前に識別子を決めてください。

パートC:NotehubでMQTTルートを作成する

  • 1
    NotehubのプロジェクトでRoutesを開き、Create Routeをクリックします。
  • 2
    MQTTを選択します。NEQTO.ai productionのような、見分けやすいルート名を入力します。
  • 3
    下の表に従って、NEQTO.aiの接続情報をNotehubの対応するフィールドにコピーします。
neqto connectという名前のルートの、NotehubのMQTTルート設定。SettingsタブとLogsタブの下に、有効になったルートのスイッチ、Route nameの欄、MQTTであることを示すConfigurationセクションがあります。
目的のMQTTルートを編集していること、そしてそれが有効になっていることを確認します。
NEQTO.aiのフィールド Notehubのフィールド 入力する内容
ブローカーURL Broker URLまたはURL エンドポイントのホストにmqtts://スキームを付けて使います。例:mqtts://your-broker.example.com。これは説明用のアドレスなので、実際のホストをコピーしてください。プレフィックスを二重に付けないでください。
ポート Port 表示されているエンドポイントのポートをコピーします。TLSありのMQTTでは一般に8883を使いますが、エンドポイントに示された値を使ってください。
トピック Topic 前後に空白を入れず、正確にコピーします。
ユーザー名 Username エンドポイントのユーザー名を正確にコピーします。
パスワード Password エンドポイントのパスワードを正確にコピーします。
CA証明書 必要な場合はAdditional self-signed certificate Notehubがブローカーの証明書チェーンを検証できない場合は、適切な信頼済みの証明書を指定します。追加の証明書が不要なのは、Notehubがそのチェーンをすでに信頼している場合だけです。

ルートのフィルターを設定し、TLSを確認する

TLSはブローカーの身元を確認し、接続を暗号化します。同じクラウド事業者を利用している場合でも、自動的に証明書が信頼されるわけではありません。信頼済みのCA証明書は、クライアント認証に使うクライアント証明書や秘密鍵とは別のものです。このガイドでは、エンドポイントのユーザー名とパスワードを使います。ルートのフィールドと証明書の選択肢については、Blues公式のMQTTルーティングのガイドを参照してください。

  • 4
    Filters > Notefilesで、ファームウェアが書き込むセンサーのファイル(sensor.qoなど)を選択します。_health.qoや_session.qoなど関係のないファイルは、このセンサー用のルートに含めないでください。
  • 5
    Notehubのプロジェクトの一部だけでこのルートを使う場合は、FleetsまたはFleets to Excludeを設定します。
  • 6
    Data > Transform DataでJSONata Expressionを選択し、下の式を入力します。実際のセンサーのイベントでプレビューします。
  • 7
    ルートをEnabledのままにし、新規作成ならCreate Route、編集ならApply Changesで保存します。

JSONata式

この式はNotehubのイベントを読み取り、デバイスの識別、時刻、値、単位を明示した、NEQTO.aiの推奨エンベロープを作成します。

JSONata Expressionの欄に貼り付けます。whenやbody.tempなどの名前は、受信するイベントのフィールドへの参照です。引用符で囲んだ文字列やJSONのリテラル値ではありません。

{
  "payload_format": "neqtoai-std",
  "timestamp": when,
  "device_id": best_id,
  "data": {
    "temperature_celsius": { "value": body.temp, "unit": "c" },
    "humidity_percent": { "value": body.humidity, "unit": "%" }
  }
}

フィールドごとの説明

ソースのフィールド 式での使われ方
when timestampを、Notehubのイベントの時刻(Unix秒、UTC)から設定します。
best_id device_idを設定します。hub.setとsnで設定したシリアル番号があればそれを、なければNotecardのUIDを使います。ファームウェアがbody.uidやbody.macのような恒久的な識別子を送っている場合は、確認したうえでそのフィールドを代わりに使えます。
body.temp data.temperature_celsius.valueを設定します。この例は摂氏を前提とし、unit: "c"を指定します。センサーが別の単位を使う場合は、先に値を変換してください。
body.humidity data.humidity_percent.valueを設定します。この例は相対湿度をパーセントで表すことを前提とし、unit: "%"を指定します。

イベントで別のフィールド名を使っている場合は、ソースのパスをそれに合わせて変更します。出力の測定値の名前は、確認の手順と一致させてください。NEQTO.aiはほかの対応しているJSON形式も受け付けますが、このエンベロープを使うとマッピングが明確になります。エンドポイントとデバイスを参照してください。

変換を確認する

when、best_id、body.temp、body.humidityを含むセンサーのイベントで、式をプレビューします。たとえば、時刻1716806400、識別子dev:example-notecard、温度22.4、湿度47.1のイベントからは、次の結果が得られます。

{
  "payload_format": "neqtoai-std",
  "timestamp": 1716806400,
  "device_id": "dev:example-notecard",
  "data": {
    "temperature_celsius": { "value": 22.4, "unit": "c" },
    "humidity_percent": { "value": 47.1, "unit": "%" }
  }
}

識別子とタイムスタンプがあり、両方の測定値に数値と意図した単位が入っていることを確認します。ソースのフィールドが欠けていると、変換結果の値が欠けることがあります。ルートを使う前に、フィールドのパスか受信するノートを修正してください。

エンドツーエンドで確認する

Notehubのルートの結果を確認し、次にNEQTO.aiに保存された測定値を確認します。接続が動作していると判断する前に、3つの確認をすべて行ってください。

1. Notehubのルートテスト

ルートの画面にTest Routeがある場合は、代表的なイベントで実行して結果を確認します。ルートテストの成功はNotehub側のルーティング動作を確認するものであり、NEQTO.ai側で測定値が正常にマッピング・保存されたことを保証するものではありません。続けて、実際のセンサーのイベントで確認してください。

2. Notehubのルートログ

新しいセンサーのノートを書き込み、Notecardを同期します。Notehubでそのイベントを開き、Route logを確認します。作成したルートを見つけ、成功の表示またはエラーの詳細を確認し、目的のセンサーのイベントが処理されたことを確かめます。既存のイベントを選んで手動でルーティングすることもできます。ルート作成前に受信した既存のイベントは、新規ルートへ自動的には送信されません。

Notehubが認証、接続、TLSのエラーを報告した場合は、デバイスのデータを確認する前にそのエラーを修正してください。MQTTのルーティングはNEQTO.aiへのHTTPリクエストではないため、ルートの成功を200 OKというメッセージだけで判断しないでください。

3. NEQTO.aiでの受信データ

  • 1
    対象のデバイスエンドポイントを開き、新しいペイロードの取り込みフィードバックを確認します。
  • 2
    変換後のdevice_idで識別されるデバイスを見つけます。そのデータの表示を開き、temperature_celsiusとhumidity_percentの最近の測定値が、期待どおりの値、単位、時刻で入っていることを確認します。
  • 3
    デバイスが見つからない場合は、識別子、アカウントのデバイス数の上限、拒否されたペイロードやマッピングされなかったペイロードについてのフィードバックを確認します。正しいアカウント、アプリケーション、エンドポイントを見ていることも確認してください。
  • 4
    エンドポイントの設定ダイアログがまだ開いている場合は、完了をクリックします。接続情報は、あとから詳細を表示で再取得できます。

有効なペイロードが処理されると、デバイスは自動で登録されます。NEQTO.aiにNotecardを事前に登録する必要はありません。恒久的な識別子を使い、新しいデバイスを追加できる空きを残しておいてください。Notehubのルートログが成功していても、それだけではデバイスが見つからない原因はわかりません。取り込みフィードバックも確認してください。

ヒントとトラブルシューティング

認証情報や識別子を変更する前に、エラーメッセージから失敗している段階を特定してください。

症状 確認すること
接続またはTLSのエラー mqtts://、表示されたブローカーのホストとポート、必要な場合は完全な信頼済みの証明書を使います。ブローカーに到達できるか、証明書が有効かを確認してください。
認証エラー エンドポイントの「詳細を表示」から、ユーザー名とパスワードをコピーし直します。前後に誤って混入した不要なスペースを削除してください。トピックも確認してください。
測定値がない、またはnull 実際のNotehubのイベントを確認し、JSONataのbody.tempまたはbody.humidityを修正します。ソースの値が、式に書いた単位であることを確認してください。
ルートは成功したが、測定値が保存されない 対象のエンドポイント、恒久的なデバイス識別子、アカウントのデバイス数の上限、取り込みフィードバック、アプリケーションの割り当てを確認します。新規に検出されたデバイスは、エンドポイントまたはデバイス自体がアプリケーションに割り当てられていない場合、そのアプリケーションの一覧に表示されないことがあります。
関係のないイベントが届く Notefilesのフィルターをセンサーのキューに限定し、Fleetのフィルターを見直します。
パスワードが表示されない、またはダイアログを閉じた 「操作」列の3点メニュー > 「詳細を表示」を開きます。パスワードはマスクされたままですが、必要な権限があればコピーしたり、「詳細をダウンロード」を再度クリックしたりできます。