Functions for device management. More...

Data Structures
struct	astarte_device_error_event_t
	Context for a single error event. More...

struct	astarte_device_connection_event_t
	Context for a single connection event. More...

struct	astarte_device_disconnection_event_t
	Context for a single disconnection event. More...

struct	astarte_device_data_event_t
	Common context for all data events. More...

struct	astarte_device_datastream_individual_event_t
	Context for a single datastream individual event. More...

struct	astarte_device_datastream_object_event_t
	Context for a single datastream object event. More...

struct	astarte_device_property_set_event_t
	Context for a single property set event. More...

struct	astarte_device_event_t
	Device event. More...

struct	astarte_device_config_t
	Configuration struct for an Astarte device. More...

Typedefs
typedef struct astarte_device *	astarte_device_handle_t
	Handle for an instance of an Astarte device.

Enumerations
enum	astarte_device_event_type_t { ASTARTE_DEVICE_EVENT_ERROR , ASTARTE_DEVICE_EVENT_CONNECTED , ASTARTE_DEVICE_EVENT_DISCONNECTED , ASTARTE_DEVICE_EVENT_DATASTREAM_INDIVIDUAL , ASTARTE_DEVICE_EVENT_DATASTREAM_OBJECT , ASTARTE_DEVICE_EVENT_PROPERTY_SET , ASTARTE_DEVICE_EVENT_PROPERTY_UNSET }
	Type of device event. More...

Functions
astarte_result_t	astarte_device_new (astarte_device_config_t cfg, astarte_device_handle_t device)
	Initialize the Astarte device.

astarte_result_t	astarte_device_destroy (astarte_device_handle_t device)
	Destroy the Astarte device instance.

astarte_result_t	astarte_device_add_interface (astarte_device_handle_t device, const astarte_interface_t *interface)
	add an interface to the device.

astarte_result_t	astarte_device_remove_interface (astarte_device_handle_t device, const astarte_interface_t *interface)
	Remove an interface from the device.

astarte_result_t	astarte_device_connect (astarte_device_handle_t device)
	Connect a device to Astarte.

astarte_result_t	astarte_device_disconnect (astarte_device_handle_t device, k_timeout_t timeout)
	Disconnect the Astarte device instance.

astarte_result_t	astarte_device_force_disconnect (astarte_device_handle_t device)
	Force a disconnection for the Astarte device instance.

astarte_result_t	astarte_device_send_individual (astarte_device_handle_t device, const char interface_name, const char path, astarte_data_t data, const int64_t *timestamp)
	Send a value through the device connection.

astarte_result_t	astarte_device_send_object (astarte_device_handle_t device, const char interface_name, const char path, astarte_object_entry_t entries, size_t entries_len, const int64_t timestamp)
	Send an aggregated object through the device connection.

astarte_result_t	astarte_device_set_property (astarte_device_handle_t device, const char interface_name, const char path, astarte_data_t data)
	Set a device property to the provided value.

astarte_result_t	astarte_device_unset_property (astarte_device_handle_t device, const char interface_name, const char path)
	Unset a device property.

astarte_result_t	astarte_device_get_event (astarte_device_handle_t device, astarte_device_event_t *event, k_timeout_t timeout)
	Fetch the next error event from the Astarte device.

void	astarte_device_event_cleanup (astarte_device_event_t *event)
	Cleanup an Astarte device event.

Detailed Description

Functions for device management.

Typedef Documentation

◆ astarte_device_handle_t

typedef struct astarte_device* astarte_device_handle_t

Handle for an instance of an Astarte device.

Each handle is a pointer to an opaque internally allocated data struct containing all the data for the Astarte device.

Enumeration Type Documentation

◆ astarte_device_event_type_t

enum astarte_device_event_type_t

Type of device event.

Enumerator
ASTARTE_DEVICE_EVENT_ERROR	Error event.
ASTARTE_DEVICE_EVENT_CONNECTED	Connection event.
ASTARTE_DEVICE_EVENT_DISCONNECTED	Disconnection event.
ASTARTE_DEVICE_EVENT_DATASTREAM_INDIVIDUAL	Datastream individual event.
ASTARTE_DEVICE_EVENT_DATASTREAM_OBJECT	Datastream object event.
ASTARTE_DEVICE_EVENT_PROPERTY_SET	Property set event.
ASTARTE_DEVICE_EVENT_PROPERTY_UNSET	Property unset event.

Function Documentation

◆ astarte_device_add_interface()

astarte_result_t astarte_device_add_interface	(	astarte_device_handle_t	device,
		const astarte_interface_t *	interface )

add an interface to the device.

Note: This function works asynchronously.; The user is responsible for making sure the interface struct remains valid for the lifetime of the device. It is recommended to declare interface structs as static constants.

Parameters

device	A valid Astarte device handle.
interface	The interface to add to the device.

Returns: ASTARTE_RESULT_OK if successful, otherwise an error code.

◆ astarte_device_connect()

astarte_result_t astarte_device_connect ( astarte_device_handle_t device )

Connect a device to Astarte.

Parameters

[in] device Device instance to connect to Astarte.

Returns: ASTARTE_RESULT_OK if successful, otherwise an error code.

◆ astarte_device_destroy()

astarte_result_t astarte_device_destroy ( astarte_device_handle_t device )

Destroy the Astarte device instance.

Note: The device handle will become invalid after this operation.; If the device is connected when calling this function it will be forcefully disconnected.

Parameters

[in] device Device instance to be destroyed.

Returns: ASTARTE_RESULT_OK if successful, otherwise an error code.

◆ astarte_device_disconnect()

astarte_result_t astarte_device_disconnect	(	astarte_device_handle_t	device,
		k_timeout_t	timeout )

Disconnect the Astarte device instance.

This function will block until all QoS 1/2 pending messages have been successfully transmitted for a timeout hass been reached.

Note: It will be possible to re-connect the device after disconnection.

Parameters

[in]	device	Device instance to be disconnected.
[in]	timeout	Timeout for the disconnection.

Returns: ASTARTE_RESULT_OK if successful, otherwise an error code.

◆ astarte_device_event_cleanup()

void astarte_device_event_cleanup ( astarte_device_event_t * event )

Cleanup an Astarte device event.

Parameters

[in] event Pointer to the event struct to cleanup.

◆ astarte_device_force_disconnect()

astarte_result_t astarte_device_force_disconnect ( astarte_device_handle_t device )

Force a disconnection for the Astarte device instance.

This function will disconnect the device from the Astarte device, ignoring any pending messages if present. The function will be non blocking and the disconnection immediate.

Note: It will be possible to re-connect the device after disconnection.

Parameters

[in] device Device instance to be disconnected.

Returns: ASTARTE_RESULT_OK if successful, otherwise an error code.

◆ astarte_device_get_event()

astarte_result_t astarte_device_get_event	(	astarte_device_handle_t	device,
		astarte_device_event_t *	event,
		k_timeout_t	timeout )

Fetch the next error event from the Astarte device.

Note: Events must be cleaned up with astarte_device_event_cleanup to prevent memory leaks.

Parameters

[in]	device	Handle to the device instance.
[out]	event	Pointer to the event struct to populate.
[in]	timeout	Zephyr timeout (e.g., K_FOREVER, K_NO_WAIT, or K_MSEC).

Returns: ASTARTE_RESULT_OK if an event was received, ASTARTE_RESULT_TIMEOUT if the queue was empty.

◆ astarte_device_new()

astarte_result_t astarte_device_new	(	astarte_device_config_t *	cfg,
		astarte_device_handle_t *	device )

Initialize the Astarte device.

This function has to be called to initialize the device SDK before doing anything else. If an error code is returned the astarte_device_destroy function must not be called.

Note: A device can be initialized and connected to Astarte only if it has been previously registered on Astarte.; A single device can be initialized at a time. If the device is already initialized, this function will return an error code.

Parameters

[in]	cfg	Configuration struct.
[out]	device	Device instance initialized.

Returns: ASTARTE_RESULT_OK if successful, otherwise an error code.

◆ astarte_device_remove_interface()

astarte_result_t astarte_device_remove_interface	(	astarte_device_handle_t	device,
		const astarte_interface_t *	interface )

Remove an interface from the device.

Note: This function works asynchronously.; The user is responsible for making sure the interface struct remains valid for the lifetime of the device. It is recommended to declare interface structs as static constants.

Parameters

device	A valid Astarte device handle.
interface	The interface to remove from the device.

Returns: ASTARTE_RESULT_OK if successful, otherwise an error code.

◆ astarte_device_send_individual()

astarte_result_t astarte_device_send_individual	(	astarte_device_handle_t	device,
		const char *	interface_name,
		const char *	path,
		astarte_data_t	data,
		const int64_t *	timestamp )

Send a value through the device connection.

Parameters

[in]	device	Handle to the device instance.
[in]	interface_name	Interface where to publish data.
[in]	path	Path where to publish data.
[in]	data	Astarte value to send.
[in]	timestamp	Timestamp of the message, ignored if set to NULL.

Returns: ASTARTE_RESULT_OK if successful, otherwise an error code.

◆ astarte_device_send_object()

astarte_result_t astarte_device_send_object	(	astarte_device_handle_t	device,
		const char *	interface_name,
		const char *	path,
		astarte_object_entry_t *	entries,
		size_t	entries_len,
		const int64_t *	timestamp )

Send an aggregated object through the device connection.

Parameters

[in]	device	Handle to the device instance.
[in]	interface_name	Interface where to publish data.
[in]	path	Path where to publish data.
[in]	entries	The object entries to stream, organized as an array.
[in]	entries_len	The number of element in the `entries` array.
[in]	timestamp	Timestamp of the message, ignored if set to NULL.

Returns: ASTARTE_RESULT_OK if successful, otherwise an error code.

◆ astarte_device_set_property()

astarte_result_t astarte_device_set_property	(	astarte_device_handle_t	device,
		const char *	interface_name,
		const char *	path,
		astarte_data_t	data )

Set a device property to the provided value.

Parameters

[in]	device	Handle to the device instance.
[in]	interface_name	Interface of the property.
[in]	path	Path of the property.
[in]	data	New value for the property.

Returns: ASTARTE_RESULT_OK if successful, otherwise an error code.

◆ astarte_device_unset_property()

astarte_result_t astarte_device_unset_property	(	astarte_device_handle_t	device,
		const char *	interface_name,
		const char *	path )

Unset a device property.

Parameters

[in]	device	Handle to the device instance.
[in]	interface_name	Interface of the property.
[in]	path	Path of the property.

Returns: ASTARTE_RESULT_OK if successful, otherwise an error code.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ astarte_device_handle_t

Enumeration Type Documentation

◆ astarte_device_event_type_t

Function Documentation

◆ astarte_device_add_interface()

◆ astarte_device_connect()

◆ astarte_device_destroy()

◆ astarte_device_disconnect()

◆ astarte_device_event_cleanup()

◆ astarte_device_force_disconnect()

◆ astarte_device_get_event()

◆ astarte_device_new()

◆ astarte_device_remove_interface()

◆ astarte_device_send_individual()

◆ astarte_device_send_object()

◆ astarte_device_set_property()

◆ astarte_device_unset_property()