- Connection APIs
- Capability APIs
- Utility APIs
- Macros
- 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_cap_attr_option_t
- iot_cap_cmd_data_t
- iot_preference_data
- iot_noti_type_t
- iot_noti_data_raw_t
- iot_noti_data_t
- iot_ext_args_t
- iot_info_type_t
- iot_info_data_t
- iot_dump_mode_t
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.
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.
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.
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.
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 |
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.
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.
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.
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
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
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
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. |
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
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.
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.
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.
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.
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.
#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
#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
#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
#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
#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
#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
typedef void *IOT_CTX;
iot_context handle
typedef void *IOT_CAP_HANDLE;
capability handle
typedef void *IOT_EVENT;
event data
typedef void (*st_status_cb)(iot_status_t iot_status, iot_stat_lv_t stat_lv, void *usr_data);
typedef void (*st_cap_init_cb)(IOT_CAP_HANDLE *cap_handle, void *init_usr_data);
typedef void (*st_cap_noti_cb)(iot_noti_data_t *noti_data, void *noti_usr_data);
typedef void (*st_cap_cmd_cb)(IOT_CAP_HANDLE *cap_handle, iot_cap_cmd_data_t *cmd_data, void *usr_data);
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.
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.
typedef struct iot_pin_t {
unsigned char pin[8]; /**< actual pin values */
} iot_pin_t;
Contains a pin values for pin type onboarding process.
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.
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.
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
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.
typedef struct {
char *preference_name; /**< Name of the preference. */
iot_cap_val_t preference_data; /**<Value of the preference. */
} iot_preference_data;
Preference data
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.
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.
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.
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.
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.
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.
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