Soracom Funk

Overview

Soracom Funk is an adapter service that sends data from a device directly to a cloud service function for processing. Funk allows you to greatly simplify the logic embedded on a device, reducing device-side resource consumption, and instead handle data in the cloud without setting up complex server environments.

Soracom Funk Overview

Funk can take data sent from Cellular, Sigfox, and LoRaWAN devices through TCP, UDP, HTTP, SMS, USSD, and LPWA protocols, and send the data to major FaaS (function-as-a-service) providers, without any complicated setup.

By removing data processing logic from the device and placing it in a FaaS provider, the hardware design of devices can be simplified and energy efficiency vastly increased.

In addition, Funk is capable of returning the data after it is processed by the FaaS provider directly back to the device, for use cases where device behavior should adjust according to the input data.

By performing data processing through the cloud FaaS provider, processing techniques can also be easily modified without the need to push updates to devices. This allows you to trivially switch between development and production environments, each with their own data processing and logging requirements, without modifying any logic embedded on the device.

Available Adapters

Currently, Funk is compatible with the following cloud function services:

Funk is runtime agnostic. You can use any runtime provided by each cloud function service.

Entry Points

To utilize Funk, your devices must be compatible with at least one of the following entry point protocols:

Air for Cellular

Entry Point Address Description
TCP tcp://funk.soracom.io:23080 Receive TCP packets from a device and forward them to your cloud function
UDP udp://funk.soracom.io:23080 Receive UDP packets from a device and forward them to your cloud function
HTTP http://funk.soracom.io Receive HTTP requests from a device and forward them to your cloud function
SMS 901041 Receive SMS messages from a device and forward them to your cloud function
USSD *901041*{data}# Receive USSD messages from a device and forward them to your cloud function

Air for Sigfox and Air for LoRaWAN

Data is captured automatically from the device. Configuring the device to send data to a specific entry point is not required.

Soracom Inventory

Data is captured automatically from the device. Configuring the device to send data to a specific entry point is not required.

Data Formats

When Funk receives data from your device, the way it sends the data to your cloud function depends on which cloud function service provider you have selected.

AWS Lambda

When data is sent to an AWS Lambda function, the request will contain two parameters which your function can access:

Azure and Google Cloud Functions

When data is sent to Azure Functions or Google Cloud Functions, it will be sent as an HTTP request with the following properties:

The X-Soracom-Token header will contain a value that looks something like this:

eyJraWQiOiJ2MS1hYmNkZWYwMDAwMDAwMDAwMDAwMDAwMDAxMjM0NTY3OC14NTA5LnBlbSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJodHRwczovL3NvcmFjb20uaW8iLCJhdWQiOiJzcm46c29yYWNvbTpPUDAwMTIzNDU2Nzg6ZzpTdWJzY3JpYmVyOjI5NTAwMDAxMjM0NTY3OCIsImp0aSI6ImhrSzdxTnlYekVNVkFYZlRxMU1CdUEiLCJpYXQiOjE1NTg2NzM0MzcsInR5cCI6InNvcmFjb20vdG9rZW4vdjEiLCJzdWIiOiJmdW5rLnNvcmFjb20uaW8iLCJjdHgiOnsic3JuIjoic3JuOnNvcmFjb206T1AwMDEyMzQ1Njc4Omc6U3Vic2NyaWJlcjoyOTUwMDAwMTIzNDU2NzgiLCJvcGVyYXRvcklkIjoiT1AwMDEyMzQ1Njc4Iiwic291cmNlUHJvdG9jb2wiOiJodHRwIiwicmVzcm91Y2VJZCI6IjI5NTAwMDAxMjM0NTY3OCIsInJlc3JvdWNlVHlwZSI6IlN1YnNjcmliZXIiLCJpbXNpIjoiMjk1MDAwMDEyMzQ1Njc4In19.abcdef******************12345678

The string contains three sections, each separated by a .. These sections make up the JWT token format: {HEADER}.{PAYLOAD}.{SIGNATURE}.

Both the Header and Payload sections are Base64-encoded strings. If we extract the Payload section and decode it, we get the following data:

{
  "iss": "https://soracom.io",
  "aud": "srn:soracom:OP0012345678:global:Subscriber:295000012345678",
  "jti": "hkK7qNyXzEMVAXfTq1MBuA",
  "iat": 1558673437,
  "typ": "soracom/token/v1",
  "sub": "funk.soracom.io",
  "ctx": {
    "srn": "srn:soracom:OP0012345678:global:Subscriber:295000012345678",
    "operatorId": "OP0012345678",
    "sourceProtocol": "http",
    "resrouceId": "295000012345678",
    "resrouceType": "Subscriber",
    "imsi": "295000012345678"
  }
}

The ctx key contains additional context information that can be used in the function to identify the device type and the device itself when processing data.

To verify the authenticity of the token, we can similarly decode the Header section to get the following data:

{
  "kid": "v1-abcdef00000000000000000012345678-x509.pem",
  "alg": "RS256"
}

This data tells us which key Funk used to sign the token. The public keys used for verifying signatures are stored on the Soracom Endorse Public Key repository: https://s3-ap-northeast-1.amazonaws.com/soracom-public-keys/.

For our sample key, we would download the following file:

https://s3-ap-northeast-1.amazonaws.com/soracom-public-keys/v1-abcdef00000000000000000012345678-x509.pem

We can then use the public key to verify the Signature section of the token:

RSASHA256(
  "{BASE64-ENCODED-HEADER}.{BASE64-ENCODED-PAYLOAD}",
  "{CONTENTS-OF-v1-abcdef00000000000000000012345678-x509.pem-FILE}"
)

If the signature in the token matches the signature calculated using the downloaded public key, then we can verify that the token has not been altered and that the request originates from a device in your account, and allow the function to continue processing the device data.

While the JWT format is relatively straightforward, we recommend using a verified library when implementing a verification process in your function, in order to avoid security risks with untested or unverified implementations.

Error Handling

If a FaaS provider returns an error response, the response is also sent back to the device. This allows you to implement error handling if needed.

When using Funk through Unified Endpoint, an error response received from the FaaS may look something like this:

{
  statusCode: 207,
  body: { 
    "result": "ng",
    "detail": { 
      "beam": { statusCode: 200, body: "..." },
      "funnel": { statusCode: 204, body: "..." },
      "funk": { statusCode: 400, body: "..." },
      "harvest": { statusCode: 200, body: "..." }
    }
  }
}

Testing

To test your function's behavior, you can use the testing features provided by your cloud function provider. For example, when using AWS Lambda, you can create test event templates and execute your function with the event template in order to simulate sending data from your device.

Limitations

Free Tier

Soracom provides a free tier for Funk with each Soracom account. Refer to the Pricing & Fee Schedule for more information.