The document provides instructions for onboarding devices to the Vitalpointz IoT platform. It describes a two step process: 1) Device addition - adding device details to allocate resources and generate credentials 2) Device onboarding - making API calls to authenticate, allocate a device, exchange capabilities, and begin sending data. Key steps involve generating an activation code during device addition, making authentication, allocation, and capability calls using the activation code and credentials, and then sending MQTT or REST messages with the assigned topic. Considerations for hardware identification and call flows are also discussed.

1. Confidential
www.vitalpointz.net1
Device On-Boarding

2. Confidential
www.vitalpointz.net
©2017 , www.vitalpointz.net
vitalpointz IoT Core Lite v1.3 and above
Device Onboarding into
vitalpointz IoT Core Lite

3. Confidential
www.vitalpointz.net
 Onboarding of devices to Vitalpointz IoT Platform happens in two
subsequent steps.
1. Device Add Process
2. Device Onboarding Process
3
Overview

4. Confidential
www.vitalpointz.net
 Device Addition is the way to ask the Platform to
 Allocate a unique Topic for a device
 Generate a Private Key and a Certificate for the device
 Program device specific rules into the Rules Engine
 Upon completion of Device addition process, Platform provides
 Device Activation Code
4
1. Device Addition…

5. Confidential
www.vitalpointz.net5
1. Device Addition…
1
2

6. Confidential
www.vitalpointz.net
 Once the form is filled, platform generates Device Activation Code
 Note this value. Device needs to be programmed with this code
6
1. Device Addition
3

7. Confidential
www.vitalpointz.net7
Fields on Device Addition Form
Name* Give a name for the device
Description & Metadata Optional
OS/CPU Optional
Number of devices to add* Enter the no of devices to be added. Max limit 9999 per form. More devices can be added later
by repeating the process.
Enrich messages Metadata object to append with every device message before forwarding to flow-processing
function. Optional.
Message Decoder Name of the function that will trigger on reception of device message, Optional.
Group name Logical grouping to manage devices on UI, Optional
Device Topic Whitelisting Device topic is whitelisted either on completion of Device Add process or on completion of
essential API calls by the device.
Device configuration User defined key-value pair object , which gets delivered to device on completion of Capability
Exchange Call (essential calls). Optional.
Device Policy Defines the policy which is enforced to messages before forwarding to above said ‘Decoder’
function.

8. Confidential
www.vitalpointz.net
 Device(s) are onboarded to Vitalpointz IoT Platform by
 Installing VESPA Agent (or)
 Implementing own Agent
 Platform exposes few APIs for smooth on-boarding of the devices
 VESPA is a reference implementation those REST APIs calls
 VESPA Agents for multiple devices are available publicly in Github
https://github.com/Judepragash/vitalpointzIOT
8
2. On-Boarding

9. Confidential
www.vitalpointz.net
 Devices would need below credentials to make REST API Calls to
the platform
1. User Access Key
2. Device Activation Code
 Device can make below REST API calls while onboarding
 Essential API calls in sequence
1. User Authenticate
2. Device Allocate (or) Device Authenticate
3. Device Capability Exchange
 Optional Calls
9
2.a. Implement your own Device Agent

10. Confidential
www.vitalpointz.net
 Navigate to Identity Tab and click on your user card.
10
Where to find User Access Key
1
2
3

11. Confidential
www.vitalpointz.net
 Target URL for the APIs in the
platform can be found by
navigating to Device Tab, clicking
on top Card.
 Expand ’Device management
Services’ menu on the slider
11
Where to find API URLs?
31 2

12. Confidential
www.vitalpointz.net
User Auth Call
 Note
 Save the returned object as the keys present in this object will be required to make
subsequent calls.
12
Let us start Implementing
Request curl --location --request POST 'https://{{URL}}/user/authenticate’
--header 'Content-Type: application/json’
--data-raw '{"userkey": "Js8DXxGPHtb7"}'
Response 200 OK
{
"device_tenant_api_url": "https://dapi-5xxxxxxx.xxxx.vitalpointz.com",
"device_tenant_mqtt_url": "mqtt-xxxxx.xxxx.vitalpointz.com:10001",
"dns": "8.8.8.8",
"token":
"eyJhbGciOXXXXXXXXVCJ9.eyJleHBrIjozNjAwLCJpYQQQQQQQQQQQQRRRIIITY1NzQsImp0aSI6Ij
BiNDk3MjU2LWEXXXXXXXXXXXNTk3MyJ9.gwVybD344PILh8IUCS_LQbRtSc5sC4QiWTiAfxx4KVk"
}

13. Confidential
www.vitalpointz.net
Device Allocate Call (very first time)
 device_tenant_url : from previous call
 device_token : from previous call
 hash : device must generate and present a unique value
 device_activation_code : platform generated value resulting from device add process.
13
Your own Agent …
Request curl --location --request POST '{{device_tenant_url}}/device/allocateAuth’
--header 'Authorization: Bearer {{device_token}}’
--header 'Content-Type: application/json’
--data-raw '{"hash": "jfdskfhhsufhu7ui84i4jrd92u394i2i","device_activation_code":"R2n3p6zL"}'
Response 200 OK
{
"deviceid": "5e4e35117883dd00323f2be6",
"devicename": "dd1",
"authcode": "uHswv2zHhfLRUgBr"
}

14. Confidential
www.vitalpointz.net
Device Allocate Call (subsequent time)
 device_tenant_url : from user authentication call
 Token : from user authentication call
 device_authcode : platform generated, from Device Allocate call.
14
Your own Agent …
Request curl --location --request GET '{{device_tenant_url}}/device/auth/{{dev_authcode}}’
--header 'Authorization: Bearer {{device_token}}’
--header 'Content-Type: application/json'
Response 200 OK
{
"deviceid": "5e4e35117883dd00323f2be6",
"devicename": "dd1",
}

15. Confidential
www.vitalpointz.net
Device Capability Exchange Call
15
Your own Agent …
Request curl --location --request POST '{{device_tenant_url}}/device/capability/{{deviceid}}’
--header 'Authorization: Bearer {{device_token}}’
--header 'Content-Type: application/json’
--data-raw '{ "device_spec": [ { "name": "model", "value": "Moto G (5) Plus" }, { "name": "os",
"value": "Android" }, { "name": "osversion", "value": "7.0" }, { "name": "manufacturer", "value":
"motorola" }, { "name": "brand", "value": "motorola" }, { "name": "hardwarevalue", "value": "qcom"
}, { "name": "serialnum", "value": "ZY2244RN46" }, { "name": "androidid", "value":
"e7d538428d8edb48" }, { "name": "btname", "value": "null" }, { "name": "btmac", "value": "null" } ],
"monitor": [ { "name": "batery" }, { "name": "ramusage" }, { "name": "storageusage" }, { "name":
"lat" }, { "name": "long" } ], "Interfaces": [ { "name": "wifi" }, { "name": "bluetooth" } ] }'
Response 200 OK
{
"mqtttopic": "i/PaQXvVS7",
"monitor": [ { "name": "batery", "interval": 60 }, { "name": "ramusage", "interval": 60 }, { "name":
"storageusage", "interval": 60 }, { "name": "lat", "interval": 60 }, { "name": "long", "interval": 60 } ],
"sync_interval": 300
}

16. Confidential
www.vitalpointz.net
 Notes on Capability Exchange Call
 Request
 deviceid is provided by the platform as response to Device allocate / device auth call.
 Device programmer is free to send any object as device_spec
 Response
 mqtttopic : must be used to send MQTT messages. Only this topic is allowed and
whitelisted by the platform.
16
Your own Agent

17. Confidential
www.vitalpointz.net
Send message over REST Interface
 Notes
 topic : must be provided by the platform. developers are free to extend the topic keeping the
top level topic intact.
 Example, in this case, topic provided by the platform is ‘z/R92lBqDrB’
17
Other Important Calls
Request url --location --request POST '{{device_tenant_url}}/device/data’
--header 'Authorization: Bearer {{device_token}}’
--header 'Content-Type: application/json’
--data-raw '{"topic": "z/R92lBqDrB/r_oY3pszG","data": "{"Temperature":40,"Notes":"this was
taken at home."}"}'
Response 200 OK
{ "status": "success",
"message": "Device data published."
}

18. Confidential
www.vitalpointz.net
Download Device Private Key
 Notes
 device_tenant_url & device_token : result of user authenticate call.
 Deviceid : result of device allocate / device auth call
18
Device chain of trust – (1)
Request curl --location --request GET '{{device_tenant_url}}/cert/client_key/{{deviceid}}’
--header 'Authorization: Bearer {{device_token}}’
Response 200 OK
-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEA58q/PPwKiEQ2KQN6N6Fnv1TPsnHcm5z5bM+Ni2mK9wWlG5
~~~~~snip ~~~~~~
eNaTxuJ3 PDBR/xBFqjp jnMuCjiLrc1tDHQYMkr+QiwYQoL8idevsEmm0UPlCUqjkfKAAtRR
-----END RSA PRIVATE KEY---

19. Confidential
www.vitalpointz.net
Download unique Device certificate
 Notes
 device_tenant_url & device_token : result of user authenticate call.
 Deviceid : result of device allocate / device auth call
19
Device chain of trust – (2)
Request curl --location --request GET '{{device_tenant_url}}/cert/client_crt/{{deviceid}}’
--header 'Authorization: Bearer {{device_token}}'
Response 200 OK
-----BEGIN CERTIFICATE-----
MIIDVDCCAjwCCQCyOEL6Ax3EXjANBg/PPwKiEQ2KQN6N6Fnv1TPsnHcm5z5bM+
~~~~~snip ~~~~~~
eNaTxuJ3 PDBR/xBFqjp jnMuCjiLrc1tDHQYMkr+QiwYQoL8idevsEmm0UPlCUqjkfKAAtRR
-----END CERTIFICATE-----

20. Confidential
www.vitalpointz.net
Download root certificate
 Notes
 device_tenant_url & device_token : result of user authenticate call.
 Deviceid : result of device allocate / device auth call
20
Device chain of trust – (3)
Request curl --location --request GET '{{device_tenant_url}}/cert/ca_root/{{deviceid}}’
--header 'Authorization: Bearer {{device_token}}'
Response 200 OK
-----BEGIN CERTIFICATE-----
MIIDVDCCAjwCCQCyOEL6Ax3EXjANBg/PPwKiEQ2KQN6N6Fnv1TPsnHcm5z5bM+
~~~~~snip ~~~~~~
eNaTxuJ3 PDBR/xBFqjp jnMuCjiLrc1tDHQYMkr+QiwYQoL8idevsEmm0UPlCUqjkfKAAtRR
-----END CERTIFICATE-----

21. Confidential
www.vitalpointz.net
Download ca chain of certificate (Root cert not returned)
 Notes
 device_tenant_url & device_token : result of user authenticate call.
 Deviceid : result of device allocate / device auth call
21
Device chain of trust – (4)
Request curl --location --request GET '{{device_tenant_url}}/cert/ca_chain/{{deviceid}}’
--header 'Authorization: Bearer {{device_token}}'
Response 200 OK
-----BEGIN CERTIFICATE-----
MIIDVDCCAjwCCQCyOEL6Ax3EXjANBg/PPwKiEQ2KQN6N6Fnv1TPsnHcm5z5bM+
~~~~~snip ~~~~~~
eNaTxuJ3 PDBR/xBFqjp jnMuCjiLrc1tDHQYMkr+QiwYQoL8idevsEmm0UPlCUqjkfKAAtRR
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIDVDCCAjwCCQCyOEL6Ax3EXjANBg/PPwKiEQ2KQN6N6Fnv1TPsnHcm5z5bM+
~~~~~snip ~~~~~~
eNaTxuJ3 PDBR/xBFqjp jnMuCjiLrc1tDHQYMkr+QiwYQoL8idevsEmm0UPlCUqjkfKAAtRR
-----END CERTIFICATE-----

22. Confidential
www.vitalpointz.net
Download Full Chain of certificates
 Notes
 device_tenant_url & device_token : result of user authenticate call.
 Deviceid : result of device allocate / device auth call
22
Device chain of trust – (5)
Request curl --location --request GET '{{device_tenant_url}}/cert/ca_full/{{deviceid}}’
--header 'Authorization: Bearer {{device_token}}'
Response 200 OK
-----BEGIN CERTIFICATE----- MIIDVDCCAjwCCQCyOEL6Ax3EXjANBg/PPwKiEQ2KQN6N6Fnv1TPsnHcm5z5bM+
~~~~~snip ~~~~~~
eNaTxuJ3 PDBR/xBFqjp jnMuCjiLrc1tDHQYMkr+QiwYQoL8idevsEmm0UPlCUqjkfKAAtRR
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE----- MIIDVDCCAjwCCQCyOEL6Ax3EXjANBg/PPwKiEQ2KQN6N6Fnv1TPsnHcm5z5bM+
~~~~~snip ~~~~~~
eNaTxuJ3 PDBR/xBFqjp jnMuCjiLrc1tDHQYMkr+QiwYQoL8idevsEmm0UPlCUqjkfKAAtRR
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE----- MIIDVDCCAjwCCQCyOEL6Ax3EXjANBg/PPwKiEQ2KQN6N6Fnv1TPsnHcm5z5bM+
~~~~~snip ~~~~~~
eNaTxuJ3 PDBR/xBFqjp jnMuCjiLrc1tDHQYMkr+QiwYQoL8idevsEmm0UPlCUqjkfKAAtRR
-----END CERTIFICATE-----

23. Confidential
www.vitalpointz.net
 If the device has a unique hardware id
such as mac id, use device allocate auth
call with hash being the hardware id.
 The flow is shown in the pic
23
Call flow considerations – (1)

24. Confidential
www.vitalpointz.net
 If the device does not have a unique
hardware id, implement this flow as
shown
24
Call flow considerations – (2)

25. Confidential
www.vitalpointz.net
©2017 , www.vitalpointz.net
Got a Question ?
ask in our Slack support channel
search in our community forum community.vitalpointz.com