SORACOM Developers

SORACOM Harvest Getting Started

Using SORACOM Harvest to collect and acquisition and visualization in the cloud for data of the device

Overview

SORACOM Harvest (below, Harvest) and is a data collection and visualization services from the IoT device. Using cellular communication provided by SORACOM Air, you can easily upload sensor data etc of IoT device to cloud without trouble. The uploaded data will be stored on the SORACOM platform for 40 days. You can graph the saved data at SORACOM’s userconsole.

Getting Started

In this document, Harvest is used to store the data of the device in the cloud and to take the data by API. It also describes how to visualize data in the userconsole. There are three steps from setup to setup.

The premise of this guide is as follows.

Step 1: Storing device data in Harvest

Harvest can start accumulating data as soon as Harvest is enabled at the user console etc .. When sending data from the device communicating from Air SIM to the entry point of Harvest, IMSI of the sender Air SIM and time stamp are automatically given and the data is saved on the SORACOM platform.

The main specifications are as follows.

Item
Data transmission protocol HTTP, TCP, UDP
Maximum data size that can be transmitted at one time 1 KB
Data retention period 40 days
Encryption function on Harvest side None
(If encryption is required, please handle it on the client side)
HTTP entry point (HTTP) http://harvest.soracom.io
TCP, UDP entry point (TCP, UDP) harvest.soracom.io:8514

Activate Harvest

In order to activate Harvest, you set it by user console, soracom-cli, API.

Attention
Harvest is a paid service. A basic fee will be generated per SIM with Harvest enabled. For details, please check the price page .

How to set it in the user console

SORACOM Harvest is set in groups. Therefore, in order to use Harvest, you need to register Air SIM in the group. For this time, let’s create a dedicated group to check the operation of SORACOM Harvest and register Air SIM there.

First open the Air SIM management screen and check the Air SIM you want to communicate with SORACOM Harvest. Then select [Change group] from the [Action] button.

A dialog for selecting the group to which Air SIM belongs is displayed, so select [Create …] from the [New group] dropdown.

The following group creation dialog is displayed. Enter the name of the group and click the [Create a new group] button. Let’s create it with the group name “hello harvest” this time.

Click the [Create Group] button to return to the original [Update selected subscribers group] dialog. Make sure the [New group] drop box is set to the hello harvest group you just created and press the [Update] button.

We will set up SORACOM Harvest for the hello harvest group we created earlier. To do the setting, open the group management screen, select the hello harvest group and open the group details screen.

Click the switch in the [SORACOM Harvest setting] group, change it to ON, and click the Save button.

Harvest setting

How to set with soracom-cli

You can enable Harvest by the following command.

$ soracom groups put-config --group-id ${group_-d} --namespace SoracomHarvest --body '[{"key":"enabled","value":true}]'

How to set with API

To enable the setting in the API, use the putConfigurationParameters API to set it as part of Group Config. Please send HTTP PUT request as follows.

$ curl -X PUT \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-Soracom-API-Key: ${API-KEY}' \
-H 'X-Soracom-Token: ${API-TOKEN}' \
-d '[{"key":"enabled","value":true}]' \ 'https://api.soracom.io/v1/groups/{group_id}/configuration/SoracomHarvest'

Sending data via HTTP

When sending data via HTTP, please send an HTTP POST request to the Harvest entry point. Also, specify the data type with content-type.

Command example:

$ curl -v -X POST \
 -H 'content-type:application/json' \
 -d '{"temperature":20}' \
 http://harvest.soracom.io

Send data with TCP, UDP

Please send data to Harvest entry point as well as HTTP in TCP and UDP. For easy testing, the telnet command is useful.

$ telnet {Harvest entry point} 8514
Trying 100.127.127.100...
Connected to 100.127.127.100.
Escape character is '^]'.

hello
201
^]

telnet> quit
Connection closed.

Step 2: Acquire data accumulated in Harvest

To get the data (download), you can use the soracom-cli or API.

How to use the soracom-cli

You can get data by the following command.

$ soracom data get --imsi ${IMSI} --coverage-type ${coverage_type}

How to use the API

Send a GET request to the API endpoint as follows. When acquiring data, please specify the IMSI of the SIM from which data was sent.

$ curl -X GET \
  -H "X-Soracom-API-Key: ${API-KEY}" \
  -H "X-Soracom-Token: ${API-TOKEN}" \
https://api.soracom.io/v1/subsribers/${IMSI}/data | jq .

[
  {
    "time": 1479350871000,
    "contentType": "application/json",
    "content": "{\"temperature\":20}"
  },
  {
    "time": 1479350881000,
    "contentType": "application/json",
    "content": "{\"temperature\":25}"
  },
  {
    "time": 1479350891000,
    "contentType": "application/json",
    "content": "{\"temperature\":20}"
  }
]

Note
When sending data to Harvest via TCP or UDP, its contents are Base64 encoded and incorporated into JSON.

Step 3: Visualize data accumulated in Harvest

First open the Air SIM management screen and check the air SIM that communicated by SORACOM Harvest. Next, select [Harvest data] from the [Action] button.

SIM list

The data is not loaded in the state where the screen has changed. When you press the [Search] button, the saved data will be displayed.

Step 4: Disable Harvest

Harvest is a paid service. You can disable harvest by the following steps.

How to set with the User Console

How to set with soracom-cli

you can disable Harvest by the following command.

$ soracom groups put-config --group-id ${group_-d} --namespace SoracomHarvest --body '[{"key":"enabled","value":false}]'

Getting Started

SORACOM Air for Cellular

SORACOM Air for Sigfox

SORACOM Beam

SORACOM Canal/Direct/Door

SORACOM Endorse

SORACOM Funnel

SORACOM Gate

SORACOM Harvest

SORACOM Inventory

SORACOM Junction

SORACOM Krypton

SORACOM Lagoon

Service Detail

Developer Tools

pagetop