MQTT静的テンプレート

デバイス統合を容易にするため、Things Cloud では、クライアントが独自のテンプレートを作成する必要なく利用できる多数の静的テンプレートがすでにサポートされています。これらのテンプレートは、デバイス管理の目的で最もよく使われるメッセージに焦点を当てています。

以下に示すテンプレートを利用するには、メッセージをトピック s/us（発行内容の一時処理の場合は t/us、静的処理の場合は q/us、CEP処理の場合は c/us）に発行する必要があります。詳細は処理モードを参照してください。

静的テンプレートでオペレーションを受信するには、トピック s/ds をサブスクライブする必要があります。

テンプレート クイックリファレンス

各テンプレートの詳細を表示するには、以下のコマンドをクリックしてください。 パラメータが角括弧で囲まれている場合、そのパラメータは任意です。

インベントリ テンプレート

• 100,createdDeviceName,deviceType
• 101,createdChildId,childName,childType
• 102,serviceExternalId,serviceType,serviceName,serviceStatus
• 104,serviceStatus
• 105 (子デバイスの取得, 応答: 106,child1,child2,…)
• 107,fragmenttoBeUninstalled1,fragment2,...
• 110,serialNumber,hardwareModel,revision
• 111,IMEI,ICCID,IMSI,MCC,MNC,LAC,cellId
• 112,latitude,longitude,altitude,accuracy
• 113,"configProp1=val1\nprop2=val2\n…"
• 114,supportedOperation1,operation2,…
• 115,currentFirmwareName,version,url
• 116,currentSoftwareName1,version1,url1,name2,…
• 117,requiredInterval
• 118,supportedLog1,log2,...
• 119,supportedConfiguration1,config2,...
• 120,configType,url,filename[,time]
• 121,profileExecuted,profileID
• 122,agentName,agentVersion,agentURL,agentMaintainer
• 123 (内部IDの取得, 応答: "124,id")
• 125 (ハートビート送信)
• 140,setAdvancedSWName1,AdvancedSWVersion1,AdvancedSWType1,AdvancedSWurl1,sw2,ver2,type2,url2,...
• 141,appendAdvancedSWName1,AdvancedSWVersion1,AdvancedSWType1,AdvancedSWurl1,sw2,ver2,type2,url2,...
• 142,deleteAdvancedSWname1,AdvancedSWVersion1,sw2,ver2,...
• 143,supportedSoftwareType1,supportedSoftwareType2,...
• 150,cloudRemoteAccessProtocol1,cloudRemoteAccessProtocol2,...

メジャーメント テンプレート

• 200,fragment,series,value[,unit,time]
• 201,type,[time],fragment1,series1,value1,[unit1],...
• 210,rssi,ber[,time]
• 211,temperature[,time]
• 212,battery[,time]

アラーム テンプレート

• 301,criticalAlarmType[,text][,time]
• 302,majorAlarmType[,text][,time]
• 303,minorAlarmType[,text][,time]
• 304,warningAlarmType[,text][,time]
• 305,alarmType,newSeverity
• 306,alarmTypeToBeCleared
• 307,alarmType,fragmentToBeRemoved1,fragment2,...

イベント テンプレート

• 400,eventType,text[,time]
• 401,latitude,longitude,altitude,accuracy[,time]
• 402,latitude,longitude,altitude,accuracy[,time] (inv. update含む)
• 407,eventType,fragmentToBeRemoved1,fragment2,...
• 408,[text],[time],[change detect],parameterPath1,parameterType1,parameterValue1[,path2,type2,value2,]...

オペレーション テンプレート

• 500 (保留中の取得)
• 501,typeToSetToExecuting
• 502,typeToSetToFailed,failureReason
• 503,typeToSetToSuccessful,parameters
• 504,operationId
• 505,operationId,failureReason
• 506,operationId,parameters
• 507,typeToSetToExecuting,failureReason
• 510,serial (再起動)
• 511,serial,commandToExecute
• 513,serial,configurationText
• 515,serial,firmwareToBeInstalled,version,url
• 516,serial,softwareToBeInstalled1,version1,url1,sw2,ver2,url2,...
• 517,serial,measurementToBeSent
• 518,serial,relayStatusToBeSet [OPEN/CLOSED]
• 519,serial,relay1Status,relay2Status,...
• 520,serial (現在の構成をアップロード)
• 521,serial,url (構成のダウンロード)
• 522,serial,logFileToBeSend,start,stop,searchText,maxLines
• 523,serial,communicationMode (SMS/IP)
• 524,serial,url,configType
• 525,serial,currentFirmwareName,version,url,dependency
• 526,serial,configType
• 527,serial,firmwareMarker,name,version,url,isPatch,dependency,softwareMarker,name,version,url,action,configurationMarker,url,type
• 528,serial,softwareToBeUpdated1,version1,url1,action1,sw2,ver2,url2,action2,...
• 529,serial,softwareToBeUpdated1,version1,type1,url1,action1,sw2,ver2,type2,url2,action2,...
• 530,serial,hostname,port,connectionKey
• 531,serial,firmwareMarker,name,version,url,isPatch,dependency,softwareMarker,name,version,type,url,action,configurationMarker,url,type
• 532,serial,parameterPath1,parameterType1,parameterValue1[,path2,type2,value2,]...

プラットフォーム機能テンプレート

• 600 (プラットフォームバージョンの取得, 応答: "601, platformVersion")
• 602 (有効なSmartRESTテンプレートIDの一覧の取得, 応答: "603,comma-separated-list-of-SmartREST-template-IDs")

クライアントは s/ds をサブスクライブすることで、以下のテンプレートを受信できます。

インベントリ テンプレート

• 106,child1,child2,…
• 124,id

オペレーション テンプレート

• 510,serial (再起動)
• 511,serial,commandToExecute
• 513,serial,configurationText
• 515,serial,firmwareToBeInstalled,version,url
• 516,serial,softwareToBeInstalled1,version1,url1,sw2,ver2,url2,...
• 517,serial,measurementToBeSent
• 518,serial,relayStatusToBeSet [OPEN/CLOSED]
• 519,serial,relay1Status,relay2Status,...
• 520,serial (現在の構成をアップロード)
• 521,serial,url (構成のダウンロード)
• 523,serial,communicationMode (SMS/IP)
• 524,serial,url,configType
• 525,serial,currentFirmwareName,version,url,dependency
• 526,serial,configType
• 527,serial,firmwareMarker,name,version,url,isPatch,dependency,softwareMarker,name,version,url,action,configurationMarker,url,type
• 528,serial,softwareToBeUpdated1,version1,url1,action1,sw2,ver2,url2,action2,...
• 529,serial,softwareToBeUpdated1,version1,type1,url1,action1,sw2,ver2,type2,url2,action2,...
• 530,serial,hostname,port,connectionKey
• 532,serial,parameterKey1,type1,value1,...

• 601, platformVersion

デバイスの自動作成

静的テンプレート用のトピックは、デバイスの自動作成をサポートしています。MQTT ClientIDに紐づく子が存在しない場合にデータを送信すると、Things Cloud は自動的にそのMQTT ClientIDのデバイスを作成します。ご自身でデバイスを作成したい場合、最初のメッセージはデバイス作成である必要があります。この場合、Things Cloud はテンプレートからデバイスを作成します。

デバイスの自動作成は、第1階層の子デバイスにも対応しています。より深い階層の子デバイスについては、配置先の親デバイスの配下の子デバイスのトピックに、子デバイス作成用テンプレートを送信する必要があります。

任意パラメータの扱い

パラメータが必須でない場合、クライアントはその箇所に空文字列を送信できます。

100,,myType

末尾のカンマは不要です。下記の2行は同じメッセージとなります。

100,,
100

発行用テンプレート

以下のテンプレートは、s/us および t/us のトピックでデータ発行に利用できます。t/ トピック（一時処理データ）については処理モードを参照してください。

インベントリ テンプレート (1xx)

デバイス作成 (100)

インベントリ内にまだ存在しないシリアル番号の新しいデバイスを作成します。タイプが c8y_Serial の外部IDと、MQTT clientIdを値としたデバイス識別子が作成されます。

例

100,myDevice,myType

子デバイス作成 (101)

現在のデバイスの子デバイスを新規作成します。作成されたオブジェクトは子デバイスとして追加されます。また、子デバイスにも c8y_Serial タイプの外部IDが登録され、値はルートデバイスのシリアルとユニークな子IDの組み合わせとなります。

例

101,uniqueChildId,myChildDevice,myChildType,true

サービス作成 (102)

指定したデバイスに新しいソフトウェアサービスを作成します。

例

102,myDatabaseDevice,systemd,DatabaseService,up

サービスステータス更新 (104)

指定したソフトウェアサービスのステータスを設定します。

例

104,up

子デバイス取得 (105)

デバイスの子デバイスを送信するトリガーを発行します。

例

105

デバイスのフラグメント削除 (107)

デバイスから1つ以上のフラグメントを削除します。

例

107,c8y_Position,c8y_Configuration

ハードウェア設定 (110)

デバイスのハードウェア情報を更新します。

例

110,1234567890,myModel,1.2.3

モバイル設定 (111)

デバイスのモバイル情報を更新します。

例

111,1234567890,,54353

位置情報設定 (112)

デバイスの位置情報を更新します。

例

112,50.323423,6.423423

構成設定 (113)

デバイスの設定プロパティを更新します。

例

113,"val1=1\nval2=2"

サポートオペレーション設定 (114)

デバイスがサポートするオペレーションを設定します。

例

114,c8y_Restart,c8y_Configuration,c8y_SoftwareList

ファームウェア設定 (115)

デバイスにインストールされているファームウェアを設定します。

例

115,firmwareName,firmwareVersion,firmwareUrl

ソフトウェアリスト設定 (116)

デバイスにインストールされているソフトウェアのリストを設定します。

例

116,software1,version1,url1,software2,,url2,software3,version3

必要可用性の設定 (117)

可用性監視用の必要なインターバル（分単位の整数値）を設定します。 詳細は デバイス可用性 の c8y_RequiredAvailability を参照してください。 この値は既存でない場合のみ設定されます。UI等で入力された値は上書きされません。

例

117,60

サポートログ設定 (118)

デバイスがサポートするログを設定します。

例

118,ntcagent,dmesg,logread

サポート構成設定 (119)

デバイスがサポートする構成を設定します。

例

119,modbus,system

現在インストール済み構成の設定 (120)

デバイスの現在インストール済み構成を設定します。

例

120,myType,http://www.my.url,config.bin,2020-07-22T17:03:14.000+02:00

適用中のデバイスプロファイル設定 (121)

適用中のデバイスプロファイルを設定します。

例

121,true,8473

デバイスエージェント情報設定 (122)

デバイス上で稼働しているエージェントの情報を提供します。

例

122,thin-edge.io,0.6,https://thin-edge.io,Cumulocity

ハートビート送信 (125)

デバイスからハートビートを送信し、可用性ステータスを更新します。

例

125

高度なソフトウェアリスト設定 (140)

デバイスにインストールされている高度なソフトウェアのリストを設定します。既存リストは上書きされます。

例

140,docker,3.2.1,systemd,https://www.docker.com/,nginx,1.6,container,https://www.nginx.com/

デバイスのマネージドオブジェクトIDの取得 (123)

デバイスのマネージドオブジェクトIDを取得します。

例

123

高度なソフトウェア項目の追加 (141)

既存の高度なソフトウェアリストに項目を追加します。

例

141,docker,3.2.1,systemd,https://www.docker.com/,nginx,1.6,container,https://www.nginx.com/

高度なソフトウェア項目の削除 (142)

既存の高度なソフトウェアリストから項目を削除します。

例

142,docker,3.2.1,nginx,1.6

サポートソフトウェアタイプ設定 (143)

デバイスがサポートするソフトウェアタイプを設定します。空要素は無視されます。空リストはc8y_SupportedSoftwareTypesフラグメントを完全に削除します。

例

143,yum,docker

サポートリモートアクセスプロトコルの設定 (150)

デバイスがサポートするクラウドリモートアクセスプロトコルのリストを設定します。値は SSH,TELNET,VNC,PASSTHROUGH が利用可能です。空要素は無視されます。空リストは c8y_RemoteAccessSupportedProtocols フラグメントを完全に削除します。

例

150,ssh,vnc

メジャーメントテンプレート (2xx)

カスタムメジャーメントの作成 (200)

特定のフラグメントとシリーズでメジャーメントを作成します。

例

200,c8y_Temperature,T,25

複数のフラグメントおよびシリーズによるカスタム測定の作成 (201)

複数のフラグメントおよびシリーズで測定を作成します。

例

201,KamstrupA220Reading,2022-03-19T12:03:27.845Z,c8y_SinglePhaseEnergyMeasurement,A+:1,1234,kWh,c8y_SinglePhaseEnergyMeasurement,A-:1,2345,kWh,c8y_ThreePhaseEnergyMeasurement,A+:1,123,kWh,c8y_ThreePhaseEnergyMeasurement,A+:2,234,kWh,c8y_ThreePhaseEnergyMeasurement,A+:3,345,kWh

信号強度メジャーメントの作成 (210)

c8y_SignalStrength タイプのメジャーメントを作成します。

例

210,-90,23,2016-06-22T17:03:14.000+02:00

温度メジャーメントの作成 (211)

c8y_TemperatureMeasurement タイプのメジャーメントを作成します。

例

211,25,2016-06-22T17:03:14.000+02:00

バッテリーメジャーメントの作成 (212)

c8y_Battery タイプのメジャーメントを作成します。

例

212,95,2016-06-22T17:03:14.000+02:00

アラームテンプレート (3xx)

クリティカルアラームの作成 (301)

クリティカルアラームを作成します。

例

301,c8y_TemperatureAlarm

メジャーアラームの作成 (302)

メジャーアラームを作成します。

例

302,c8y_TemperatureAlarm,"This is an alarm"

マイナーアラームの作成 (303)

マイナーアラームを作成します。

例

303,c8y_TemperatureAlarm

警告アラームの作成 (304)

警告アラームを作成します。

例

304,c8y_TemperatureAlarm,,2013-06-22T17:03:14.000+02:00

既存アラームの重大度の更新 (305)

既存のアラームの重大度を変更します。

例

305,c8y_TemperatureAlarm,CRITICAL

既存アラームをクリアする (306)

既存アラームをクリアします。

例

306,c8y_TemperatureAlarm

アラームのフラグメント削除 (307)

特定タイプのアラームのフラグメントを1つ以上削除します。

例

307,c8y_TemperatureAlarm,c8y_Position,c8y_Configuration

イベントテンプレート (4xx)

基本イベントの作成 (400)

指定されたタイプとテキストのイベントを作成します。

例

400,c8y_MyEvent,"Something was triggered"

位置更新イベントの作成 (401)

c8y_Positionを含む一般的な位置情報更新イベントを作成します。

例

401,51.151977,6.95173,67

デバイス更新を伴う位置更新イベントの作成 (402)

c8y_Position を含む一般的な位置情報更新イベントを作成します。さらに、デバイスは同じ c8y_Position フラグメントで更新されます。

例

402,51.151977,6.95173,67

イベントのフラグメント削除 (407)

特定のタイプのイベントから1つ以上のフラグメントを削除します。

例

407,c8y_MyEvent,c8y_Position,c8y_Configuration

デバイスパラメータ更新イベントの作成 (408)

デバイスのパラメータ更新イベントを作成します。このイベントは常に c8y_ParameterUpdate というタイプになり、ペイロードで指定されたフラグメントおよびプロパティを含みます。change detect が有効の場合、イベント内の指定された状態が当時すでに既知でなかった場合にのみイベントが作成されます。

例

408,,,,c8y_RelayStatus.left,BOOLEAN,true,c8y_RelayStatus.right,BOOLEAN,false

オペレーションテンプレート (5xx)

PENDINGオペレーションの取得 (500)

エージェントに対するすべてのPENDINGオペレーションの送信をトリガーします。

例

500

オペレーションをEXECUTINGに設定 (501)

指定されたフラグメントの最も古いPENDINGオペレーションをEXECUTINGに設定します。

例

501,c8y_Restart

オペレーションをFAILEDに設定 (502)

指定されたフラグメントの最も古いEXECUTINGオペレーションをFAILEDに設定します。

例

502,c8y_Restart,"Could not restart"

オペレーションをSUCCESSFULに設定 (503)

指定されたフラグメントの最も古いEXECUTINGオペレーションをSUCCESSFULに設定します。

デバイスはフラグメントとして送信されたオペレーションのタイプに基づいて、追加のステップをトリガーする追加パラメータを送信できます（オペレーションの更新のセクション参照）。

例

503,c8y_Restart

オペレーションをEXECUTINGに設定 (504)

指定されたIDのオペレーションにEXECUTINGを設定します。オベレーションが存在し、要求元のデバイスをソースとして持つ必要があります。

例

504,123

オペレーションをFAILEDに設定 (505)

指定されたIDのオペレーションにFAILEDを設定します。オベレーションが存在し、要求元のデバイスをソースとして持つ必要があります。

例

505,123,"Could not restart"

オペレーションをSUCCESSFULに設定 (506)

指定されたIDのオペレーションにSUCCESSFULを設定します。オベレーションが存在し、要求元のデバイスをソースとして持つ必要があります。

オペレーションのタイプに基づいて、追加のステップのトリガーとなる追加パラメータをデバイスに送信できるようになります（オペレーションの更新に関するセクションを参照）。

例

506,123

EXECUTINGオペレーションをFAILEDに設定 (507)

指定されたフラグメントを持つEXECUTINGオペレーションをFAILEDに設定します。 フラグメントパラメータが空の場合、すべてのEXECUTINGオペレーションがFAILEDに設定されます。

例

507,c8y_Restart,"Unexpected device restart"

プラットフォーム機能テンプレート (6xx)

プラットフォームバージョンの取得 (600)

プラットフォームバージョンを取得します。プラットフォームがAPIインターフェースをサポートしているか、またはそれらへのリクエストからどのような振る舞いを期待すべきかを評価するために使用されます。

例

600

有効なSmartRESTテンプレートの一覧 (602)

テナントに関連付けられた有効なSmartRESTテンプレートIDの一覧を取得します。

例

602

サブスクライブテンプレート

インベントリテンプレート (1xx)

子デバイスの取得 (106)

デバイスのすべての子デバイスをリストします。

例

106,child1,child2,child3

デバイス管理オブジェクトIDの取得 (124)

デバイス管理オブジェクトID を取得します。

例

124,12345

オペレーションテンプレート (5xx)

すべてのオペレーション応答は同じ基本構造を持ち、messageIdから始まり、その後にオペレーションを処理するルートデバイスまたは子デバイスのIDが続きます。

再起動 (510)

デバイスを再起動します。

例

510,DeviceSerial

コマンド (511)

オペレーションで送信されるコマンドを実行します。

例

511,DeviceSerial,execute this

構成 (513)

オペレーションで送信される構成を設定します。

例

513,DeviceSerial,"val1=1\nval2=2"

ファームウェア (515)

URLからファームウェアをインストールします。

例

515,DeviceSerial,myFirmware,1.0,http://www.my.url

ソフトウェアリスト (516)

オペレーションで送信されたソフトウェアをインストールします。

例

516,DeviceSerial,softwareA,1.0,url1,softwareB,2.0,url2

メジャーメント要求オペレーション (517)

リクエスト名で指定されたメジャーメントを送信します。

例

517,DeviceSerial,LOGA

リレー (518)

リレーを開閉します。

例

518,DeviceSerial,OPEN

リレーリスト (519)

リスト内のリレーを開閉します。

例

519,DeviceSerial,OPEN,CLOSE,CLOSE,OPEN

構成ファイルのアップロード (520)

現在の構成は Things Cloud からデバイスにアップロードされます。

例

520,DeviceSerial

構成ファイルのダウンロード (521)

URLから構成ファイルをダウンロードします。

例

521,DeviceSerial,http://www.my.url

ログファイルの要求 (522)

指定したパラメーターのログファイルをアップロードします。

例

522,DeviceSerial,logfileA,2013-06-22T17:03:14.000+02:00,2013-06-22T18:03:14.000+02:00,ERROR,1000

通信モード (523)

通信モードを変更します。

例

523,DeviceSerial,SMS

タイプで構成ファイルのダウンロード (524)

タイプ の URL から構成ファイルをダウンロードします。

例

524,DeviceSerial,http://www.my.url,type

パッチからのファームウェア (525)

パッチからファームウェアをインストールします。

例

525,DeviceSerial,firmwareName,1.0,http://www.my.url,dependency

タイプで構成ファイルのアップロード (526)

設定は Things Cloud からタイプでデバイスにアップロードされます。

例

526,DeviceSerial,type

デバイスプロファイルの設定 (527)

デバイスプロファイルを設定します。

例

527,DeviceSerial,$FW,firmwareName,1.0,http://www.my.url,true,dependency,$SW,softwareA,1.0,http://www.my.url1,action1,softwareB,2.0,http://www.my.url2,action2,$CONF,http://www.my.url1,type1,http://www.my.url2,type2

ソフトウェアの更新 (528)

デバイスにインストールされているソフトウェアを更新します。

例

528,DeviceSerial,softwareA,1.0,url1,install,softwareB,2.0,url2,install

高度なソフトウェアの更新 (529)

デバイスにインストールされているソフトウェアを更新します。

例

529,DeviceSerial,softwareA,1.0,url1,install,softwareB,2.0,url2,install

クラウドリモートアクセス接続 (530)

リモート アクセス デバイス エージェントによるトンネリングを確立します。

例

530,DeviceSerial,10.0.0.67,22,eb5e9d13-1caa-486b-bdda-130ca0d87df8

ソフトウェアタイプ付きデバイスプロファイルの設定 (531)

ソフトウェアタイプ付きのデバイスプロファイルを設定します。

例

531,DeviceSerial,$FW,firmwareName,1.0,http://www.my.url,true,dependency,$SW,softwareA,1.0,http://www.my.url1,type1,action1,softwareB,2.0,http://www.my.url2,type2,action2,$CONF,http://www.my.url1,type1,http://www.my.url2,type2

パラメータ更新オペレーション (532)

c8y_ParameterUpdate オペレーションが作成されたことをデバイスに通知します。

例

Operation with fragments:

{
  "c8y_ParameterUpdate": {},
  "c8y_ParameterUpdate_MyParameter": {},
  "c8y_ParameterUpdate_DeviceMaintainer": {},
  "c8y_ParameterUpdate_Problems": {},
  "MyParameter": true,
  "DeviceMaintainer": {
    "name": "John Smithsky",
    "contact": "12312"
  },
  "Problems": null
}

Will result in the message:

532,someSerial,MyParameter,b,true,DeviceMaintainer.name,s,John Smithsky,DeviceMaintainer.contact,s,12312,Problems,,

パラメータの最大数は 100 です。これを超えるパラメータを含むオペレーションは、このテンプレートではプッシュできません。

プラットフォーム機能テンプレート (6xx)

プラットフォームバージョンの返却 (601)

600 を使用したリクエスト後にプラットフォームバージョンを返却します。

例

601,2025.0.0

有効なSmartRESTテンプレートの一覧の返却 (603)

602 を使用したリクエストで、利用可能なすべてのSmartRESTテンプレートIDと追加機能の一覧を返却します。

例

603,100,101,102,...,603

オペレーションの更新

テンプレートを使用してオペレーションをSUCCESSFUL状態に設定すると、サーバーで追加の呼び出しをトリガーする追加のパラメータの送信がサポートされます。次の表に、この機能をサポートするオペレーションと、パラメータを使用して実行されるオペレーションを示します。