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 |
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
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.
#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_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 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.