SmartThings SDK for Direct Connected Devices - C APIs

Connection APIs
Capability APIs
Utility APIs
- st_info_get
- st_create_log_dump
Macros
Typedefs

Connection APIs

st_conn_init

IOT_CTX* st_conn_init(unsigned char *onboarding_config,
                      unsigned int onboarding_config_len,
                      unsigned char* device_info,
                      unsigned int device_info_len);

st-iot-core initialize function

This function initializes st-iot-core for device.

Parameters

direction	name	purpose
in	onboarding_config	staring pointer of `onboarding_config.json` contents
in	onboarding_config_len	size of `onboarding_config.json` contents
in	device_info	starting pointer of `device_info.json` contents
in	device_info_len	size of `device_info.json` contents

Returns
return IOT_CTX handle(a pointer) if it succeeds, or NULL if it fails.

st_conn_set_noti_cb

int st_conn_set_noti_cb(IOT_CTX *iot_ctx,
                        st_cap_noti_cb noti_cb,
                        void *noti_usr_data);

Register callback function for notification event.

This function registers user callback function which will be called when notification event occurs (such as "rate limit", "delete device").
NOTE: The user callback function must return immediately because MQTT working thread will resume work when after user callback has returned.

Parameters

direction	name	purpose
in	iot_ctx	iot_context handle generated by st_conn_init()
in	noti_cb	The callback function which will be called when notification event occurs. see also st_cap_noti_cb
in	noti_usr_data	User data for `noti_cb`.

Returns
0 if it works successfully, non-zero for error case.

st_conn_start

int st_conn_start(IOT_CTX *iot_ctx,
                  st_status_cb status_cb,
                  iot_status_t maps,
                  void *usr_data,
                  iot_pin_t *pin_num);

st-iot-core server connection function

This function tries to connect server.

Parameters

direction	name	purpose
in	iot_ctx	iot_context handle generated by st_conn_init()
in	status_cb	user callback function to receive status of st-iot-core. see also st_status_cb
in	maps	status of st-iot-core interested to receive through status_cb. see also iot_status_t
in	usr_data	user data(a pointer) to use in status_cb
in	pin_num	if PIN ownership validation type used, valid 8 digit pin should be set. otherwise set null. see also iot_pin_t

Returns
return 0 if it works successfully, non-zero for error case.

st_conn_cleanup

int st_conn_cleanup(IOT_CTX *iot_ctx,
                    bool reboot);

st-iot-core device clean-up function

This function cleans-up all DATA including provisioning & registered data.

Parameters

direction	name	purpose
in	iot_ctx	iot_context handle generated by st_conn_init()
in	reboot	boolean set true for auto-reboot of system, else false.

Returns
return 0 if it works successfully, non-zero for error case.

st_conn_ownership_confirm

void st_conn_ownership_confirm(IOT_CTX *iot_ctx,
                               bool confirm);

easysetup user confirm report function

This function reports the user confirmation to easysetup.

Parameters

direction	name	purpose
in	iot_ctx	iot_context handle generated by st_conn_init()
in	confirm	user confirmation result

Capability APIs

st_cap_handle_init

IOT_CAP_HANDLE *st_cap_handle_init(IOT_CTX *iot_ctx,
                                   const char *component,
                                   const char *capability,
                                   st_cap_init_cb init_cb,
                                   void *init_usr_data);

Create and initialize a capability handle.

This function creates a capability handle, and initializes it with input args.

Parameters

direction	name	purpose
in	iot_ctx	iot_context handle generated by st_conn_init()
in	component	Component string. Default component name is "main".
in	capability	Capability string. This should be matched with "id" value of capability definition json format.
in	init_cb	The function which is called to initialize device state. see also st_cap_init_cb
in	init_usr_data	User data for init_cb

Returns
Pointer of created capability handle.

st_cap_cmd_set_cb

int st_cap_cmd_set_cb(IOT_CAP_HANDLE *cap_handle,
                      const char *cmd_type,
                      st_cap_cmd_cb cmd_cb,
                      void *usr_data);

Register callback function for command message.

This function registers user callback for command message from ST server.
If the capability(used to create handle) and cmd_type of command message are same with input arguments, the callback function will be called.
NOTE: The user callback function must return immediately because MQTT working thread will resume work when after user callback has returned.

Parameters

direction	name	purpose
in	cap_handle	The capability handle to register cb function which is generated by st_cap_handle_init()
in	cmd_type	The commands interested to process.
in	cmd_cb	The callback function invoked when command is received. see also st_cap_cmd_cb
in	usr_data	User data for cmd_cb.

Returns
0 if it works successfully, non-zero for error case.

st_cap_create_attr

IOT_EVENT* st_cap_create_attr(IOT_CAP_HANDLE *cap_handle,
                              const char *attribute,
                              iot_cap_val_t *value,
                              const char *unit,
                              const char *data);

Create IOT_EVENT data.

This function creates a new IOT_EVENT data with input parameters. Once it returns, user has full responsibility for deallocating event data by using st_cap_free_attr.
NOTE: IOT_EVENT created in this function must be passed to st_cap_send_attr function for sending events.

direction	name	purpose
in	cap_handle	Capability handle generated by st_cap_handle_init()
in	attribute	The attribute string of `IOT_EVENT` data.
in	value	The value to add to `IOT_EVENT` data. see also iot_cap_val_t
in	unit	The unit string if needed. Otherwise NULL.
in	data	The data json object if needed. Otherwise NULL.

Returns
Pointer of IOT_EVENT which is used to publish device status.

st_cap_free_attr

void st_cap_free_attr(IOT_EVENT* event);

Free IOT_EVENT data.

This function frees IOT_EVENT data.

Parameters

direction	name	purpose
in	event	The IOT_EVENT data to free.

st_cap_send_attr

int st_cap_send_attr(IOT_EVENT *event[],
                     uint8_t evt_num);

Request to publish deviceEvent.

This function creates a deviceEvent with the list of IOT_EVENT data and requests to publish it.
If there is no error, this function returns sequence number which is unique value to identify the deviceEvent message.
NOTE: IOT_EVENT must be created from st_cap_create_attr()

Parameters

direction	name	purpose
in	event	The IOT_EVENT data list to create the deviceEvent.
in	evt_num	The number of IOT_EVENT data in the event.

Returns
return "sequence number" (which is positive integer) if successful, negative integer for error case.

Utility APIs

st_info_get

int st_info_get(IOT_CTX *iot_ctx,
                iot_info_type_t info_type,
                iot_info_data_t *info_data);

st-iot-core information getting function

This function tries to get current iot-core's information

Parameters

direction	name	purpose
in	iot_ctx	iot_context handle generated by st_conn_init()
in	info_type	type of `iot_info_types_t` to get its value
out	info_data	A pointer to actual information data to get each type of iot_info_type_t

Returns
0 if it works successfully, non-zero for error case.

st_create_log_dump

int st_create_log_dump(IOT_CTX *iot_ctx,
                       char **log_dump_output,
                       size_t max_log_dump_size,
                       size_t *allocated_size,
                       int log_mode);

create log_dump

NOTE: log_dump_output should be freed after used.

Parameters

direction	name	purpose
in	iot_ctx	iot_context handle generated by st_conn_init()
out	log_dump_output	A pointer of not allocated pointer for log dump buffer. it will allocated in this function
in	max_log_dump_size	maximum size of log dump.
out	allocated_size	allocated memory size of log_dump_output
in	log_mode	log mode generated by OR operation of following values `IOT_DUMP_MODE_NEED_BASE64` : make log encoded to base64 `IOT_DUMP_MODE_NEED_DUMP_STATE` : add dump state in log

Returns
0 if it works successfully, non-zero for error case.

Macros

ST_CAP_CREATE_ATTR_NUMBER

#define ST_CAP_CREATE_ATTR_NUMBER(cap_handle, attribute, value_number, unit, data, output_attr)\
{\
	iot_cap_val_t value;\
\
	value.type = IOT_CAP_VAL_TYPE_NUMBER;\
	value.number = value_number;\
	output_attr = st_cap_create_attr(cap_handle, attribute, &value, unit, data);\
}

Helper for creating number type attribute

ST_CAP_SEND_ATTR_NUMBER

#define ST_CAP_SEND_ATTR_NUMBER(cap_handle, attribute, value_number, unit, data, output_seq_num)\
{\
	IOT_EVENT *attr = NULL;\
	iot_cap_val_t value;\
\
	value.type = IOT_CAP_VAL_TYPE_NUMBER;\
	value.number = value_number;\
	attr = st_cap_create_attr(cap_handle, attribute, &value, unit, data);\
	if (attr != NULL){\
		output_seq_num = st_cap_send_attr(&attr, 1);\
		st_cap_free_attr(attr);\
	}\
}

Helper for sending number type attribute

ST_CAP_CREATE_ATTR_STRING

#define ST_CAP_CREATE_ATTR_STRING(cap_handle, attribute, value_string, unit, data, output_attr)\
{\
	iot_cap_val_t value;\
\
	value.type = IOT_CAP_VAL_TYPE_STRING;\
	value.string = value_string;\
	output_attr = st_cap_create_attr(cap_handle, attribute, &value, unit, data);\
}

Helper for creating string type attribute

ST_CAP_SEND_ATTR_STRING

#define ST_CAP_SEND_ATTR_STRING(cap_handle, attribute, value_string, unit, data, output_seq_num)\
{\
	IOT_EVENT *attr = NULL;\
	iot_cap_val_t value;\
\
	value.type = IOT_CAP_VAL_TYPE_STRING;\
	value.string = value_string;\
	attr = st_cap_create_attr(cap_handle, attribute, &value, unit, data);\
	if (attr != NULL){\
		output_seq_num = st_cap_send_attr(&attr, 1);\
		st_cap_free_attr(attr);\
	}\
}

Helper for sending string type attribute

ST_CAP_CREATE_ATTR_STRINGS_ARRAY

#define ST_CAP_CREATE_ATTR_STRINGS_ARRAY(cap_handle, attribute, value_string_array, array_num, unit, data, output_attr)\
{\
	iot_cap_val_t value;\
\
	value.type = IOT_CAP_VAL_TYPE_STR_ARRAY;\
	value.str_num = array_num;\
	value.strings = value_string_array;\
	output_attr = st_cap_create_attr(cap_handle, attribute, &value, unit, data);\
}

Helper for creating string array type attribute

ST_CAP_SEND_ATTR_STRINGS_ARRAY

#define ST_CAP_SEND_ATTR_STRINGS_ARRAY(cap_handle, attribute, value_string_array, array_num, unit, data, output_seq_num)\
{\
	IOT_EVENT *attr = NULL;\
	iot_cap_val_t value;\
\
	value.type = IOT_CAP_VAL_TYPE_STR_ARRAY;\
	value.str_num = array_num;\
	value.strings = value_string_array;\
	attr = st_cap_create_attr(cap_handle, attribute, &value, unit, data);\
	if (attr != NULL){\
		output_seq_num = st_cap_send_attr(&attr, 1);\
		st_cap_free_attr(attr);\
	}\
}

Helper for sendting string array type attribute

Typedefs

IOT_CTX

typedef void *IOT_CTX;

iot_context handle

IOT_CAP_HANDLE

typedef void *IOT_CAP_HANDLE;

capability handle

IOT_EVENT

typedef void *IOT_EVENT;

event data

st_status_cb

typedef void (*st_status_cb)(iot_status_t iot_status, iot_stat_lv_t stat_lv, void *usr_data);

st_cap_init_cb

typedef void (*st_cap_init_cb)(IOT_CAP_HANDLE *cap_handle, void *init_usr_data);

st_cap_noti_cb

typedef void (*st_cap_noti_cb)(iot_noti_data_t *noti_data, void *noti_usr_data);

st_cap_cmd_cb

typedef void (*st_cap_cmd_cb)(IOT_CAP_HANDLE *cap_handle, iot_cap_cmd_data_t *cmd_data, void *usr_data);

iot_status_t

typedef enum iot_status {
	IOT_STATUS_IDLE = (1 << 0),          /**< For idle status, not connected. supports IOT_STAT_LV_STAY */
	IOT_STATUS_PROVISIONING = (1 << 1),  /**< For provisioning status. do onboarding process. supports IOT_STAT_LV_START/CONN/DONE/FAIL */
	IOT_STATUS_NEED_INTERACT = (1 << 2), /**< For user interation status. need to interact with user. only supports IOT_STAT_LV_STAY/FAIL */
	IOT_STATUS_CONNECTING = (1 << 3),    /**< For server connecting status. do connecting server. supports IOT_STAT_LV_START/DONE/FAIL */

	IOT_STATUS_ALL = (IOT_STATUS_IDLE | IOT_STATUS_PROVISIONING
                      | IOT_STATUS_NEED_INTERACT | IOT_STATUS_CONNECTING),
} iot_status_t;

Contains a enumeration values for types of iot_status.

iot_stat_lv_t

typedef enum iot_stat_lv {
	IOT_STAT_LV_STAY = 0,     /**< meanings for staying level with each status */
	IOT_STAT_LV_START = 1,    /**< meanings for start level with each status  */
	IOT_STAT_LV_DONE = 2,     /**< meanings for done level with each status */
	IOT_STAT_LV_FAIL = 3,     /**< meanings for fail level with each status */
	IOT_STAT_LV_CONN = 4,     /**< meanings for connection with mobile */
	IOT_STAT_LV_SIGN_UP = IOT_STAT_LV_START, /**< meanings for trying to sign-up process */
	IOT_STAT_LV_SIGN_IN = 6,  /**< meanings for trying to sign-in process */
} iot_stat_lv_t;

Contains a enumeration values for types of iot_status level.

iot_pin_t

typedef struct iot_pin_t {
	unsigned char pin[8];    /**< actual pin values */
} iot_pin_t;

Contains a pin values for pin type onboarding process.

iot_cap_val_type_t

typedef enum iot_cap_val_type {
	IOT_CAP_VAL_TYPE_UNKNOWN = -1,  /**< For undefined type. */
	IOT_CAP_VAL_TYPE_INTEGER,       /**< For integer. */
	IOT_CAP_VAL_TYPE_NUMBER,        /**< For float number. */
	IOT_CAP_VAL_TYPE_INT_OR_NUM,    /**< For integer or float number. */
	IOT_CAP_VAL_TYPE_STRING,        /**< For NULL-terminated string. */
	IOT_CAP_VAL_TYPE_STR_ARRAY,     /**< For array of NULL-terminated strings. */
	IOT_CAP_VAL_TYPE_JSON_OBJECT,   /**< For json object. */
	IOT_CAP_VAL_TYPE_BOOLEAN        /**< For boolean. */
} iot_cap_val_type_t;

Contains a enumeration values for types of capability.

iot_cap_val_t

typedef struct {
	/**
	 * Data type to notify valid data.
	 *
	 * Even though there are 4 different type of data
	 * (integer, number, string, strings) in this structure,
	 * only one type of data is used.
	 */
	iot_cap_val_type_t type; /**< Type of capability's data. */

	uint8_t str_num; /**< Number of stings. Only used for sting array. */
	int integer;     /**< Integer. */

	union {
		double number;     /**< Float number. */
		char *string;      /**< NULL-terminated string. */
		char **strings;    /**< Array of NULL-terminated strings. */
		char *json_object; /**< Json object payload strings */
		bool boolean;      /**< boolean */
	};
} iot_cap_val_t;

Contains a various type of data which can be int, double, string and string array.

iot_info_type_t

typedef enum iot_info_type {
	IOT_INFO_TYPE_IOT_STATUS_AND_STAT,  /**< get current st_status. */
	IOT_INFO_TYPE_IOT_PROVISIONED,      /**< get provision state, provisioned or not */
} iot_info_type_t;

Contains a enumeration values for types of notification.

Files

APIs.md

Latest commit

History

APIs.md

File metadata and controls

SmartThings SDK for Direct Connected Devices - C APIs

Connection APIs

st_conn_init

st_conn_set_noti_cb

st_conn_start

st_conn_cleanup

st_conn_ownership_confirm

Capability APIs

st_cap_handle_init

st_cap_cmd_set_cb

st_cap_create_attr

st_cap_free_attr

st_cap_send_attr

Utility APIs

st_info_get

st_create_log_dump

Macros

ST_CAP_CREATE_ATTR_NUMBER

ST_CAP_SEND_ATTR_NUMBER

ST_CAP_CREATE_ATTR_STRING

ST_CAP_SEND_ATTR_STRING

ST_CAP_CREATE_ATTR_STRINGS_ARRAY

ST_CAP_SEND_ATTR_STRINGS_ARRAY

Typedefs

IOT_CTX

IOT_CAP_HANDLE

IOT_EVENT

st_status_cb

st_cap_init_cb

st_cap_noti_cb

st_cap_cmd_cb

iot_status_t

iot_stat_lv_t

iot_pin_t

iot_cap_val_type_t

iot_cap_val_t

iot_info_type_t