Integrating DataHub SDK

Dasudian FlowEngine Tutorial from Dasudian

IoT DataHub is based on MQTT lightweight messaging protocol, which is dedicated for IoT applications. Dasudian DataHub is programmed in Erlang to implement optimized MQTT protocol, making the data transmission over it is secure, reliable, stable and resource-saving. DataHub is designed for massively concurrent device connection and data transmission. The DataHub SDK is to be integrated with applications running on Windows, Linux, Android, iOS and other Embedded Operation System, and to aggregate the data from multi-sources and in different structures, sending them to Dasudian Cloud. DataHub is bi-directional, so that DataHub SDK can send data to Dasudian Cloud and can receive data from Cloud and/or other sources by subscribing a specific TOPIC.

How to use the SDK:

1. To create a client instance.

2. If you want the client to receive messages, just subscribe a specific topic.

3. Send messages to the cloud.

4. Destroy the client while quite.

Features of SDK:

1. When connection lost, the SDK will automatically reconnect; if the connection fails, the reconnection will happen in 1s, 2s, 4s, 8s, 16s, and 1s ... vice versa, the maximum reconnection interval is 16 seconds.

2. The SDK is working in save threads.

3. One client can only create one system process and if need more than one client multiple threads are created.

Data Structures

1. The message struct type: datahub_message_s

 #include <DataHubCommon.h> 

Member Variables:

 unsigned int payload_len 

 void * payload 

Member Variables Descriptions:

payload_len: the length of message, must be positive number

payload: the start address of the sent message

2. The struct type: DataHubClient::datahub_options_s

 #include <DataHubClient.h> 

Protected Member Variables:

 (char *) server_url [protected]

 int debug [protected] 

 int cleansession [protected] 

 (void *) context [protected] 

Member Variables Descriptions:

server_url: the URL of the cloud server, in the format of protocol://address:port, the protocol support tcp and ssl; the address and port are provided by Dasudian supporters; the default URL is DEFAULT_SERVER_URL

debug: toggle on/off the debugging; DATAHUB_TRUE debug on and DATAHUB_FALSE debug off; the default value is DATAHUB_FALSE

cleansession: whether to store the session status at client; if DATAHUB_FALSE the client will store all the subscribed topics and all the sent messages while the client is off-line; otherwise DATAHUB_TRUE the client will clean all the subscribed topics and sent message when it is off-line.

context: the parameter passed to callback functions message Received() and connectionStatusChanged() which matches the first parameter context of the callbacks.

3. DataHubClient Class

Every client is solely defined by client id, so please make sure every client has an unique client id

 #include <DataHubClient.h> 

Derived from <NSObject >

Structs:

 struct datahub_options_s 

Constructors:

 (int) - datahub_create:instance_id:instance_key:client_type:client_id:options: 

This method creates a client instance, which is for connecting MQTT server in cloud

 (int) - datahub_sendrequest:topic:msg:data_type:QoS:timeout: 

This method is for sending synchronous messages

 (int) - datahub_subscribe:topic:Qos:timeout:

This method is for synchronously subscribing a specific topic

 (int) - datahub_unsubscribe:topic:timeout:

This method is for synchronously unsubscribing a specific topic

 (void) - datahub_destroy:

This method is for disconnecting and destroying the client

 (void) - datahub_callback_free:message:

This method is for manually freeing the occupied memory by topics and messages

Class Methods:

 (instancetype) + shareInstance

Protected Methods:

 typedef struct DataHubClient::datahub_options_s datahub_options

Member Variables

 id<DataHubClientDelegate> delegate 

 messageReceivedBlock messageReceivedBlock 

Members Definition:

The options:

 (typedef struct datahub_options_s) datahub_options [protected] 

Represent a client instance:

 (instancetype) shareInstance 

To create a client instance and connect to the cloud server via MQTT

(int) datahub_create: 
                           
(datahub_client *) client
                           
instance_id:(char *) instance_id
                           
instance_key: (char *) instance_key
                           
client_type: (char *) client_type
                           
client_id: (char *) client_id
                           
option: (datahub_options *) options 

                  

                    
client
                    
If method execute successfully a client instance will be returned. note: not be NULL
                  
                  

                    
instance_id
                    
The unique identifier for a customer, provided by Dasudian. note: not be NULL 
                  
                  

                    
instance_key
                    
The passcode for securely connecting Dasudian Cloud. note: not be NULL 
                  
                   

                    
client_type
                    
The type of a client, such as sensor, charging_pile, car_batter etc. note: not be NULL 
                  
                   

                    
client_id
                    
The unique identifier of a client and every client must have different id. If two clients share the same id, one of them will can not connect to the cloud. The client id could be MAC address of a device or some third-party ID, such as QQ, Wechat, Phone number, Facebook, Twitter etc., you can also use a random number as the client id. note: not be NULL 
                  
                  

                    
options
                    
MQTT options, please look up the datahub_options struct for the detailed options. If do some settings you need to use DATAHUB_OPTIONS_INITIALIZER to initialize first and if no settings, just put it as NULL, note: can be NULL 
                  
                

RETURN: ERROR_NONE is successful otherwise fail

Send synchronous messages:

(int) datahub_sendrequest: 
                           
(datahub_client *) client
                           
topic:(char *) topic
                           
msg: (datahub_message *) msg
                           
datahub_type: (datahub_data_type) data_type
                           
QoS: qos
                           
timeout: (int) timeout 

Note: this method will block the process and thus it's suggested to create a child thread for implementing it.

                  

                    
client
                    
If method execute successfully a client instance will be returned. Not be NULL
                  
                  

                    
topic
                    
The topic that messages are sent to and the clients who subscribed this topic will receive these messages. Not be NULL 
                  
                  

                    
msg
                    
The message sent and should be initialized by DATAHUB_MESSAGE_INITIALIZER before using it. The message size should be no more than 512KB, otherwise error occurs. Not be NULL 
                  
                   

                    
data_type
                    
Can be JSON, TEXT or BINARY 
                  
                   

                    
qos
                    
The QoS of messaging. 0 - message may be lost; 1 - message must arrive but may be repeated; 2 - message must arrive and will arrive once only 
                  
                  

                    
timeout
                    
The maximum time for the method to be blocked and be careful it is NOT the timeout for message received confirmation 
                  
                

RETURN:

ERROR_NONE for success, the message must be sent out successfully;

ERROR_TIMEOUT, indicates the maximum waiting time is out for method blocking, but message may or may not arrive cloud. You should set a very good time according to the message size and network conditions.

Synchronously subscribe a topic:

(int) datahub_subscribe: 
                           
(datahub_client *) client
                           
topic:(char *) topic
                           
QoS: qos
                           
timeout: (int) timeout 

Note: this method will block the process and thus it's suggested to create a child thread for implementing it.

                  

                    
client
                    
If method execute successfully a client instance will be returned. Not be NULL
                  
                  

                    
topic
                    
The topic that messages are sent to and the clients who subscribed this topic will receive these messages. Not be NULL 
                  
                   

                    
qos
                    
The QoS of messaging. 0 - message may be lost; 1 - message must arrive but may be repeated; 2 - message must arrive and will arrive once only 
                  
                  

                    
timeout
                    
The maximum time for the method to be blocked and be careful it is NOT the timeout for message received confirmation 
                  
                

RETURN:

ERROR_NONE for success, the message must be sent out successfully;

ERROR_TIMEOUT, indicates the maximum waiting time is out for method blocking, but message may or may not arrive cloud. You should set a very good time according to the message size and network conditions.

Synchronously unsubscribe a topic:

(int) datahub_unsubscribe: 
                           
(datahub_client *) client
                           
topic:(char *) topic
                           
timeout: (int) timeout 

Note: this method will block the process and thus it's suggested to create a child thread for implementing it.

                  

                    
client
                    
If method execute successfully a client instance will be returned. Not be NULL
                  
                  

                    
topic
                    
The topic that messages are sent to and the clients who subscribed this topic will receive these messages. Not be NULL 
                  
                  

                    
timeout
                    
The maximum time for the method to be blocked and be careful it is NOT the timeout for message received confirmation 
                  
                

RETURN:

ERROR_NONE for success, the message must be sent out successfully;

ERROR_TIMEOUT, indicates the maximum waiting time is out for method blocking, but message may or may not arrive cloud. You should set a very good time according to the message size and network conditions.

Destroy client and disconnect:

(int) datahub_destroy: 
                           
(datahub_client *) client
                

                  

                    
client
                    
The client instance returned by datahub_create(). Not be NULL
                  
                

RETURN: none

Receiving messages:

(void) datahub_callback_free: 
                           
(char *) topic
                           
message: (datahub_message *) msg
                

Note: the memory occupied by topic and message need to be freed by programmer manually

                  

                    
topic
                    
The returned topic
                  
                  

                    
msg
                    
The returned message
                  
                

RETURN: none

Set delegate:

(id<DataHubClientDelegate>) delegate [read], [write], [nonatomic], [assign]

Block variable, the callback function while receiving messages:

(messageReceivedBlock) messageReceivedBlock [read], [write], [nonatomic], [strong]

Demo

Please refer to the Demo Application at Github.com and for more API information.

How to Get Instance ID and Instance Key?

On Dasudian.com, when you logged in you can see Manage Apps button on your Overview page. Click it, a page that list all of your apps will be displayed. You can click Show API Key button to see your Instance ID and Instance Key.

Events Tracking and Processing

You can define any event messages and send them to cloud over DataHub.

And you can store any event as messages on the cloud and process them with Flow Engine.