Types specific to the S2C Library. More...

Data Structures
struct	s2c_mobile_client_info_t
	Information about a connected Mobile client This is returned by s2c_get_mobile_client_list() More...

struct	s2c_file_target_t
	Target of S2C file operation. More...

struct	s2c_file_t
	S2C file information. More...

struct	s2c_file_handle_t
	S2C File handle, returned by s2c_file_open() or s2c_file_create() More...

struct	s2c_file_list_parameters_t
	File listing parameters. More...

Typedefs
typedef void(*	s2c_status_update_handler_t) (s2c_status_flag_t new_status)
	Handler to be triggered when the device's status changes. More...

typedef const void *	s2c_config_t[S2C_SETTING_COUNT]
	Array of pointers to configure the S2C library.

typedef void(*	s2c_cloud_message_callback_t) (msgpack_object_dict_t *dictionary)
	Callback when the cloud issues a non-stream message to the device via websocket. More...

typedef uint8_t (	s2c_broadcast_callback_t) (uint8_t *buffer, uint16_t max_length)
	Custom broadcast packet callback. More...

typedef zos_bool_t(*	s2c_command_callback_t) (const s2c_mobile_client_info_t client, const char command_string)
	Callback for when a Mobile attempts to execute a command on the Device. More...

typedef void(*	s2c_stream_listener_t) (const char stream, void arg, msgpack_object_dict_t *dictionary)
	Callback for when stream data has been received from the Cloud or Mobile. More...

Enumerations
enum	s2c_setting_t { S2C_SETTING_FLAGS, S2C_SETTING_CLOUD_TOKEN, S2C_SETTING_DEVICE_KEY, S2C_SETTING_DEVICE_CODE, S2C_SETTING_DEVICE_TITLE, S2C_SETTING_BROADCAST_CALLBACK, S2C_SETTING_CLOUD_DISCONNECTED_HANDLER, S2C_SETTING_LOCAL_CONNECTED_HANDLER, S2C_SETTING_LOCAL_DISCONNECTED_HANDLER, S2C_SETTING_STREAM_READ_REQUEST_HANDLER, S2C_SETTING_COMMAND_CALLBACK, S2C_SETTING_CLOUD_MESSAGE_CALLBACK, S2C_SETTING_STATUS_UPDATE_HANDLER, S2C_SETTING_MOBILE_FILE_TIMEOUT, S2C_SETTING_COUNT }
	S2C library settings. More...

enum	s2c_flag_t { S2C_FLAG_BROADCAST_ENABLED = (1 << 1), S2C_FLAG_GUEST_VERIFICATION_REQUIRED = (1 << 2), S2C_FLAG_GUESTS_ALWAYS_ALLOWED = (1 << 3), S2C_FLAG_SETUP_VERIFICATION_REQUIRED = (1 << 4) }
	S2C Settings flags. More...

enum	s2c_status_flag_t { S2C_STATUS_HAVE_DEVICE_KEY = (1 << 0), S2C_STATUS_HAVE_CLOUD_TOKEN = (1 << 1), S2C_STATUS_SERVER_ON_WLAN = (1 << 2), S2C_STATUS_SERVER_ON_SOFTAP = (1 << 3), S2C_STATUS_CLOUD_CONNECTED = (1 << 4), S2C_STATUS_MOBILE_CONNECTED = (1 << 5), S2C_STATUS_DEVICE_LISTENERS = (1 << 6), S2C_STATUS_HOST_LISTENERS = (1 << 7), S2C_STATUS_SOFTAP_OPEN = (1 << 8), S2C_STATUS_GUESTS_ALLOWED = (1 << 9), S2C_STATUS_GUESTS_CONNECTED = (1 << 10), S2C_STATUS_FILE_TRANSFER_ACTIVE = (1 << 11), S2C_STATUS_HOST_CONNECTED = (1 << 12), S2C_STATUS_SETUP_VERIFICATION_REQUIRED = (1 << 13) }
	The S2C libraries status. More...

enum	s2c_node_t { S2C_NODE_DEVICE = 0, S2C_NODE_HOST = 1, S2C_NODE_MOBILE = 2, S2C_NODE_CLOUD = 3, S2C_NODE_DMS_DEVICE = 4, S2C_NODE_DMS_PRODUCT = 5 }
	The target system node of a packet. More...

enum	s2c_mobile_client_flag_t
	Mobile client flags.

enum	s2c_response_code_t { S2C_RESPONSE_CODE_SUCCESS = 0, S2C_RESPONSE_CODE_FAILED = 1, S2C_RESPONSE_CODE_PARSE_ERROR = 2, S2C_RESPONSE_CODE_UNKNOWN = 3, S2C_RESPONSE_CODE_TOO_FEW_ARGS = 4, S2C_RESPONSE_CODE_TOO_MANY_ARGS = 5, S2C_RESPONSE_CODE_UNKNOWN_OPTION = 6, S2C_RESPONSE_CODE_BAD_ARGS = 7, S2C_RESPONSE_CODE_BUFFER_OVERFLOW = 8 }
	Command response code. More...

enum	s2c_file_flag_t { S2C_FILE_FLAG_OVERWRITE = (1 << 1) }
	S2C file operation flags. More...

Detailed Description

Types specific to the S2C Library.

Typedef Documentation

typedef uint8_t*(* s2c_broadcast_callback_t) (uint8_t *buffer, uint16_t max_length)

Custom broadcast packet callback.

This is periodically called when the device broadcasts on the local network. It is also called when the device periodically updates its cloud connection.

This callback may be used to add custom device information to the broadcast packet.

Note: The format of the packet MUST be in MessagePack. Refer to the MessagePack for more information about how to construct MessagePack data.

Parameters

`buffer`	Buffer to hold the custom broadcast data in MessagePack format
`max_length`	The maximum length of the supplied buffer

Returns: Pointer to the end of the buffered data

typedef void(* s2c_cloud_message_callback_t) (msgpack_object_dict_t *dictionary)

Callback when the cloud issues a non-stream message to the device via websocket.

This callback executes in the context of the Zap thread. The callback is supplied with the parsed JSON tokens context. The context is automatically cleaned up after the callback returns.

See the following link for the various messages the cloud may issue: https://cloud.zentri.com/support/api/device/ws

Parameters

dictionary The parsed JSON context, msgpack_object_dict_t

typedef zos_bool_t(* s2c_command_callback_t) (const s2c_mobile_client_info_t *client, const char *command_string)

Callback for when a Mobile attempts to execute a command on the Device.

This callback can be used as a security feature. It is called before a local client attempts to execute a command. If the callback returns ZOS_FALSE then the command won't be executed and the client will receive and error code.

If the callback returns ZOS_TRUE then the command will be executed.

Note: Some commands are required as part of the setup process. If this callback always returns ZOS_FALSE then the device will not be able to be setup.

Parameters

`client`	The mobile client attempting to execute the command, see s2c_mobile_client_info_t
`command_string`	The command string the Mobile wants to execute

Returns: ZOS_TRUE if the remote Mobile is allowed to execute the command, ZOS_FALSE else

typedef void(* s2c_status_update_handler_t) (s2c_status_flag_t new_status)

Handler to be triggered when the device's status changes.

This handler is triggered whenever the device's status flags change, see s2c_status_flag_t

This handler should be registered with the setting S2C_SETTING_STATUS_UPDATE_HANDLER

Parameters

new_status The new status of the Device, see s2c_status_flag_t

typedef void(* s2c_stream_listener_t) (const char *stream, void *arg, msgpack_object_dict_t *dictionary)

Callback for when stream data has been received from the Cloud or Mobile.

This callback executes in the context of the Zap thread. The callback is supplied with the parsed JSON tokens. The tokens are automatically cleaned up after the callback returns.

Parameters

`stream`	The stream whose data has been received from the Cloud or Mobile
`arg`	Argument supplied when the listener was registered, s2c_register_listener()
`dictionary`	The parsed JSON context, msgpack_object_dict_t

Enumeration Type Documentation

enum s2c_file_flag_t

S2C file operation flags.

Enumerator
S2C_FILE_FLAG_OVERWRITE	Overwrite exiting file if necessary.

enum s2c_flag_t

S2C Settings flags.

Enumerator
S2C_FLAG_BROADCAST_ENABLED	Enable UDP broadcast for advertising device on local network.
S2C_FLAG_GUEST_VERIFICATION_REQUIRED	Mobile client guest connections are verified by Cloud beforing being granted access. Note Only the Mobile client requires an internet connection If NOT enabled, Mobile client guest connections are NOT verified by the Cloud, In this case no Cloud connection is required
S2C_FLAG_GUESTS_ALWAYS_ALLOWED	If this flag is set then guest connections are always allowed, otherwise s2c_allow_mobile_client_guests() must first be invoked before a guest may connect.
S2C_FLAG_SETUP_VERIFICATION_REQUIRED	If set, the host/device must verify a mobile before the mobile may continue device setup.

enum s2c_node_t

The target system node of a packet.

Enumerator
S2C_NODE_DEVICE	The Device (i.e. the ZentriOS application running a ZentriOS module)
S2C_NODE_HOST	The external host MCU connected to the Device's serial bus.
S2C_NODE_MOBILE	Mobile application (e.g. iPhone or Android App)
S2C_NODE_CLOUD	S2C Cloud connector.
S2C_NODE_DMS_DEVICE	Device Management Server device (e.g. files specific to the device)
S2C_NODE_DMS_PRODUCT	Device Management Server product (e.g. files specific to the product the device is associated)

enum s2c_response_code_t

Command response code.

Enumerator
S2C_RESPONSE_CODE_SUCCESS	The command was successful.
S2C_RESPONSE_CODE_FAILED	The command failed, probably in the firmware somewhere.
S2C_RESPONSE_CODE_PARSE_ERROR	Failed to parse the command.
S2C_RESPONSE_CODE_UNKNOWN	Unknown command.
S2C_RESPONSE_CODE_TOO_FEW_ARGS	Not enough command arguments.
S2C_RESPONSE_CODE_TOO_MANY_ARGS	Too many command arguments.
S2C_RESPONSE_CODE_UNKNOWN_OPTION	Unknown option (e.g. known 'set' command option)
S2C_RESPONSE_CODE_BAD_ARGS	Invalid command arguments.
S2C_RESPONSE_CODE_BUFFER_OVERFLOW	Serial command line buffer overflow.

enum s2c_setting_t

S2C library settings.

These index the s2c_config_t passed to the library on initialization.

Enumerator
S2C_SETTING_FLAGS	Settings flags, see s2c_flag_t.
S2C_SETTING_CLOUD_TOKEN	Cloud token supplied by a remote app, this is used to log the device into the cloud.
S2C_SETTING_DEVICE_KEY	Device key supplied by a remote app for encryption local server client connects, this is used to encrypt connects with local mobile apps.
S2C_SETTING_DEVICE_CODE	The code of this device (e.g BMC123) this is broadcasted on the local network.
S2C_SETTING_DEVICE_TITLE	A custom title for the device (e.g. Kitchen Light), this may be set by the mobile app or the cloud, Note this value is broadcast in the mDNS TXT record and UDP broadcast packet, i.e. it'll be visible to mobile app's trying to discover the device
S2C_SETTING_BROADCAST_CALLBACK	Optional callback to broadcast custom packets for devcie, see s2c_broadcast_callback_t.
S2C_SETTING_CLOUD_DISCONNECTED_HANDLER	Optional event handler which indicates if the remote cloud disconnects, zos_event_handler_t.
S2C_SETTING_LOCAL_CONNECTED_HANDLER	Optional event handler which indicates if a client connects to the local server, zos_event_handler_t.
S2C_SETTING_LOCAL_DISCONNECTED_HANDLER	Optional event handler which indicates if a client disconnect from the local server, zos_event_handler_t.
S2C_SETTING_STREAM_READ_REQUEST_HANDLER	Optional event handler which indicates if a client requests the device's current stream values, zos_event_handler_t.
S2C_SETTING_COMMAND_CALLBACK	Optional, s2c_command_callback_t, callback which is called when a locally connected Mobile issues a command to the Device. This callback can stop the command from executing.
S2C_SETTING_CLOUD_MESSAGE_CALLBACK	Optional, s2c_cloud_message_callback_t, callback which is called when the cloud issues a non-stream message to the Device via websocket.
S2C_SETTING_STATUS_UPDATE_HANDLER	Optional event handler which invokes @ ref s2c_status_update_handler_t when the device's status flags change.
S2C_SETTING_MOBILE_FILE_TIMEOUT	The maximum amount of time in seconds to wait for mobile to accept the host/device's file operation before timeout. Default value is 7 seconds
S2C_SETTING_COUNT	The total number of settings.

enum s2c_status_flag_t

The S2C libraries status.

These flags are broadcasts on the local network

Enumerator
S2C_STATUS_HAVE_DEVICE_KEY	The device has a key for the local server (i.e. local connections are encrypted)
S2C_STATUS_HAVE_CLOUD_TOKEN	The device has a cloud token (i.e. it's able to connect to the cloud)
S2C_STATUS_SERVER_ON_WLAN	The device's local server is running the the WLAN interface.
S2C_STATUS_SERVER_ON_SOFTAP	The device's local server is running on the SoftAP interface.
S2C_STATUS_CLOUD_CONNECTED	The device is connected to the cloud.
S2C_STATUS_MOBILE_CONNECTED	One or more mobiles connected to device.
S2C_STATUS_DEVICE_LISTENERS	Device has listeners registered.
S2C_STATUS_HOST_LISTENERS	Host has listeners registered.
S2C_STATUS_SOFTAP_OPEN	The SoftAP is Open (i.e. non-secure), a Diffie-Hellman key exchange is required if the device does NOT have a key i.e. if the S2C_STATUS_HAVE_DEVICE_KEY flag is not set
S2C_STATUS_GUESTS_ALLOWED	Indicates the device allows guests connections.
S2C_STATUS_GUESTS_CONNECTED	Indicates if one or more guests are currently connected.
S2C_STATUS_FILE_TRANSFER_ACTIVE	A file is actively being transferred.
S2C_STATUS_HOST_CONNECTED	A host MCU is connected.
S2C_STATUS_SETUP_VERIFICATION_REQUIRED	A mobile must be verified by the host/device before it may continue device setup.

TypesSilicon-to-Cloud (S2C)

Data Structures

Typedefs

Enumerations

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Types
Silicon-to-Cloud (S2C)