Thing Providers

Version 1.9.8

Last updated: 2018-09-05

Overview

Follow these steps to integrate your device with the Geeny platform. At the end, consumers of your devices will be able to authorize applications to access data sent by their devices.

Demo: Kadabra

Geeny demo apps

In the Geeny demo flow, Kadabra is a fictitious Thing Provider with a smart lock device. Kadabra has completed the onboarding process, and now consumers can authorize the Lighty app to access the data from their Kadabra smart lock.

Under the hood, Kadabra is a working example of an onboarded Thing Provider. Click here to view the source code on GitHub.

Step 1: Define Thing Types & Message Types

First, you must define a semantic blueprint for your device (as a “Thing Type”) and each parameter of data it sends or receives (as a “Message Type”) on the Geeny platform. This will tell Geeny how to interact with your IoT device.

  1. Log in to the Developers Dashboard.
  2. Click the button labeled Onboard Your Thing Type.
  3. Fill out the information about your Thing Type. Note that all fields are required.
  4. Now you must add the data parameters to your Thing Type as Resources. Click the button labeled Choose Message Type.
  5. Click the tab labeled Create a new Message Type.
  6. Fill out the fields with information about the data being sent in this Message Type. Enter an example of the payload in JSON format in the Data sample field. Note that all fields are required.
  7. Add the Message Type to the resource and then specify the URI where the device subscribes or publishes this message, as well as the method (pub or sub).
  8. Click Add This Resource.
  9. Follow this process for each Message Type that your device will send or receive. Note the URI for each resource, as you will need it for transmitting data to Geeny.
  10. When you have finished adding resources, click Submit.

Your new Thing Type will be created and visible on the Developers Dashboard.

Important: Thing Type ID & access key

For the next steps, you will need your Thing Type ID and Thing Type access key. You can find these by clicking on the name of your Thing Type under Your Thing Types.

The Thing Type access key enables the Geeny platform to receive data from Things of your Thing Type. To generate your access key, click the button on the Thing Type details page labeled Generate:

Generate access key

Once you generate the key, it will be available on this page indefinitely. You can revoke it and issue a new one from this page as well.

Step 2: Geeny Connect flow with OAuth 2 authorization

Your system should have an OAuth 2 provider set up to collect users’ consent to the exchange of their data between an Application Provider and your system.

OAuth 2 is a standard authorization process used by many developers and companies. See RFC 6479 for more information about the OAuth 2 authorization code grant type flow.

Geeny Connect flow

When an end user on the Application Provider’s side triggers the Geeny Connect flow, the Geeny platform will attempt to authorize the user using the OAuth 2 authorization code grant type method. Please create an OAuth 2 app for Geeny on your OAuth provider system. If you don’t have an OAuth provider in place, we have an example project to get you started here. We will provide you with the redirect_url, which should be whitelisted for the app. The general flow is as follows:

Thing Provider Authorization Flow

What you need to send us

Once this flow is implemented on your system, please send the following information to our engineers so that we can complete the configuration on the Geeny Platform:

Name Description
AUTHORIZATION_URL Authorization URL (e.g., https://{your-base-URL}/account/authorize)
ACCESS_TOKEN_URL Access URL (e.g., https://{your-base-URL}/account/access_token)
USER_PROFILE_URL User profile URL which returns the user id of the authenticated user (e.g., https://{your-base-URL}/user)
client_id OAuth 2 client id.
client_secret OAuth 2 client secret.
GEENY_WEBHOOK_URL URL of the webhook endpoint that the Geeny platform will call in order to inform you of a successful connection with an Application Provider.
provider Your name as a plain lowercase string.

Here are descriptions of each step in the process:

1. Authorization Code Request

The Geeny platform will make a request on this user’s behalf to the AUTHORIZATION_URL endpoint on your system’s OAuth Provider.

Parameters:

  • client_id
  • redirect_url
  • response_type

Sample request:

https://your_oauth_service/authorize?client_id=123456&response_type=code&redirect_uri=http://geeny.io/oauth/code_callback

2. Authorization Code Response

A successful user login should return a valid authorization code to the redirect_url.

3. Access Token Request

The Geeny platform will now make a request to the ACCESS_TOKEN_URL endpoint with the authorization code that was returned.

Parameters:

  • client_id
  • client_secret
  • grant_type
  • code

Sample request:

POST /token HTTP/1.1
Host: https://your_oauth_service/accesstoken
Content-Type: application/x-www-form-urlencoded

client_id=client_id&client_secret=client_secret&grant_type=authorization_code&code=AUTHORIZATION_CODE

4. Access Token Response

A valid access token for this user should be returned if the authorization code and client credentials are valid.

Sample response:

{
  token_type: "bearer",
  access_token: "123456asdfg",
  expires_in: SECONDS_UNTIL_EXPIRATION
}

5. User Profile Request

The Geeny platform will make a request to the USER_PROFILE_URL endpoint on your system with the access token that was provided.

Sample request:

GET /user HTTP/1.1
Host: yourservice.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer ACCESS_TOKEN

6. User Profile Response

The user’s unique identifier on your system should be returned as a JSON payload. If the field name is something other than user_id, please let us know.

Sample response:

{
  user_id: "zxcvbnm"
}

7. Webhook Notification Response

The Geeny platform will send a request to the GEENY_WEBHOOK_URL to confirm that the platform is ready to receive data from your system on this user’s behalf. For the authentication flow, the action parameter will always be user_authenticated, but it can be configured to send additional commands to your system in the future.

Sample webhook:

<your-webhook-domain>/webhooks/geeny-notifications

Sample payload:

  {
      "action": "user_authenticated",
      "user_id": "<your-user-id>",            
      "thing_type_id": "<geeny-thing-type-id>"
  }
  • user_id is the User ID generated on your end.
  • thing_type_id is the ID of the Thing Type you created previously.

Step 3: Configure data transmission to the Geeny platform

The final step is to modify your backend to communicate with the Geeny Push Messages API.

Click here for the full documentation of the Push Messages API.

URL:

POST https://developers.geeny.io/data/push/<thing-type-id>

Headers:

  • Authorization: Bearer <your-thing-type-access-key> (see the previous section)
  • Content-Type: application/json

Parameters:

Name Type Required? Description
id string(UUID) Yes Generated UUID to identify your message.
uri string(URI) Yes The port or address of the resource on the Thing Type that is communicating with the platform. For instance, if your Thing type can measure both internal and external temperature but uses the temperature Message Type for both, the uri would specify which one is being transmitted.
device_id string Yes Generated identifier for your user’s device.
user_id string Yes Generated identifier for the consumer who owns the device.
payload string(base64) Yes The data payload. This can be a single message or an array of messages, but it must be encoded as base64. Click here for information about standardizing data payloads.
device_sn string No The serial number of the device sending data.
device_name string No The name of the device.

Sample request:

curl -X POST \
https://developers.geeny.io/data/push/28964763-4e20-493a-b54f-b58a1b93ee21 \
  -H 'Authorization: Bearer eyJhbGciOiJSUzUxMiJ9...' \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "id": "7bf1ca7a-0d1d-4108-98e4-dcee1fdf647b",
    "user_id": "1099ccd3466a7c75ad9bc102",
    "device_id": "1099ccd3466a7c75ad9bc102",
    "uri": "human_message",
    "payload": "eyJodW1hbl9tZXNzYWdlIjogIkFBQUFBQUEifQ==",
    "device_name": "My Thing"
  }
]'

Step 4: Test data transmission

Now that everything is set up, you can use the Thing Emulator and the debug endpoint to test data transmission from your Thing Type to the Geeny platform.

Thing Emulator

The Thing Emulator acts as a Virtual Thing — i.e., an instance of a Thing Type that lives in our backend. You can use it to test bidirectional transmission between the Geeny platform and the Thing Type using a web interface on the Developers Dashboard.

To create a Virtual Thing:

  1. Log in to the Developers Dashboard.
  2. Click the Register your Thing button.
    • If you already have one or more Things, click the plus (+) button next to Your Things.
  3. Enter a name for the Virtual Thing and choose the Thing Type you created in the previous step.
  4. Click Register.

You will be taken back to the homepage of the Developers Dashboard, and your Virtual Thing will be listed under Your Things.

Now, click on the name of your Virtual Thing and then select the tab labeled Logs & Thing Emulator. Scroll down past the logs console to the section labeled Emulator:

Thing Emulator

In the left-hand console, you can test sending messages to the Geeny platform from the Virtual Thing (i.e., using pub resources). In the right-hand console, you can test sending commands to the Virtual Thing (i.e., using sub resources). Each message that you send from the Thing will appear in the logs console above.

Log messages

Debug endpoint

The Push Messages API includes a debug endpoint for testing data transmission to the Geeny platform. When you send a message to the /debug endpoint, the Geeny platform ignores the user_id included in the message and instead associates it with the owner of the Thing Type.

Sample URL:

POST https://developers.geeny.io/data/push/<thing-type-id>/debug

When you send a message to the /debug endpoint, a Virtual Thing will be generated and named after the value of "device_name" specified in the message (see the previous step). To see the test messages arriving on the Geeny platform, click on the Virtual Thing and select the Logs & Thing Emulator tab. The messages will appear in the logs console.

Click here for the full debug mode API reference.

How Things receive commands

When an application sends a command to a Thing, the command is received over the webhook URL that you configured in step 2. This is an example of the webhook payload of a command:

{
    "action": "command",
    "thing_type_id": "<geeny-thing-type-id>", // ID of the your Thing Type
    "user_id": "<your-user-id>",              // User ID generated on your end
    "device_id": "<device-identifier>",
    "uri": "<thing-type-resource-sub-uri>",
    "payload": "<base64-encoded-message-payload>"   
}

Step 5: Edit and Publish Thing Type

If you need to change any of the Thing Type’s properties, you can click the Edit Thing Type button at the top of the Thing Type’s details page:

Edit Thing Type

When you have finished testing your Thing Type and are ready to make it accessible to the Application Providers in the Geeny Alliance, then click the Publish Thing Type button at the top of your Thing Type’s details page.

NOTE: Once you publish your Thing Type, you cannot make any changes to it again.

Once it’s been published, Application Providers will be able to incorporate your Thing Type and its Message Types in their applications.

Optional: Onboard devices with Push Messages API

The Push Messages API includes an endpoint for directly onboarding your Things to the Geeny platform. This endpoint was designed for Things that are only capable of receiving commands from the platform (i.e., they only use sub resources).

NOTE: This endpoint also includes debug mode. As with the previous Push Messages API call, simply append /debug to the URL.

URL:

POST /api/v1/devices/{thing-type-id}

Headers:

  • Authorization: Bearer <your-thing-type-access-key>
  • Content-Type: application/json

Parameters:

Name Type Required? Description
user_id string(UUID) Yes Unique external user identifier. Ignored in debug mode.
device_id string(UUID) Yes Unique external device identifier.
device_sn string No (Optional) External device serial number.
device_name string Yes Name of the external device.

Sample call using cURL:

curl -X POST \
  https://developers.geeny.io/data/devices/28964763-4e20-493a-b54f-b58a1b93ee21 \
  -H 'Authorization: Bearer eyJhbGciOiJSUzUxMiJ9...' \
  -H 'Content-Type: application/json' \
  -d '{
  "user_id": "32a361b6-20b1-4191-ac17-9f87dd858dad",
  "device_id": "d41b0f78-9bf0-4a54-afcd-60048e36c1a9",
  "device_sn": "123AAA",
  "device_name": "Brian's Smart Plug"
}'

Sample response:

{
  "status": "success"
}

The Things will appear on the Developers Dashboard under Your Things.

Conclusion

This concludes the onboarding process. With these properties implemented, your devices will transmit data over the Geeny platform and can be shared with applications upon consumer authorization.