Connect Thingsee IoT to standard IoT data endpoints

Setup AWS API Gateway for Thingsee Messages

• Setup AWS API Gateway
• Create API Gateway resource and endpoint that can handle HTTP POST method
  • e.g. HTTP POST /thingsee
• Assign AWS Lambda function to the HTTP POST method
• Set up custom authorizer, basic authorisation or no authentication
• Let us know the endpoint and authentication so that we can complete the integration from Thingsee Operations Cloud
• After that, you should start receiving Thingsee Messages to your Lambda function

Example

In this example we will use Serverless framework as deployment tool. The technology stack contains API Gateway with AWS Lambda integration, written in NodeJS

First, make sure you have Node and npm installed

Then, install the Serverless framework:

npm install -g serverless

After that, configure the AWS credential:

serverless config credentials --provider aws --key <AWS_ACCESS_KEY> --secret <AWS_SECRET_ACCESS_KEY> --profile demo-profile --overwrite

Note that the profile name can be anything, later it should match the key profile: inside Serverless template. Then, create a project:

serverless create --template aws-nodejs --path thingsee-integration-service

Navigate to folder "thingsee-integration-service", replace the content of ”serverless.yml” with this:

service: thingsee-integration-service # NOTE: update this with your service name
provider:
  name: aws
  runtime: nodejs8.10
  stage: prod
  region: eu-west-1
  profile: demo-profile # This should match the profile you specified earlier
functions:
  ThingseePost:
    handler: handler.thingseePost
    events:
      - http:
          path: thingsee
          method: post
          authorizer: Authorizer
  Authorizer:
    handler: handler.authorizer

Then, replace content of ”handler.js” with this:

'use strict';

module.exports.thingseePost = async (event, context) => {
  const thingseeData = event.body;
  console.log('Thingsee data: ', thingseeData);
  // Do something with thingseeData...
  return {
    statusCode: 200,
    body: 'OK',
  };
};

// Policy helper function
const buildIamPolicy = (principalId, effect, event) => {
  const resource = event.methodArn;
  const policy = {
    principalId,
    policyDocument: {
      Version: '2012-10-17',
      Statement: [
        {
          Action: 'execute-api:Invoke',
          Effect: effect,
          // Resource: arn:aws:execute-api:{region}:{accountId}:{apiId}/{stage}/*
          Resource: `${resource.split(event.httpMethod)[0]}*`,
        },
      ],
    },
  };

  return policy;
};

module.exports.authorizer = (event, context, callback) => {
  if (!event.authorizationToken) {
    // Not supply Authorization header
    return callback('Unauthorized');
  }

  const [tokenType, tokenValue] = event.authorizationToken.split(' ');

  if (tokenType.toLowerCase() !== 'bearer') {
    // Authorization type is not Bearer
    return callback('Unauthorized');
  }

  if (tokenValue !== 'FOO') {
    // 'FOO' is just an example token, replace it with your token
    // Invalid token
    return callback('Unauthorized');
  }

  return callback(null, buildIamPolicy('exampleUser', 'Allow', event));
};

Congrats, you finish the API! Now you need to deploy it, inside the "thingsee-integration-service" folder, run:

serverless deploy -v

Take a look at the output, it’s going to have something like this:

endpoints:
  POST - https://xxxxxx.execute-api.eu-west-1.amazonaws.com/prod/thingsee

Send us that endpoint, and provide us your Authorization Token (of course it should not be "FOO"..)

After that is done, you should start receiving following JSON arrays (example) to your API Gateway. Please be aware that the messages come always as JSON arrays, and you need to parse the objects preferably by tsmId-field so that you know what properties to expect.

[
  {
      "tsmId": 12101,
      "tsmEv": 10,
      "hall": 0,
      "hallCount": 0,
      "tsmTs": 1520416221,
      "tsmTuid": "XXXX03X2Z80562557",     // unique sensor device id
      "tsmGw": "XXXX00EFS80560445",      // unique gateway device id
  },
  {
      "tsmId": 1110,
      "tsmEv": 10,
      "batl": 100,
      "tsmTs": 1520416221,
      "tsmTuid": "XXXX03X2Z80562557",
      "tsmGw": "XXXX00EFS80560445",
  },
  {
      "tsmId": 12100,
      "tsmEv": 10,
      "airp": 101364.599,
      "lght": 6,
      "temp": 21.3,
      "humd": 21.7,
      "tsmTs": 1520416221,
      "tsmTuid": "XXXX03X2Z80562557",
      "tsmGw": "XXXX00EFS80560445",
  },
  {
      "tsmId": 1111,
      "tsmEv": 10,
      "accx": -1024,
      "accy": 64,
      "accz": -192,
      "tsmTs": 1520416221,
      "tsmTuid": "XXXX03X2Z80562557",
      "tsmGw": "XXXX00EFS80560445",
  }
]