Send data from a device to a cloud service function

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.

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:

• AWS Lambda
• Azure Functions
• Google Cloud Functions

Entry Points

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

Air for Cellular

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:

• event – An object representing the event or trigger that invokes the Lambda function, containing the data sent from your device in the body value, in the data format or content type specified (JSON, text, or binary).
• context – An object containing additional information about the Lambda function invocation. Funk will set data related to the device which triggered the function call, which can be used by the Lambda function during processing:

{ 
  "custom": { 
    "operatorId": "OP0012345678", 
    "sourceProtocol": "http", 
    "resourceId": "295000012345678", 
    "resourceType": "Subscriber", 
    "srn": "srn:soracom:OP0012345678:global:Subscriber:295000012345678", 
    "imsi": "295000012345678", 
    "imei": "800000012345678" 
  } 
} Code language: JSON / JSON with Comments (json)

The payload of the context parameter will vary depending on which device type (cellular, Sigfox, LoRaWAN, or Inventory) is calling the function.

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:

• HTTP method – POST
• HTTP request body – The data sent from your device, in the data format or content type specified (JSON, text, or binary).
• HTTP headers – The HTTP request will include the following headers:
  • User-Agent – SORACOM Funk
  • Content-Type – application/json
  • X-Soracom-Token – A JSON Web Token (JWT) which can be used to identify and authenticate the device before performing any processing.

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

eyJraWQiOiJ2MS1hYmNkZWYwMDAwMDAwMDAwMDAwMDAwMDAxMjM0NTY3OC14NTA5LnBlbSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJodHRwczovL3NvcmFjb20uaW8iLCJhdWQiOiJzcm46c29yYWNvbTpPUDAwMTIzNDU2Nzg6ZzpTdWJzY3JpYmVyOjI5NTAwMDAxMjM0NTY3OCIsImp0aSI6ImhrSzdxTnlYekVNVkFYZlRxMU1CdUEiLCJpYXQiOjE1NTg2NzM0MzcsInR5cCI6InNvcmFjb20vdG9rZW4vdjEiLCJzdWIiOiJmdW5rLnNvcmFjb20uaW8iLCJjdHgiOnsic3JuIjoic3JuOnNvcmFjb206T1AwMDEyMzQ1Njc4Omc6U3Vic2NyaWJlcjoyOTUwMDAwMTIzNDU2NzgiLCJvcGVyYXRvcklkIjoiT1AwMDEyMzQ1Njc4Iiwic291cmNlUHJvdG9jb2wiOiJodHRwIiwicmVzcm91Y2VJZCI6IjI5NTAwMDAxMjM0NTY3OCIsInJlc3JvdWNlVHlwZSI6IlN1YnNjcmliZXIiLCJpbXNpIjoiMjk1MDAwMDEyMzQ1Njc4In19.abcdef******************12345678Code language: CSS (css)

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"
  }
}Code language: JSON / JSON with Comments (json)

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"
}Code language: JSON / JSON with Comments (json)

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.pemCode language: JavaScript (javascript)

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}"
)Code language: JavaScript (javascript)

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: "..." }
    }
  }
}Code language: CSS (css)

Limitations

When using Funk with Sigfox and LoRaWAN devices, processed data cannot be returned to the device.