SORACOM Developers

SORACOM Inventory : 機能の説明

SORACOM Inventory で使用する用語

Resource model - Inventory ではデバイス上の情報を「Resource Model(リソースモデル)」という形式で管理しています。Resource Modelは LwM2M で規定されており、Object、Object Instance、Resourceのツリー構造になっています。各要素には番号が割り当てられ、/3/0/0 のようになります。

Agent - Inventory での管理対象のデバイスで動作する実行可能なバイナリもしくはSDKです。管理対象のデバイスは当Agentが動作していることが必須となります。

Bootstrap - Inventory を利用するにあたり、最初に行われるデバイス登録と鍵交換です。Bootstrapが完了すると、デバイスが Inventory に登録され、ユーザーコンソールのデバイス一覧に表示されるようになります。また、Wifiや有線などのインターネット経由でデバイス管理(デバイス情報の読み書き、実行)が可能になります。

Inventoryの仕組みと構成

Inventory では、デバイス管理の仕組みとしてOMA DM LwM2M(以下、LwM2M)を利用します。

コアとなるコンポーネントは、以下の3つです。

Bootstrap Server は主にデバイスとの接続確立のための認証情報の確認や鍵の交換などの機能を提供します。 Device Management Server は Inventory のサーバーコンポーネントとして、主要な機能の多くを提供するコンポーネントです。 Agentは実行可能なバイナリもしくはSDKとして提供され、デバイス上でAgentとして動作し、Bootstrap Server、Device Management Serverとの通信します。

Inventory を利用するにあたって、最初に行われる処理はSORACOMプラットフォームへのデバイス登録と鍵交換(bootstrap)です。認証を行うために Air SIM で通信を行い、デバイス上のAgentでbootstrapを実行します。このとき、Agent は Bootstrap Server と通信を行い、デバイスの情報を SORACOM のプラットフォームに登録すると共に今後の通信のために鍵交換を行います。bootstrapが完了すると、デバイスが Inventoryに登録され、ユーザーコンソールのデバイス一覧に表示されるようになります。

Inventoryに登録済みのデバイスは、ユーザーコンソールやAPIを使ってデバイス上のデータの読み書き(Read, Write)をしたり、デバイス側で値に変化があったら通知を受けたり(Observe)、コマンドを実行(Execute)したりするために、Agentを通じて Device Management Server と通信を行います。最初に行った bootstrap の段階でデバイスの認証や鍵交換しているため、bootstrap 済みのデバイスはWiFi などで通信していてもInventoryを使ってデバイスをリモート管理できます。

リソースモデル

Inventoryではデバイス上の情報を「Resource Model」という形式で管理しています。リソースモデルはLwM2Mで規定されており、オブジェクト(Object)、オブジェクトインスタンス(Object Instance)、リソース(Resource)のツリー構造になっています。各要素には番号が割り当てられ、 /3/0/0 のように表現できます。

例えば /3/0/0 はデバイスの製造元(Manufacturer)を表すリソースであり、Agentはサーバーからの Readリクエストに対して、自分の製造元情報を返します。また、 /3/0/4 は (Reboot) を表します。このExecute リクエストがDevice Management Serverから送信されると、デバイス自身の再起動が行われます。

定義済みのリソースモデルは、OMA LightweightM2M (LwM2M) Object and Resource Registryから確認できます。

なお、LwM2Mでは、リソースへのオペレーション呼び出しとレスポンスが定義されています。呼び出されたオペレーションの動作はAgent側で実装します。例えば、先に挙げた例の /3/0/0(製造元情報)へのReadに対して、どのように製造元情報を取得するかについてはAgentの実装に任されています。 ソラコムでは、参照実装として以下のAgentを提供しています。

カスタムオブジェクト

LwM2M Registryに多くのリソースが定義されていますが、独自に定義できます。(カスタムオブジェクト) カスタムオブジェクトはXML, JSONで定義します。 以下は、 ObjectID 30000 で定義した例となります。

カスタムオブジェクト定義の例(XML)

<?xml version="1.0" encoding="UTF-8"?>
<LWM2M xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://openmobilealliance.org/tech/profiles/LWM2M.xsd">
    <Object ObjectType="MODefinition">
        <Name>Custom Model</Name>
        <Description1>Custom model</Description1>
        <ObjectID>30000</ObjectID>
        <ObjectURN>urn:oma:lwm2m:oma:30000</ObjectURN>
        <MultipleInstances>Single</MultipleInstances>
        <Mandatory>Optional</Mandatory>
        <Resources>
            <Item ID="0">
                <Name>CurrentX</Name>
                <Operations>R</Operations>
                <MultipleInstances>Single</MultipleInstances>
                <Mandatory>Mandatory</Mandatory>
                <Type>Float</Type>
                <RangeEnumeration />
                <Units>m</Units>
                <Description>Current location in X.</Description>
            </Item>
            <Item ID="1">
                <Name>TargetX</Name>
                <Operations>RW</Operations>
                <MultipleInstances>Single</MultipleInstances>
                <Mandatory>Mandatory</Mandatory>
                <Type>Float</Type>
                <RangeEnumeration />
                <Units>m</Units>
                <Description>Target location in X.</Description>
            </Item>
            <Item ID="2">
                <Name>Execute Command</Name>
                <Operations>E</Operations>
                <MultipleInstances>Single</MultipleInstances>
                <Mandatory>Mandatory</Mandatory>
                <Type />
                <RangeEnumeration />
                <Units />
                <Description>Execute command.</Description>
            </Item>
        </Resources>
        <Description2 />
    </Object>
</LWM2M>

当定義をコンソールから保存することで、ユーザーコンソールからカスタムオブジェト、リソース名を表示できます。 カスタムオブジェクトを定義する場合、これに対応したクライアントエージェントの実装も必要となります。

クライアントエージェントの実装については、エージェントのReadmeを参照ください。

SORACOM アプリケーションサービスを利用したクラウド連携

デバイスグループの設定により、SORACOM Beam、Funnel、Harvest を利用できます。 デバイスがデバイスグループに所属している必要があります。また、Observeした属性が各サービスに転送される対象になります。

デバイスグループ設定

Beamの場合のフォーマット

Beamでは、HTTPもしくはHTTPSで転送されます。 フォーマットは以下のとおりです。

Header

{
  "host": "xxxxxxx.com",
  "connection": "close",
  "content-type": "application/json",
  "x-soracom-timestamp": "1524554877520",
  "x-soracom-device-id": "d-vlqqxxxxxxxxxxxxxxx",
  "x-soracom-operator-id": "OP0000000000",
  "transfer-encoding": "chunked",
  "x-request-id": "feexxxxxxxxxxx-xxxxxxxxxx",
  "x-forwarded-for": "13.112.xxx.xxx",
  "x-forwarded-proto": "https",
  "x-forwarded-port": "443",
  "via": "1.1 vegur",
  "connect-time": "0",
  "x-request-start": "1524554879323",
  "total-route-time": "0"
}

Body

{
  "deviceId": "d-vlqqxxxxxxxxxxxxxxx",
  "path": "/3/0",
  "lastModifiedTime": 1524554897553,
  "resources": {
    "13": {
      "name": "Current Time",
      "value": "Apr 24, 2018 7:28:17 AM"
    }
  }
}

Funnelの場合のフォーマット

ResourceをObserveした時は以下の通りとなります。(Resource1つずつ送信されます。)

/3/0/13 をObserveした場合の例

 {
   "operatorId": "OP0000000000",
   "timestamp": 1524551762283,
   "destination": {
     "resourceUrl": "https://xxxxx.us-west-2.amazonaws.com/my-kinesis-firehose",
     "service": "firehose",
     "provider": "aws"
   },
   "credentialsId": "aws-credentials",
   "payloads": {
     "path": "/3/0",
     "lastModifiedTime": "1524551761992",
     "deviceId": "d-vlqqxxxxxxxxxxxxxx",
     "resources": {
       "13": {
         "name": "Current Time",
         "value": "Apr 24, 2018 6:36:01 AM"
       }
     }
   },
   "sourceProtocol": "device",
   "deviceId": "d-vlqqxxxxxxxxxxxxxx"
 }

ObjectInstanceをObserveした場合は、以下のようなフォーマットで送信されます。

/6/0 をObserveした場合の例

{
   "operatorId": "OP0000000000",
   "timestamp": 1524551772514,
   "destination": {
     "resourceUrl": "https://xxxxx.us-west-2.amazonaws.com/my-kinesis-firehose",
     "service": "firehose",
     "provider": "aws"
   },
   "credentialsId": "aws-credentials",
   "payloads": {
     "path": "/6/0",
     "lastModifiedTime": "1524551771914",
     "deviceId": "d-vlqqxxxxxxxxxxxxxx",
     "resources": {
       "1": {
         "name": "Longitude",
         "value": 65.1006164550781
       },
       "0": {
         "name": "Latitude",
         "value": 56.1010437011719
       },
       "5": {
         "name": "Timestamp",
         "value": "Apr 24, 2018 6:36:11 AM"
       }
     }
   },
   "sourceProtocol": "device",
   "deviceId": "d-vlqqxxxxxxxxxxxxxx"
}

Harvestの場合のフォーマット

Harvestの場合、リソース名(パス)、値が以下のように送信されます。

{ 
    "Example resource (/3303/0/5757)": 123,
     "Example resource2 (/3303/0/5758)": 456
}
pagetop