Sigfox接続機能

操作マニュアル

1. はじめに

本書では、Things Cloud Sigfox接続機能に関する操作について説明します。

Sigfox接続機能では、Sigfoxネットワーク事業者の提供する Sigfox Cloud と Things Cloud を接続するインターフェースを提供します。このインターフェースを用いることにより、Sigfox 対応デバイスを Things Cloud のデバイスとして登録し、データを可視化することができます。

一度 Things Cloud への接続設定を行えば、以後 Sigfox Cloud へのデバイス登録により Things Cloud に簡単に Sigfox 対応デバイスを接続することができます。

本書に含まれる内容は以下の通りです。 Sigfox対応デバイスを準備し、Things Cloud に接続するまでの一連の手順を記載しています。

表題 内容 備考
2. 利用条件 および 制約事項 Sigfox接続機能の利用条件及び制約事項を記載しています。
3. Sigfoxプロバイダー設定 Sigfox Cloudのアカウント情報をThings Cloudに登録します。 Sigfox Cloud - Things Cloud間通信の認証に必要な設定です。(テナント毎に設定が必要です。)
4. デバイスプロトコル登録 Things Cloud にデバイスプロトコル(デバイスがアップロードするフォーマットを定義したもの)を登録します。 新しいデバイスプロトコルのデバイスを接続する際に行います。
5. デバイス登録 デバイスをThings Cloud へSigfoxデバイスとして登録します。 Sigfoxデバイスの登録によりSigfox Cloudにも自動的にデバイス登録が行われます。
6. デバイスデータの確認 Sigfox対応デバイスからのデータが Things Cloud に接続されたかを確認します。 デバイス接続後、いつでも確認できます。
7. デバイスの操作 デバイスにコマンドを実行させるためのオペレーションを送信します。 デバイス制御のコマンドが用意されているデバイスのみに対応しています。
8. サブテナントでのSigfox接続機能利用 サブテナントにおいてSigfox接続機能を利用するために、Sigfoxアプリケーションをサブスクライブします。 Sigfox接続設定済の親テナントからサブテナントを作成し、サブテナントでSigfox接続機能を利用する場合には、サブテナントに対してSigfoxアプリケーションを追加します。
9. FAQと利用上の注意事項 Sigfox接続機能(Sigfox接続)利用時のFAQおよび注意事項を記載しています。

2. 利用条件 および 制約事項

3. Sigfoxプロバイダー設定

3.1. 事前準備

Things CloudにSigfoxプロバイダ設定を行う前に、まずはSigfox Cloud上で、APIを利用するために必要な認証情報(API ACCESS)を作成しておく必要があります。
以下の2つのステップを実行することで、Sigfox Cloudでのセットアップは完了します。

Step 1

※Step 1は、必要な権限を持った “Associated user"をまだ作成していない場合のみ、実行してください。
Sigfox Cloudにログインし、新しくユーザを作成します。ユーザを任意のグループに追加し、次の権限プロファイルを選択してください。

Step 2

“GROUP” ページから “Associated user” を作成したグループを選択し、 “API ACCESS” タブを選択したら、以下の権限プロファイルを設定した新しいエントリーを作成します。

Sigfox Cloudでのセットアップは以上です。

3.2 接続設定

ここからは Things Cloud で設定を行います。
管理アプリケーションを表示し、左側のナビゲータから「接続」を選択します。
「接続」画面の「Sigfoxプロバイダ設定」タブを選択した状態で表示される、下記の入力項目を設定します。

入力項目 内容 備考
ログイン Sigfox Cloud で作成した API ACCESS のログイントークン
パスワード Sigfox Cloud で作成した API ACCESS のパスワードトークン
親グループ ID Sigfox Cloud で作成した該当するグループのID Sigfox CloudでGROUPの一覧画面から該当するグループを選択した画面で、URLからIDを確認することができます。
例) “https://backend.sigfox.com/group/9823ruj29j9d2j9828hd8/info”

入力後、「資格情報を保存」ボタンを押します。

4. デバイスプロトコル登録

4.1. デバイスプロトコルを新規に作成する場合

「デバイスタイプ」>「デバイスプロトコル」を選択します。
デバイスプロトコルの画面で「デバイスプロトコルを追加」を選択します。

デバイスプロトコルを選択するウィンドウが表示されるので、「Sigfox」を選択し、名前を設定したら「作成」ボタンを押します。

入力項目が現れるので、それらに入力します。 なお、付録2でデバイスプロトコルの設定例を掲載しています。

入力項目 内容 備考
説明 デバイスプロトコルの説明 デバイスプロトコルに関して説明事項があれば入力する。
ソース メッセージのタイプが決定されるソース メッセージタイプが表されているペイロードの位置(開始ビットとビット長)を入力する。
デバイスメッセージのデコードロジック定義 追加を押下し、デバイスメッセージ仕様を元に以下を入力する。
・メッセージID: メッセージタイプを識別する数値
・名前: 測定対象等の名前
・表示カテゴリ: 測定対象等のカテゴリ
(例:Temperature Mode)
・開始ビット/ビット数: データ位置の指定
・乗数: データに乗算する場合に設定する値(デフォルト値は1)
・オフセット: データに加算もしくは減算する場合に設定する値(デフォルト値は0)
・単位: データの単位(任意入力)
・オプション: データ形式に応じて選択
・機能: 実行するアクションを選択 
(選択した機能に応じタイプ/シリーズ/テキスト等を入力)

入力後、「保存」ボタンを押します。

保存後、デバイスプロトコルの画面上に以下のように表示されます。

4.2. デバイスプロトコルをインポートする場合

デバイスプロトコルをファイル(JSON形式)から取り込んで登録(インポート)することもできます。
JSON形式のデバイスプロトコル情報は、テナントに登録済みのデバイスプロトコルがあれば、その情報を取得(エクスポート)して利用することもできます。

テナントに登録済みのデバイスプロトコルからファイルを取得する場合は、「デバイスプロトコル」画面からエクスポートします。

インポート

「デバイスプロトコル」画面の「インポート」を選択し、「デバイスプロトコルのインポート」画面を表示します。

ファイルを指定し、必要であれば名前を変更します。「インポート」ボタンを押して、登録します。

5. デバイス登録

デバイス管理アプリケーションの左のメニュー「登録」を押下し、「デバイスを登録」ボタンを押下します。

「Sigfox」を押下します。

注記: LoRaWAN接続機能も利用している場合は、「カスタムデバイス登録」と表示されます。

表示された入力フォームに必要事項を設定します。

入力項目 内容 備考
ID デバイスを一意に識別する値 一意な16進数の値です。通常、Sigfox対応の通信モジュールに工場出荷時に書き込まれています。
PAC 移植認証コード Sigfoxクラウドへのデバイス登録時に必要な、16進数のワンタイム認証コードです。初期値は通常、Sigfox対応の通信モジュールに工場出荷時に書き込まれています。
契約 Sigfoxクラウドの契約情報 デバイス登録を行う契約情報を選択します。
デバイスタイプ 項目3で設定したデバイスプロトコルを選択 登録したいデバイスと対応するものを選択してください。
製品の証明書キー Sigfox Ready certificate(P2認証)の認証番号 P_から始まる番号で、Sigfox Partner networkサイトからも確認可能です。

入力後、「次へ」ボタンを押します。正常に登録されると、以下のように表示されます。

デバイス一覧からも、登録したデバイスが確認できるようになります。

デバイス登録後、Sigfox Cloudへ自動的にデバイス登録が行われます。Sigfox Cloudへデバイスが登録されることをデバイスのプロビジョニングと呼びます。

6. デバイスデータの確認

デバイスからのデータは、イベントとして Things Cloud に格納されます。
デバイス管理アプリケーションから、該当デバイスを選び、計測値やイベントを見ることでデータの到着を確認することができます。

イベントには Sigfox の payload がヘキサ文字列として “com_Sigfox_UnprocessedDataEvent.data” プロパティに格納されます。
デバイスプロトコルでのデバイスプロトコル設定に関わらず、以下のデータはSigfoxデバイスからのデータアップロード時に共通して作成されます。

7. デバイスの操作

7.1. 事前準備

downlinkによってオペレーションを送信するには、Sigfox Cloudのcallback設定のdownlinkを有効にします。

次に、callbackの設定を変更します。変更対象は、SERVICE callbacks - Acknowledge のみです。

Bodyの値を以下のように変更してください。

Sigfox Cloudでのセットアップは以上です。

7.2. コマンドの送信

ここからは Things Cloud で操作を行います。
デバイス管理アプリケーションを開き、オペレーションの送信先となる該当デバイスを選択します。次に"シェル"タブをクリックします。

シェルコマンドを入力するか、または">_定義済みのコマンドを取得"項目で定義済みのコマンドを表示/編集します。
“実行"をクリックすると、デバイスへのオペレーション送信待機状態となります。

送信待機状態のコマンドが送信されるタイミング

デバイスから送信されたデータに “ack=true” が含まれているcallbackを受信すると、そのHTTPレスポンスとして、保留中となっているコマンドが送信されます。
デバイスから"ack=true"が送信されるタイミングは、デバイスによって決められています。また、Sigfoxサービスの契約内容によって1日に送信可能なDownlinkの上限回数が異なります。

ステータス

Sigfox Cloudへの送信が成功すると、以下のようにステータスが"成功"に変わります。

注記:Sigfox基地局からデバイスへdownlinkが送信された場合に、ステータスが"成功"となります。(デバイスにコマンドが到着したかどうかまでは確認できません。)

定義済みコマンド

頻繁に利用するコマンドなどを定義済みのコマンドとして保存し、利用時に取得して送信することが可能です。
コマンドを新規に定義するには、“定義済みのコマンドを取得"を押し、“新規追加"を押します。

名前、カテゴリ、コマンドを入力し、“保存"します。

定義済みのコマンドを送信する場合、前の画面に戻り、定義済みのコマンドを選択し"実行"を押します。

8. サブテナントでのSigfox接続機能利用

Sigfox接続機能を利用中の親テナントから作成したサブテナントで、Sigfox接続機能を利用するために必要な事前設定です。
管理>サブテナント画面から、Sigfox接続機能を利用するサブテナントを選択します。

“アプリケーション"のタブを押し、右側の利用可能なアプリケーションから"Sigfox-agent"を選択したときに表示される登録ボタンを押します。

左側の登録済みアプリケーションに"Sigfox-agent"が追加されます。

サブテナントでSigfox接続機能を利用するために必要な事前設定は以上です。

9. FAQと利用上の注意事項

9.1. FAQ

No. Q A
1 Things Cloud 内でのデバイス名は? 初期デバイス名は SigFox device {デバイスID} の形式になります。例えば、デバイスID が 0017B46C であった場合、SigFox device 0017B46C となります。
2 デバイス名は変えられないの? デバイスが登録された後、自由に名称を変更することができます。変更しても、デバイス管理アプリケーションからデバイスを選択し、「アイデンティティ」から デバイスID 値を確認することができます。
3 デバイスからデータが送信されていないことを検知するには? 通常の Things Cloud 利用の場合と同様、可能です。デバイス管理アプリケーションからデバイスを選択し、「情報」タブを選び、「接続の監視」セクションの要求間隔に値を記入することで、その時間内にデータ送信がない場合にアラームを発生させることができます。

9.2. トラブルシューティング

こちらを参照してください。

トラブルシューティング

1. Sigfoxクラウドにデバイスが追加されない

Things Cloudにはデバイス登録できたが、Sigfoxクラウドにデバイスが追加されないという場合、下記のアラームが作成されていないかご確認ください。

上記画像のアラームが作成されている場合、お使いのデバイスは prototype としてのみ登録可能なデバイスです。通常のデバイス登録手順ではお使いいただけませんが、以下の手順でデバイス登録することができます。
ただし、prototype デバイスについては、Things Cloudではサポート対象外となります。

1-(1) Sigfoxクラウドに該当デバイスで使用するデバイスタイプを作成する

該当デバイスに紐付けるデバイスタイプがすでにSigfoxクラウドに存在する場合は、この手順をスキップしてください。

入力項目 設定値 備考
Name デバイスタイプの名称です。次の命名規則で設定してください。
c8y_{テナントid}_{デバイスタイプ名}
例)c8y_testTenant_SensitDiscovery
{デバイスタイプ名}は、Things Cloudで紐付けるデバイスタイプ名と同じである必要があります。
Description 特に何も記載する必要はありません。
Keep-alive (in minutes) 0
Subscription automatic renewal 有効
Contract 使用する契約情報を選択してください。
Alert email 特に何も記載する必要はありません。
Downlink mode callback
Downlink data in hexa デフォルト値から変更しないでください。
Payload parsing Display in ASCII

1-(2) 作成したデバイスタイプにcallbackを登録する

Custom callbackから、次の4つのcallbackを設定します。

1-(2)-1 DATA callbacks

入力項目 設定値 備考
Type DATA, BIDIR
Channel URL
Send duplicate 無効
Custom payload config 特に何も記載する必要はありません。
Url pattern 次の値を設定してください。
https://{テナントドメイン}/service/sigfox-agent/sigfoxDataCallback
例)https://sigfoxtest.je1. thingscloud.ntt.com/service/ sigfox-agent/sigfoxDataCallback
Use HTTP Method POST 一度プルダウンを設定後、もう一度プルダウンをクリックすると入力フォームが表示されます。
Send SNI 無効
Headers Authorizationヘッダーを追加します。以下の値をBase64エンコードした値を設定してください。
{テナントid}/sigfox_cumulocity_agent_user:sigfox_pass_{テナントid}

設定例)Basic dDAwMDAwMDAwL3Np Z2ZveF9jdW11bG9j aXR5X2FnZW50X3Vz ZXI6c2lnZm94X3Bh c3NfdDAwMDAwMDAw
※base64文字列は表示上スペースを入れていますが、実際の設定ではスペースを入れないで下さい
テナントidとテナント名は異なるパラメータです。ご注意ください。
Content type application/json
Body {“device”:"{device}", “time”:"{time}", “snr”:"{snr}", “station”:"{station}", “data”:"{data}", “avgSignal”:"{avgSnr}", “lat”:"{lat}", “lng”:"{lng}", “rssi”:"{rssi}", “seqNumber”:"{seqNumber}", “ack”:"{ack}"}

1-(2)-2 SERVICE callbacks - ACKNOWLEDGE

入力項目 設定値 備考
Type SERVICE, ACKNOWLEDGE
Channel URL
Send duplicate 無効
Url pattern 次の値を設定してください。
https://{テナントドメイン}/service/sigfox-agent/sigfoxServiceAcknowledgeCallback
例)https://sigfoxtest.je1. thingscloud.ntt.com/service/ sigfox-agent/sigfoxServiceAcknowledgeCallback
Use HTTP Method POST 一度プルダウンを設定後、もう一度プルダウンをクリックすると入力フォームが表示されます。
Send SNI 無効
Headers Authorizationヘッダーを追加します。以下の値をBase64エンコードした値を設定してください。
{テナントid}/sigfox_cumulocity_agent_user:sigfox_pass_{テナントid}

設定例)Basic dDAwMDAwMDAwL3Np Z2ZveF9jdW11bG9j aXR5X2FnZW50X3Vz ZXI6c2lnZm94X3Bh c3NfdDAwMDAwMDAw
※base64文字列は表示上スペースを入れていますが、実際の設定ではスペースを入れないで下さい
テナントidとテナント名は異なるパラメータです。ご注意ください。
Content type application/json
Body {“device”:"{device}", “time”:"{time}", “duplicate”:"{duplicate}", “avgSnr”:"{avgSnr}", “station”:"{station}", “lat”:"{lat}", “lng”:"{lng}", “infoCode”:"{infoCode}", “infoMessage”:"{infoMessage}", “downlinkAck”:"{downlinkAck}", “downlinkOverusage”:"{downlinkAck}"}

1-(2)-3 SERVICE callbacks - STATUS

入力項目 設定値 備考
Type SERVICE, STATUS
Channel URL
Send duplicate 無効
Url pattern 次の値を設定してください。
https://{テナントドメイン}/service/sigfox-agent/sigfoxServiceStatusCallback
例)https://sigfoxtest.je1. thingscloud.ntt.com/service/ sigfox-agent/sigfoxServiceStatusCallback
Use HTTP Method POST 一度プルダウンを設定後、もう一度プルダウンをクリックすると入力フォームが表示されます。
Send SNI 無効
Headers Authorizationヘッダーを追加します。以下の値をBase64エンコードした値を設定してください。
{テナントid}/sigfox_cumulocity_agent_user:sigfox_pass_{テナントid}

設定例)Basic dDAwMDAwMDAwL3Np Z2ZveF9jdW11bG9j aXR5X2FnZW50X3Vz ZXI6c2lnZm94X3Bh c3NfdDAwMDAwMDAw
※base64文字列は表示上スペースを入れていますが、実際の設定ではスペースを入れないで下さい
テナントidとテナント名は異なるパラメータです。ご注意ください。
Content type application/json
Body {“device”:"{device}", “time”:"{time}", “duplicate”:"{duplicate}", “avgSnr”:"{avgSnr}", “station”:"{station}", “lat”:"{lat}", “lng”:"{lng}", “batt”:"{batt}", “temp”:"{temp}", “seqNumber”:"{seqNumber}"}

1-(2)-4 ERROR callbacks

入力項目 設定値 備考
Type ERROR
Channel URL
Url pattern 次の値を設定してください。
https://{テナントドメイン}/service/sigfox-agent/sigfoxErrorCallback
例)https://sigfoxtest.je1. thingscloud.ntt.com/service/ sigfox-agent/sigfoxErrorCallback
Use HTTP Method POST 一度プルダウンを設定後、もう一度プルダウンをクリックすると入力フォームが表示されます。
Send SNI 無効
Headers Authorizationヘッダーを追加します。以下の値をBase64エンコードした値を設定してください。
{テナントid}/sigfox_cumulocity_agent_user:sigfox_pass_{テナントid}

設定例)Basic dDAwMDAwMDAwL3Np Z2ZveF9jdW11bG9j aXR5X2FnZW50X3Vz ZXI6c2lnZm94X3Bh c3NfdDAwMDAwMDAw
※base64文字列は表示上スペースを入れていますが、実際の設定ではスペースを入れないで下さい
テナントidとテナント名は異なるパラメータです。ご注意ください。
Content type application/json
Body {“device”:"{device}", “time”:"{time}", “info”:"{info}", “severity”:"{severity}"}

1-(3) Sigfoxクラウドに prototype としてデバイス登録する

Sigfoxクラウドにデバイスを登録します。

入力項目 設定値
Identifier (hex!) デバイスのIDを設定してください。
Name デバイスの名称です。次の命名規則で設定してください。
c8y_{テナントid}_{デバイスタイプ名}00{デバイスid}
例)c8y_testTenant_SensitDiscovery00B43F14
PAC デバイスの移植認証コードを設定してください。
End product certificate 何も入力せず、“Where can I find the end product certificate?” というリンクを押下し、表示されたチェックボックス(Register as a prototype (remaining prototypes which can be registered in your group: 999))にチェックを入れてください。
Type 作成したデバイスタイプを選択してください。
Lat (-90° to +90°) 必要であれば任意の値を設定してください。
Lng (-180° to +180°) 必要であれば任意の値を設定してください。
Subscription automatic renewal 有効
Activable 有効

1-(4) Things Cloudにデバイスを登録する

Things Cloudにデバイスを登録します。デバイス登録時、必ずSigfoxクラウドに作成したデバイスタイプと同じ名前のデバイスタイプを選択してください。
また、“製品の証明書キー"には “P_100” などダミー値を設定してください。

登録が完了すると、以下のようなアラームが作成されますが、問題ありません。

以上でデバイス登録は完了です。
デバイスからアップロードされたデータが、Things Cloudに反映されていることをご確認ください。

2. デバイスの登録設定ができない

次のようなエラーメッセージが出る場合①

Sigfoxプロバイダ接続設定をしていない または Sigfoxプロバイダ接続設定で入力したパスワードが誤っている可能性があります。設定内容をご確認ください。

注記:正しく登録完了した場合は、以下のようなポップアップが表示されます。

次のようなエラーメッセージが出る場合②

何らかの理由でサーバへの接続に失敗しています。少し時間をおいてから、もう一度お試しください。

次のようなエラーメッセージが出る場合③

同一テナントで登録済みのデバイスで使用したデバイスタイプを使って、別のSigfox契約を選択しデバイス登録をしている可能性があります。登録フォームでの設定値をご確認ください。

注記: Sigfoxクラウドでは、同じデバイスタイプ名を複数のcontractに登録することができません。

3. デバイスからデータがアップロードされない

該当のデバイスに、アラームが作成されていないかご確認ください。

上記のアラームが作成されている場合、別テナントに既に同デバイスが登録されている可能性があります。
Sigfoxクラウド上のデバイスタイプは、先に登録したテナントに紐づくデバイスタイプが登録されているため、後から登録したテナントにデータをアップロードしたい場合は、以下の手順でSigfoxクラウド上のデバイスタイプにcallbackを作成し、デバイスに紐付いているデバイスタイプを変更する必要があります。

注記: 既に別テナントに登録されているデバイスをThings Cloudに登録した場合、Sigfoxクラウド上では、後から登録したデバイスのデバイスタイプも作成されていますが、callbackまでは登録されていないため、手動で登録する必要があります。

3-(1) Sigfoxクラウドのデバイスタイプにcallbackを設定する

Sigfoxクラウドに作成されたデバイスタイプを見つけ、callbacks画面を表示します。
デバイスタイプの命名規則は、c8y_{テナントid}_{デバイスタイプ名} です。

1-(2) 作成したデバイスタイプにcallbackを登録するの手順を参考にして、callbackを設定します。

3-(2) デバイスタイプを変更する

該当デバイスのInformation画面を表示し、Transferを押下します。

New Device Typeに先ほど作成したデバイスタイプを選択します。

必要な操作は以上です。
デバイスからアップロードされたデータが、意図したテナントにアップロードされていることをご確認ください。

4. デバイスタイプを変更したい

一度登録したデバイスのデバイスタイプは、GUIからは変更できません。(デバイス情報画面から手動で書き換えても、反映されません。)
APIで直接managedObjectを更新するか、一度デバイスを削除して登録し直す必要があります。

注記: 同テナントに登録済みのデバイスについて、デバイスタイプを変えてもう一度デバイス登録をすると、登録が成功したように見えますが、実際にはデバイスタイプは変更されていないため、ご注意ください。

API経由でデバイスタイプを変更する

デバイスタイプは、該当デバイスのmanagedObject.c8y_LpwanDevice.typeで設定されているので、変更後のデバイスタイプのmanagedObjectIdを設定し、managedObjectを更新することでデバイスタイプを変更できます。以下のbodyを参考にして、エンドポイントにPUTリクエストを投げることで更新できます。

注記: サーバに10分間はキャッシュが残っているため、デバイスタイプ変更前のデータアップロードから10分以上間隔をあけてから、新しいデバイスタイプを紐付け、データをアップロードしてください。

5. Sigfoxプロバイダの接続設定ができない

Sigfox Cloud の認証情報(ログイン/パスワード/親グループ ID)の組み合わせに誤りがある可能性があります。入力内容をご確認ください。