SDK understanding and workflow
What is SDK
SDK provides basic functionality to start device communication. The IoTConnect platform has device SDKs in various languages, which are ready to go by making some configuration changes. You can find more details on the language and features of IoTConnect SDK here.
Below are three concepts you need to understand before using IoTConnect SDK or building your custom SDK.
1. Discover
Your device needs to discover where it will get information regarding the broker to connect and start communication. IoTConnect will make sure account information is valid and has a subscription.
Your device needs to send a REST request to the IoTConnect server to verify your account and discover the identity URL, discovery needs few parameters to fetch Identity Endpoint. For this, You need CPID or SID, IOTConnect-supported language, version, and environment. All you can get form your account’s key vault page.
2. Get identity and connect
On successful validation from IoTConnect discovery, the platform will provide information on where the device must get identity. The device will get information to send/receive data if the device is valid.
On the success of the Discovery Call, you will get the URL of the Identity API. This API will provide additional values required to establish the device connection, send telemetry data, etc.
Once you get all the required details of the host where your device needs to get connected and start sending data, you need to initiate the MQTT client and connect using the required details. Based on auth type, you need to connect to the broker.
Note: If you have your device connection information known or does not support HTTP calls, in that case, you can use known information like host id and device id (for X.509- based device) and direct make a connection to the broker and ask for additional information using Device Identity Messages, more on these messages please click here.
3. Communication
Communication can be done in two ways: device-to-cloud and cloud-to-device. If the device SDK is doing both, it is considered bidirectional. Each message has a specific format and topic based on data behavior.
Device-to-cloud: As the name suggests, when the device sends something to the platform, it can report invalid data or send updated status.
Cloud-to-device: The platform sends information back to the device with this message. It can be an initiation of any process or change in behavior that will receive a message from the platform. When the device sends information to the platform, it can report sensor value, status updates, etc. Each message is added message type. This type of device has to send a message on a specific topic.
IoTConnect supports several messages based on data behavior, defined using message type. You can find details on all message types here.
Identity service provides a list of topics based on the message type. Device SDK has to send a predefined JSON message to a specific topic.
IoTConnect supports below message types
- Reporting message
- Fault message
- Acknowledgment message
You can find more details on device to cloud messages here.
To receive a message from the platform, the device SDK has to subscribe to topics mentioned in c2d. On top of this, to capture shadow updates or get all shadow values, make a message exchange on a specific topic. You can find more details on cloud to device messages here.