SORACOM Developers

Documents

SORACOM Funnel function detail

In this guide, we will explain SORACOM Funnel (Funnel) from the technical point of view in detail.

What is Funnel

Funnel is an adapter that transfers data from a device directly to a specific cloud service.

By simply specifying resources on the cloud service, you can collect data directly from the device. The big difference with SORACOM Beam is that the destination is not a general-purpose protocol, but you can use the cloud service quickly with minimal effort. Please refer to SORACOM Funnel for service overview and Getting Started for usage.

Configuration overview

Funnel can be used from the SIM belonging to the group by making the following settings for the group.

configuration

Corresponding cloud service (resource type)

This is a list of cloud services that can be selected as the data transmission destination.

Communication protocol

A list of protocols that can be used when sending data from the device to the Funnel entry point.

Each protocol will be explained in more detail below.

HTTP

Send data sent by HTTP POST request as one data to cloud service.

Request

The request format conforms to the usual POST method. Acceptable Content - Type headers are the following three types.

Response

Based on the request sent, the following response is returned to the device.

Below is an example of data transmission when JSON is selected as the format of data to be transmitted.

$ curl -v -d '{"key":"value"}' -H 'Content-Type: application/json' http://funnel.soracom.io
* Rebuilt URL to: http://funnel.soracom.io/
*   Trying 100.127.65.43...
* Connected to funnel.soracom.io (100.127.65.43) port 80 (#0)
> POST / HTTP/1.1
> Host: funnel.soracom.io
> User-Agent: curl/7.49.0
> Accept: */*
> Content-Type: application/json
> Content-Length: 15
>
* upload completely sent off: 15 out of 15 bytes
< HTTP/1.1 204 No Content
< Date: Tue, 06 Dec 2016 16:19:37 GMT
< Connection: keep-alive

TCP

Send one packet of TCP sent (strictly one TCP segment) as one data to the cloud service.

Request

The maximum transmission data size per request is based on the TCP fragment size. Although it is 65,536 bytes on the specification of TCP, it is actually affected by the MTU of the network path, so please note that it is around 1500 bytes.

Response

TCP has no concept of request & response like HTTP, so a TCP packet containing the code and message described in the following Body as a payload is returned from the Funnel entry point.

Below is an example of data transmission when JSON is selected as the format of data to be transmitted.

# Establish TCP session with Funnel entry point
$ nc -v funnel.soracom.io 23080
found 0 associations
found 1 connections:
     1: flags=82<CONNECTED,PREFERRED>
    outif en0
    src 192.168.43.232 port 51053
    dst 100.127.65.43 port 23080
    rank info not available
    TCP aux info available

Connection to funnel.soracom.io port 23080 [tcp/*] succeeded!

# Sneding JSON
(request) {"key":"value"}
(response) 200

# Sending invalid JSON
(request) bad text
(response) 400 Invalid JSON is send to funnel.

UDP

Send one packet of TCP sent (strictly TCP segment) to the cloud service as one piece of data.

Request

The maximum transmission data size per request is 65,536 bytes on the specification because it conforms to the maximum size of the UDP datagram, but please be aware that it will actually be around 1500 bytes because it will be affected by the MTU of the network path.

Response

Since there is no concept of request & response like UDP in UDP, a UDP packet containing the code and message described in the following Body as payload is returned from the Funnel entry point.

Below is an example of data transmission when JSON is selected as the format of data to be transmitted.

# Start up UDP client and check connectivity with entry point
$ nc -v -u funnel.soracom.io 23080
found 0 associations
found 1 connections:
     1: flags=82<CONNECTED,PREFERRED>
    outif (null)
    src 192.168.43.232 port 61136
    dst 100.127.65.43 port 23080
    rank info not available

# Connection success. Nc sends a UDP datagram for connection confirmation. (If JSON is specified as the data format, format error will be returned (but no problem))
Connection to funnel.soracom.io port 23080 [udp/*] succeeded!
(response) 400 Invalid JSON is send to funnel.
(response) 400 Invalid JSON is send to funnel.
(response) 400 Invalid JSON is send to funnel.
(response) 400 Invalid JSON is send to funnel.


# Sending JSON
(request) {"key":"value"}
(response) 200

# Sending invalid JSON
(request) bad text
(response) 400 Invalid JSON is send to funnel.

Entry point

The entry point is the destination of data sent from the device to the Funnel. The following entry points are prepared for each protocol.

Protocol Entry point
HTTP http://funnel.soracom.io
TCP funnel.soracom.io:23080
UDP funnel.soracom.io:23080

Data sent to the cloud service

The data sent to the cloud service has the following format.

{
    "operatorid": "SORACOM account ID",
    "timestamp": "Date and time when Funnel received data (unix time)",
    "destination" : {
        "resourceUrl": "Destination cloud service URL",
        "service": "(aws-iot|kinesis|firehose|eventhubs|pubsub)",
        "provider":"(aws|azure|google)"
    },
    "credentialId": "ID of SORACOM's authentication information",
    "payloads": "The transmitted data body",
    "sourceProtocol": "(tcp|udp|http|unspecified)",
    "imsi": "The IMSI of the source SIM"
}

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