Page tree
Skip to end of metadata
Go to start of metadata

This document applies to device makers that would like to connect their device to the Smartenit Cloud.

In order to get access to the MQTT Broker, a valid client_id, client_secret, and device_id are required. The first two fields are normally created or assigned per type of device from a Smartenit application. This will allow the cloud to limit the usage of the broker or to distinguish between devices using the API.

The main steps to get a connection to the broker for real communication are:

  1. Register a device
  2. Discover a device
  3. Link a device to an account
  4. Request access to broker
  5. Connect to the broker
  6. Subscribe to allowed topics
  7. Publish messages

Register a device

Before the client is able to register a new device, it is important to get a valid access token from the OAuth 2.0 endpoint in the API. This step will provide a token with enough scope for registering devices using a unique hwId as an identifier, so the cloud can return the same ID consistently, very important for backup and restore and for avoiding duplicated devices in the database.

The following command can be used to get an access token

 

Get a client credential Token
Request:
curl -X POST -H "Content-Type: application/json" \
    -d '{
    "grant_type": "client_credentials",
    "client_id": "CLIENT_ID",
    "client_secret": "CLIENT_SECRET"
}' "https://api.smartenit.io/v2/oauth2/token"
 
 
{
    "access_token": "8eMu7xv7f4pLCVhHRlYmJxLh1kwPkpTKq...",
    "token_type": "Bearer",
    "expires_in": 10800
}

 

Now using the token the device can be registered:

Request:
curl -X POST -H "Content-Type: application/json" \
    -H "Authorization: Bearer 8eMu7xv7f4pLCVhHRlYmJxLh1kwPkpTKq..." \
    -d '{
    "name": "My Wifi device",
    "type": "wifi",
    "interfaces": [
        {
            "name":"wlan0",
            "ip": "192.168.0.10",
            "mac": "85:35:97:76:56:46"
        }
    ],
    "hwId": "85:35:97:76:56:46",
    "components": {}
}' "https://api.smartenit.io/v2/devices/register"

It's important to include the device interfaces information when registering, this will allow users to connect with the devices using a local network.

 

{
  "message": "Device registered successfully",
  "data": {
    "updatedAt": "2016-08-29T19:39:39.267Z",
    "createdAt": "2016-08-29T19:39:39.267Z",
    "name": "My Wifi device",
    "type": "wifi",
    "hwId": "85:35:97:76:56:46",
    "xIp": "181.141.5.128",
    "_id": "57c48f7ba9db1ef36a32e1b2",
    "backups": null,
    "cognitoIdentityId": null,
    "parents": {
      "areas": []
    },
    "interfaces": [
      {
        "updatedAt": "2016-08-29T19:39:39.267Z",
        "createdAt": "2016-08-29T19:39:39.267Z",
        "name": "wlan0",
        "ip": "192.168.0.10",
        "mac": "85:35:97:76:56:46"
      }
    ],
    "components": [],
    "topic": null,
    "accountId": null
  }
}

 

Once the device is registered in the API it can be discovered by a client application.

Notice that at this point the accountId attribute is set to null, this means that the device is not linked to any account and will not be able to connect real-time. In order to link this device to an account, a user using a client application must discover the device and link it to its account.

Discover a device

Now, the device is registered and can be discovered by a user. The basic strategy will use the external IP to detect that the user and the device are connected to the same local network. As it is shown above, the cloud will respond with the deviceId acquired and the accountId associated to this device. As in the example, it will return null if it is not associated yet to any account. In this scenario, the device can not use real-time communication until it is fully associated. This is intended for limiting the number of devices creating traffic in the broker, as they will send information that will not be used at all.

Link a device to an account

In order to start using a device in real time, the device must be linked to an account. In order to link the account, clients can use the device discovery service to list devices in their same local network.

curl -X POST -H "Content-Type: application/json" \
    -H "Authorization: Bearer 8eMu7xv7f4pLCVhHRlYmJxLh1kwPkpTKq..." \
    "https://api.smartenit.io/v2/devices/discover"

This will return a list of devices

{
	"data": [{
		"_id": "547d9e3b7c40af67db433ebb",
		"updatedAt": "2016-12-30T09:45:28.346Z",
		"createdAt": "2016-12-30T09:45:28.346Z",
		"hwId": "547d9e3b7c40af67db433ebb",
		"name": "Gateway 1 with 2 interfaces",
		"xIp": "190.159.104.146",
		"type": "gateway",
		"accountId":null,
		"media": {
			"updatedAt": "2016-12-30T09:45:28.622Z",
			"createdAt": "2016-12-30T09:45:28.622Z",
			"v": 1
		},
		"state": "created",
		"backups": null,
		"cognitoIdentityId": null,
		"parents": {
			"updatedAt": "2016-12-30T09:45:28.621Z",
			"createdAt": "2016-12-30T09:45:28.621Z",
			"actions": [],
			"devices": [],
			"areas": []
		}
	}]
}

Once you have this list you can link one of the devices of the list to a specific account. When called, the link service will use the access_token data to link the device to a specific accountId.

curl -X POST -H "Content-Type: application/json" \
    -H "Authorization: Bearer 8eMu7xv7f4pLCVhHRlYmJxLh1kwPkpTKq..." \
	-d '{
    	"deviceId": "547d9e3b7c40af67db433ebb"
	}'
    "https://api.smartenit.io/v2/devices/link"

This will reurn the linked device

{
	"data": {
		"_id": "547d9e3b7c40af67db433ebb",
		"updatedAt": "2016-12-30T09:45:28.346Z",
		"createdAt": "2016-12-30T09:45:28.346Z",
		"hwId": "547d9e3b7c40af67db433ebb",
		"name": "Gateway 1 with 2 interfaces",
		"xIp": "190.159.104.146",
		"type": "gateway",
		"accountId":"547d9e3b7c40afebb67db433",
		"media": {
			"updatedAt": "2016-12-30T09:45:28.622Z",
			"createdAt": "2016-12-30T09:45:28.622Z",
			"v": 1
		},
		"state": "created",
		"backups": null,
		"cognitoIdentityId": null,
		"parents": {
			"updatedAt": "2016-12-30T09:45:28.621Z",
			"createdAt": "2016-12-30T09:45:28.621Z",
			"actions": [],
			"devices": [],
			"areas": []
		}
	}
}
Notice that the accountId field has now information about the account

Request access to broker

The device must keep trying to register until an accountId is returned. This will indicate that the device has been linked and can request access to the broker for providing real-time communication. This step requires a new access token specifically for this device, this can be done providing the deviceId obtained while registering the device.

 

curl -X POST -H "Content-Type: application/json" \
    -d '{
    "grant_type": "client_credentials",
    "client_id": "CLIENT_ID",
    "client_secret": "CLIENT_SECRET"
    "device_id": "DEVICE_ID"
}' \
    "https://api.smartenit.io/v2/oauth2/token"

 

Response:

{
    "access_token": "8eMu7xv7f4pLCVhH.....",
    "token_type": "Bearer",
    "expires_in": 10800
}

Connect to the broker

Subscribe to allowed topics

Publish messages

  • No labels