Skip to content

Files

Latest commit

bf0d20f · Jan 10, 2025

History

History
868 lines (711 loc) · 28.6 KB

APIs.md

File metadata and controls

868 lines (711 loc) · 28.6 KB

SmartThings SDK for Direct Connected Devices - C APIs



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

st_conn_start_ex

int st_conn_start_ex(IOT_CTX *iot_ctx,
                    iot_ext_args_t *ext_args);

expanded st-iot-core server connection function

This function tries to connect server with extension arguments

Parameters

direction name purpose
in iot_ctx iot_context handle generated by st_conn_init()
in ext_args extension arguments for sepcific connection control

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


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.

See Also
ST_CAP_CREATE_NUMBER
ST_CAP_CREATE_STRING
ST_CAP_CREATE_STRING_ARRAY

st_cap_create_attr_with_option

IOT_EVENT* st_cap_create_attr_with_option(IOT_CAP_HANDLE *cap_handle,
                              const char *attribute,
                              iot_cap_val_t *value,
                              const char *unit,
                              const char *data,
                              iot_cap_attr_option_t *options);

Create IOT_EVENT data including options

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.
in options The option object if needed. Otherwise NULL.

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

See Also
ST_CAP_CREATE_NUMBER
ST_CAP_CREATE_STRING
ST_CAP_CREATE_STRING_ARRAY

st_cap_create_attr_with_id

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

Create Create IOT_EVENT data with releated command ID

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.
in command_id The commandId related with the this event if needed. Otherwise NULL.

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

See Also
ST_CAP_CREATE_NUMBER
ST_CAP_CREATE_STRING
ST_CAP_CREATE_STRING_ARRAY

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.

See Also
ST_CAP_SEND_ATTR_NUMBER
ST_CAP_SEND_ATTR_STRING
ST_CAP_SEND_ATTR_STRING_ARRAY


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.

st_change_health_period

int st_change_health_period(IOT_CTX *iot_ctx,
                       unsigned int new_period);

change sending health period

This function changes health ping period.

Parameters

direction name purpose
in iot_ctx iot_context handle generated by st_conn_init()
in new_period new health ping period to change (seconds)

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

st_change_device_name

int st_change_health_period(IOT_CTX *iot_ctx,
                       const char *new_name);

change device name

This function changes device name. It reflects ST app's device name.

Parameters

direction name purpose
in iot_ctx iot_context handle generated by st_conn_init()
in new_name new device name null-terminated string

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

st_cap_send_attr_v2

int st_cap_send_attr_v2(IOT_CTX *iot_ctx,
                      st_attr_data* attr_data[],
                      uint8_t attr_num);

Request to publish deviceEvent.(version 2)

This function sends list of attr data to server. When there is no error, this function returns sequence number, which is unique value to identify the deviceEvent message.

Parameters

direction name purpose
in iot_ctx iot_context handle generated by st_conn_init()
in attr_data The st_attr_data data list to create the deviceEvent.
in attr_num The number of attr_data list.

Returns
return sequence number(which is positive integer) if successful, negative integer 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_NULL,          /**< For null 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_cap_attr_option_t

typedef struct {
	uint8_t state_change; /**< force this attribute value update event */
	char *command_id;     /**< event related commandId, if not used, set NULL */
	bool *displayed;      /**< whether the event should be displayed in the history feed, if not used, set NULL */
} iot_cap_val_t;

Attribute extended options structure

iot_cap_cmd_data_t

typedef struct {
	/**
	 * Number of arguments.
	 *
	 * Usally 1, but if commands type is 'json object',
	 * it could be more than 1. (See colorControl capability.)
	 */
	uint8_t num_args;       /**< Number of arguments. */

	/**
	 * Name of each argument.
	 *
	 * This is used only if there is more than one argument.
	 */
	iot_cap_val_t *cmd_data;	/**< Value of each arguments. */

	int total_commands_num;		/**< Total number of commands in a bunch of commands */
	int order_of_command;		  /**< Order of this command in a bunch of commands */

	char *command_id;		      /**< commandId */	 
} iot_cap_cmd_data_t;

Contains data for "command" payload.

iot_preference_data

typedef struct {
	char *preference_name;	/**< Name of the preference. */
	iot_cap_val_t preference_data;	/**<Value of the preference. */
} iot_preference_data;

Preference data

iot_noti_type_t

typedef enum iot_noti_type {
	IOT_NOTI_TYPE_UNKNOWN = -1,		     /**< For undefined type. */
	IOT_NOTI_TYPE_DEV_DELETED,		     /**< For device deleted event. */
	IOT_NOTI_TYPE_RATE_LIMIT,		       /**< For rate limit event. */
	IOT_NOTI_TYPE_QUOTA_REACHED,		   /**< For data quota reached event. */
	IOT_NOTI_TYPE_SEND_FAILED,		     /**< For send failed event. */
	IOT_NOTI_TYPE_COMMANDS,			       /**< For commands */
	IOT_NOTI_TYPE_PREFERENCE_UPDATED,  /**< For preference update */
} iot_noti_type_t;

Contains a enumeration values for types of notification.

iot_noti_data_raw_t

typedef union {
	/* rate limit case */
	struct _rate_limit {
		int count;			                        /**< Current rate limit count. */
		int threshold;		                      /**< Current rate limit threshold. */
		int remainingTime;	                    /**< How much time remains for rate limit releasing. */
		int sequenceNumber;	                    /**< Sequence number of event that triggered rate limit */
	} rate_limit;
	/* quota reached case */
	struct _quota {
		int used;			                          /**< Current used data usage in bytes. */
		int limit;			                        /**< Current data limit in bytes. */
	} quota;
	/* send fail case */
	struct _send_fail {
		int failed_sequence_num;		            /**< Send failed events sequence number. */
	} send_fail;
	/* commands */
	struct _commands {
		st_command_data *commands_data;	        /**< commands data list */
		int commands_num;					              /**< Number of commands data list */
	} commands;
	/* Preference */
	struct _preferences {
		size_t preferences_num;		              /**< Number of preferences data list */
		iot_preference_data *preferences_data;	/**< Preferences data list */
	} preferences;
} iot_noti_data_raw_t;

Contains data for raw data of each notification.

iot_noti_data_t

typedef struct {
	iot_noti_type_t type;	    /**< Type of notification's data. */
	iot_noti_data_raw_t raw;	/**< Raw data of each notification. */
} iot_noti_data_t;

Contains data for notification data.

iot_ext_args_t

typedef struct {
	st_status_cb status_cb;	/**< user callback function to receive status of st-iot-core */
	iot_status_t maps;		  /**< status of st-iot-core interested to receive through status_cb */
	void *usr_data;			    /**< user data(a pointer) to use in status_cb */
	iot_pin_t *pin_num;		  /**< if PIN ownership validation type used, valid 8 digit pin should be set. otherwise set null. */

	iot_status_t start_pt;	/**< starting connection point, support only IOT_STATUS_PROVISIONING & IOT_STATUS_CONNECTING cases */
	bool skip_usr_confirm;	/**< set true to skip user-confirm, else false. */
} iot_ext_args_t;

Contains data for extension options.

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.

iot_info_data_t

typedef union {
	/* to get current iot_status case */
	struct _st_status {
		iot_status_t iot_status;	/**< current reported status of st-iot-core. */
		iot_stat_lv_t stat_lv;		/**< current reported iot_status's level. */
	} st_status;
	/* to get provisioned state case */
	bool provisioned;				    /**< to check provisoned or not */
} iot_info_data_t;

Contains data for iot-core information.

iot_dump_mode_t

typedef enum iot_dump_mode {
    IOT_DUMP_MODE_NEED_BASE64 = (1 << 0),	       /**< make log encoded to base64 */
    IOT_DUMP_MODE_NEED_DUMP_STATE = (1 << 1),    /**< add dump_state in log_dump */
} iot_dump_mode_t;

Contains a enumeration values for mode of iot_dump