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

/

エンドポイントとデバイス

「エンドポイントとデバイス」は、ハードウェアからのデータがNEQTO.aiに入ってくる場所です。エンドポイントは、ハードウェアが使う接続設定と認証情報を持ちます。デバイスは、データを送る1台の機器です。属性は、温度、湿度、バッテリーなど、そのデバイスからの1つの測定項目です。保存されたデバイスのデータは、ダッシュボード、アラート、分析で使えます。

各要素の関係:1つのエンドポイントは複数のデバイスからデータを受け取れ、1つのデバイスは複数の属性のデータを送信できます。エンドポイントはご自身で作成します。デバイスと属性は、恒久的なデバイス識別子と、マッピングできる測定値を含む有効なペイロードを受信したときに、NEQTO.aiが作成できます。データが届く前に、デバイスを手動で作成することもできます。
データの流れの図。ハードウェアまたは内蔵のシミュレーターが、MQTT、HTTPS、WSSのいずれかでデバイスエンドポイントにJSONを送ります。NEQTO.aiはトピックまたはペイロードからデバイスを特定し、その測定値を属性に自動でマッピングします。データはその後、ダッシュボード、アラート、分析で使われます。
データの流れ:エンドポイントに入り、デバイスと属性になり、ダッシュボードやアラートへ進みます。

データがNEQTO.aiに届く経路は2つあります。ほとんどのデバイスは、上の図のようにデバイスエンドポイントに送信します。また、インテグレーションからデバイスを作成することもできます。インテグレーションは、デバイスから受け取るのではなく、外部のクラウドサービスからデータを取り込みます。どちらの場合も、属性が自動でマッピングされたデバイスになります。どのデバイスにもソース(エンドポイントまたはインテグレーション)のラベルが付くため、両者を見分けられます。後述のデバイス一覧のソース列を参照してください。

クイックスタート

次の手順で、デバイスを接続し、最初の測定値を確認します。

  • 1
    アプリケーションを開いてデバイスエンドポイントに移動します。デバイスエンドポイントを追加をクリックし、接続タイプ(MQTT、HTTPS、WSS)を選択します。
  • 2
    最後のステップに表示される認証情報(ストリームID、ホスト/URL、ポート、ユーザー名、パスワード、CA証明書)をコピーします。詳細をダウンロードですべてを保存するか、各値のコピーボタンで1つずつコピーします。
  • 3
    デバイスの接続方法を開き、推奨のneqtoai-stdの例か、対応しているほかのJSON形式を使います。まだハードウェアがない場合は、デモ用のエンドポイントを作成し、代わりに内蔵のシミュレーターを使ってください。
  • 4
    NEQTO.aiが最初の有効なメッセージを処理すると、デバイスが表示され、マッピングできる測定値が属性になります。ダッシュボードやアラートで使う前に、デバイスのデバイスデータタブで保存された値を確認してください。

デバイスエンドポイント

1つのエンドポイントは、1つのプロトコルと認証の設定を持ちます。エンドポイントを通じて送信するデバイスはそのエンドポイントに紐付き、その詳細に表示されます。

アプリケーション内のデバイスエンドポイント一覧の表。表の上のオレンジ色のバナーで、このアカウントの1件のエンドポイントがポート1883で暗号化せずにMQTTを送信していると警告し、TLSへの移行方法のリンクがあります。列は名前(該当する場合はデモのタグ付き)、説明、プロトコル、アカウント、作成者、アプリケーション、接続しているデバイス名を示すデバイス数です。プロトコルの列では、MQTTのエンドポイントに緑のTLSまたはオレンジの平文のバッジが付いています。表の上に検索欄があり、各行の「操作」列に3点メニューがあります。
デバイスエンドポイントの一覧。1行が1つの接続で、デバイス列に、そこへ送信しているものが表示されます。

接続タイプ

タイプはエンドポイントの作成時に選び、あとから変更することはできません。認証タイプも同じです。

タイプ 用途 受け取る情報
MQTT ほとんどのIoTデバイスとゲートウェイ。常時接続で、オーバーヘッドの小さい接続です。 ストリームID、ブローカーURL、ポート、トピック、ユーザー名、パスワード、および(TLSの場合)CA証明書
HTTPS HTTPリクエストでデータを送るデバイス、スクリプト、サービス ストリームID、取り込み用のURL、ポート、メソッド(POST)、CA証明書、および(基本認証の場合)ユーザー名とパスワード。ペイロードは1リクエストあたり最大1 MBです。
WebSocket Secure(WSS) WebSocketを開いたままにしてフレームを流し続けるアプリやゲートウェイ ストリームID、セキュアなWebSocketのURL、ポート、CA証明書、および(基本認証の場合)ユーザー名とパスワード

MQTTエンドポイントを作成するときは、TLSが既定で選択されています。TLSでは、ユーザー名とパスワードで認証し、CA証明書が提供されます。TLSに対応できない機器向けにTLSなしを選ぶこともできますが、その場合は認証情報と測定値が暗号化されずにネットワークを流れるため、推奨されません。TLSなしのMQTTエンドポイントには、タイプの横に平文のバッジが表示され、デバイスエンドポイントのページにはその数が警告として表示されます。HTTPSとWSSでは、認証タイプとして「基本認証」(ユーザー名とパスワード)か「なし」を選びます。以前のHTTPとWSの種類は廃止されました。

エンドポイントのデバイスをTLSに移行する

古いエンドポイントと同じアプリケーションに新しいMQTT(TLSあり・推奨)エンドポイントを作成し、古いエンドポイントにペイロードデコーダーがあれば新しい方にも設定します。次に、各デバイスに新しいホスト、ポート8883、トピック、ユーザー名とパスワード、必要であればCA証明書を設定し直します。デバイスの外部IDは変えないでください。NEQTO.aiはエンドポイントをまたいで外部IDでデバイスを照合するため、移行してもデバイスの記録と履歴はそのまま残ります。すべてのデバイスが新しいエンドポイントに送信するようになったら、古いエンドポイントを削除します。削除すると、そのエンドポイント経由でのみアプリケーションに属していたデバイスはアプリケーションから外れるため、先に新しいエンドポイントを同じアプリケーションに入れておきます。

以前の認証情報が通信中に盗み取られた可能性がある場合は、エンドポイントの詳細にあるパスワードを再生成で置き換えます。新しいパスワードは最大5分で反映され、接続中のデバイスは再接続するまで接続を維持します。「デバイスエンドポイントを編集」の権限が必要で、パスワードを持つすべてのエンドポイントで使えます。

TLS非対応デバイスの接続

デバイスがTLSに対応していない場合や、エンドポイントの証明書を信頼できない場合は、ローカルのブリッジやプロキシでTLS接続を処理できます。MQTT(TLSなし)を使うより安全です。デバイスと同じネットワークに常時稼働するコンピューターやゲートウェイが必要です。デバイスの接続先をその機器に変更できることも条件です。暗号化されない接続は、信頼できるローカルネットワーク内に限定してください。クラウド上の中継サービスだけでは、デバイスから中継サービスまでの接続は暗号化されません。

エンドポイントの追加方法

デバイスエンドポイントを追加では、最初にエンドポイントの設定方式を選択します。ここでもその後のフォームでも、ウィザードのすべての選択肢に?アイコンがあり、クリックすると、どのような場合に適しているかの簡潔な説明が表示されます。

デバイスエンドポイントを選択するダイアログ。右上に設定アシストのボタンと、その下に残りのクレジット数(残り24999 / 25000クレジット)があり、4つのタイルが並んでいます。既存のデバイスエンドポイントを使用、デバイスエンドポイント作成、DEMOのリボンが付いたデモ用デバイスエンドポイント作成、HPE Aruba Networkingのロゴが付いたAruba用デバイスエンドポイント作成です。各タイルの隅に疑問符のアイコンがあります。下にキャンセルボタンがあります。
それぞれの方法の説明は、?の中にあります。
選択肢 使う場合
既存のデバイスエンドポイントを使用 機器がすでに接続しているものと同じプロトコルを使うため、そのエンドポイントの認証情報を再利用する場合。エンドポイントがすでにある場合にのみ表示されます。
デバイスエンドポイント作成 まだプラットフォームにデータを送っていない機器
デモ用デバイスエンドポイント作成 ハードウェアの準備ができていない場合。代わりに内蔵のシミュレーターがエンドポイントにデータを送信するため、その上で作成したものは無駄にならず、そのまま活用できます。実際の機器はあとから接続できます。
Aruba用デバイスエンドポイント作成 機器をAruba Centralで管理している場合。サインインするとエンドポイントが1つのArubaグループに紐付けられ、そのグループのデバイスはデバイスごとの設定なしでデータを送ります。

エンドポイントの作成

デバイスエンドポイント作成をクリックすると、次のフォームが開きます。

右上に設定アシストのボタンと残りのクレジット数があるデバイスエンドポイント作成のフォーム。デバイスエンドポイント名の欄にはHVAC & Lighting Controllersと入力されています。注記で、接続タイプはエンドポイントの作成後は変更できないと警告しています。その下にMQTT(TLS対応)、HTTPS、WebSocketのカードがあり、それぞれに疑問符のアイコンがあります。MQTTのカードが選択され、MQTT(TLSあり・推奨)とMQTT(TLSなし)の2つの選択肢が表示され、前者が選ばれています。それぞれにも疑問符のアイコンがあります。下部に戻る、キャンセル、次へのボタンがあります。
ステップ1:エンドポイントに名前を付け、接続タイプを選択します。MQTTは、別の選択をしない限りTLSを使用します。
  • 1
    デバイスエンドポイント名を入力します(必須、100文字以内)。名前はアカウント内で一意である必要があります。500文字以内の説明も追加できます。
  • 2
    接続タイプ(MQTT、HTTPS、WebSocket)を選択し、選択肢が複数ある場合は認証タイプも選択します。接続タイプは作成後は変更できません。変更するには、新しいエンドポイントを作成します。
  • 3
    アプリケーションを管理する権限があれば、エンドポイントをアプリケーションに割り当てて、適切なチームが見られるようにできます。
MQTT(TLSなし)の横の疑問符のアイコンを開いた同じフォーム。MQTT(TLSなし)という見出しのポップオーバーで、ネットワークを観測できる者は認証情報も測定値も読み取れると警告し、TLSに対応できない機器に限り、できればプライベートネットワーク内でのみ使用するよう説明しています。
?を開くと、その選択肢が適している場合がわかります。

エンドポイントへのアクセスは権限で管理されます。エンドポイントの閲覧、作成、編集、削除は、アカウントまたはアプリケーションの単位で別々の権限になっているため、一覧を開けても操作が表示されない場合があります。

HVAC & Lighting ControllersというMQTTのエンドポイントを作成した後の概要画面。見出しは、デバイスエンドポイントが作成されたという内容です。MQTTの接続情報のラベルの右に、設定アシストのボタンと残りのクレジット数があります。ストリームID、ブローカーURL、ポート、トピック、ユーザー名、マスクされたパスワードの各行にコピーボタンがあり、CA証明書の行には有効期限とコピー、ダウンロードのボタンがあります。下部に戻る、別のエンドポイントを追加、デバイスを追加、完了のボタンがあります。
ステップ2:ハードウェアを設定する前に、認証情報をコピーまたはダウンロードします。
認証情報は安全に保管してください。概要画面では、値ごとにコピーボタンがあり、CA証明書には別にダウンロードがあります。詳細をダウンロードで、接続情報をすべてテキストファイルとして保存します。パスワードは画面上では常にマスクされていますが、コピーボタンと詳細をダウンロードでは実際の値を取得できます。権限があれば、あとから詳細を表示を開き直して、コピーしたり詳細を再度ダウンロードしたりできます。

設定アシスト

エンドポイントのウィザードの各ステップには設定アシストボタンがあり、今いるステップについてAtollaに質問します。質問は自動で作成・送信され、答えはウィザードの横のAtollaのパネルに表示されます。このボタンは、Atollaを使う権限がある場合に表示されます。NEQTO.aiのほかの場所でAtollaができることはAtollaに質問を参照してください。

認証情報が質問に含まれることはありません。設定アシストが送信するのは、ステップ名と、そのステップで選択した内容のうち、エンドポイント名や接続タイプなどあらかじめ決まった項目だけです。接続情報はその中に含まれず、パスワードや証明書はフォームに残ります。

データの送信:ペイロードのガイド

NEQTO.aiは柔軟なJSONペイロードを受け付け、推奨される、最も確実に解釈されるエンベロープとしてneqtoai-stdを用意しています。エンドポイントのウィザードのデバイスの接続方法のヘルパーでは、エンドポイントのプロトコルに合わせたこの例が、対応している代替の形式、フィールドリファレンス、トラブルシューティングのヒントとともに表示されます。

MQTTのエンドポイントで開いたデバイスの接続方法のヘルパーパネル。見出しの横に設定アシストのボタンと残りのクレジット数があります。上部のヒントで、このエンドポイントの接続情報でデバイスを設定し、推奨の例か対応しているほかのJSON形式を使うよう説明しています。その下のMQTTトピックの選択肢のブロックには、エンドポイント自身のトピック、設定を変更せずに対応しているベンダーのトピックの形式を代わりに使えること、事前設定済みのトピック形式の欄が開いています。その注記には、トピックに含まれるデバイス識別子が外部IDになりdevice_idより優先されること、推奨ペイロードがすべての対応トピックで使えること、トピックは最大512文字、トピックから取得する識別子は最大128文字であること、第三者の名称は提携や推奨を意味しないことが書かれています。
製品内の「デバイスの接続方法」のヘルパー。同じ内容を以下で説明しています。
エンベロープのフィールドは推奨であり、常に必須ではありません。payload_formatは標準形式を直接選びます。ない場合、NEQTO.aiがペイロードの形式を判別します。タイムスタンプのフィールドがない場合、NEQTO.aiはワーカーがメッセージを受信した時刻を使います。解析した結果が許容範囲外のタイムスタンプはスキップされ、形式が不正なタイムスタンプも、デバイスの特定方法によっては拒否されることがあります。受信時刻を使いたい場合は、このフィールドを省略してください。受け付ける形式、範囲、UTCで送るべき理由はタイムスタンプとタイムゾーンで説明しています。デバイスの識別は、対応しているMQTTトピック、ペイロードの最上位または入れ子にある恒久的な識別子のフィールド、あるいはエンドポイントに紐付く唯一の有効なデバイスから得られます。dataのラッパーは任意で、測定値は最上位に置くことも、オブジェクトのラッパーの中に入れ子にすることもできます。

MQTTトピックの選択肢

MQTTのエンドポイントでは、エンドポイントの詳細に表示されるトピックが、NEQTO.aiの推奨トピックです。これまでどおりそのトピックに送信することも、以下の対応しているベンダー固有のトピックの形式を使うこともできます。同じエンドポイントのユーザー名とパスワードを使い、エンドポイントの設定を変更する必要はありません。

MQTTのログインでエンドポイントが特定されます。ベンダーのトピックにエンドポイントIDを含める必要はありません。NEQTO.aiは、接続に使われた認証情報のエンドポイントにメッセージを安全に紐付けます。クライアントがトピックにほかのエンドポイントのIDを入れて、そのエンドポイントを選ぶことはできません。

波括弧で囲まれた名前はプレースホルダーなので、実際の値に置き換えてください。たとえば、losant/{deviceId}/stateはlosant/freezer-17/stateのようになります。Azureの末尾に示した{...}は、ベンダーの任意のサフィックスを受け付けることを意味します。波括弧をそのまま送信しないでください。

トピックの種類 受け付けるトピックのパターン デバイスの識別とテレメトリのルール
NEQTO.aiデフォルト data/v1/{endpointId}またはdata/v1/{endpointId}/{...} 任意のサフィックスの階層を受け付けますが、デバイスの識別には使われません。ペイロードの恒久的な識別子を使うか、有効なデバイスが1台だけ紐付いている場合は自動のフォールバックを使います。
Losant losant/{deviceId}/state deviceIdでデバイスを識別します。取り込まれるのはstateチャンネルだけです。
Azure IoTデバイス devices/{deviceId}/messages/events/{...} deviceIdでデバイスを識別します。Azureのプロパティバッグのサフィックスを受け付けます。
Azure IoTモジュール devices/{deviceId}/modules/{moduleId}/messages/events/{...} deviceIdでデバイスを識別し、moduleIdも抽出されます。
Tasmota tele/{deviceId}/SENSORまたはtele/{deviceId}/STATE deviceIdでデバイスを識別します。ほかのTasmotaのチャンネルは取り込まれません。
ChirpStack application/{applicationId}/device/{devEui}/event/up devEuiでデバイスを識別します。取り込まれるのはupイベントだけです。
The Things Stack v3/{applicationId}/devices/{deviceId}/up deviceIdでデバイスを識別します。
ThingsBoard v1/devices/me/telemetry トピックにデバイス識別子がありません。複数のデバイスにはペイロードの恒久的な識別子を使ってください。紐付くデバイスが1台だけなら、自動のフォールバックを使えます。
汎用デバイス階層 sites/{siteId}/devices/{deviceId}/telemetry deviceIdでデバイスを識別し、siteIdも抽出されます。

対応しているトピックにデバイス識別子が含まれている場合、その値がデバイスの外部IDになり、ペイロードのdevice_idより優先されます。トピックに識別子がない場合、NEQTO.aiはペイロードの最上位または入れ子の恒久的な識別子か、エンドポイントに紐付く唯一の有効なデバイスを使えます。state、SENSOR、upのような固定のチャンネルの部分は、大文字と小文字が区別されます。

MQTTトピックは最大512文字です。対応しているトピックから取得するデバイス識別子は最大128文字です。トピックと、トピックから取得する識別子では制御文字は拒否されますが、表示可能なベンダーの記号やUnicodeは受け付けます。

トピックの対応とペイロードの対応は別のものです。以下の推奨ペイロードのガイドは、対応しているすべてのトピックで使えます。AWS IoTのトピック名やその他の独自のトピック階層はアプリケーション側で定義されるものなので、ブローカーが受け付ける前に、プラットフォームの管理者が追加のトピックテンプレートを設定する必要があります。

第三者の名称は互換性のあるトピック形式を示すためだけに使用しており、それらの第三者との提携や推奨を意味するものではありません。

このneqtoai-stdのJSONが、推奨される基本形式です。同等の対応しているJSON形式も受け付けます。測定値のキーはご自身のセンサー名で、最上位に置くことも、任意のオブジェクトのラッパーの中に入れ子にすることもできます。名前に単位を含める必要はありません。

{
  "payload_format": "neqtoai-std",
  "timestamp": 1716806400000,
  "device_id": "AA:BB:CC:AA:BB:02",
  "data": {
    "temperature":     { "value": 22.4, "unit": "c" },
    "humidity":        { "value": 62.3, "unit": "%" },
    "battery_percent": { "value": 82,   "unit": "%" },
    "rssi_dbm":        { "value": -55,  "unit": "dBm" }
  }
}

エンベロープのフィールド

フィールド 区分 型 備考
payload_format 推奨 文字列 ルーティングのヒントです。"neqtoai-std"は標準形式を直接選びます。ない場合は、ペイロードの形式が自動で判別されます。
timestamp 推奨 数値、文字列、またはオブジェクト Unixエポックの秒またはミリ秒、またはUTCのISO 8601。ない場合は、ワーカーの受信時刻が使われます。範囲外のタイムスタンプはスキップされ、形式が不正なタイムスタンプも拒否されることがあります。下記の構造化オブジェクトはneqtoai-stdで使えます。タイムスタンプとタイムゾーンを参照してください。
device_id 推奨 文字列または数値 デバイスごとの恒久的なID。画面上ではデバイスの外部IDになります。デバイス識別子を含む対応したMQTTトピックでは、トピックの値が優先されます。ない場合、NEQTO.aiはペイロードの入れ子の恒久的な識別子を調べることができます。自動のフォールバックは、エンドポイントに有効なデバイスが1台だけある場合にのみ使われます。
data 推奨 オブジェクトまたはキーと値の配列 センサーの測定値です。ラッパーは任意で、測定値は最上位に置くことも、任意のオブジェクトのラッパーの中に入れ子にすることもできます。識別子、タイムスタンプ、メタデータとして認識されたものは除外されます。

最上位では、エンベロープのフィールド名はアンダースコアとハイフンを除いたうえで、大文字と小文字を区別せずに照合されます。デバイスIDの主な別名にはdevice、mac、serial、sn、dev_eui、imei、external_idがあります。タイムスタンプの別名にはts、time、datetime、reported_at、epochがあります。ラッパーの名前に特別な意味はなく、入れ子のオブジェクトや配列から測定値と恒久的な識別子が調べられます。

一意に特定できるデバイス識別子を使ってください。device_id、device、uuid、mac_address、serial_number、dev_eui、imei、bdAddr、hwIdのような明確な入れ子の識別子は、測定値ではなく識別のためのメタデータとして認識されます。id、sender、destinationのような汎用的な入れ子のフィールドは、デバイスを識別するものとはみなされません。最上位のsn、ts、time、index、sequenceは常にメタデータとして予約されていますが、入れ子の中にある同じ短い名前のフィールドは、センサーの測定値として扱われることがあります。
同じヘルパーを下にスクロールしたところ。推奨ペイロード例には、payload_format、ミリ秒のtimestamp、device_idと、temperature、humidity、battery_percent、rssi_dbmをそれぞれ値と単位で持つdataからなるneqtoai-stdのJSONと、コピーボタンがあります。その下のフィールドリファレンスの表(フィールド・区分・型・備考)には、payload_format、timestamp、device_id、dataが並び、それぞれ推奨と表示され、受け付ける型と、省略した場合の扱いが書かれています。
同じヘルパーを下にスクロールしたところ:推奨ペイロードの例と、以下で説明するフィールドリファレンス。

測定値フィールド

  • センサー測定値:{ "value": <number | string | boolean>, "unit": "<unit>" }。
  • 単位:50文字以内の自由形式のテキストです。主な単位:°C、°F、%、hPa、V、A、W、dBm、m/s、kWh、lux、ppm。オン/オフやカテゴリーの値には"state"を使います。
  • スカラー / カテゴリー:単純な文字列、数値、真偽値です(例:"status": "normal")。NEQTO.aiはこれを分類し、測定単位または"state"を推定しようとします。有効なマッピングが見つからない場合は、測定値を抽出できなかったことがメッセージで報告されます。
  • 名前:フィールド名はご自身のラベルです。名前に単位を含める必要はなく、NEQTO.aiが各測定値を自動で分類します。
  • 混在:同じペイロード内で、測定値の形式とスカラーの形式を混在させられます。

1つのエンドポイントで複数のデバイスを扱う

1つのエンドポイントで、複数のデバイスを扱えます。各メッセージには、対応しているMQTTトピックまたはペイロードで、恒久的で一意なデバイス識別子(例:device_id、serial、または明確な入れ子の識別子)を付けてください。識別子がない場合、自動のフォールバックが使われるのは、エンドポイントに有効なデバイスが1台だけ紐付いているときに限られます。

最上位のJSON配列で、複数のデバイスのオブジェクトをまとめて送れます。NEQTO.aiは配列の各要素を別々の測定値として処理するため、各要素は、デバイスを一意に特定できる識別子と有効な測定のフィールドを含むか、引き継ぐ必要があります。

構造化タイムスタンプ(neqtoai-stdのみ)

payload_formatを"neqtoai-std"に設定すると、エポックのタイムスタンプの代わりにこのオブジェクトを使えます。offsetは±HHMMの形式です。有効な暦の値とオフセットの値を使ってください。対応していない値は拒否されるか、意図とは異なる日付になることがあります。

"timestamp": {
  "year": "2026", "month": "05", "day": "26",
  "hour": "14", "minute": "30", "second": "00",
  "offset": "+0900"
}

タイムスタンプとタイムゾーン

timestampのフィールドは、測定値が測定された時刻です。NEQTO.aiは測定値をその時刻で保存し、グラフもその時刻に描きます。UTCで送ってください。Unixエポック時刻はタイムゾーンをまったく持たないため、最も安全です。Zで終わるISO 8601の文字列も使えます。

送る値 例 NEQTO.aiの解釈
Unixエポック秒 1716806400 推奨。100億未満の数値は秒として解釈されます。
Unixエポックミリ秒 1716806400000 推奨。それより大きい数値はミリ秒として解釈されます。どちらの例も2024年5月27日10:40(UTC)です。
UTCのISO 8601 "2024-05-27T10:40:00Z" 書かれたとおりに解釈されます。
オフセット付きのISO 8601 "2024-05-27T19:40:00+09:00" 指定したオフセットでUTCに変換されます。上記の構造化オブジェクトも同じように扱われます。
オフセットなしのISO 8601 "2024-05-27T10:40:00" デバイス側で想定しているタイムゾーンにかかわらず、UTCとして解釈されます。下の警告を参照してください。
タイムスタンプなし フィールドを省略 NEQTO.aiがメッセージを受信した時刻

エポックの値は、"1716806400"のような数値の文字列でも使えます。マイクロ秒とナノ秒の値には対応しておらず、それらを使う測定値はスキップされます。

デバイスに信頼できる時計がない場合は、このフィールドを省略してください。その場合、NEQTO.aiはメッセージを受信した時刻を使い、その精度はネットワークの遅延の範囲内です。デバイスがオフラインの間に保持し、あとからまとめて送った測定値は、すべて測定した時刻ではなく届いた時刻になります。

タイムスタンプは、1970年1月1日(UTC)から、NEQTO.aiの時計の24時間先までの範囲である必要があります。範囲外の測定値はスキップされ、リアルタイムの取り込みフィードバックで報告されます。メッセージ内のほかの有効な測定値は保存されます。

現地時刻を送る場合は、UTCオフセットを含めてください。NEQTO.aiは、オフセットのないタイムスタンプをUTCとして解釈します。
  • ニューヨークでは、オフセットのないタイムスタンプは4〜5時間早い時刻になります。夏時間により、現地時刻のタイムスタンプには1時間の空白や重複も生じます。固定の-05:00のオフセットは、夏時間の間は誤りになります。
  • 東京では、オフセットを省略すると測定値が9時間未来の時刻として解釈されてしまいます。これは24時間制限の許容範囲内に収まるため、NEQTO.aiは測定値を受け入れます。

どちらの場合もNEQTO.aiが警告できます。デバイスまたはエンドポイントの詳細を開いている間、デバイスのタイムスタンプが受信時刻より1時間以上進んだまま、または遅れたままの状態が10分以上続くと、通知が表示されます。東京なら「デバイス … のデータの時刻が、受信時刻より9時間進んでいます」、冬のニューヨークなら「…受信時刻より5時間遅れています」のように表示されます。

デバイスの時計をUTCに設定するか、Unixエポック時刻を送ってください。現地時刻を送る場合は、測定した時点で適用されていたUTCオフセットを使ってください。

送信方法

プロトコル 送り方
MQTT JSONのメッセージをMQTTトピックにパブリッシュします。
HTTPS JSONをHTTP POSTでエンドポイントのURLに送信します。
WSS JSONをWebSocket接続でテキストフレームとして送信します。

トラブルシューティング

症状 考えられる原因
接続またはTLSハンドシェイクが失敗する ホストまたはポートが正しくないか、TLSの設定がエンドポイントと一致していません。認証情報の概要画面で、エンドポイントの詳細を確認してください。
認証が拒否される ユーザー名またはパスワードが一致していないか、エンドポイントが削除されたか、認証情報が変更されています。
接続できたがデバイスが表示されない 間違ったトピックやURL、または対応していないトピックやURLに送信しているか、テレメトリ以外のチャンネルを使っているか、ペイロードを解析できませんでした。デフォルトのMQTTトピックでは、エンドポイントIDが一致している必要があります。
デバイスは表示されるが測定値が表示されない マッピングできるセンサーのフィールドが見つからなかったか、測定値が空または不正な形式だったか、ペイロードに識別子、タイムスタンプ、メタデータしか含まれていませんでした。
ゲートウェイ:サードパーティのゲートウェイの中には、ペイロードを設定しなくてもNEQTO.aiにデータを送るものがあります。HPE Arubaのインテグレーション(Aruba用デバイスエンドポイント作成の選択肢)はその1つで、そのデバイスは自動でエンドポイントにデータを送ります。ご自身で設定するデバイスでは、neqtoai-stdが推奨される基本形式ですが、対応しているほかのJSON形式も受け付けます。

エンドポイントの管理

デバイスエンドポイントの表の各行には、3点メニューがあります。行の右端の操作列にある⋮(3点)アイコンをクリックすると開きます。このメニューには、権限で許可されている操作が表示され、編集や、デモ用のエンドポイントではシミュレーターなどがあります。

デバイスエンドポイントの行で、「操作」列の3点メニューを開いたところ。詳細を表示、データプッシュ、シミュレーター、削除、編集の5つの項目が並び、メニュー全体が赤枠で囲まれています。
エンドポイントの「操作」列の3点メニュー。詳細を表示、データプッシュ、シミュレーター、削除、編集を使えます。
  • エンドポイント名で一覧を検索します。
  • 詳細を表示は、認証情報の概要を開き直し、エンドポイントのペイロードデコーダーを表示し、現在そのエンドポイントに送信しているすべてのデバイスを一覧表示します。
  • データプッシュは、データプッシュの画面を開きます。この画面から、エンドポイントへ必要なときにペイロードを送信できます。表示されるのは、MQTTとWebSocketのエンドポイントで、「デバイスエンドポイントを編集」の権限を持つユーザーだけです。データプッシュを参照してください。
  • シミュレーターは、アプリケーション内のデモ用エンドポイントで、内蔵のシミュレーターを開きます。表示されるのは、アカウントのオーナー、アカウント内のすべてのアプリケーションにフルアクセスできるユーザー、そのアプリケーションで「シミュレーターを表示」と「シミュレーター操作を実行」の両方を持つメンバーです。操作方法はシミュレーターを参照してください。
  • 編集で変更できるのは名前と説明だけです。接続の設定は変わりません。
  • 削除は、エンドポイントとその認証情報を無効にし、該当する場合はデモのシミュレーターを停止し、エンドポイントとデバイス、アプリケーションとの紐付けを削除します。デバイスの記録は削除されません。ほかのソースで紐付いているデバイスは引き続き使えますが、このエンドポイントに依存していたデバイスは、このエンドポイントを通じたデータの受信が止まります。削除したエンドポイントは画面上では復元できません。新しいエンドポイントを作成し、ハードウェアをその新しい認証情報で更新してください。

ペイロードデコーダー

デバイスによっては、JSONではなく、コンパクトなバイナリやテキストのフレームを送るものがあります。エンドポイントのペイロードデコーダーは、NEQTO.aiが読み取る前にそれらのメッセージをデータに変換します。そのため、デバイス、その属性、測定値は、JSONのデバイスと同じように表示されます。デコーダーは、デバイスが送るデータのサンプルからAtollaが作成します。

デコーダーは1つのエンドポイントに1つまでです。MQTT、HTTPS、WSSのエンドポイントで、JSONのオブジェクトや配列ではないメッセージすべてに対して実行されます。JSONのオブジェクトや配列には使われません。WSSの接続では最初のフレームでパーサーが決まり、その後も変わらないため、組み込みのArubaパーサーが受け付けた接続のフレームはデコーダーに渡りません。

デコーダーがない場合、NEQTO.aiはバイナリやテキストのメッセージをすべて拒否し、「メッセージをJSONとして読み取れませんでした。ペイロードの形式を確認してください。」と表示します。この通知にはデコーダーを設定があり、デコーダーのダイアログを開けます。

赤いエラー通知。「メッセージをJSONとして読み取れませんでした。ペイロードの形式を確認してください。」というメッセージの下に、デコーダーを設定のリンクがあります。
デコーダーのないエンドポイントに届いたバイナリのメッセージ。ボタンからデコーダーのダイアログが開きます。

デコーダーを設定する

エンドポイントの詳細を表示を開きます。ペイロードデコーダーの設定をクリックすると、ペイロードデコーダーを設定が開きます。

  • 1
    エンコード(16進数、Base64、テキスト)を選択し、サンプルペイロードを1行に1つずつ、10件まで貼り付けます。同じ文字列でも16進数とBase64ではバイト列が異なることがあるため、エンコードはご自身で選択してください。ダイアログには各サンプルがサイズとともに表示され、選択したエンコードとして無効なサンプルや64 KiBを超えるサンプルにはエラーが表示されます。
  • 2
    必要に応じてペイロード仕様またはコーデックを入力します。データシートのペイロードの説明部分かメーカーのデコーダーのコード(50,000文字まで)を貼り付けるか、10 MBまでのPDFを添付するか、その両方を行います。どちらもない場合、Atollaは意味を特定できないバイトをrawフィールドとして残し、その旨をメモに記載します。
  • 3
    デコーダーを下書きをクリックします。Atollaはサンプルを比較してどのバイトが変化するかを確認するため、下書きにはサンプルが3件以上、それぞれ2 KBまで必要です。下書きは通常3分以内に終わりますが、失敗した下書きをAtollaが修正する場合はさらに時間がかかります。消費するのは10クレジットで、プランでAIクレジットを使用する場合、開始前にボタンの横に表示されます。
ペイロードデコーダーを設定のダイアログ。エンコードは16進数で、サンプルペイロードには8バイトの16進数のサンプルが4件入力され、その下にサイズとバイト列とともに1件ずつ表示されています。ペイロード仕様またはコーデック(任意)には、メーカーのCN-4 Climate Nodeのコーデックが入力されています。その下にPDFを添付のボタンと、10クレジットと残りのクレジット数が表示されたデコーダーを下書きのボタンがあります。保存した内容が取り込みに反映されるまで最大15秒かかるという注記の下に、キャンセルと無効な保存のボタンがあります。
Atollaはサンプルをもとに下書きします。仕様が提供されていれば、それも使用します。

下書きを確認する

下書きが返ってくると、Atollaからのメモに、デコーダーがバイトをどう読み取るかと、Atollaが説明できなかった内容が示されます。結果には、サンプルごとにバイト列、デコード結果、警告が表示されます。デコーダーのコードはダイアログには表示されません。

  • サンプルを変更すると、結果は古いものとして表示されます。テストは、現在のデコーダーをサンプルに対してもう一度実行します。AIは使わず、クレジットも消費しません。
  • 変更してほしい点に、「湿度は5.1ではなく51になるはずです」のように変更点を書き、書き直すをクリックします。Atollaは現在のデコーダーをもとに書き直します。書き直したデコーダーがすべてのサンプルをデコードできた場合、1回につき追加で10AIクレジットを消費します。
  • 下書きや書き直しが一部のサンプルで失敗した場合、Atollaは1回だけ修正を試み、そのことを伝えます。それでもすべてのサンプルをデコードできない下書きでは、クレジットは消費されません。メモを添えて書き直すか、ペイロード仕様またはコーデックを追加してください。
ダイアログに戻ってきた下書き。Atollaからのメモには、CN-4 Climate Nodeの測定フレームの見分け方と各フィールドの単位が英語で書かれています。結果にはテストのボタンがあり、サンプルごとの行に、バイト列、air_temp、rh、co2_ppm、bat_pct、door、tamperを含むJSONのデコード結果、警告欄のなしが表示されています。下に変更してほしい点の入力欄と書き直すのボタンがあります。
保存する前に、すべてのサンプルのデコード結果を確認してください。

失敗したサンプルは、その行に理由が表示されます。

結果 意味
デコーダーのエラー このバイト列で、デコーダーのコードが失敗しました。
デコーダーが拒否しました デコーダーが意図的にメッセージを拒否しました。たとえば、仕様上は測定値ではないとされているフレームです。
時間切れ デコーダーが1つのメッセージに時間をかけすぎました。
メモリ不足 デコーダーが使用したメモリが多すぎました。
出力が無効です デコーダーが、NEQTO.aiがデータとして読み取れないものを返しました。

デコーダーの保存、編集、削除

保存すると、デコーダーは新しいバージョンとして保存され、エンドポイントの詳細にはバージョンN(日時に保存)と表示されます。保存するたびに前のバージョンは置き換えられ、戻せるバージョン履歴はありません。保存した内容が取り込みに反映されるまで、最大15秒かかります。

エンドポイントの詳細にあるペイロードデコーダーのセクション。このエンドポイントが受け取るバイナリやテキストのメッセージをデータに変換し、JSONのメッセージには使われないという説明があります。編集と削除のボタンがあり、状態はバージョン1と保存日時です。
エンドポイントの詳細には、保存したバージョンと、編集、削除のボタンが表示されます。
  • 編集は、保存したデコーダーをサンプルとともに開き直します。そのままテストや書き直しができます。仕様のテキストとPDFは保存されないため、書き直す前にもう一度追加してください。
  • 削除では、まずこのデコーダーを削除しますか?と確認されます。15秒以内に、このエンドポイントへのバイナリやテキストのメッセージは再び解析エラーになります。
  • 保存したデコーダーがメッセージをデコードできない場合は、メッセージが拒否されたときでエラーと対処方法を確認してください。

デコーダーの設定、変更、削除には、アカウントまたはアプリケーションで「デバイスエンドポイントを作成」と「デバイスを作成」の2つの権限が必要です。権限がない場合も、セクションとデコーダーのバージョンは表示されますが、ボタンは表示されず、後述の通知にもデコーダーのボタンは付きません。アプリケーション内では、ボタンはそのアプリケーション自身のページでのみ表示されます。

リアルタイムの取り込みフィードバック

エンドポイントの詳細、または紐付くデバイスのページを開いている間、右上の通知に、新しいメッセージが取り込み処理をどう進んでいるかが表示されます。ページを更新せずに、新しい接続を確認したり、メッセージが失敗した理由を確認したりできます。

処理の段階

問題なく取り込まれるペイロードでは、処理が進むにつれて次の段階が表示されます。

通知 起きたこと
「メッセージを受信しました。フォーマットを解析しています。」 メッセージが届き、NEQTO.aiがそれをこのエンドポイントに紐付けました。
「メッセージのフォーマットを解析しています。」 NEQTO.aiがペイロードを読み取り、正規化しています。
「デバイスを認識しました。データを抽出しています。」 NEQTO.aiがメッセージをデバイスに紐付け、その測定値を解析しました。
「データを保存しました。」 測定値が保存されました。これでダッシュボード、アラート、分析で使われます。
縦に3つ重なった通知。上から順に、灰色の感嘆符のアイコンが付いたメッセージを受信しました。フォーマットを解析しています、緑のチェックマークが付いたデバイスを認識しました。データを抽出しています、緑のチェックマークが付いたデータを保存しましたと表示されています。
問題なく取り込まれた場合に画面に重なって表示される通知。リアルタイムの更新のため、重なる順序が異なることがあります。各通知は、メッセージごとではなく、ページを開くたびに1回表示され、数秒で閉じるため、画面には一部しか表示されないことがあります。

各段階はページを開くたびに1回表示されます。そうしないと、数秒ごとに送信するデバイスで画面が埋まってしまうため、後続のメッセージでは成功した段階は繰り返し表示されません。改めて表示するには、エンドポイントまたはデバイスのページを開き直してください。

「メッセージを受信しました。フォーマットを解析しています。」はMQTTに固有のものです。HTTPSとWSSでは、フィードバックは「メッセージのフォーマットを解析しています。」から始まり、意味は同じです。

メッセージが拒否されたとき

拒否されたメッセージでは、大きなエラーの通知が表示されます。同じデバイスで同じ種類の失敗が繰り返された場合は重複が除かれるため、問題が続いていても、メッセージごとに新しい通知が出ることはありません。別のデバイスが同じように失敗した場合は、そのデバイス用の通知が表示されます。

失敗の通知は、閉じるまで残ります。上記の進行状況の通知は数秒で消えますが、対応が必要な失敗は画面に残ります。マッピングの失敗は、デバイスが再びマッピングできる測定値を含むメッセージを送ったときにも消えます。過負荷と一時的な保存エラーのメッセージは、自動で消えます。
赤いエラーの通知。メッセージをJSONとして読み取れなかったので、ペイロードの形式を確認するよう表示され、その下にデコーダーを設定のリンクがあります。
拒否されたペイロードでは、何が問題だったかが、対応できる言葉で表示されます。
メッセージ 対処方法
「デバイスIDが見つかりません。ペイロードに device_id フィールドを追加するか、トピックにIDを含めてください。」 メッセージのどこにもデバイスを特定するものがなく、エンドポイントにはフォールバック先となる唯一のデバイスもありません。データの送信:ペイロードのガイドの説明に従って、恒久的な識別子を追加してください。
「メッセージをJSONとして読み取れませんでした。ペイロードの形式を確認してください。」 ペイロードが有効なJSONではないか、メッセージが届いたMQTTトピックがこのエンドポイントで受け付けるものではありません。データの送信:ペイロードのガイドと照らし合わせて、両方を確認してください。デバイスが意図的にバイナリやテキストを送っている場合は、通知のデコーダーを設定からエンドポイントのペイロードデコーダーを開けます。
「エンドポイントのペイロードデコーダーがメッセージをデコードできませんでした。デコーダーを確認してください。」 エンドポイントにペイロードデコーダーがあり、このメッセージで失敗しました。エンドポイントにデコーダーがあると、JSONのオブジェクトや配列でないメッセージはすべてデコーダーに渡されるため、形式が不正なJSONでもJSONの通知ではなくこの通知が表示されます。通知のデコーダーを開くは、保存済みのサンプルとともにデコーダーを開きます。失敗したメッセージをサンプルとして貼り付けてテストし、2 KB以下であればメモを添えて書き直してください。64 KiBを超えるメッセージも同じように失敗しますが、テストはできないため、送信側で短くしてください。ペイロードデコーダーを参照してください。
「無効なデバイス『…』がこの識別子を引き続き使用しているため、データは保存されませんでした。受信を再開するにはデバイスを有効にしてください。識別子を再利用するには、デバイスを完全に削除してください。」 無効なデバイスが、このメッセージの識別子を保持したままのため、何も保存されません。受信を再開するにはデバイスを有効にし、識別子を再利用するにはデバイスを完全に削除してください。無効化、復元、削除を参照してください。
「メッセージは受信しましたが、データを抽出できませんでした。ペイロードのフィールドを確認してください。」 デバイスは認識されましたが、有効な測定値のマッピングが見つかりませんでした。ペイロードに識別子、タイムスタンプ、メタデータしか含まれていないか、測定値のフィールドが空、不正な形式、または分類できない可能性があります。測定のフィールドを追加または修正して、再送してください。
「デバイス … からメッセージを受信しましたが、マッピング済みのフィールドが見つかりませんでした。」 — 続いて期待するフィールドと受信したフィールドの一覧 上の行と同じ失敗で、NEQTO.aiがデバイスに紐付けたメッセージの場合です。通常は、ファームウェアやペイロードの変更で測定値のフィールド名が変わったことが原因です。期待するフィールドと受信したフィールドの一覧で、どの名前が変わったかがわかります。これらの一覧が省略されるのは、マッピング済みのフィールドがまだないデバイスのように、比較するものがない場合だけです。
「デバイス … のデータをスキップしました:タイムスタンプが許容範囲外です。」(または「…現在よりN分以上未来の時刻です」、「…過去に離れすぎています」、「…有効な日付ではありません」) デバイスの時計が間違っているか、タイムスタンプがNEQTO.aiに意図とは違う形で解釈される形式になっています。未来の場合は、タイムスタンプが24時間より先であることを意味し、通常は日付を誤って設定した時計か、マイクロ秒のエポック値が原因です。過去の場合は、1970年より前の日付を意味します。メッセージにはデバイス名が表示されます。時計を修正するか、タイムスタンプを省略して受信時刻を使ってください。タイムスタンプとタイムゾーンを参照してください。
「このメッセージ形式はN回失敗したため、H時間停止されています。ペイロードを修正すると再試行されます。」 設定を誤った1台のデバイスが処理を占有しないよう、NEQTO.aiは識別に失敗し続ける形式のペイロードを一時的に保留します。ペイロードを修正してください。保留は自動で解除され、修正した形式は新しい形式として扱われます。
「プランが有効でないため、データの取り込みが停止されています。」 アカウントのデータは何も保存されていません。プランの期限切れや猶予期間の終了で、取り込みが停止します。アカウントを再開するには、サポートにお問い合わせください。
「プランのデバイス上限に達したため、このデバイスは作成されませんでした。」 新しいデバイスを登録しようとしましたが、上限のため登録できませんでした。不要になったデバイスを削除するか、請求タブでデバイスの上限が高いプランに変更してください。管理を参照してください。アカウントに請求タブがない場合は、上限を引き上げるためにサポートにお問い合わせください。
「システムが一時的に過負荷となり、メッセージが破棄されました。まもなく回復します。」 一時的な集中で受信キューがいっぱいになり、このメッセージは破棄されました。保存も再試行もされませんが、後続のメッセージは処理できます。繰り返し起きる場合は、デバイスの送信頻度を下げるか、送信のタイミングをずらしてください。ペイロードデコーダーがあるエンドポイントでは、デバイスの送信頻度に対してデコーダーの処理が遅すぎることを示している場合もあります。制限と運用上の詳細を参照してください。
「データを受信しましたが、一時的な保存エラーのため保存できませんでした。データは保存されていません。」 書き込みが失敗し、この測定値は自動では再試行されません。後続のメッセージは成功する可能性があります。エラーが続く場合は、サポートにお問い合わせください。
赤いエラーの通知。デバイスNT-RTU-ROOF-07からメッセージを受信したがマッピング済みのフィールドが見つからなかったことが表示され、期待するフィールドとしてdata.temperature.value、data.humidity.value、data.battery.value、受信したフィールドとしてpayload_format、timestamp、device_id、dataと、マッピングのないdata配下のフィールド2つが並び、データフィールドのマッピング、またはフィールド名が変わった場合はペイロード形式を確認するよう書かれています。
マッピングの失敗では、デバイス名と、期待したフィールドと受信したフィールドが表示されるため、どの名前が変わったかがわかります。
これらの通知はリアルタイムの表示で、記録ではありません。見ている間に届いたメッセージについて表示されるもので、閉じると消え、あとから見返せる履歴はありません。実際に保存された内容は、デバイスのデバイスデータタブで確認してください。

デバイス

デバイスは、1台の機器を表します。NEQTO.aiが最初に識別したペイロードから作成することも、データの送信が始まる前にハードウェアを登録するために手動で作成することもできます。

アプリケーションのデバイス一覧の表。6台のデバイスがすべて接続中で、デバイス名の横に緑のWi-Fiアイコンがあります。列はデバイス名、デバイスエンドポイント、エンドポイントと表示されるソースのバッジ、タグ、ダッシュボード、属性、アプリケーション、作成日時、最終接続、操作です。表の上に検索欄、タグのフィルター、列の設定、有効/無効の切り替えがあります。
デバイス一覧。緑は接続中を意味し、最終接続の列で、最後にデータが届いた時刻がわかります。

一覧の表示

  • 接続状態は、各デバイス名の横に表示されます。接続中は緑のWi-Fi、そうでない場合は赤です。
  • 未対応のアラートは、アラートを閲覧できる場合に、アプリケーションのデバイス一覧で、接続状態のアイコンと名前の間に、件数を示す小さな赤いバッジとして表示されます。そのアプリケーションで、デバイスのアラートイベントのうちまだ新規、進行中、保留中のものを数え、99を超えると99+と表示し、未対応のものがなければ表示されません。クリックすると、そのデバイスとこれら3つのステータスで絞り込んだアラート履歴が新しいタブで開きます。アラート履歴はアプリケーションに属するため、アカウントレベルの一覧には数は表示されません。
  • ソースは、各デバイスがどのようにNEQTO.aiに入ったかを示します。デバイスエンドポイントに送信するデバイスにはエンドポイントのバッジ、インテグレーションを通じて外部サービスから取り込まれたデバイスにはインテグレーションのバッジ(横にインテグレーション名)が付きます。この列はデフォルトで表示されます。
  • 名前で検索し、ツールバーのタグのフィルターかタグの列の見出しから、タグでフィルターをかけます。
  • スイッチで、有効と無効のデバイスの表示を切り替えます。無効のデバイスは、無効にした(完全には削除していない)デバイスです。データを送り続けている無効のデバイスには、名前の下に注記が表示されます。無効化、復元、削除を参照してください。
  • ほとんどの列で並べ替えができます。最終接続で並べ替えると、データを送っていないデバイスを見つけられます。
  • 列の設定で表示する列を選択します。いくつかの列(外部ID、ベンダー、モデル、アカウント、メモ、プロファイル、アプリケーション内のシステム)はデフォルトで非表示で、選んだ内容はアプリケーションごとに記憶されます。
  • プロファイルは、各デバイスのデータの解釈方法を示します。EnOcean(EEP付き)、BLE、STDのいずれかです。この列はデフォルトで非表示です。
  • ダッシュボードは、そのデバイスの関連ダッシュボードを開き、そのデバイスを表示するウィジェットを持つすべてのダッシュボードと、それぞれのウィジェット数を一覧表示します。デバイスを変更または削除する前に確認してください。行の操作メニューからも同じ表示を開けます。デバイスリストとアラートリストのウィジェットは、デバイスを表示するものとして数えられません。そのほかはダッシュボードのページで説明しています。
  • アプリケーション内のデバイスの操作メニューにあるAtollaでダッシュボード作成は、そのデバイスを選択した状態でダッシュボードの作成を開きます。ダッシュボードを作成する権限がない場合はグレー表示になり、Atollaを利用できない場合は表示されません。ダッシュボードを参照してください。
アプリケーションのデバイス一覧の先頭の4行。Cold Room Sensor 1の名前の横にある未対応のアラート数1を赤枠で囲んでいます。ほかの3台、Fleet Tracker GPS-01、Smart Thermostat、CNC Machine Floor 2にはバッジがありません。4台とも接続中です。
赤い数は、そのデバイスの未対応のアラートイベントの数です。未対応のものがないデバイスには表示されません。

新しいデバイスの名前の付け方

最初のペイロードから作成されたデバイスには、nameやdeviceNameのようなペイロードの名前のフィールドから名前が付きます。それがなければモデルから、それもなければメーカー名に「sensor」を付けた名前になります。プレースホルダーのunknown(大文字と小文字は区別しません)や、MACアドレスなどの識別子に見える値は名前として扱われません。どれもないデバイスは、Autoと外部IDをつないだ名前(例:Auto 0013A20041B2C3D4)になり、後続のメッセージで正式な名称やモデル名を受信するまで、その名前が維持されます。届いた時点で一度だけ名前が変わりますが、ユーザーが名前を変更していた場合は変わりません。ファームウェアとファームウェアバージョンは、手入力した値があっても、実際の値を含む最新のメッセージの値に更新されます。空の値やunknownで置き換えられることはありません。名前がすでに使われている場合は、末尾に区別のための文字が追加されます。

デバイスを手動で追加する

作成の権限があれば、デバイス一覧の上にあるデバイスを追加をクリックします。フォームでは、外部ID、デバイス名、ベンダー、モデル、および1つ以上のタグが必須です。ファームウェア、ファームウェアバージョン、ゲートウェイ、メモ、画像も入力できます。また、QRコードをスキャンで、利用できる詳細を入力することもできます。デバイス名は100文字以内、外部IDは255文字以内です。

アカウントのデバイス数がすでにプランの上限に達している場合、デバイスは作成されず、「デバイス制限に達しました」に「許可されたデバイスの最大数に達しました。」と表示されます。不要になったデバイスを削除するか、請求タブでデバイスの上限が高いプランに変更してください。管理を参照してください。

ハードウェアが送信を始めるときは、同じ外部IDを使ってください。手動で作成したデバイスには、NEQTO.aiがその識別子の測定値を受信してマッピングするまで、属性もデバイスデータもありません。外部IDはアカウント内で一意です。

「デバイス編集」ページ

デバイスの行をクリックするか、操作メニューから詳細を表示または詳細を編集を選択すると、デバイス編集が開きます。このページでデバイスを確認でき、編集の権限があれば設定を変更できます。次のタブがあります。

タブ 内容
一般情報 編集できるメタデータ:デバイス名、ベンダー、モデル、ファームウェア、ファームウェアバージョン、タグ、メモ、画像。外部IDは読み取り専用です。EnOceanのデバイスでは、編集できるEEPの選択欄も表示されます(ドロップダウンからコードを選択します)。
属性 このデバイスで自動検出された測定項目です。後述を参照してください。
デバイスデータ デバイスから届いているリアルタイムと直近のペイロードの値です。
接続監視 アプリケーション内でのみ表示されます。デバイスのオフラインタイムアウトと接続アラートの設定です。アラートのページを参照してください。
異常検知設定 このデバイスのセンサーごとの異常検知で、アカウントレベルのデバイス一覧からもアプリケーション内からも開けます。ウォームアップの進捗とシグマの設定は両方に表示されます。異常検知アラートのスイッチは、アラートがアプリケーションに属するため、アプリケーション内でのみ表示されます。アラートのページを参照してください。
一般情報タブを開いたデバイス編集の画面。左側に一般情報、属性、デバイスデータ、接続監視、異常検知設定の5つのタブが並んでいます。中央の列にはデバイス画像のドロップエリアがあり、その下にデバイスのエンドポイントと検出された属性があります。右の列にはデバイス名、ベンダー、モデル、ファームウェア、ファームウェアバージョン、タグ、メモの編集できる欄があり、外部IDは読み取り専用としてグレー表示です。ヘッダーにキャンセル、変更を保存、削除があります。
編集の権限があれば、外部ID以外の一般情報の欄を変更できます。
デバイスデータタブを開いたデバイス編集の画面。最新の測定値のカードには、最新の測定値のタイムスタンプと、各属性の現在の値と単位(摂氏の温度、パーセントの湿度とバッテリー)が表示されています。その下のデバイスのトレンドのパネルでは、同じ3つの属性の推移が色分けした線で描かれ、凡例にそれぞれの名前があります。
デバイスデータには、保存された最新の測定値と、属性のリアルタイムの推移が表示されます。

接続状態の判定方法

これはリアルタイムのpingではありません。デバイスは、データが届き続けている間は接続中とみなされます。オフラインタイムアウトの間に何も受信しなければ、オフラインとしてマークされます。タイムアウトは、アプリケーション内のデバイスの接続監視タブで分単位で設定でき、入力できる最小値は10分です。接続アラートをオフにしたデバイスはオフラインとしてマークされることはなく、複数のアプリケーションに属するデバイスは、そのうち最も短いタイムアウトでオフラインになります。

新しいデバイスには自動タイムアウトが設定され、その値はオフラインタイムアウトの欄に表示されます。インテグレーションが定期的にデータを取得するデバイスでは、インテグレーションの同期間隔の2倍に、10分以上の余裕を加えた値になります。

データを直接送信するデバイスの送信が途絶えると、NEQTO.aiは最近の受信状況から通常の送信間隔を推定します。その間隔の2倍が自動タイムアウトより長い場合、タイムアウトを間隔の2倍に10分以上の余裕を加えた値に引き上げます。調整後のタイムアウトを超えてデータが届かなければ、デバイスはオフラインになります。推定には6回以上の送信が必要なため、送信頻度の低い新しいデバイスは、最初の数回の送信の合間にオフラインと表示されることがあります。

手動で設定したタイムアウトや、自動調整の導入前に保存されたタイムアウト値は変更されません。また、アラートに承認済みまたは有効なペイロード送信アクションがある間は、送信間隔の推定による引き上げも行われません。固定のタイムアウトは、デバイスの送信間隔より長くしてください。

同じタブで、接続アラートのオン・オフ、メール通知とSMS通知、ペイロード送信を選び、通知停止時間帯とエスカレーションのステップを設定できます。アラートがオンの間、アプリ内通知は常にオンです。SMSには、受信者のプロフィールに電話番号が登録され、SMSの受信が許可されていることが必要です。デバイスの編集権限がない場合、これらの設定は読み取り専用です。

接続状態が変わると、デバイス一覧とデバイスのページは、開いている間に自動で更新されます。手動で更新する必要はありません。

デバイスの検索

アラートやウィジェットのデバイスの選択欄は、入力に合わせて検索します。結果が空であることと、検索を実行できなかったことは別のもので、それぞれ異なる表示になります。検索に失敗しました。もう一度お試しください。は、検索が完了しなかったことを意味し、該当するデバイスが存在しないとは限りません。判断する前に、もう一度検索をお試しください。

デバイスの整理

  • タグは、一覧全体を絞り込める「キー:値」のラベルです(例:floor:3、site:warehouse-A)。管理方法はタグのセクションを参照してください。
  • ベンダーとモデルは、列として表示して並べ替えに使えるデバイスのメタデータです。デバイスを絞り込んだりグループ分けしたりするにはタグを使います。
  • デバイスの操作メニュー(メインのデバイス一覧)のアプリケーションに追加で、どのチームに表示するかを制御します。

無効化、復元、削除

無効にするは元に戻せますが、完全に削除は元に戻せません。有効なデバイスを無効にすると、無効の一覧に移り、外部IDは予約されたまま残ります。見つけるには、一覧の切り替えを無効にします。そこから有効にするで復元するか、完全に削除で削除して外部IDを解放します。完全な削除は、デバイスを無効にした後でなければできません。

NEQTO.aiは無効のデバイスの測定値を保存しませんが、拒否した数は記録します。無効のデバイスがデータを送り続けている場合、無効の一覧ではその名前の下に、拒否した測定値の数、いつから拒否しているか、最後に届いた日時が注記として表示されます。注記の見出しは、最後に拒否した測定値が1日以内ならデータを送信し続けています、それより前なら無効化後にデータを送信しましたです。デバイスのデバイスデータタブにも同じ注記が表示され、受信を再開するにはデバイスを有効にし、識別子を再利用するにはデバイスを完全に削除するよう案内されます。何も送っていない無効のデバイスでは、「このデバイスは無効のため、データは表示されません。」と表示されます。デバイスを有効にすると、数はリセットされます。

無効にしても、デバイスのアラートはそのままです。完全に削除した場合は異なります。

  • 閾値アラートからは、そのデバイスを指定したトリガー条件と解除条件がすべて削除され、デバイスはアラートのデバイス一覧から外れます。アラート自体は残ります。ほかのデバイスの条件が残っているアラートは、それらで動作し続けます。トリガー条件が残っていないアラートは、有効なデバイスが割り当てられるまで、「閾値アラート」画面のカードにデバイス未割り当てと表示され、要確認の件数に含まれます。トリガー条件が変わった承認済みのペイロード送信は、アラートにほかのデバイスの条件が残っていても、改めて承認が必要です。そのアクションは設定変更ありと表示され、再び承認して有効化するまでペイロードを送信できません。
  • そのデバイスを対象とする接続アラートと異常検知アラートは削除されます。
  • アラート履歴には、デバイスを無効にした時点でそのイベントが表示されなくなり、完全に削除した後も戻りません。
  • デバイスは、アプリケーション、システム、タグ、ウィジェットの系列からも外れます。ウィジェット自体は残ります。

故障したデバイスを交換する場合は、完全に削除する前に、アラートの条件を更新し、影響を受けるペイロード送信を元の状態に戻してください。

  • 1
    新しいデバイスを登録し、古いデバイスを使っているすべてのアプリケーションに追加します。
  • 2
    各アプリケーションで閾値アラートを開き、リスト表示に切り替えます。件数による絞り込み、検索、列のフィルターをすべて解除します。列からデバイス列を追加し、古いデバイスで絞り込みます。各結果を開いて編集をクリックし、トリガー条件と解除条件を新しいデバイスに変更して保存します。
  • 3
    デバイスのフィルターを解除し、残りのアラートの解除条件も確認します。古いデバイスを解除条件だけに使うアラートは、このフィルターでは見つかりません。該当する条件を変更し、アラートをそれぞれ保存してください。
  • 4
    各アプリケーションでアクションを開きます。影響を受けた送信のうち、以前承認されていたものを再承認し、以前有効だったものを再び有効化します。
  • 5
    無効の一覧に戻り、古いデバイスを完全に削除します。

条件のデバイスを変更すると、その条件の計算は削除されるため、新しいデバイスで追加し直してください。バッジについてはアラートページで説明しています。

デバイスを有効にすると、紐付くエンドポイントのいずれかで同じデバイス名がすでに使われていないか、また、プランに上限がある場合はアカウントのデバイスの上限が改めて確認されます。どちらかの確認に失敗した場合、競合を解決するまでデバイスは無効のままです。

外部IDがすでに使われているとき

デバイスの外部IDはアカウント全体で一意なので、すでに使われている識別子で2台目のデバイスを作成しようとすると拒否されます。これは、インテグレーションのサンプルからデバイスを作成するときや、APIを使うときに最もよく起きます。

赤いエラーの通知。見出しに「エラーが発生しました。もう一度お試しください。」と表示され、その下に「この識別子を持つデバイスは、このアカウントに既に存在します。」と表示されています。
この識別子は、すでに表示できるデバイスが使っています。デバイス一覧で外部IDの列を表示すると見つけられます。

無効にしたデバイスが、わかりにくい衝突の原因になることがあります。無効にしても外部IDは予約されたまま残りますが、無効のデバイスはデフォルトの一覧には表示されません。エラーには無効のデバイスの名前と、そのデバイスを有効にするか、完全に削除して識別子を解放するかの2つの選択肢が表示されます。

赤いエラーの通知。見出しに「エラーが発生しました。もう一度お試しください。」と表示され、その下に「無効なデバイス「Rooftop Weather」がこの識別子を引き続き使用しています。識別子を再利用するには、そのデバイスを有効にするか、完全に削除してください。」と表示されています。
無効のデバイスも識別子を保持したままです。ここに表示された名前のデバイスを見つけるには、デバイス一覧を無効に切り替えてください。

属性

属性は、温度、湿度、バッテリー、在室状況など、デバイスからマッピングされた1つの測定項目です。属性は、ウィジェット、アラート、分析で使われる名前付きの値を提供します。

属性は自動でマッピングされます。デバイスのペイロードが届くと、NEQTO.aiは利用できるフィールドを再帰的に読み取り、見つけた測定値ごとに属性を作成し、その値への正確なパスを記録します。dataのラッパーは必須ではありません。属性を手動で作成または削除することはなく、属性はデータの有効なマッピングに従います。新しいペイロードの構造では、フィールドをマッピングする前に分類が必要になることがあります。マッピング済みの同じ構造を持つ後続のメッセージでは、そのマッピングが再利用されます。
属性タブを開いたデバイス編集の画面。自動検出された測定項目が表で一覧表示されています。見出しは件数付きの属性で、横にライブの表示と更新ボタンがあります。列は種類、属性名、表示名、単位と、各行に編集の項目を持つ操作メニューです。種類の列には、temperatureの行に温度計、humidityの行にしずく、batteryの行にバッテリーのアイコンがあります。各行には、元の属性名の横に、Temperature、Humidity、Batteryという読みやすい表示名があります。
自動検出された属性。アイコンは測定の種類を表し、表示名と単位はご自身で調整できます。

編集できる項目

この画面では、検出されたJSONのパスや元の属性名は変更できません。属性の表示方法を変えるには、操作メニューを開いて編集を選択します。

  • 表示名:わかりやすいラベルです(必須、255文字以内)。たとえばt1を「給気温度」に変更します。
  • 単位:値と一緒に表示される単位です(50文字以内)。たとえば°C、%、hPaです。

元になる属性名は固定で、編集フォームでは読み取り専用で表示されます。

表示名と単位はアカウント単位の設定です。変更は、アカウント内でその属性が表示されるすべての場所に、すべてのユーザーに対して適用されます(ペイロードで送られる元の単位は固定のマッピングキーのまま残り、変わるのは画面に表示される単位だけです)。属性を編集する権限は、アカウントレベルだけでなくアプリケーションレベルでも付与できます。

属性の編集フォーム。読み取り専用の属性名の欄、編集できる表示名と単位の欄があり、キャンセルと変更を保存のボタンがあります。
属性の編集:表示名と単位だけを変更できます。
対応している値の型:NEQTO.aiは、標準的なJSONの値(数値、文字列、真偽値、null、配列、オブジェクト)を受け付けます。入れ子のオブジェクトや配列は、測定値の候補となるフィールドがないか調べられます。メッセージから有効なマッピングが得られない場合、最終的な測定値は保存されず、リアルタイムの取り込みフィードバックで、測定値を抽出できなかったことが報告されます。ペイロードを修正するか、値と単位を明示して、再度送信してください。

デモ用エンドポイントとシミュレーター

デモ用のエンドポイントでは、ハードウェアなしでデータを生成できます。内蔵のシミュレーターがエンドポイントを通じてサンプルのデバイスの測定値を送信するため、機器を接続する前に、ペイロードのマッピングを確認したり、ダッシュボードやアラートを作成したりできます。

シミュレーターは、デモ用エンドポイントの行にある「操作」列の3点メニューのシミュレーターか、アプリケーションのサイドバーのシミュレーターから開きます。シミュレーターのデバイスの追加、Atollaによる作成、シミュレーターのすべての操作はシミュレーターで説明しています。

制限と運用上の詳細

これらの制限は、エンドポイントの設定、取り込み、接続監視に影響します。取り込むペイロードには、どのプランでも上限はありません。

制限 値
HTTPSのペイロードのサイズ 1リクエストあたり1 MB
HTTPSのリクエストレート クライアントのIPとエンドポイントごとに制限されます。サービスのデフォルトは15分あたり100リクエストですが、環境によって変更されている場合があります。現在のウィンドウと残りのリクエスト数は、RateLimit-*のレスポンスヘッダーで確認してください。
MQTTトピックの長さ 最大512文字
MQTTトピックから取得するデバイス識別子 最大128文字。制御文字は使用不可
接続のタイムアウト 最小10分
ペイロードデコーダー エンドポイントごとに1つ。メッセージは1件64 KiBまで。頻繁に送信するデバイスでは、デコーダーの処理が遅いと、過負荷の通知とともにメッセージが破棄されることがあります。
エンドポイントの名前と説明 名前は100文字、説明は500文字
  • デバイスの識別子は変えずに使い続けてください。対応しているトピックの識別子か、device_idのようなペイロードのフィールドを使ってください。選んだ識別子が変わると、NEQTO.aiはそのハードウェアを新しいデバイスとして扱います。
  • neqtoai-stdは推奨であり、必須ではありません。最も確実に解釈される経路を直接選びます。payload_formatのないペイロードも、自動で判別・正規化されます。
  • エンドポイントのタイプは変更できません。MQTT、HTTPS、WSSのどれにするかを最初に決めてください。
  • データを送らないデバイスはオフラインに見えることがあります。自動のタイムアウトはデバイスが送信する頻度に合わせて調整されることがありますが、手動で設定したタイムアウトは変わらないため、送信間隔より長くしてください。
  • ペイロードの構造を一貫させてください。同じフィールドのパスと値の形式を使い続けると、後続のメッセージで既存の属性のマッピングが再利用されます。構造を変えると、新しいフィールドの分類が必要になることがあります。
  • MQTTの取り込みでは、ブローカーからの配信の停滞を監視しています。ワーカーが接続したままメッセージを受信しなくなった場合、ブローカーのセッションが自動で再起動されます。デバイスの設定を変更する必要はありません。中断中に送られたメッセージが届くかどうかは、引き続きデバイスのMQTTのQoSとセッションの設定によります。