Soracom Inventory

Resource Observation

When you observe a device resource, the device agent will notify the Inventory Device Management server whenever that resource's value changes. You can control how that notification is handled, by combining Inventory with Beam, Funnel, or Funk to forward the notification to your private server or cloud service, or with Harvest to capture the resource value.

Because the device agent will only send a notification when the value changes, this provides a power- and data-efficient method of receiving notifications or monitoring device information without utilizing periodic polling techniques.

Forwarding Data with Beam

Configuration

To enable Beam for Inventory devices:

  1. Login to the User Console. From the Menu, open the Device Groups screen.

  2. From the list of groups, click the name of the group you want to configure to open its settings page.

  3. From the Basic Settings tab, click the SORACOM Beam panel to expand its settings.

  4. Click the button and select the Inventory → HTTP/HTTPS entry point.

  5. Enter the Beam configuration, then click the Save button.

    The Inventory → HTTP/HTTPS entry point configuration follows the same parameters as the Beam HTTP entry point. Refer to the HTTP Entry Point documentation for more information.

Once saved, Inventory will relay notifications to Beam, which will then forward the notification to your forwarding destination.

Resource Notification Format

The Inventory → HTTP/HTTPS entry point will forward resource data using the following format:

HTTP request header:

{
  "host": "xxxxxxx.com",
  "connection": "close",
  "content-type": "application/json",
  "x-soracom-timestamp": "1524554877520",
  "x-soracom-device-id": "d-abcdef00000012345678",
  "x-soracom-operator-id": "OP0012345678",
  "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"
}

HTTP request body:

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

Forwarding Data with Funnel

Configuration

To enable Funnel for Inventory devices:

  1. Login to the User Console. From the Menu, open the Device Groups screen.

  2. From the list of groups, click the name of the group you want to configure to open its settings page.

  3. From the Basic Settings tab, click the SORACOM Funnel panel to expand its settings.

  4. Enable Funnel by switching the option to ON.

  5. Enter the Funnel configuration, then click the Save button.

    Refer to the Funnel Configuration documentation for more information.

Once saved, Inventory will relay notifications to Funnel, which will then forward the notification to your cloud service.

Resource Notification Format

When Inventory receives a notification for a resource, it will forward resource data using the following format:

{
  "operatorId": "OP0012345678",
  "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-abcdef00000012345678",
    "resources": {
      "13": {
        "name": "Current Time",
        "value": "Apr 24, 2018 6:36:01 AM"
      }
    }
  },
  "sourceProtocol": "device",
  "deviceId": "d-abcdef00000012345678"
}

Instance Notification Format

When Inventory receives a notification for an instance, it will forward all resource data within that instance using the following format:

{
  "operatorId": "OP0012345678",
  "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-abcdef00000012345678",
    "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-abcdef00000012345678"
}

Collecting Data with Harvest

Configuration

To enable Harvest for Inventory devices:

  1. Login to the User Console. From the Menu, open the Device Groups screen.

  2. From the list of groups, click the name of the group you want to configure to open its settings page.

  3. From the Basic Settings tab, click the SORACOM Harvest panel to expand its settings.

  4. Enable Harvest by switching the option to ON. Then click the Save button.

Resource Notification Format

When Inventory receives a notification for an resource, it will send the resource data to Harvest using the following format:

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