LPWAN

はじめに

このセクションでは、非IPデバイスを統合するためのメカニズムについて詳しく説明します。Things Cloud は、Loriot、Actility、Sigfox を含む 3 つの主要な LPWAN 接続プロバイダー向けのネイティブコネクタを提供します。これらのコネクタは、デバイスのプロビジョニングとデータ取得に必要なベンダー固有の API を抽象化します。

このセクションでは、LPWAN エージェントの設定と動作について説明します。LPWAN エージェントは、次の中核機能を実行します。

  • 取り込み - Sigfox、Loriot、または Actility（ThingPark）のバックエンドからアップリンクメッセージを受信します。
  • 正規化 - 接続プロバイダーをデバイスロジックから切り離し、標準の Things Cloud インターフェイスを使用してデバイスを管理できるようにします。
  • 変換 - バイナリペイロードをユーザー定義のデバイスプロトコル経由でルーティングし、メジャーメント、イベント、アラームを抽出します。
  • ダウンリンク管理 - デバイスへの送信のために、コマンドをキューに入れて Network Server API に転送します。

Loriot LoRa

はじめに

Things Cloud は、Loriotエージェントマイクロサービスを介して Loriot Network Server と連携できます。以下のことが可能です。

  • 2つの方法でデバイスを登録する:
    • Loriot LNS接続を作成し、Things Cloud を使用してデバイスを登録する。
    • Loriot Network Server 経由で Loriotエージェントのエンドポイントを設定し、アップリンクメッセージ経由でデバイスを登録する。ダウンリンクメッセージを送信できるようにするには、この方法で作成されたデバイスは、接続およびデバイスタイプに関連付けるために、Things Cloud 経由で再登録する必要があります。
  • ペイロード処理のために、LoRaデバイスにデバイスプロトコルを割り当てる。
  • webベースのユーザーインターフェイスを使用してアップストリームペイロードパケットをデコードする。
  • Things Cloud イベントを通じて生のデバイスデータを後処理する。
  • LoRaデバイスで既存の Things Cloud 機能を活用する。たとえば、接続監視、デバイス管理、ダッシュボードによるデータの可視化、リアルタイム分析など。

次の図は、Things Cloud Loriot LoRa統合の概要を示しています。

Things Cloud Loriot LoRa integration

備考
この機能を使用するには、ご利用のサブスクリプションにこの機能が含まれている必要があります。このドキュメントで説明されている機能が表示されない場合は、プロダクトサポート にお問い合わせください。

Things Cloud でLoRaデバイスを使用する前に、Loriot Network Server で Things Cloud Loriotエージェントのエンドポイント詳細を設定する必要があります。

基本認証を使用したLoriotエンドポイントの設定

Loriot Network Server では複数のアプリケーションを作成できます。各アプリケーションではLoRaデバイスを設定できます。

ユーザー認証情報を使用してLoriotエージェントのエンドポイントを指定するには、Loriot Network Server アカウント内のいずれかのアプリケーションに移動し、ナビゲータの Application メニューで Output を選択します。

Loriot Network Server は、Output セクションで使用可能なさまざまなコネクタを使用して、LoRaデバイスメッセージを外部アプリケーションに転送します。

Output page with https forwarder

基本認証を使用してLoriotエンドポイントを設定するには、Things Cloud データフォワーダーを使用します。

Setting endpoint credentials

Loriotエージェントは “gw”（ゲートウェイ情報）メッセージのみを処理するため、Gateway Information オプションは常に有効にしておいてください。

Enable gateway information option

これで、アップリンクメッセージを受信すると、Loriotデバイスを Things Cloud に登録できるようになります。

Loriot LoRaデバイスのリクエストを処理する際、Loriotエージェントは、そのデバイスがまだ存在しない場合、Things Cloud プラットフォーム内に自動的にデバイスを作成します。 つまり、Loriot LoRaデバイスを明示的に登録する必要はありません。

Loriot Network Server は2種類のメッセージをLoriotエージェントに転送します: “rx”（アップリンクメッセージ）と “gw”（ゲートウェイ情報）です。

Loriot LoRaエージェントは、Things Cloud で重複したメジャーメントやイベントが作成されるのを避けるため、“gw” メッセージのみを処理します。これは、大半の情報が “rx” メッセージと “gw” メッセージで共通しており、さらに “gw” メッセージにはすべてのゲートウェイ情報も含まれているためです。

備考
Loriot LoRaエージェントに接続する際は、Loriot Network Server で “gw” メッセージオプションを有効にする必要があります。Things Cloud によるデバイス登録 を参照してください。

以下のLoriot LoRaデバイスメッセージでは、gws はネットワークに関与するゲートウェイのリストを表します。

{
    "cmd"  : "gw",
    "EUI"  : "0102030405060708",
    "ts"   : 1470850675433,
    "ack"  : false,
    "fcnt" : 1,
    "port" : 1,
    "data" : "0102AABB",
    "freq" : 868500000,
    "dr"   : "SF12 BW125 4/5",
    "gws"  : [
        {
            "rssi"  : -130,
            "snr"   : 1.2,
            "ts"    : 43424140,
            "gweui" : "1122334455667788.0",
            "lat"   : 47.284687,
            "lon"   :  8.565746
        }
    ]
}

Loriot LoRaエージェントは、最も古いタイムスタンプを持つ gw を選択して処理します。 Loriot LoRaエージェントは、rssi 値を標準の Things Cloud SignalStrength オブジェクトにマッピングし、lat および lon の値でデバイスのマネージドオブジェクトを更新します。

ダウンリンクオペレーションを送信できるようにするには、アップリンクメッセージ経由で登録されたデバイスを、接続およびデバイスタイプに関連付けるために、Things Cloud を使用して再登録する必要があります（Things Cloud によるデバイス登録 を参照）。

Things Cloud プラットフォームによるデバイス登録

Things Cloud でのLoriot LNS接続の作成

Things Cloud でLoRaデバイスを使用する前に、管理アプリケーションで Things Cloud Loriotエージェントのエンドポイント詳細を設定する必要があります。Settings メニューの Connectivity タブをクリックすると、複数のLoriot接続を作成、編集、削除、更新できます。

新しい接続を追加するには

初めて Connectivity を選択すると、接続を作成するよう求められます。Add Connection をクリックします。

次の情報を入力します。

  • Name - 作成するLoriot接続の名前
  • Base URL - Loriotプロバイダーアカウントに関連付けられたURL
  • Username - Loriotアカウントのユーザー名
  • Password - Loriotアカウントのパスワード

Save をクリックします。入力した情報が正しければ、“Connection created” というメッセージが表示されます。

別の接続を追加するには、Add Connection をクリックし、上記の手順に従います。

備考
Loriotエージェントは “gw”（ゲートウェイ情報）メッセージのみを処理するため、Gateway Information オプションは常に有効にしておいてください。

Enable gateway information option

接続を更新するには

更新する接続を選択し、編集を行って接続を保存します。

接続に関連付けられたデバイスが存在する場合は、“Can not update the LNS Connection with <name of LNS Connection> as it’s associated with <number of devices>. Click the link to download the file with the details of the associated devices: /service/<agent-context-path>/lns-connection/<lns-connection-name>/device” というエラーメッセージが表示されます。

Update connection information

接続を削除するには

削除する接続を選択し、Delete をクリックします。

接続に関連付けられたデバイスが存在する場合は、“Can not delete the LNS Connection with <name of LNS Connection> as it’s associated with <number of devices>. Click the link to download the file with the details of the associated devices: /service/<agent-context-path>/lns-connection/<lns-connection-name>/device” というエラーメッセージが表示されます。

Delete connection

Loriotデバイス登録

Things Cloud にLoriotデバイスを登録するには、デバイス管理アプリケーションで Devices > Registration に移動し、右上の Register device をクリックして、ドロップダウンから Single device registration > Loriot LoRa を選択します。

Register devices

備考
Loriot が使用可能なオプションの1つとして表示されない場合、ご利用のテナントは関連アプリケーションをサブスクライブしていません。上部の情報を参照してください。

次のウィンドウで、必要な情報を入力します。

  • Title - 登録するデバイスのタイトル。
  • Device EUI - これはデバイスの一意の識別子です。16文字（8バイト）の16進数です。デバイス本体で確認できます。
  • Application EUI - これはIEEE EUI64アドレス空間におけるグローバルなアプリケーションIDで、デバイスのアプリケーションプロバイダーを一意に識別します。16文字（8バイト）の16進数です。
  • Application key - これはデバイス固有のAES-128アプリケーションキーで、アプリケーション所有者によってデバイスに割り当てられ、暗号化を担います。アプリケーションキーは32文字（16バイト）の16進数です。
  • Connection - テナントで設定されているすべてのLoriot接続を一覧表示します。Application name オプション（以下を参照）は、選択したLoriot接続に基づいて入力されます。
  • Application name - Loriotプロバイダーでデバイスを登録する適切なアプリケーション名を選択します。
  • Device protocol - ドロップダウンリストから適切なデバイスプロトコルを選択します。デバイスプロトコルの作成方法の詳細については、デバイスプロトコルの作成 を参照してください。

Register devices

Register をクリックして、デバイス登録リクエストを送信し、デバイスを作成します。

イベントを受信することで、デバイスが接続されていることを確認できます。デバイスをクリックして Events タブを開きます。このデバイスに関連するすべてのイベントが一覧表示されます。

接続済みデバイスの表示および管理の詳細については、デバイス管理アプリケーション も参照してください。

デバイスをあるLNS接続から別のLNS接続へ移行するには、デバイスを再登録する必要があります。

  1. デバイスの LPWAN タブに移動します。
  2. Provider connection ドロップダウンをクリックします。
  3. デバイスをあるLNS接続から別のLNS接続へ移行するにはデバイスを再登録する必要があることを示すプロンプトが表示されます。Re-Register ボタンをクリックします。
  4. デバイス登録ページに移動するので、上記の手順に従い、目的のLNS接続を選択して再登録を実行できます。

Loriot管理ロール権限の割り当て

Things Cloud プラットフォームで、Loriot Network Server に設定されたユーザーに Loriot管理ロール権限を割り当てます。

管理アプリケーションで、ナビゲータの Roles をクリックし、“Loriot” の ADMIN チェックボックスを選択します。

Set loriot admin role

デバイスプロトコルの作成

LoRaデバイスのデータを処理するには、Things Cloud がデバイスのペイロード形式を理解する必要があります。ペイロードデータを Things Cloud データにマッピングするには、LoRaデバイスプロトコルを作成します。

デバイス登録 中に、このデバイスプロトコルを関連付けることができます。すると、このデバイスについて受信した16進ペイロードを持つアップリンクメッセージは、デバイスプロトコルで設定した内容にマッピングされます。

備考
デバイスプロトコルのマッピングは、メッセージタイプに基づく固定バイト位置のデコードのみをサポートします。 Number of bits フィールドで設定するデバイスペイロード部分の長さは、最大32ビット（4バイト）です。

デバイスプロトコルを作成するには、デバイス管理アプリケーションに移動し、ナビゲータの Device types メニューで Device protocols を選択します。既存のデバイスプロトコルをインポートすることも、新しいものを作成することもできます。

定義済みデバイスプロトコルのインポート

  1. Device protocols ページで、Import をクリックします。
  2. 定義済みデバイスタイプ（たとえば “LoRaWAN Demonstrator”）を選択するか、ファイルからアップロードします。
  3. Import をクリックします。

Import device protocol

または、ファイルからデバイスプロトコルを読み込んでインポートすることもできます。

新しいデバイスプロトコルの作成

Device protocols ページで、上部メニューバーの New device protocol をクリックします。次のウィンドウが開きます。

Create new LoRa protocol

デバイスプロトコルタイプとして LoRa を選択し、名前を入力して Create をクリックします。

Message types で、メッセージタイプを指定します。LoRaデバイスは、タイプごとに異なるエンコーディングを持つさまざまな種類のメッセージを送信できます。

Source ドロップダウンボックスで、メッセージタイプのエンコーディング方法を選択します。

  • FPort - メッセージのFPortパラメータを見ることでメッセージタイプを判定できる場合。
  • Payload - メッセージペイロード自体の一部を見ることでメッセージタイプを判定できる場合。

次のペイロード構造の例では、最初の1バイトがメッセージタイプのソースを示しています（ハイライト部分）。

Example payload: message type source

ユーザーインターフェイスでは、この種のメッセージタイプソース情報を次のように入力できます。Start bit フィールドでペイロード内のどこからメッセージタイプ情報が始まるかを示し、Number of bits フィールドでその情報の長さを示します。たとえば、start bit = “0”、number of bits = “8” です。

LoRa protocol payload

Add value をクリックして、値の設定を作成します。

LoRa protocol add value

表示されるウィンドウで、次の例のように該当する値を設定します。

新しい値ウィンドウ パート1 LoRa protocol add new value

新しい値ウィンドウ パート2 LoRa protocol add new value

値の設定では、メッセージタイプのペイロード内の値を Things Cloud データにマッピングします。

Message type で、デバイスのメッセージ仕様に従って Message ID を設定し、Things Cloud データにマッピングします。メッセージIDは、メッセージタイプを識別する数値です。これは、デバイスプロトコルのメインページで指定したソース（つまり Payload または FPort）に見つかったメッセージIDと照合されます。メッセージIDは10進数で入力する必要があります（16進数ではありません）。

このペイロード構造の例では、メッセージIDは “1” です。

Example payload: message type source

LoRa bits

General で、値の名前と、値リスト内で表示されるカテゴリを指定します。この値に関連付けられた名前は、指定した Display category の下に表示されます。

Value selection で、どこから値を抽出するかを定義します。これを行うには、Start bit フィールドで値情報がどこから始まるかを示し、Number of bits フィールドでその情報の長さを示します。ビット数の最大値は32ビット（4バイト）です。

この例では、“Channel 1 Type” 情報は2バイト目から始まり（つまり、start bit = “16”）、長さは1バイトです（つまり、number of bits = “8”）。

Example payload: value selection

LoRa bits

16進値は10進数に変換され、その後 “value normalisation” が適用されます。

Value normalisation で、プラットフォームに保存する前に生の値をどのように変換するかを定義し、次の適切な値を入力します。

  • Multiplier - Value selection から抽出した値に掛ける値です。小数、負数、正数を指定できます。デフォルトでは1に設定されています。
  • Offset - 加算または減算するオフセット値です。小数、負数、正数を指定できます。デフォルトでは0に設定されています。
  • Unit (optional) - 値と一緒に保存する単位を定義できます（たとえば温度単位 “C” は摂氏を表します）。

ペイロードのデコード方法の詳細については、デバイスのドキュメントを参照してください。

備考
ペイロードをデコードするための “Little endian” サポートが追加されています。

必要に応じて、Options で次のいずれかのオプションを選択します。

  • Signed - 値が符号付き数値の場合。
  • Packed decimal - 値がBCDエンコードされている場合。

Functionalities で、このデバイスプロトコルの動作方法を指定します。

  • Send measurement - デコードされた値でメジャーメントを作成します。
  • Raise alarm - 値がゼロでない場合にアラームを作成します。
  • Send event - デコードされた値でイベントを作成します。
  • Update managed object - デコードされた値でマネージドオブジェクト内のフラグメントを更新します。

また、メジャーメント、イベント、またはマネージドオブジェクトフラグメント内に複数の値を持つネスト構造を作成することもできます。メジャーメントの場合、同じタイプのすべてのプロパティはマージされてネスト構造が作成されます。イベントまたはマネージドオブジェクトの場合、同じフラグメントを持つすべてのプロパティがマージされてネスト構造が作成されます。下記の “Position” デバイスプロトコルのネスト構造の例 も参照してください。

OK をクリックして、値をデバイスプロトコルに追加します。

Value configurations of created device protocol

Save をクリックすると、定義した値を持つデバイスプロトコルが作成されます。

単一プロパティの例

次の画像は、バッテリーレベルが変化したときにメジャーメントを送信するメッセージの例を示しています。

新しい値ウィンドウ パート1 Battery level changes example

新しい値ウィンドウ パート2

Battery level changes example

ネスト構造の例

次の画像は、GPSデバイスの現在位置を報告するデバイスプロトコルのネスト構造の例を示しています。表示カテゴリ名は “Position” で、経度と緯度の値を含みます。

メッセージIDはすべての値で同じである必要があります。残りのパラメータは上記の手順に従って入力してください。Managed object fragment フィールドに “c8y_Position” を入力し、経度と緯度それぞれについて新しい値を作成します。

新しい値ウィンドウ、経度

Value creation: Longitude-nested

新しい値ウィンドウ、緯度

Value creation: Latitude-nested

結果は次のようになります。

Value configuration in detail: nested structure

カスタムデコードの使用

Loriotエージェントは、カスタムマイクロサービスを組み込むことでデコード機能もサポートします。詳細については、LPWANカスタムプロトコル を参照してください。

Loriot LoRaデバイスプロトコルの割り当て

Loriot LoRaデバイスが Things Cloud プラットフォームで使用可能になったら、LPWAN タブからデバイスプロトコルを割り当てる必要があります。

Assign device protocol

ドロップダウンリストから該当するプロトコルを選択し、Apply をクリックします。正常に適用されると、“Device protocol set” というメッセージが表示されます。

オペレーションの送信

デバイスが16進コマンドの送信をサポートしている場合、シェルオペレーションを使用して送信できます。これらのコマンドはシリアルモニターコマンドではないことに注意してください。

オペレーションを送信するには、デバイス管理アプリケーションの All devices でオペレーション送信先のデバイスに移動し、Shell タブに切り替えます。

次のスクリーンショットでは、デバイスプロトコルの定義済みコマンドとその形式の例をいくつか確認できます。

Predefined shell commands

Command フィールドにシェルコマンドを入力するか、定義済みコマンドを表示/編集します。

ポートを指定せずにコマンドを入力した場合、デバイスのデフォルトターゲットポート（つまりポート1）に送信されます。コマンドを入力し、ポートを定義した場合（形式 “command:port”）、デフォルトポートではなく指定したターゲットポートに送信されます。

Port configuration

Execute をクリックします。オペレーションがデバイスに送信されます。タイミングはLoriotプラットフォームによって異なります。

オペレーションが正常にLoriotプラットフォームへ送信されると、オペレーションのステータスは SUCCESSFUL に設定されます。コマンドの検証で問題が発生した場合、またはオペレーションがLoriotプラットフォームに送信された後に問題が発生した場合、オペレーションのステータスは FAILED に設定されます。

アップリンクメッセージを受信すると、Things Cloud プラットフォームは次のメジャーメントとイベントを作成し、対応するデバイスマネージドオブジェクトを更新します。

  • Unprocessed data - 未処理データを含む c8y_LoriotUplinkRequest タイプのイベントが作成されます。
  • Position - デバイスマネージドオブジェクトの c8y_Position フラグメントが更新され、デバイスの緯度、経度、高度、精度情報が取り込まれます。また、位置情報を含むイベントも作成されます。
  • Spreading factor - デバイスマネージドオブジェクトの c8y_SpreadingFactor フラグメントが更新され、デバイスのスプレッディングファクターが取り込まれます。
  • Signal strength - デバイス信号強度のRSSI値およびSNR値を含むメジャーメントが作成されます。

トラブルシューティング

デバイス登録

Loriot Network Server アカウントでLoriotエージェントのエンドポイントを設定した後も、Things Cloud にLoRaデバイスが登録されない

Loriotエージェントは、ユーザーが適切な権限を持っているかを検証します。Loriot Network Server に設定されているユーザーに Loriot管理ロールが割り当てられているか確認してください。

Loriotエージェントは “gw” メッセージのみを処理するため、Loriot Network Server で Gateway Information が有効になっていることを確認してください。

デバイスタイプエラー警告

デバイスにデバイスプロトコルが割り当てられていない場合、ログに “Device type error” という警告メッセージが表示されます。 デバイスプロトコルを割り当てるには、Loriot LoRaデバイスプロトコルの割り当て のセクションを参照してください。

Actility LoRa

はじめに

Things Cloud は、Actility の ThingPark Wireless、Enterprise、または Community エディションを介して LoRa デバイスと連携できます。以下が可能です。

  • Things Cloud のデバイス管理アプリケーションを使用して、LoRa デバイスを簡単にプロビジョニングおよびデプロビジョニングできます。ThingPark のユーザーインターフェイスでの操作は不要です。
  • web ベースのユーザーインターフェイスを使用して、アップストリームのペイロードパケットをデコードできます。
  • Things Cloud のイベントを通じて、生データのデバッグおよび後処理を行えます。
  • Things Cloud のオペレーションを使用して、ダウンストリームデータをデバイスに送信できます。
  • LoRa デバイスで、既存の Things Cloud 機能を利用できます。たとえば、接続監視、デバイス管理、ダッシュボードによるデータ可視化、リアルタイム分析などです。

以下の図は、Things Cloud Actility LoRa 統合の概要を示しています。

Things Cloud Actility LoRa integration

備考
ご利用のサブスクリプションにこの機能が含まれている必要があります。このドキュメントで説明されている機能が表示されない場合は、製品サポート にお問い合わせください。

複数の ThingPark アカウント接続の設定

Things Cloud で LoRa デバイスを使用する前に、管理アプリケーションで ThingPark アカウントの詳細を設定する必要があります。

新しい接続を追加するには

設定 メニューの 接続 タブをクリックして、複数の Actility 接続を作成、編集、削除、または更新します。

初めて 接続 を選択すると、接続の作成を求められます。接続を追加 をクリックします。

以下の情報を入力します。

設定名 注記
名前 作成する Actility 接続の名前。
説明 作成する Actility 接続の説明。
Actility ThingPark URL 使用する対応する Actility DX API のベース URL。
プロファイル ID ThingPark アカウントのプロファイル識別子。
アプリケーションサーバー ID ThingPark プラットフォームとエージェント間の TLS セキュリティ用アプリケーションサーバー ID。任意項目です。セキュリティを無効にするには空のままにします。有効にすると、エージェントはすべてのアップリンクおよびダウンリンクメッセージに対してトークンを生成します。
アプリケーションサーバーキー アップリンクおよびダウンリンク通信のための、ThingPark プラットフォームとエージェント間の TLS セキュリティ用アプリケーションサーバー秘密鍵。値は 16 バイトの 16 進数である必要があります。任意項目です。セキュリティを無効にするには空のままにします。有効にすると、エージェントはすべてのアップリンクおよびダウンリンクメッセージに対してトークンを生成します。
Admin API version ThingPark 管理 API が使用するバージョン。デフォルトでは “latest” に設定されています。
Core API version ThingPark コア API が使用するバージョン。デフォルトでは “latest” に設定されています。
ユーザー名 ThingPark アカウントのユーザー名。
パスワード ThingPark アカウントのパスワード。
接続タイプ 使用する ThingPark アカウントのタイプ（Enterprise または Wireless）。
環境固有の情報

以下の設定は ThingPark 環境によって異なります。

ThingPark community:

  • URL: https://community.thingpark.io/thingpark/dx/
  • プロファイル ID: community-api
  • アプリケーションサーバー ID とキー: 空のままにします（内部的に HTTPS を使用）
  • 接続タイプ: Enterprise を選択

その他の環境（Enterprise/Wireless）:

  • URL: ThingPark サポートにお問い合わせください
  • Profile ID: ThingPark サポートにお問い合わせください
  • Application server ID and key: ThingPark のアプリケーションサーバープロファイルで確認するか、ThingPark サポートにお問い合わせください
  • Connection type: お使いの環境に応じて選択してください（Enterprise または Wireless）
重要
同じ ThingPark ログイン（ユーザー名とパスワード）を他のテナントに使用しないでください。 プロファイル ID、ユーザー名、パスワードは、ThingPark プラットフォームにさらにリクエストを送信するためのアクセストークンを取得するために使用されます。特定の接続のアカウント認証情報を置き換えることで、アクセストークンを更新できます。

Setting provider credentials

保存 をクリックします。正しい情報を入力すると、“Connection created” というメッセージが表示されます。

別の接続を追加するには、接続を追加 をクリックし、上記の手順に従います。

接続を更新するには

更新する接続を選択し、編集してから接続を保存します。

接続に関連付けられたデバイスがある場合は、“Can not update the LNS Connection with <name of LNS Connection> as it’s associated with <number of devices>. Click the link to download the file with the details of the associated devices: /service/<agent-context-path>/lns-connection/<lns-connection-name>/device” というエラーメッセージが表示されます。

Update connection information

接続を削除するには

削除する接続を選択し、削除 をクリックします。

接続に関連付けられたデバイスがある場合は、“Can not delete the LNS Connection with <name of LNS Connection> as it’s associated with <number of devices>. Click the link to download the file with the details of the associated devices: /service/<agent-context-path>/lns-connection/<lns-connection-name>/device” というエラーメッセージが表示されます。

Delete connection

デバイスプロトコルの作成

LoRa デバイスからのデータを処理するために、Things Cloud はデバイスのペイロード形式を理解する必要があります。ペイロードデータを Things Cloud データにマッピングするには、LoRa デバイスプロトコルを作成します。

デバイス登録の間に、このデバイスプロトコルを関連付けることができます。すると、このデバイスに対して受信した 16 進ペイロードを持つアップリンクコールバックは、デバイスプロトコルで設定した内容にマッピングされます。

デバイス登録時に割り当てられたデバイスプロトコルは、デバイス詳細ページの LPWAN タブから変更できます。

Actility LPWAN Tab

備考
デバイスプロトコルのマッピングでは、メッセージタイプに基づく固定バイト位置のデコードのみをサポートしています。 ビット数 フィールドで設定するデバイスペイロード部分の長さは、最大 32 ビット（4 バイト）です。

デバイスプロトコルを作成するには、デバイス管理アプリケーションに移動し、ナビゲータの デバイスタイプ メニューで デバイスプロトコル を選択します。既存のデバイスプロトコルをインポートすることも、新しいものを作成することも、LPWAN カスタム codec マイクロサービスによって作成されたデバイスプロトコルを使用することもできます。

定義済みデバイスプロトコルのインポート

デバイスプロトコル ページで、インポート をクリックします。

定義済みのデバイスタイプ（たとえば “LoRaWAN Demonstrator”）を選択するか、ファイルからアップロードします。インポート をクリックします。

Import device protocol

または、ファイルからデバイスプロトコルを読み込んでインポートすることもできます。

新しいデバイスプロトコルの作成

デバイスプロトコル ページで、上部のメニューバーにある 新しいデバイスプロトコル をクリックします。以下のウィンドウが開きます。

Create new LoRa protocol

デバイスプロトコルタイプとして LoRa を選択し、名前を指定して 作成 をクリックします。

メッセージタイプ でメッセージタイプを指定します。LoRa デバイスは、タイプごとに異なるエンコーディングで異なるタイプのメッセージを送信できます。

ソース ドロップダウンボックスで、メッセージタイプのエンコード方法を選択します。

  • FPort: メッセージタイプを、メッセージの FPort パラメーターを見ることで判別できる場合。
  • ペイロード: メッセージタイプを、メッセージペイロード自体の一部を見ることで判別できる場合。

次のペイロード構造の例では、最初のバイトがメッセージタイプのソースを示しています（強調表示部分）。

Example payload: message type source

ユーザーインターフェイスでは、この種のメッセージタイプソース情報を次のように入力できます。開始ビット フィールドでペイロード内のメッセージタイプ情報の開始位置を指定し、ビット数 フィールドでその情報の長さを指定します。たとえば、開始ビット = “0”、ビット数 = “8” です。

LoRa protocol payload

値を追加 をクリックして、値設定を作成します。

LoRa protocol add value

表示されるウィンドウで、次の例のように関連する値を設定します。

新しい値ウィンドウ パート 1 LoRa protocol add new value

新しい値ウィンドウ パート 2 LoRa protocol add new value

値設定では、メッセージタイプのペイロード内の値を Things Cloud データにマッピングします。

メッセージタイプ で、デバイスメッセージ仕様に従って メッセージ ID を設定し、Things Cloud データにマッピングします。メッセージ ID は、メッセージタイプを識別する数値です。これは、デバイスプロトコルのメインページで指定されたソース（つまり、ペイロードまたは FPort）内で見つかったメッセージ ID と照合されます。メッセージ ID は 10 進数で入力する必要があります（16 進数ではありません）。

このペイロード構造の例では、メッセージ ID は “1” です。

Example payload: message type source

LoRa bits

一般 で、値の名前と、その値一覧に表示されるカテゴリを指定します。この値に関連付けられた名前は、指定された 表示カテゴリ の下に表示されます。

値の選択 で、値をどこから抽出するかを定義します。そのために、開始ビット フィールドで値情報の開始位置を指定し、ビット数 フィールドでその情報の長さを指定します。ビット数の最大値は 32 ビット（4 バイト）です。

この例では、“Channel 1 Type” 情報はバイト 2 から始まり（つまり、開始ビット = “16”）、長さは 1 バイトです（つまり、ビット数 = “8”）。

Example payload: value selection

LoRa bits

16 進値は 10 進数に変換され、その後 “値の正規化” が適用されます。

値の正規化 で、生の値をプラットフォームに保存する前にどのように変換するかを定義し、以下に適切な値を入力します。

  • 乗数: この値は、値の選択 から抽出された値に乗算されます。小数、負数、正数を指定できます。デフォルトは 1 です。
  • オフセット: この値は、加算または減算されるオフセットを定義します。小数、負数、正数を指定できます。デフォルトは 0 です。
  • 単位（任意）: 値とともに保存される単位を定義できます（たとえば温度単位 “C” は摂氏を表します）。

ペイロードのデコード方法の詳細については、デバイスのドキュメントを参照してください。

備考
ペイロードをデコードするための “Little endian” サポートが追加されました。

必要に応じて、オプション で次のいずれかを選択します。

  • 符号付き - 値が符号付き数値の場合。
  • Packed decimal - 値が BCD エンコードされている場合。

機能 で、このデバイスプロトコルの動作方法を指定します。

  • メジャーメントを送信: デコードされた値でメジャーメントを作成します。
  • アラームを発生: 値が 0 でない場合にアラームを作成します。
  • イベントを送信: デコードされた値でイベントを作成します。
  • マネージドオブジェクトを更新: デコードされた値でマネージドオブジェクト内のフラグメントを更新します。

また、メジャーメント、イベント、またはマネージドオブジェクトフラグメント内に複数の値を含むネスト構造にすることもできます。メジャーメントの場合、同じタイプのすべてのプロパティはマージされてネスト構造が作成されます。イベントまたはマネージドオブジェクトの場合、同じフラグメントを持つすべてのプロパティがマージされてネスト構造が作成されます。以下の “Position” デバイスプロトコルのネスト構造の例も参照してください。

OK をクリックして、値をデバイスプロトコルに追加します。

Value configurations of created device protocol

保存 をクリックすると、定義した値でデバイスプロトコルが作成されます。

単一プロパティの例

次の画像は、バッテリーレベルが変化したときにメジャーメントを送信するメッセージの例を示しています。

新しい値ウィンドウ パート 1 Battery level changes example

新しい値ウィンドウ パート 2

Battery level changes example

ネスト構造の例

次の画像は、GPS デバイスの現在位置を報告するデバイスプロトコルのネスト構造の例を示しています。表示カテゴリの名前は “Position” で、経度と緯度の値を含みます。

メッセージ ID はすべての値で同じである必要があります。その他のパラメーターは、上記の説明に従って入力してください。マネージドオブジェクトフラグメント フィールドに “c8y_Position” を入力し、経度と緯度のそれぞれについて新しい値を作成します。

新しい値ウィンドウ、経度

Value creation: Longitude-nested

新しい値ウィンドウ、緯度

Value creation: Latitude-nested

結果は次のようになります。

Value configuration in detail: nested structure

カスタムデコード/エンコードの使用

Actility エージェントは、カスタムマイクロサービスをプラグインすることによるデコード/エンコード機能もサポートしています。詳細については、LPWAN カスタムプロトコル を参照してください。

Actility LoRa デバイスの登録

Things Cloud で LoRa デバイスを登録するには、デバイス管理アプリケーションで デバイス > 登録 に移動します。右上の デバイスを登録 をクリックし、ドロップダウンから 単一デバイス登録 > Actility LoRa を選択します。

Register devices

Things Cloud は、LoRa ネットワークに接続する推奨かつ最も安全な方法である Over-the-Air Activation（OTAA）による LoRa デバイスのプロビジョニングを完全にサポートしています。 Activation by Personalization（ABP）を使用する必要がある場合は、ABP を使用した LoRa デバイス登録 を参照してください。

次のウィンドウで必要な情報を入力します。

  • 接続: テナント内で設定されているすべての Actility 接続を一覧表示します。以下のデバイスプロファイルおよび接続プランのオプションは、選択した Actility 接続に基づいて設定されます。

  • デバイスプロファイル: 登録するデバイスに一致する Actility Thingpark デバイスプロファイルをドロップダウンリストから選択します。

    Actility ThingPark デバイスプロファイルでは、multi-RF プロファイルの管理、異なる LoRaWAN クラス（A、B、または C）との互換性の確保、およびサードパーティアプリケーションとの容易な統合のためのアプリケーションペイロードデコードが可能です。

  • デバイスプロトコル: ドロップダウンリストから適切なデバイスプロトコルを選択します。デバイスプロトコルの作成方法の詳細については、デバイスプロトコルの作成 を参照してください。

  • デバイス EUI: これはデバイス固有の識別子です。16 文字（8 バイト）の 16 進数です。デバイス本体に記載されています。

  • アプリケーション EUI: これは IEEE EUI64 アドレス空間におけるグローバルなアプリケーション ID であり、デバイスのアプリケーションプロバイダーを一意に識別します。16 文字（8 バイト）の 16 進数です。1 つのテナントに対して設定できるアプリケーション EUI は 1 つだけですが、複数のテナントで同じアプリケーション EUI を使用できます。

  • アプリケーションキー: これはデバイス固有の AES-128 アプリケーションキーで、アプリケーション所有者によってデバイスに割り当てられ、JOIN 通信を暗号化する役割を担います。アプリケーションキーは 32 文字（16 バイト）の 16 進数です。 このキーはデバイス本体に記載されています。

  • 接続プラン: ドロップダウンリストから適切な接続プランを選択します。

Register devices

登録 をクリックして、デバイス登録リクエストを送信し、デバイスを作成します。

デバイスが実際に接続されていることは、イベントが実際に受信されていることを確認することで検証できます。デバイスをクリックして イベント タブを開くことで確認できます。このデバイスに関連するすべてのイベントがここに一覧表示されます。

プロビジョニングステータスは、デバイスの 情報 タブ内の デバイスデータ に表示されます。

Device data

接続済みデバイスの表示および管理の詳細については、デバイス管理アプリケーション も参照してください。

デバイスをある LNS 接続から別の接続に移行するには、デバイスを再登録する必要があります。

  1. デバイスの LPWAN タブに移動します。
  2. プロバイダー接続 ドロップダウンをクリックします。 デバイスをある LNS 接続から別の接続に移行するには、デバイスを再登録する必要があることを示すプロンプトが表示されます。
  3. 再登録 をクリックします。

デバイス登録ページに移動し、上記の手順に従って目的の LNS 接続を選択し、再登録を実行できます。

LoRa デバイス登録プロセス

デバイスは、上記のワークフローに基づいて作成されます。

最初に、デバイスがすでに存在するかどうかを確認します。ThingPark アカウントに同じデバイス EUI を持つデバイスが存在しない場合、最初に ThingPark プラットフォーム上でデバイスがプロビジョニングされ、その後 ThingPark プラットフォーム上のデバイスへのリンク付きで Things Cloud プラットフォーム上に作成されます。デバイスが ThingPark アカウントに存在する場合は、アプリケーション EUI（OTAA アクティベーションの場合）およびデバイスプロファイルに基づいてそれらのデバイスを比較する検証が適用されます。検証に成功した場合、デバイスは ThingPark プラットフォーム上のデバイスへのリンク付きで Things Cloud 上にのみ作成されます。検証に失敗した場合は失敗メッセージが表示され、デバイスは Things Cloud 上に作成されません。

Activation by Personalization（ABP）を使用した LoRa デバイス登録

パーソナライゼーションによるデバイス有効化は推奨されず、Things Cloud の LoRa デバイス登録では完全にはサポートされていません。

ただし、このアクティベーションタイプで Things Cloud にデバイスを作成し、LoRa 機能（デバイスへのオペレーション送信、デバイスのデプロビジョニング、カスタムデバイスプロトコル設定による LoRa デバイスプロトコルタイプの設定など）を使用したい場合は、まず ThingPark プラットフォームでデバイスをプロビジョニングする必要があります。さらに、http://actility-server.je1.thingscloud.ntt.com を “Third Party AS (HTTP)” とする宛先で、Things Cloud 用の “AS Routing Profile” を作成し、デバイスに手動で割り当てる必要があります。その後、LoRa デバイス登録を使用してこのデバイスを登録できます。この場合、LoRa デバイス登録の アプリケーションキー フィールドは無効です。

一般的なデバイス登録で作成された LoRa デバイスの制限

LoRa デバイスの一般的なデバイス登録は、現在はサポートされていません。

一般的なデバイス登録プロセスを使用して Things Cloud で作成された既存の LoRa デバイスには制限があります。これらのデバイスでは、デバイスへのオペレーション送信、デバイスのデプロビジョニング、およびカスタムデバイスプロトコル設定による LoRa デバイスプロトコルタイプの設定はできません。

LoRa 機能を完全に使用するには、これらのデバイスを削除し、LoRa デバイス登録を使用して再登録することを推奨します。

LoRa デバイスのデプロビジョニング

ThingPark プラットフォームで LoRa デバイスをデプロビジョニングできます。これは、デバイスがネットワークに接続されなくなることを意味します。履歴データは引き続き Things Cloud で利用できますが、ThingPark ではデバイスが削除されます。

デバイスをデプロビジョニングするには、デバイス管理アプリケーションの すべてのデバイス で対象デバイスに移動します。右上の その他 をクリックし、デバイスをデプロビジョニング を選択します。

Deprovision device

デプロビジョニングを確認すると、デバイスは ThingPark でデプロビジョニングされます。

デバイスを再度プロビジョニングするには、デバイスを削除して、LoRa デバイス登録を使用して再登録する必要があります。

オペレーションの送信

LoRa デバイスが 16 進コマンドの受信をサポートしている場合、シェルオペレーションを使用して送信できます。これらのコマンドはシリアルモニターコマンドではない点に注意してください。

オペレーションを送信するには、デバイス管理アプリケーションの すべてのデバイス でオペレーションを送信したいデバイスに移動し、シェル タブに切り替えます。

以下のスクリーンショットでは、デバイスプロトコルの定義済みコマンドとその形式の例を確認できます。

Predefined shell commands

コマンド フィールドで、シェルコマンドを入力するか、定義済みコマンドを表示または編集します。

ポートを指定せずにコマンドを入力した場合、そのコマンドはデバイスのデフォルトターゲットポート（つまりポート 1）に送信されます。コマンドとポートを指定した場合（形式 “command:port”）、デフォルトポートではなく、指定されたターゲットポートに送信されます。

Port configuration

実行 をクリックします。オペレーションがデバイスに送信されます。タイミングは Actility ThingPark に依存します。

オペレーションのステータスは、ThingPark プラットフォームへの送信に成功すると SUCCESSFUL に設定されます。コマンドの検証で問題が発生した場合、または Thingpark プラットフォームにオペレーションが送信された後に問題が発生した場合、オペレーションのステータスは FAILED に設定されます。

ThingPark API 可用性の監視

ThingPark API は監視されており、到達不能になった場合、この機能を使用しているすべてのサブスクライブ済みテナントに通知するためにアラームが作成されます。ThingPark API に再び到達可能になると、アラームは直ちにクリアされます。

ThingPark API monitoring alarm

アップリンクメッセージを受信すると、Things Cloud プラットフォームは以下のメジャーメントとイベントを作成し、対応するデバイスのマネージドオブジェクトを更新します。

  • 未処理データ - 未処理データを含む c8y_ActilityUplinkRequest タイプのイベント（このタイプは設定ファイルで設定された event.uplink.type に基づきます）が作成されます。
  • 位置 - デバイスの緯度、経度、高度、精度情報を取得するために、デバイスのマネージドオブジェクトの c8y_Position フラグメントが更新されます。また、位置情報を含むイベントも作成されます。
  • スプレッディングファクター - デバイスのスプレッディングファクターを取得するために、デバイスのマネージドオブジェクトの c8y_SpreadingFactor フラグメントが更新されます。
  • 信号強度 - デバイス信号強度の RSSI および SNR 値を持つメジャーメントが作成されます。

トラブルシューティング

デバイス登録

デバイスへのアクセスが拒否されました

この警告メッセージは、デバイス登録に使用したものと同じデバイス EUI を持つプロビジョニング済みデバイスが ThingPark にすでに存在し、アプリケーション EUI（OTAA アクティベーションの場合）およびデバイスプロファイルに基づいてそれらのデバイスを比較する検証が失敗した場合に表示されます。

これを解決するには、接続 アプリケーションから正しいアプリケーション EUI とデバイスプロファイルを指定して、再試行してください。

LoRa プロバイダー設定が見つかりません

この警告メッセージは、ThingPark アカウント用の認証情報が設定されていない場合に表示されます。これを解決するには、設定 をクリックして、接続が設定されている管理アプリケーションに移動します。

Device registration failure without credentials

これを解決するには、複数の ThingPark アカウント接続の設定 を参照してください。

プロバイダーからのデバイスプロファイル取得に失敗しました

この警告メッセージは、テナントの Thingpark へのアクセストークンが無効になった場合に表示されます。同じ ThingPark 認証情報が別のテナントで使用されると、トークンが無効になることがあります。

この問題は、Actility ThingPark 認証情報を再設定してアクセストークンを更新することで解決できます。認証情報の再設定については、複数の ThingPark アカウント接続の設定 を参照してください。

デバイスプロトコルが設定されていません

この警告メッセージは、デバイス登録に使用する LoRa デバイスプロトコルが存在しない場合に表示されます。これを解決するには、デバイスプロトコル をクリックして、プロトコルが設定されている デバイスプロトコル ページに移動します。

No device protocol given for LoRa

これを解決するには、デバイスデータベース で少なくとも 1 つのデバイスプロトコルを設定してください。

空きスロットのある接続プランがありません

この警告メッセージは、Actility ThingPark の接続プランがデバイス数の上限に達した場合に表示されます。

これを解決するには、接続プランのデバイスクォータ上限について ThingPark に問い合わせるか、ThingPark から未使用のデバイスを削除して、Things Cloud でのデバイス登録を再試行してください。

接続

LoRa プラットフォームへの認可に失敗しました

この警告メッセージは、指定されたプロファイル ID、ユーザー名、またはパスワードが無効な場合に表示されます。

これを解決するには、正しい認証情報を入力して再試行してください。

Actility プラットフォームへの認証に失敗しました。ベース URL が正しいか確認してください

これを解決するには、正しい URL を入力して再試行してください。

Actility プラットフォームへの認証がステータスコード ‘400’ で失敗しました。プロファイル ID が正しいか確認してください

これを解決するには、正しいプロファイル ID を入力して再試行してください。

Actility プラットフォームへの認証がステータスコード ‘401’ で失敗しました。認証情報が正しいか確認してください

これを解決するには、正しいユーザー名とパスワードを入力して再試行してください。

Sigfox

はじめに

Things Cloud は、Sigfox Cloud を介して Sigfox デバイスと連携できます。以下のことが可能です。

  • Things Cloud のデバイス管理アプリケーションを使用して、Sigfox デバイスを簡単にプロビジョニングする。
  • web ベースのユーザーインターフェイスを使用して、アップストリームのペイロードパケットをデコードする。
  • Things Cloud のイベントを通じて、生のデバイスデータをデバッグおよび後処理する。
  • Things Cloud のオペレーションを使用して、デバイスにダウンストリームデータを送信する。
  • Sigfox デバイスで既存の Things Cloud 機能を利用する。たとえば、接続監視、デバイス管理、ダッシュボードによるデータ可視化、リアルタイム分析など。

次の図は、Things Cloud の Sigfox 統合の概要を簡単に示しています。

Things Cloud Sigfox integration

必要条件
Sigfox エージェントを使用できるようにするには、テナントがアプリケーション sigfox-agent をサブスクライブしている必要があります。問題がある場合は、製品サポート にお問い合わせください。

接続設定の管理

デバイスを登録する前に、管理アプリケーションの 接続 ページで Sigfox Cloud の認証情報を設定する必要があります。これらの Sigfox Cloud 認証情報は Sigfox で設定する必要があります。

Things Cloud への API アクセスを作成する前に、Sigfox Cloud 内で Things Cloud グループに追加され、以下のプロファイルを持つ「Associated user」が必要です。

  • Customer [R]
  • Device Manager [W]
重要
以下で説明するプロファイルがない場合、必要な Sigfox API アクセスを設定できません。

ステップ 1

すでに associated user がある場合は、そのユーザーが以下に記載されたプロファイルを持っていることを確認し、ステップ 2 に進んでください。

グループ名に制約はありません。以降の手順では、サンプルのグループ名として「Cumulocity」を使用します。

まず、Sigfox Cloud アカウントに入り、新しいユーザーを作成します。ユーザーをグループに追加し、「Customer [R]」および「Device Manager [W]」プロファイルを選択します。

New user

ステップ 2

適切なグループとプロファイルを持つ「Associated user」を作成したら、グループ ページに移動します。API access タブで新しいエントリを作成し、次のプロファイルを追加します。

  • Customer [R]
  • Device Manager [W]

API access page

ステップ 3

API access エントリが作成されたら、管理アプリケーションの 接続 ページから Sigfox Cloud アカウントを Things Cloud に接続できます。接続 ページに移動し、Sigfox provider settings タブに切り替えます。

接続 タブでは、複数の Sigfox 接続の作成、更新、削除を行えます。

接続を作成するには、次の情報を指定する必要があります。

  • 名前: 作成する Sigfox 接続の名前。
  • 説明: 作成する Sigfox 接続の説明。
  • ログイン: ログイントークンは Sigfox Cloud の API access エントリ内にあります。
  • パスワード: パスワードトークンは Sigfox Cloud の API access エントリ内の Password の横にあります。
  • 親グループ ID: この ID は、Sigfox アカウントにログインし、「Things Cloud」グループを選択したときに URL に表示されます。例: https://backend.sigfox.com/group/9823ruj29j9d2j9828hd8/info。
  • ベース URL: Sigfox Cloud アカウントを指す URL。
備考
以下のスクリーンショット内のグループ名はあくまで例です。必ずしも「Things Cloud」である必要はありません。

Sigfox group ID

Sigfox connectivity update

保存 をクリックします。正しい情報を入力している場合は、「Credentials successfully saved」というメッセージが表示されます。

別の接続を追加するには、接続を追加 をクリックし、上記の手順に従ってください。

接続を更新するには

更新する接続を選択し、編集を行って接続を保存します。

接続に関連付けられたデバイスがある場合は、「Can not update the LNS Connection with <name of LNS Connection> as it’s associated with <number of devices>. Click the link to download the file with the details of the associated devices: /service/<agent-context-path>/lns-connection/<lns-connection-name>/device」というエラーメッセージが表示されます。

Update connection information

接続を削除するには

削除する接続を選択し、削除 をクリックします。

接続に関連付けられたデバイスがある場合は、「Can not delete the LNS Connection with <name of LNS Connection> as it’s associated with <number of devices>. Click the link to download the file with the details of the associated devices: /service/<agent-context-path>/lns-connection/<lns-connection-name>/device」というエラーメッセージが表示されます。

Delete connection information

Sigfox プラットフォームへの認証に失敗しました

Sigfox プラットフォームへの認証に失敗しました。親グループ ID および/または認証情報が正しいか確認してください。

これを解決するには、正しいベース URL、または親グループ ID、またはユーザー名、またはパスワードを指定して再試行してください。

デバイスプロトコルの作成

Sigfox デバイスからのデータを処理するには、Things Cloud がデバイスのペイロード形式を理解する必要があります。ペイロードデータを Things Cloud データにマッピングするには、Sigfox デバイスプロトコルを作成します。

デバイス登録の際に、このデバイスプロトコルを関連付けることができます。すると、このデバイスに対して受信した 16 進数ペイロードを持つ uplink コールバックが、デバイスプロトコルで設定した内容にマッピングされます。

Sigfox デバイス登録時に割り当てられたデバイスプロトコルは、デバイス詳細ページの LPWAN タブから変更できます。

Sigfox LPWAN Tab

備考
デバイスプロトコルマッピングは、メッセージタイプに基づく固定バイト位置のデコードのみをサポートします。 ビット数 フィールドで設定するデバイスペイロード部分の長さは、最大 32 ビット（4 バイト）です。

デバイスプロトコルを作成するには、デバイス管理アプリケーションのナビゲータにある デバイスタイプ メニューで デバイスプロトコル を選択します。既存のデバイスプロトコルをインポートするか、新規作成できます。

デバイスプロトコルのインポート

デバイスプロトコル ページで、インポート をクリックします。

目的の定義済みデバイスタイプを選択するか、ファイルからアップロードします。準備ができたら、再度 インポート をクリックします。

新しいデバイスプロトコルの作成

デバイスプロトコル ページで、新しいデバイスプロトコル をクリックし、オプション一覧から Sigfox を選択します。

New Sigfox protocol

デバイスプロトコルの名前と、必要に応じて説明を入力し、作成 をクリックします。

メッセージタイプ で、メッセージタイプを指定します。Sigfox デバイスは、タイプごとに異なるエンコーディングで異なる種類のメッセージを送信できます。デバイスによっては、メッセージの FPort パラメータを確認することでタイプを判別できる場合（Source: FPort）と、メッセージペイロード自体の一部を見ることで判別できる場合（Source: Payload）があります。

ソース フィールドで、メッセージタイプのエンコード方法を選択します。

  • ペイロード: メッセージペイロード自体の一部を見ることでメッセージタイプを判別できる場合

次のサンプルペイロード構造では、最初のバイトがメッセージタイプソースを示しています（ハイライト表示部分）。

Example payload: message type source

ユーザーインターフェイスでは、この種のメッセージタイプソース情報を次のように入力できます。開始ビット フィールドで、ペイロード内のどこからメッセージタイプ情報が始まるかを示します。ビット数 フィールドで、この情報の長さを示します。たとえば、開始ビット = “0”、ビット数 = “8” です。

Sigfox protocol

値の設定

値 セクションで、値を追加 をクリックして値設定を作成します。

次のウィンドウで、この例のように関連する値を設定します。

新しい値ウィンドウ パート 1 Sigfox protocol add new value

新しい値ウィンドウ パート 2 Sigfox protocol add new value

値設定では、メッセージタイプのペイロード内の値を Things Cloud データにマッピングします。

メッセージタイプ で、デバイスのメッセージ仕様に従って メッセージ ID を設定します。メッセージ ID は、メッセージタイプを識別する数値です。これは、デバイスプロトコルのメインページで指定したソース（つまり、Payload または FPort）で見つかったメッセージ ID と照合されます。メッセージ ID は 10 進数で入力する必要があります（16 進数ではありません）。

このサンプルペイロード構造では、メッセージ ID は “1” です。

Example payload: message type source

Sigfox bits

一般 で、値の名前と、値リストで表示されるカテゴリを指定します。

値の選択 で、値をどこから抽出するかを指定します。開始ビット フィールドで値情報の開始位置を示し、ビット数 フィールドで情報の長さを示します。ビット数の最大値は 32 ビット（4 バイト）です。

この例では、「Channel 1 Type」情報はバイト 2 から始まり（つまり、開始ビット = “16”）、長さは 1 バイトです（つまり、ビット数 = “8”）。

Example payload: value selection

Sigfox bits

16 進数の値は 10 進数に変換され、その後「値の正規化」が適用されます。

値の正規化 で、プラットフォームに保存する前に生の値をどのように変換するかを指定し、次の項目に適切な値を入力します。

  • 乗数: この値は、値の選択 から抽出した値に乗算されます。10 進数、負数、正数を指定できます。デフォルトでは 1 に設定されています。
  • オフセット: この値は、加算または減算されるオフセットを定義します。10 進数、負数、正数を指定できます。デフォルトでは 0 に設定されています。
  • 単位（任意）: 値とともに保存される単位を定義できます（たとえば温度単位「C」は摂氏を表します）。

ペイロードのデコード方法の詳細については、デバイスのドキュメントを参照してください。

必要に応じて、オプション で次のいずれかを選択します。

  • Signed - 値が符号付き数値の場合。
  • Packed decimal - 値が BCD エンコードされている場合。

機能 で、このデバイスプロトコルの動作方法を指定します。

  • メジャーメントを送信: デコードされた値でメジャーメントを作成します。
  • アラームを発生: 値がゼロでない場合にアラームを作成します。
  • イベントを送信: デコードされた値でイベントを作成します。
  • マネージドオブジェクトを更新: デコードされた値でマネージドオブジェクト内のフラグメントを更新します。

また、メジャーメント、イベント、またはマネージドオブジェクトのフラグメント内に複数の値を持つネスト構造を作成することもできます。メジャーメントの場合、同じタイプのすべてのプロパティがマージされてネスト構造が作成されます。イベントまたはマネージドオブジェクトの場合、同じフラグメントを持つすべてのプロパティがマージされてネスト構造が作成されます。（以下の「Position」デバイスプロトコルのネスト構造の例も参照してください。）

OK をクリックして値をデバイスプロトコルに追加します。

Value configurations of created device protocol

保存 をクリックしてデバイスプロトコルを作成します。

単一プロパティの例

次の画像は、バッテリーレベル値が変化したときにメジャーメントを送信するメッセージの例を示しています。

新しい値ウィンドウ パート 1 Battery level changes example

新しい値ウィンドウ パート 2 Battery level changes example

ネスト構造の例

次の画像は、GPS デバイスの現在位置をレポートするデバイスプロトコルのネスト構造の例を示しています。デバイスプロトコル名は「Position」で、経度と緯度の値が含まれます。

メッセージ ID はすべての値で同じである必要があります。残りのパラメータは上記の説明に従って入力してください。マネージドオブジェクトフラグメント フィールドに「c8y_Position」と入力し、経度と緯度それぞれに対して新しい値を作成します。

新しい値ウィンドウ、経度

Value creation: Longitude-nested

新しい値ウィンドウ、緯度

Value creation: Latitude-nested

結果は次のようになります。

Value configuration in detail: nested structure

カスタムデコード/エンコードの使用

Sigfox エージェントは、カスタムマイクロサービスをプラグインすることで、デコード/エンコード機能もサポートします。詳細は LPWAN カスタムプロトコル を参照してください。

Sigfox デバイスの登録

Things Cloud に Sigfox デバイスを登録するには、デバイス管理アプリケーションで デバイス > 登録 に移動し、右上の デバイスを登録 をクリックして、ドロップダウンから 単一デバイス登録 > Sigfox を選択します。

Register devices

備考
  • Sigfox が利用可能なオプションの 1 つとして表示されない場合、テナントは関連アプリケーションをサブスクライブしていません。はじめにの要件を参照してください。
  • Sigfox Cloud プラットフォームで作成されるデバイスタイプには、次の命名規則があります。
    c8y_{tenantId}_{device-protocol-name}_{contractId}。例: c8y_myTenant_mySigfoxDeviceProtocol_aabbcc5b78c901d64eecf4faaa
  • 構築された名前が 100 文字を超える場合、100 文字未満になるまで切り詰められます。

次のウィンドウで、必要な情報を入力します。

  • ID: 一意のデバイス ID。値は 16 進数である必要があります。
  • PAC: デバイスの Porting authorization code。値は 16 進数である必要があります。
  • 接続: テナント内で設定されたすべての Sigfox 接続が一覧表示されます。以下の契約オプションは、選択した Sigfox 接続に基づいて入力されます。
  • 契約: 希望する契約を選択します（アクティブおよび期限切れを含むすべての契約が一覧表示されます）。
  • デバイスプロトコル: ドロップダウンリストから希望するデバイスプロトコルを選択します。
  • 製品証明書キー: このキーは https://partners.sigfox.com/ にあります。デバイスに移動して証明書キーをコピーしてください。チェックボックスが選択されておらず、製品証明書キーも指定されていない場合、デバイスはプロトタイプと見なされます。
備考
「Device type」という用語は Sigfox と Things Cloud の両方で使われますが、意味は異なります。Sigfox では、デバイスタイプはデバイスからのデータをどのようにルーティングするかを指定します。Things Cloud では、デバイスタイプは特定タイプのデバイスから送信されるデータを記述します。

Register devices1

登録 をクリックしてデバイス登録リクエストを送信し、デバイスを作成します。

デバイスが実際に接続されていることは、イベントが実際に到着しているか確認することで検証できます。デバイスをクリックしてその イベント タブを開いてください。このデバイスに関連するすべてのイベントがここに一覧表示されます。

接続済みデバイスの表示と管理の詳細については、デバイス管理アプリケーション も参照してください。

デバイスを 1 つの LNS 接続から別の接続へ移行するには、デバイスを再登録する必要があります。 デバイスの LPWAN タブに移動します。 Provider connection ドロップダウンをクリックします。 デバイスを 1 つの LNS 接続から別の接続へ移行するには、デバイスを再登録する必要があることを示すプロンプトが表示されます。 再登録 ボタンをクリックします。

ユーザーはデバイス登録ページに移動し、上記の手順に従って希望する LNS 接続を選択して再登録を実行できます。

一般デバイス登録で登録されたデバイスの更新

デバイスが以前に一般デバイス登録によって登録されていた場合、Sigfox Cloud で次の URL を手動で変更する必要があります。

  • https://sigfox-agent.je1.thingscloud.ntt.com/sigfoxDataCallback を https://<tenantId>.je1.thingscloud.ntt.com/service/sigfox-agent/sigfoxDataCallback に変更。
  • https://sigfox-agent.je1.thingscloud.ntt.com/sigfoxServiceAcknowledgeCallback を https://<tenantId>.je1.thingscloud.ntt.com/service/sigfox-agent/sigfoxServiceAcknowledgeCallback に変更。
  • https://sigfox-agent.je1.thingscloud.ntt.com/sigfoxServiceStatusCallback を https://<tenantId>.je1.thingscloud.ntt.com/service/sigfox-agent/sigfoxServiceStatusCallback に変更。
  • https://sigfox-agent.je1.thingscloud.ntt.com/sigfoxErrorCallback を https://<tenantId>.je1.thingscloud.ntt.com/service/sigfox-agent/sigfoxErrorCallback に変更。
備考
Sigfox デバイスの一般デバイス登録は、現在はサポートされていません。

オペレーションの送信

デバイスが 16 進数コマンドの送信をサポートしている場合、シェルオペレーションを使用して送信できます。

オペレーションを送信するには、デバイス管理アプリケーションの すべてのデバイス でオペレーションを送信したいデバイスに移動し、シェル タブに切り替えます。

備考
オペレーションはすぐに EXECUTING 状態にはなりません。デバイスが downlink メッセージを待機しているときに EXECUTING になります。その後、最初に作成された保留中のオペレーションが EXECUTING 状態になります。

uplink メッセージを受信すると、Things Cloud プラットフォームは次のメジャーメントとイベントを作成し、対応するデバイスマネージドオブジェクトを更新します。

  • 未処理データ - タイプ com_sigfox_UnprocessedDataEvent のイベントが未処理データとともに作成されます。
  • 位置情報 - デバイスマネージドオブジェクトの c8y_Position フラグメントが更新され、デバイスの緯度、経度、高度、精度情報が記録されます。
  • 信号強度 - デバイス信号強度の RSSI および SNR 値を含むメジャーメントが作成されます。

トラブルシューティング

デバイス登録

空きスロットのあるアクティブな契約がありません

空きスロットのあるアクティブな契約は、アクティベーション終了時刻と使用中トークンに基づいてフィルタリングされます。アクティベーション終了時刻が現在時刻より大きいか、アクティベーション終了時刻が無制限である契約、および最大トークン数が使用中トークン数より多いか、最大トークン数が無制限である契約が対象になります。

このエラーを解決するには、support.sigfox.com に連絡して Sigfox アカウント用の契約を作成してもらってください。

Sigfox provider settings が見つかりません

この警告メッセージは、sigfox 接続用に設定された接続がない場合に表示されます。

これを解決するには、Sigfox 認証情報の設定を参照してください。

Sigfox デバイスタイプが設定されていません

この警告メッセージは、デバイス登録に使用できる Sigfox デバイスプロトコルが存在しない場合に表示されます。

これを解決するには、デバイスデータベース で少なくとも 1 つのデバイスプロトコルを設定してください。

接続

backend.sigfox.com の Sigfox コールバックが正しく作成されていません

Sigfox callbacks error

コールバック設定用の情報はマイクロサービスによって取得されます。

設定が正しいか確認するには、次の REST API リクエストを実行してください。

```http
GET {{url}}/tenant/currentTenant
```
備考
上記のリクエストは、使用できる API リクエストの単なる例です。REST API リクエストの詳細については、Things Cloud OpenAPI仕様 の Tenants を参照してください。

この警告メッセージは、Sigfox アカウント用に設定された接続がない場合に表示されます。これを解決するには、設定 をクリックして管理アプリケーションに移動し、そこで接続を設定します。

Device registration failure without connections

デバイスプロトコルが設定されていません

この警告メッセージは、デバイス登録に使用できる Sigfox デバイスプロトコルが存在しない場合に表示されます。これを解決するには、デバイスプロトコル をクリックして デバイスプロトコル ページに移動し、そこでプロトコルを設定します。

No device protocol given for Sigfox

アラームのプロビジョニングに関する問題

転送オペレーションに失敗しました

!Failed operation

「transfer operation failed」アラームがトリガーされた場合、デバイスはすでに Sigfox プラットフォームでプロビジョニングされており、Sigfox プラットフォームでのデバイスタイプの変更に失敗しています。この問題を修正するには、Sigfox プラットフォームでデバイスタイプを意図したものに手動で変更する必要があります。

Provisioned ステータスが false に設定されている

!False provision

このアラームの場合、Provisioned ステータスが “false” に設定されていることがわかります。これは Sigfox プラットフォームからデータが来ていないことを意味します。アラームメッセージには、エラーに関する詳しい情報があります。このケースでは、登録時に指定された PAC コードが無効でした。

備考
プロビジョニングプロセスが完了していても失敗した場合は、失敗理由を含む情報がアラームとして返されます。

Provisioned ステータスは、デバイスプロビジョニングプロセスが完了し、Sigfox プラットフォームから成功情報を受信したときに true に設定されます。さらに、デバイスから uplink メッセージが取得されたときにも true に設定されます。

備考
ステータスは非同期に更新されるため、true に設定されるまで少し待つ必要がある場合があります。

コールバックの作成に失敗しました

Callback creation failed

このアラームは、Sigfox プラットフォームで 1 つ以上のコールバック作成リクエストが失敗したときに作成されます。このアラームは アラーム ページまたは ホーム ページで確認できます。

この問題を修正するには、Sigfox プラットフォームの web インターフェイスに移動し、アラームに記載された ID のデバイスタイプを確認します。

Device Type Id in the alarm

この場合、次のアドレスに移動します: https://backend.sigfox.com/devicetype/5cd3d97ee833d9746698b27d/callbacks

記載されたコールバックが Sigfox プラットフォーム内で見つからない場合は、手動で作成する必要があります。コールバック作成に必要な情報は、すべてアラームの説明内にすでに記載されています。上記アラームのケースでは、最初に次のコールバックが一覧表示されています。

  • [[callback=[type=DATA_BIDIR, url=«tenant_url»/service/sigfox-agent/sigfoxDataCallback, httpMethod=POST, bodyTemplate={“device”:"{device}",“time”:"{time}",“snr”:"{snr}",“station”:"{station}",“data”:"{data}",“rssi”:"{rssi}",“seqNumber”:"{seqNumber}",“ack”:"{ack}"}, contentType=application/json, headers={Authorization=Basic …}]]]

コールバックを手動で作成するには、次のプロパティを入力する必要があります。

  • type
  • url
  • httpMethod
  • bodyTemplate
  • contentType
  • headers
備考
アラームに表示される Authorization ヘッダーには、ユーザー認証情報は表示されません。

アラームに記載されていないプロパティは次のとおりです。

  • sendSni
  • sendDuplicate

これらのプロパティは false に設定されます。

LPWANカスタムプロトコル

はじめに

Things Cloud は、Actility LoRa などの Things Cloud LPWANエージェントを介して、LPWANネットワークプロバイダー経由でLPWANデバイスと連携できます。

当社のLoRa統合では、LoRaセンサーデータから Things Cloud データモデルへのバイナリマッピングを作成するために、セルフサービス方式でデバイスプロトコルを定義できます。
ただし、このアプローチは動的なペイロードを送信するLoRaデバイスには機能しません。
動的なペイロードを持つLoRaデバイスを統合するには、ペイロードのデコードとコマンドのエンコードのためのカスタムcodecをマイクロサービスの形式で作成できます。
このマイクロサービスをカスタムcodecマイクロサービスと呼びます。
カスタムcodecマイクロサービスは、LoRaペイロードおよびコマンドのデコードとエンコードのための特定の契約に準拠する、一般的な Things Cloud マイクロサービスです。

LPWANエージェントがアップリンクメッセージを受信すると、デコードのためにデバイスデータをカスタムcodecマイクロサービスが公開するRESTエンドポイント（/decode など）に転送します。
同様に、ユーザーがデバイスシェルを通じてデバイスコマンドを実行すると、LPWANエージェントはエンコードのためにコマンドテキストをカスタムcodecマイクロサービスが公開するRESTエンドポイント（/encode など）に転送します。

カスタムcodecマイクロサービスの実装

カスタムcodecマイクロサービスは一般的な Things Cloud マイクロサービスであり、次のように実装して有効化できます。

  1. OpenAPI Specification に準拠した /encode および /decode RESTエンドポイントを公開するマイクロサービスを作成し、エンコードおよびデコード機能を実装します。

  2. マイクロサービスは、サポートする各LPWANデバイスタイプに対してデバイスプロトコルを作成する必要があります。lpwan-custom-codecライブラリを使用する場合、デバイスプロトコルは自動的に作成されます。
    それ以外の場合は、インベントリAPIを使用して、次のJSON構造でデバイスプロトコルを記述する新しいマネージドオブジェクトを作成する必要があります。

    このcodecマイクロサービスがサポートするすべてのデバイスメーカーとデバイスモデルの組み合わせごとに、デバイスプロトコル（type および fieldbusType プロパティと c8y_LpwanCodecDetails フラグメントを含む）と外部IDを作成する必要があります。

    • type は常に “c8y_LpwanDeviceType” です。
    • fieldbusType は常に “lpwan” です。
    • c8y_LpwanCodecDetails フラグメントには以下が含まれます。
      • codecServiceContextPath- カスタムcodecマイクロサービスのコンテキストパス。
      • supportedDevice- サポートされるデバイス情報。
        • deviceManufacturer- デバイスメーカー。
        • deviceModel- デバイスモデル。
      • supportedDeviceCommands- このデバイスがサポートするコマンドのリスト。
        • name- コマンド名。作成する事前定義コマンドテンプレートの名前と一致している必要があります（以下を参照）。
        • category- コマンドカテゴリ。作成する事前定義コマンドテンプレートのカテゴリと一致している必要があります（以下を参照）。

    インベントリAPIを使用してデバイスプロトコルを作成するためのJSON構造の例:

    {
	"name": "<<Name of the LPWAN device protocol>>",
	"description": "<<Description of the LPWAN device protocol>>",
	"type": "c8y_LpwanDeviceType",
	"fieldbusType": "lpwan",
	"c8y_IsDeviceType": {},
	"c8y_LpwanCodecDetails": {
		"codecServiceContextPath": "<<Custom Codec microservice context path>>",
		"supportedDevice": {
			"deviceManufacturer": "<<Supported device manufacturer>>",
            "deviceModel": "<<Supported device model>>",
			"supportedDeviceCommands": [
				{
					"name": "<<Command name, matching the name of the Predefined Command template you create>>",
					"category": "<<Command category, matching the category of the Predefined Command template you create>>"
				}
			]
		}
	}
}

    Identity APIを使用してデバイスプロトコル用の外部IDを作成するためのJSON構造の例:

    {
	"externalIds": [
		{
			"managedObject": "<<ID of the Device protocol managed object>>",
			"externalId": "<<Device Protocol Name>>",
			"type": "c8y_SmartRestDeviceIdentifier"
		}
	]
}

  3. デバイスに割り当てられたデバイスプロトコルに基づいて、LPWANエージェントは対応するマイクロサービスにリクエストを自動的にルーティングします。
    デバイスダウンリンクコマンドについては、デバイスプロトコルの c8y_LpwanCodecDetails フラグメントの “supportedDeviceCommands” にリストされている事前定義コマンドが実行された場合にのみ、LPWANエージェントはデバイスシェルコマンドリクエストを /encode エンドポイントに転送します。

    デバイスタイプで指定された、サポートされる各デバイスコマンド（supportedDeviceCommands）に対して、事前定義コマンドテンプレートを作成する必要があります。

    次の例は、インベントリAPIを使用して事前定義コマンドテンプレートを作成するためのJSON構造を示しています。

     {
	"type": "c8y_DeviceShellTemplate",
	"name": "<<Command name, matching the name of the supported command mentioned in the device protocol>>",
	"deviceType": [
		"<<Device Protocol Name>>"
	],
	"category": "<<Command Category>>",
	"command": "<<Command string which gets copied to the device shell command prompt when the user chooses this Predefined command>>",
	"deliveryTypes": [
		"Default"
	]
}

LPWANカスタムcodecライブラリの使用

利便性のため、Things Cloud は、JavaでSpringBootアプリケーションとしてカスタムcodecマイクロサービスを開発するためのJavaライブラリ com.nsn.cumulocity.clients-java:lpwan-custom-codec を提供しています。
サブスクライブされると、このようなカスタムcodecマイクロサービスは、カスタムcodecマイクロサービスの実装 で説明した必要なデバイスプロトコルと事前定義コマンドテンプレートを自動的に作成します。

このライブラリを使用してカスタムcodecマイクロサービスを作成するには、次の手順を実行します。

  1. pom.xmlファイルに次の依存関係を追加します。

     ```xml
 <dependency>
         <groupId>com.nsn.cumulocity.clients-java</groupId>
         <artifactId>lpwan-custom-codec</artifactId>
         <version>${c8y.version}</version>
     </dependency>
 ```

  2. Spring Bootアプリケーションを作成し、そのメインクラスに次のアノテーションを付けます。

    @CodecMicroserviceApplication `com.cumulocity.microservice.lpwan.codec.annotation.CodecMicroserviceApplication`

  3. 次のJavaインターフェイスを実装し、次のアノテーションを付けます。

    @Component `org.springframework.stereotype.Component`

    a. com.cumulocity.microservice.lpwan.codec.Codec の supportedDevices メソッドを実装して、このカスタムcodecサービスがサポートするデバイスメーカー、デバイス名、およびコマンドを指定します。

     ```java
 package com.cumulocity.microservice.lpwan.codec;

 public interface Codec {
      Set<DeviceInfo> supportsDevices();
 }
 ```

    b. com.cumulocity.microservice.customdecoders.api.service.DecoderService の decode メソッドを実装して、デコード機能を提供します。decodeメソッドは次の入力を受け取ります。

    • inputData- デコード対象のデバイスペイロード。
    • deviceId- デバイスマネージドオブジェクトID。
    • args- 以下のキーを含むマップ。
      • deviceManufacturer- デバイスメーカー。
      • deviceModel- デバイスモデル。
        • sourceDeviceEui- デバイスeui。
        • fport- fport（任意）。

    このライブラリは、デコーダー入力を抽出するためのラッパークラス com.cumulocity.microservice.lpwan.codec.decoder.model.LpwanDecoderInputData も提供します。

      ```java
   package com.cumulocity.microservice.customdecoders.api.service;

   public interface DecoderService {
       DecoderResult decode(String inputData, GId deviceId, Map<String, String> args) throws DecoderServiceException;
   }
   ```

    c. com.cumulocity.microservice.customencoders.api.service.EncoderService の encode メソッドを実装して、エンコード機能を提供します。

     ```java
 package com.cumulocity.microservice.customencoders.api.service;

 public interface EncoderService {
     EncoderResult encode(EncoderInputData encoderInputData) throws EncoderServiceException;
 }
 ```

  4. マイクロサービスマニフェストファイル cumulocity.json に次の権限を追加します。マニフェスト内の該当フィールド名は requiredRoles ですが、実際に追加するのは必要な権限文字列のリストです。

    "requiredRoles": [
   "ROLE_INVENTORY_ADMIN",
   "ROLE_INVENTORY_READ"
]

サンプルcodecマイクロサービスのデプロイ

サンプルcodec lora-codec-lansitec マイクロサービスをビルドする手順です。

  1. https://github.com/Cumulocity-IoT//cumulocity-examples.git リポジトリをクローンします。
  2. mvn clean install を使用してマイクロサービスをビルドします。これにより、lanitec codecマイクロサービスのZIPファイルが作成されます。
  3. Things Cloud 管理 UIを使用してZIPファイルをアップロードし、マイクロサービスをデプロイします。
  4. デバイス管理を開きます。デバイスプロトコル の下に、lansitec codecマイクロサービスによって作成されたタイプ “lpwan” のデバイスプロトコルが表示されます。

以下の画像は、デバイス管理内のデバイスプロトコルオプションを示しています。

デバイスプロトコルページ

以下の画像は、サブスクリプション時にカスタムcodecマイクロサービスによって作成されたデバイスプロトコルの例を示しています。

サブスクリプション時に作成されたデバイスプロトコルのリスト

作成されたデバイスプロトコルは、いずれかのLPWANエージェントでLPWANのデバイス登録を行う際のドロップダウンに表示されます。
以下にActility LoRaデバイス登録を示します。

デバイス登録

LPWAN デバイスタブからデバイスプロトコルを割り当てることもできます。
そのためには、特定のデバイスに移動します。
次に、LPWAN タブに切り替え、新しいデバイスプロトコル をクリックして、上で作成されたデバイスプロトコルを表示します。

デバイスプロトコルマッピング

サポートされるデバイスコマンドは、デバイスシェル タブの 事前定義コマンドオプション から利用できます。

デバイスでサポートされるコマンド