Overview

Implementation of RDMnet device functionality; see Using the Device API.

RDMnet devices are clients which exclusively receive and respond to RDM commands. Devices operate on only one scope at a time. This API wraps the RDMnet Client API and provides functions tailored specifically to the usage concerns of an RDMnet device.

See Using the Device API for a detailed description of how to use this API.

Data Structures
struct	RdmnetDeviceCallbacks
	A set of notification callbacks received about a device. More...

struct	RdmnetVirtualEndpointConfig
	Configuration information for a virtual endpoint on a device. More...

struct	RdmnetPhysicalEndpointResponder
	Identifying information for a physical RDM responder connected to an RDMnet gateway. More...

struct	RdmnetPhysicalEndpointConfig
	Configuration information for a physical endpoint on a device. More...

struct	RdmnetDeviceConfig
	A set of information that defines the startup parameters of an RDMnet Device. More...

Macros
#define	RDMNET_DEVICE_INVALID -1
	An invalid RDMnet device handle value.

#define	RDMNET_VIRTUAL_ENDPOINT_INIT(endpoint_num)
	An initializer for an RdmnetVirtualEndpointConfig instance. More...

#define	RDMNET_PHYSICAL_ENDPOINT_INIT(endpoint_num)
	An initializer for an RdmnetPhysicalEndpointConfig instance. More...

#define	RDMNET_DEVICE_CONFIG_DEFAULT_INIT(manu_id)
	A default-value initializer for an RdmnetDeviceConfig struct. More...

Typedefs
typedef int	rdmnet_device_t
	A handle to an RDMnet device.

typedef void(*	RdmnetDeviceConnectedCallback) (rdmnet_device_t handle, const RdmnetClientConnectedInfo info, void context)
	A device has successfully connected to a broker. More...

typedef void(*	RdmnetDeviceConnectFailedCallback) (rdmnet_device_t handle, const RdmnetClientConnectFailedInfo info, void context)
	A connection attempt failed between a device and a broker. More...

typedef void(*	RdmnetDeviceDisconnectedCallback) (rdmnet_device_t handle, const RdmnetClientDisconnectedInfo info, void context)
	A device which was previously connected to a broker has disconnected. More...

typedef void(*	RdmnetDeviceRdmCommandReceivedCallback) (rdmnet_device_t handle, const RdmnetRdmCommand cmd, RdmnetSyncRdmResponse response, void *context)
	An RDM command has been received addressed to a device. More...

typedef void(*	RdmnetDeviceLlrpRdmCommandReceivedCallback) (rdmnet_device_t handle, const LlrpRdmCommand cmd, RdmnetSyncRdmResponse response, void *context)
	An RDM command has been received over LLRP, addressed to a device. More...

typedef void(*	RdmnetDeviceDynamicUidStatusCallback) (rdmnet_device_t handle, const RdmnetDynamicUidAssignmentList list, void context)
	The dynamic UID assignment status for a set of virtual responders has been received. More...

typedef struct RdmnetDeviceCallbacks	RdmnetDeviceCallbacks
	A set of notification callbacks received about a device.

typedef struct RdmnetVirtualEndpointConfig	RdmnetVirtualEndpointConfig
	Configuration information for a virtual endpoint on a device. More...

typedef struct RdmnetPhysicalEndpointResponder	RdmnetPhysicalEndpointResponder
	Identifying information for a physical RDM responder connected to an RDMnet gateway.

typedef struct RdmnetPhysicalEndpointConfig	RdmnetPhysicalEndpointConfig
	Configuration information for a physical endpoint on a device. More...

typedef struct RdmnetDeviceConfig	RdmnetDeviceConfig
	A set of information that defines the startup parameters of an RDMnet Device.

Functions
void	rdmnet_device_config_init (RdmnetDeviceConfig *config, uint16_t manufacturer_id)
	Initialize an RDMnet Device Config with default values for the optional config options. More...

void	rdmnet_device_set_callbacks (RdmnetDeviceConfig config, RdmnetDeviceConnectedCallback connected, RdmnetDeviceConnectFailedCallback connect_failed, RdmnetDeviceDisconnectedCallback disconnected, RdmnetDeviceRdmCommandReceivedCallback rdm_command_received, RdmnetDeviceLlrpRdmCommandReceivedCallback llrp_rdm_command_received, RdmnetDeviceDynamicUidStatusCallback dynamic_uid_status_received, void context)
	Set the main callbacks in an RDMnet device configuration structure. More...

etcpal_error_t	rdmnet_device_create (const RdmnetDeviceConfig config, rdmnet_device_t handle)
	Create a new instance of RDMnet device functionality. More...

etcpal_error_t	rdmnet_device_destroy (rdmnet_device_t handle, rdmnet_disconnect_reason_t disconnect_reason)
	Destroy a device instance. More...

etcpal_error_t	rdmnet_device_send_rdm_ack (rdmnet_device_t handle, const RdmnetSavedRdmCommand received_cmd, const uint8_t response_data, size_t response_data_len)
	Send an RDM ACK response from a device. More...

etcpal_error_t	rdmnet_device_send_rdm_nack (rdmnet_device_t handle, const RdmnetSavedRdmCommand *received_cmd, rdm_nack_reason_t nack_reason)
	Send an RDM NACK response from a device. More...

etcpal_error_t	rdmnet_device_send_rdm_update (rdmnet_device_t handle, uint16_t subdevice, uint16_t param_id, const uint8_t *data, size_t data_len)
	Send an asynchronous RDM GET response to update the value of a local parameter. More...

etcpal_error_t	rdmnet_device_send_rdm_update_from_responder (rdmnet_device_t handle, const RdmnetSourceAddr source_addr, uint16_t param_id, const uint8_t data, size_t data_len)
	Send an asynchronous RDM GET response to update the value of a parameter on a sub-responder. More...

etcpal_error_t	rdmnet_device_send_status (rdmnet_device_t handle, const RdmnetSavedRdmCommand received_cmd, rpt_status_code_t status_code, const char status_string)
	Send an RPT status message from a device. More...

etcpal_error_t	rdmnet_device_send_llrp_ack (rdmnet_device_t handle, const LlrpSavedRdmCommand received_cmd, const uint8_t response_data, uint8_t response_data_len)
	Send an ACK response to an RDM command received over LLRP. More...

etcpal_error_t	rdmnet_device_send_llrp_nack (rdmnet_device_t handle, const LlrpSavedRdmCommand *received_cmd, rdm_nack_reason_t nack_reason)
	Send an ACK response to an RDM command received over LLRP. More...

etcpal_error_t	rdmnet_device_add_physical_endpoint (rdmnet_device_t handle, const RdmnetPhysicalEndpointConfig *endpoint_config)
	Add a physical endpoint to a device. More...

etcpal_error_t	rdmnet_device_add_physical_endpoints (rdmnet_device_t handle, const RdmnetPhysicalEndpointConfig *endpoint_configs, size_t num_endpoints)
	Add multiple physical endpoints to a device. More...

etcpal_error_t	rdmnet_device_add_virtual_endpoint (rdmnet_device_t handle, const RdmnetVirtualEndpointConfig *endpoint_config)
	Add a virtual endpoint to a device. More...

etcpal_error_t	rdmnet_device_add_virtual_endpoints (rdmnet_device_t handle, const RdmnetVirtualEndpointConfig *endpoint_configs, size_t num_endpoints)
	Add multiple virtual endpoints to a device. More...

etcpal_error_t	rdmnet_device_remove_endpoint (rdmnet_device_t handle, uint16_t endpoint_id)
	Remove an endpoint from a device. More...

etcpal_error_t	rdmnet_device_remove_endpoints (rdmnet_device_t handle, const uint16_t *endpoint_ids, size_t num_endpoints)
	Remove multiple endpoints from a device. More...

etcpal_error_t	rdmnet_device_add_static_responders (rdmnet_device_t handle, uint16_t endpoint_id, const RdmUid *responder_uids, size_t num_responders)
	Add one or more responders with static UIDs to a virtual endpoint. More...

etcpal_error_t	rdmnet_device_add_dynamic_responders (rdmnet_device_t handle, uint16_t endpoint_id, const EtcPalUuid *responder_ids, size_t num_responders)
	Add one or more responders with dynamic UIDs to a virtual endpoint. More...

etcpal_error_t	rdmnet_device_add_physical_responders (rdmnet_device_t handle, uint16_t endpoint_id, const RdmnetPhysicalEndpointResponder *responders, size_t num_responders)
	Add one or more responders to a physical endpoint. More...

etcpal_error_t	rdmnet_device_remove_static_responders (rdmnet_device_t handle, uint16_t endpoint_id, const RdmUid *responder_uids, size_t num_responders)
	Remove one or more responders with static UIDs from a virtual endpoint. More...

etcpal_error_t	rdmnet_device_remove_dynamic_responders (rdmnet_device_t handle, uint16_t endpoint_id, const EtcPalUuid *responder_ids, size_t num_responders)
	Remove one or more responders with dynamic UIDs from a virtual endpoint. More...

etcpal_error_t	rdmnet_device_remove_physical_responders (rdmnet_device_t handle, uint16_t endpoint_id, const RdmUid *responder_uids, size_t num_responders)
	Remove one or more responders from a physical endpoint. More...

etcpal_error_t	rdmnet_device_change_scope (rdmnet_device_t handle, const RdmnetScopeConfig *new_scope_config, rdmnet_disconnect_reason_t disconnect_reason)
	Change the device's scope. More...

etcpal_error_t	rdmnet_device_change_search_domain (rdmnet_device_t handle, const char *new_search_domain, rdmnet_disconnect_reason_t disconnect_reason)
	Change the device's DNS search domain. More...

etcpal_error_t	rdmnet_device_get_scope (rdmnet_device_t handle, char scope_str_buf, EtcPalSockAddr static_broker_addr)
	Retrieve the device's current scope configuration. More...

Macro Definition Documentation

◆ RDMNET_DEVICE_CONFIG_DEFAULT_INIT

#define RDMNET_DEVICE_CONFIG_DEFAULT_INIT ( manu_id )

Value:

  {                                                                                            \
    {{0}}, {NULL, NULL, NULL, NULL, NULL, NULL, NULL}, NULL, RDMNET_SCOPE_CONFIG_DEFAULT_INIT, \
        {(0x8000 | manu_id), 0}, NULL, NULL, 0, NULL, 0, NULL, 0                               \
  }

A default-value initializer for an RdmnetDeviceConfig struct.

Usage:

RdmnetDeviceConfig config = RDMNET_DEVICE_CONFIG_DEFAULT_INIT(MY_ESTA_MANUFACTURER_ID);

// Now fill in the required portions as necessary with your data...

RDMNET_DEVICE_CONFIG_DEFAULT_INIT

#define RDMNET_DEVICE_CONFIG_DEFAULT_INIT(manu_id)

A default-value initializer for an RdmnetDeviceConfig struct.

Definition: device.h:297

RdmnetDeviceConfig

A set of information that defines the startup parameters of an RDMnet Device.

Definition: device.h:227

Parameters

manu_id Your ESTA manufacturer ID.

◆ RDMNET_PHYSICAL_ENDPOINT_INIT

#define RDMNET_PHYSICAL_ENDPOINT_INIT ( endpoint_num )

Value:

  {                                                 \
    (endpoint_num), NULL, 0                         \
  }

An initializer for an RdmnetPhysicalEndpointConfig instance.

Usage:

// Create a physical endpoint with an endpoint ID of 4.
RdmnetPhysicalEndpointConfig endpoint_config = RDMNET_PHYSICAL_ENDPOINT_INIT(4);
// Assign the other members of the struct to associate initial responders with this endpoint.

Parameters

endpoint_num The endpoint identifier for this endpoint. Valid values are between 1 and 63,999 inclusive.

◆ RDMNET_VIRTUAL_ENDPOINT_INIT

#define RDMNET_VIRTUAL_ENDPOINT_INIT ( endpoint_num )

Value:

  {                                                \
    (endpoint_num), NULL, 0, NULL, 0               \
  }

An initializer for an RdmnetVirtualEndpointConfig instance.

Usage:

// Create a virtual endpoint with an endpoint ID of 20.
RdmnetVirtualEndpointConfig endpoint_config = RDMNET_VIRTUAL_ENDPOINT_INIT(20);
// Assign the other members of the struct to associate initial responders with this endpoint.

Parameters

endpoint_num The endpoint identifier for this endpoint. Valid values are between 1 and 63,999 inclusive.

Typedef Documentation

◆ RdmnetDeviceConnectedCallback

typedef void(* RdmnetDeviceConnectedCallback) (rdmnet_device_t handle, const RdmnetClientConnectedInfo *info, void *context)

A device has successfully connected to a broker.

Parameters

[in]	handle	Handle to the device which has connected.
[in]	info	More information about the successful connection.
[in]	context	Context pointer that was given at the creation of the device instance.

◆ RdmnetDeviceConnectFailedCallback

typedef void(* RdmnetDeviceConnectFailedCallback) (rdmnet_device_t handle, const RdmnetClientConnectFailedInfo *info, void *context)

A connection attempt failed between a device and a broker.

Parameters

[in]	handle	Handle to the device which has failed to connect.
[in]	info	More information about the failed connection.
[in]	context	Context pointer that was given at the creation of the device instance.

◆ RdmnetDeviceDisconnectedCallback

typedef void(* RdmnetDeviceDisconnectedCallback) (rdmnet_device_t handle, const RdmnetClientDisconnectedInfo *info, void *context)

A device which was previously connected to a broker has disconnected.

Parameters

[in]	handle	Handle to the device which has disconnected.
[in]	info	More information about the disconnect event.
[in]	context	Context pointer that was given at the creation of the device instance.

◆ RdmnetDeviceDynamicUidStatusCallback

typedef void(* RdmnetDeviceDynamicUidStatusCallback) (rdmnet_device_t handle, const RdmnetDynamicUidAssignmentList *list, void *context)

The dynamic UID assignment status for a set of virtual responders has been received.

This callback need only be implemented if adding virtual responders with dynamic UIDs. See Devices and Gateways and Using the Device API for more information.

Note that the list may indicate failed assignments for some or all responders, with a status code.

Parameters

[in]	handle	Handle to the device which has received the dynamic UID assignments.
[in]	list	The list of dynamic UID assignments.
[in]	context	Context pointer that was given at the creation of the device instance.

◆ RdmnetDeviceLlrpRdmCommandReceivedCallback

typedef void(* RdmnetDeviceLlrpRdmCommandReceivedCallback) (rdmnet_device_t handle, const LlrpRdmCommand *cmd, RdmnetSyncRdmResponse *response, void *context)

An RDM command has been received over LLRP, addressed to a device.

Parameters

[in]	handle	Handle to the device which has received the RDM command.
[in]	cmd	The RDM command data.
[out]	response	Fill in with response data if responding synchronously (see Handling RDM Commands).
[in]	context	Context pointer that was given at the creation of the device instance.

◆ RdmnetDeviceRdmCommandReceivedCallback

typedef void(* RdmnetDeviceRdmCommandReceivedCallback) (rdmnet_device_t handle, const RdmnetRdmCommand *cmd, RdmnetSyncRdmResponse *response, void *context)

An RDM command has been received addressed to a device.

Parameters

[in]	handle	Handle to the device which has received the RDM command.
[in]	cmd	The RDM command data.
[out]	response	Fill in with response data if responding synchronously (see Handling RDM Commands).
[in]	context	Context pointer that was given at the creation of the device instance.

◆ RdmnetPhysicalEndpointConfig

typedef struct RdmnetPhysicalEndpointConfig RdmnetPhysicalEndpointConfig

Configuration information for a physical endpoint on a device.

See Devices and Gateways for more information on endpoints.

◆ RdmnetVirtualEndpointConfig

typedef struct RdmnetVirtualEndpointConfig RdmnetVirtualEndpointConfig

Configuration information for a virtual endpoint on a device.

See Devices and Gateways for more information on endpoints.

Function Documentation

◆ rdmnet_device_add_dynamic_responders()

etcpal_error_t rdmnet_device_add_dynamic_responders	(	rdmnet_device_t	handle,
		uint16_t	endpoint_id,
		const EtcPalUuid *	responder_ids,
		size_t	num_responders
	)

Add one or more responders with dynamic UIDs to a virtual endpoint.

This function can only be used on virtual endpoints. Dynamic UIDs for the responders will be requested from the broker and the assigned UIDs (or error codes) will be delivered to the device's RdmnetDeviceDynamicUidStatusCallback. Save these UIDs for comparison when handling RDM commands addressed to the dynamic responders. Add the endpoint first with rdmnet_device_add_virtual_endpoint(). See Devices and Gateways for more information on endpoints.

Parameters

handle	Handle to the device to which to add responders.
endpoint_id	ID for the endpoint on which to add the responders.
responder_ids	Array of responder IDs (permanent UUIDs representing the responder).
num_responders	Size of the responder_ids array.

Returns: kEtcPalErrOk: Responders added sucessfully (pending dynamic UID assignment).; kEtcPalErrInvalid: Invalid argument, or the endpoint is a physical endpoint.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNoMem: Could not allocate memory for additional responders.; kEtcPalErrNotFound: Handle is not associated with a valid device instance, or endpoint_id is not an endpoint that was previously added.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_device_add_physical_endpoint()

etcpal_error_t rdmnet_device_add_physical_endpoint	(	rdmnet_device_t	handle,
		const RdmnetPhysicalEndpointConfig *	endpoint_config
	)

Add a physical endpoint to a device.

See Devices and Gateways for more information on endpoints.

Parameters

handle	Handle to the device to which to add a physical endpoint.
endpoint_config	Configuration information for the new physical endpoint.

Returns: kEtcPalErrOk: Endpoint added successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNoMem: Could not allocate memory for additional endpoint.; kEtcPalErrNotFound: Handle is not associated with a valid device instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_device_add_physical_endpoints()

etcpal_error_t rdmnet_device_add_physical_endpoints	(	rdmnet_device_t	handle,
		const RdmnetPhysicalEndpointConfig *	endpoint_configs,
		size_t	num_endpoints
	)

Add multiple physical endpoints to a device.

See Devices and Gateways for more information on endpoints.

Parameters

handle	Handle to the device to which to add physical endpoints.
endpoint_configs	Array of configuration structures for the new physical endpoints.
num_endpoints	Size of endpoint_configs array.

Returns: kEtcPalErrOk: Endpoints added successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNoMem: Could not allocate memory for additional endpoints.; kEtcPalErrNotFound: Handle is not associated with a valid device instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_device_add_physical_responders()

etcpal_error_t rdmnet_device_add_physical_responders	(	rdmnet_device_t	handle,
		uint16_t	endpoint_id,
		const RdmnetPhysicalEndpointResponder *	responders,
		size_t	num_responders
	)

Add one or more responders to a physical endpoint.

This function can only be used on physical endpoints. Add the endpoint first with rdmnet_device_add_physical_endpoint(). See Devices and Gateways for more information on endpoints.

Parameters

handle	Handle to the device to which to add responders.
endpoint_id	ID for the endpoint on which to add the responders.
responders	Array of physical responder structures.
num_responders	Size of the responders array.

Returns: kEtcPalErrOk: Responders added sucessfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNoMem: Could not allocate memory for additional responders.; kEtcPalErrNotFound: Handle is not associated with a valid device instance, or endpoint_id is not an endpoint that was previously added.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_device_add_static_responders()

etcpal_error_t rdmnet_device_add_static_responders	(	rdmnet_device_t	handle,
		uint16_t	endpoint_id,
		const RdmUid *	responder_uids,
		size_t	num_responders
	)

Add one or more responders with static UIDs to a virtual endpoint.

This function can only be used on virtual endpoints. Add the endpoint first with rdmnet_device_add_virtual_endpoint(). See Devices and Gateways for more information on endpoints.

Parameters

handle	Handle to the device to which to add responders.
endpoint_id	ID for the endpoint on which to add the responders.
responder_uids	Array of static responder UIDs.
num_responders	Size of the responder_uids array.

Returns: kEtcPalErrOk: Responders added sucessfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNoMem: Could not allocate memory for additional responders.; kEtcPalErrNotFound: Handle is not associated with a valid device instance, or endpoint_id is not an endpoint that was previously added.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_device_add_virtual_endpoint()

etcpal_error_t rdmnet_device_add_virtual_endpoint	(	rdmnet_device_t	handle,
		const RdmnetVirtualEndpointConfig *	endpoint_config
	)

Add a virtual endpoint to a device.

See Devices and Gateways for more information on endpoints.

Parameters

handle	Handle to the device to which to add a virtual endpoint.
endpoint_config	Configuration information for the new virtual endpoint.

Returns: kEtcPalErrOk: Endpoint added successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNoMem: Could not allocate memory for additional endpoint.; kEtcPalErrNotFound: Handle is not associated with a valid device instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_device_add_virtual_endpoints()

etcpal_error_t rdmnet_device_add_virtual_endpoints	(	rdmnet_device_t	handle,
		const RdmnetVirtualEndpointConfig *	endpoint_configs,
		size_t	num_endpoints
	)

Add multiple virtual endpoints to a device.

See Devices and Gateways for more information on endpoints.

Parameters

handle	Handle to the device to which to add virtual endpoints.
endpoint_configs	Array of configuration structures for the new virtual endpoints.
num_endpoints	Size of endpoint_configs array.

Returns: kEtcPalErrOk: Endpoints added successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNoMem: Could not allocate memory for additional endpoints.; kEtcPalErrNotFound: Handle is not associated with a valid device instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_device_change_scope()

etcpal_error_t rdmnet_device_change_scope	(	rdmnet_device_t	handle,
		const RdmnetScopeConfig *	new_scope_config,
		rdmnet_disconnect_reason_t	disconnect_reason
	)

Change the device's scope.

Will disconnect from the current scope, sending the disconnect reason provided in the disconnect_reason parameter, and then attempt to discover and connect to a broker for the new scope. The status of the connection attempt will be communicated via the callbacks associated with the device instance.

Parameters

handle	Handle to the device for which to change the scope.
new_scope_config	Configuration information for the new scope.
disconnect_reason	Disconnect reason to send on the previous scope, if connected.

Returns: kEtcPalErrOk: Scope changed successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Handle is not associated with a valid device instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_device_change_search_domain()

etcpal_error_t rdmnet_device_change_search_domain	(	rdmnet_device_t	handle,
		const char *	new_search_domain,
		rdmnet_disconnect_reason_t	disconnect_reason
	)

Change the device's DNS search domain.

Non-default search domains are considered advanced usage. If the device's scope does not have a static broker configuration, the scope will be disconnected, sending the disconnect reason provided in the disconnect_reason parameter. Then discovery will be re-attempted on the new search domain.

Parameters

handle	Handle to the device for which to change the search domain.
new_search_domain	New search domain to use for discovery.
disconnect_reason	Disconnect reason to send to the broker, if connected.

Returns: kEtcPalErrOk: Search domain changed successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Handle is not associated with a valid device instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_device_config_init()

void rdmnet_device_config_init	(	RdmnetDeviceConfig *	config,
		uint16_t	manufacturer_id
	)

Initialize an RDMnet Device Config with default values for the optional config options.

The config struct members not marked 'optional' are not meanizngfully initialized by this function. Those members do not have default values and must be initialized manually before passing the config struct to an API function.

Usage example:

RdmnetDeviceConfig config;

RDMNET_DEVICE_CONFIG_INIT(&config, 0x6574);

Parameters

[out]	config	Pointer to RdmnetDeviceConfig to init.
[in]	manufacturer_id	ESTA manufacturer ID. All RDMnet Devices must have one.

◆ rdmnet_device_create()

etcpal_error_t rdmnet_device_create	(	const RdmnetDeviceConfig *	config,
		rdmnet_device_t *	handle
	)

Create a new instance of RDMnet device functionality.

Each device is identified by a single component ID (CID). Typical device applications will only need one device instance. The library will attempt to discover and connect to a broker for the scope given in config->scope_config (or just connect if a static broker is given); the status of these attempts will be communicated via the callbacks associated with the device instance.

Parameters

[in]	config	Configuration parameters to use for this device instance.
[out]	handle	Filled in on success with a handle to the new device instance.

Returns: kEtcPalErrOk: Device created successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNoMem: No memory to allocate new device instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_device_destroy()

etcpal_error_t rdmnet_device_destroy	(	rdmnet_device_t	handle,
		rdmnet_disconnect_reason_t	disconnect_reason
	)

Destroy a device instance.

Will disconnect from the broker to which this device is currently connected (if applicable), sending the disconnect reason provided in the disconnect_reason parameter.

Parameters

[in]	handle	Handle to device to destroy, no longer valid after this function returns.
[in]	disconnect_reason	Disconnect reason code to send to the connected broker.

Returns: kEtcPalErrOk: Device destroyed successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Handle is not associated with a valid device instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_device_get_scope()

etcpal_error_t rdmnet_device_get_scope	(	rdmnet_device_t	handle,
		char *	scope_str_buf,
		EtcPalSockAddr *	static_broker_addr
	)

Retrieve the device's current scope configuration.

Parameters

[in]	handle	Handle to the device from which to retrieve the scope configuration.
[out]	scope_str_buf	Filled in on success with the scope string. Must be at least of length E133_SCOPE_STRING_PADDED_LENGTH.
[out]	static_broker_addr	(optional) Filled in on success with the static broker address, if present. Leave NULL if you don't care about the static broker address.

Returns: kEtcPalErrOk: Scope information retrieved successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Handle is not associated with a valid device instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_device_remove_dynamic_responders()

etcpal_error_t rdmnet_device_remove_dynamic_responders	(	rdmnet_device_t	handle,
		uint16_t	endpoint_id,
		const EtcPalUuid *	responder_ids,
		size_t	num_responders
	)

Remove one or more responders with dynamic UIDs from a virtual endpoint.

This function can only be used on virtual endpoints. See Devices and Gateways for more information on endpoints.

Parameters

handle	Handle to the device from which to remove responders.
endpoint_id	ID for the endpoint on which to remove the responders.
responder_ids	Array of responder IDs to remove.
num_responders	Size of responder_ids array.

Returns: kEtcPalErrOk: Responders removed sucessfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Handle is not associated with a valid device instance, endpoint_id is not an endpoint that was previously added, or one or more responder_ids were not previously added to the endpoint.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_device_remove_endpoint()

etcpal_error_t rdmnet_device_remove_endpoint	(	rdmnet_device_t	handle,
		uint16_t	endpoint_id
	)

Remove an endpoint from a device.

See Devices and Gateways for more information on endpoints.

Parameters

handle	Handle to the device from which to remove an endpoint.
endpoint_id	ID of the endpoint to remove.

Returns: kEtcPalErrOk: Endpoint removed sucessfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Handle is not associated with a valid device instance, or endpoint_id is not an endpoint that was previously added.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_device_remove_endpoints()

etcpal_error_t rdmnet_device_remove_endpoints	(	rdmnet_device_t	handle,
		const uint16_t *	endpoint_ids,
		size_t	num_endpoints
	)

Remove multiple endpoints from a device.

See Devices and Gateways for more information on endpoints.

Parameters

handle	Handle to the device from which to remove endpoints.
endpoint_ids	Array of IDs representing the endpoints to remove.
num_endpoints	Size of the endpoint_ids array.

Returns: kEtcPalErrOk: Endpoints removed sucessfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Handle is not associated with a valid device instance, or one or more endpoint_ids are not endpoints that were previously added.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_device_remove_physical_responders()

etcpal_error_t rdmnet_device_remove_physical_responders	(	rdmnet_device_t	handle,
		uint16_t	endpoint_id,
		const RdmUid *	responder_uids,
		size_t	num_responders
	)

Remove one or more responders from a physical endpoint.

This function can only be used on physical endpoints. See Devices and Gateways for more information on endpoints.

Parameters

handle	Handle to the device from which to remove responders.
endpoint_id	ID for the endpoint on which to remove the responders.
responder_uids	Array of responder UIDs to remove.
num_responders	Size of responder_uids array.

Returns: kEtcPalErrOk: Responders removed sucessfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Handle is not associated with a valid device instance, endpoint_id is not an endpoint that was previously added, or one or more responder_uids were not previously added to the endpoint.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_device_remove_static_responders()

etcpal_error_t rdmnet_device_remove_static_responders	(	rdmnet_device_t	handle,
		uint16_t	endpoint_id,
		const RdmUid *	responder_uids,
		size_t	num_responders
	)

Remove one or more responders with static UIDs from a virtual endpoint.

This function can only be used on virtual endpoints. See Devices and Gateways for more information on endpoints.

Parameters

handle	Handle to the device from which to remove responders.
endpoint_id	ID for the endpoint on which to remove the responders.
responder_uids	Array of static responder UIDs to remove.
num_responders	Size of the responder_uids array.

Returns: kEtcPalErrOk: Responders removed sucessfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Handle is not associated with a valid device instance, endpoint_id is not an endpoint that was previously added, or one or more responder_uids were not previously added to the endpoint.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_device_send_llrp_ack()

etcpal_error_t rdmnet_device_send_llrp_ack	(	rdmnet_device_t	handle,
		const LlrpSavedRdmCommand *	received_cmd,
		const uint8_t *	response_data,
		uint8_t	response_data_len
	)

Send an ACK response to an RDM command received over LLRP.

Parameters

[in]	handle	Handle to the device from which to send the LLRP RDM ACK response.
[in]	received_cmd	Previously-received command that the ACK is a response to.
[in]	response_data	Parameter data that goes with this ACK, or NULL if no data.
[in]	response_data_len	Length in bytes of response_data, or 0 if no data.

Returns: kEtcPalErrOk: LLRP ACK response sent successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Handle is not associated with a valid device instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_device_send_llrp_nack()

etcpal_error_t rdmnet_device_send_llrp_nack	(	rdmnet_device_t	handle,
		const LlrpSavedRdmCommand *	received_cmd,
		rdm_nack_reason_t	nack_reason
	)

Send an ACK response to an RDM command received over LLRP.

Parameters

[in]	handle	Handle to the device from which to send the LLRP RDM NACK response.
[in]	received_cmd	Previously-received command that the ACK is a response to.
[in]	nack_reason	RDM NACK reason code to send with the NACK.

Returns: kEtcPalErrOk: LLRP NACK response sent successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Handle is not associated with a valid device instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_device_send_rdm_ack()

etcpal_error_t rdmnet_device_send_rdm_ack	(	rdmnet_device_t	handle,
		const RdmnetSavedRdmCommand *	received_cmd,
		const uint8_t *	response_data,
		size_t	response_data_len
	)

Send an RDM ACK response from a device.

Parameters

[in]	handle	Handle to the device from which to send the RDM ACK response.
[in]	received_cmd	Previously-received command that the ACK is a response to.
[in]	response_data	Parameter data that goes with this ACK, or NULL if no data.
[in]	response_data_len	Length in bytes of response_data, or 0 if no data.

Returns: kEtcPalErrOk: ACK response sent successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Handle is not associated with a valid device instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_device_send_rdm_nack()

etcpal_error_t rdmnet_device_send_rdm_nack	(	rdmnet_device_t	handle,
		const RdmnetSavedRdmCommand *	received_cmd,
		rdm_nack_reason_t	nack_reason
	)

Send an RDM NACK response from a device.

Parameters

[in]	handle	Handle to the device from which to send the RDM NACK response.
[in]	received_cmd	Previously-received command that the NACK is a response to.
[in]	nack_reason	RDM NACK reason code to send with the NACK.

Returns: kEtcPalErrOk: NACK response sent successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Handle is not associated with a valid device instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_device_send_rdm_update()

etcpal_error_t rdmnet_device_send_rdm_update	(	rdmnet_device_t	handle,
		uint16_t	subdevice,
		uint16_t	param_id,
		const uint8_t *	data,
		size_t	data_len
	)

Send an asynchronous RDM GET response to update the value of a local parameter.

This version is for updating a parameter on the device's default responder. For updates from sub-responders, use rdmnet_device_send_rdm_udpate_from_responder(). See Devices and Gateways for more information.

Parameters

[in]	handle	Handle to the device from which to send the updated RDM data.
[in]	subdevice	The subdevice of the default responder from which the update is being sent (0 for the root device).
[in]	param_id	The RDM parameter ID that has been updated.
[in]	data	The updated parameter data, or NULL for messages with no data.
[in]	data_len	The length of the updated parameter data, or 0 for messages with no data.

Returns: kEtcPalErrOk: RDM update sent successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Handle is not associated with a valid device instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_device_send_rdm_update_from_responder()

etcpal_error_t rdmnet_device_send_rdm_update_from_responder	(	rdmnet_device_t	handle,
		const RdmnetSourceAddr *	source_addr,
		uint16_t	param_id,
		const uint8_t *	data,
		size_t	data_len
	)

Send an asynchronous RDM GET response to update the value of a parameter on a sub-responder.

This version is for updating a parameter on a physical or vitual responder associated with one of a device's endpoints. In particular, this is the one for a gateway to use when it collects a new queued message from a responder. See Devices and Gateways for more information.

Parameters

[in]	handle	Handle to the device from which to send the updated RDM data.
[in]	source_addr	The addressing information of the responder that has an updated parameter.
[in]	param_id	The RDM parameter ID that has been updated.
[in]	data	The updated parameter data, or NULL for messages with no data.
[in]	data_len	The length of the updated parameter data, or 0 for messages with no data.

Returns: kEtcPalErrOk: RDM update sent successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Handle is not associated with a valid device instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_device_send_status()

etcpal_error_t rdmnet_device_send_status	(	rdmnet_device_t	handle,
		const RdmnetSavedRdmCommand *	received_cmd,
		rpt_status_code_t	status_code,
		const char *	status_string
	)

Send an RPT status message from a device.

Status messages should only be sent in response to RDM commands received over RDMnet, if something has gone wrong while attempting to resolve the command.

Parameters

[in]	handle	Handle to the device from which to send the RPT status.
[in]	received_cmd	Previously-received command that the status message is a response to.
[in]	status_code	RPT status code to send.
[in]	status_string	(optional) status string to send. NULL for no string.

Returns: kEtcPalErrOk: Status sent successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Handle is not associated with a valid device instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_device_set_callbacks()

void rdmnet_device_set_callbacks	(	RdmnetDeviceConfig *	config,
		RdmnetDeviceConnectedCallback	connected,
		RdmnetDeviceConnectFailedCallback	connect_failed,
		RdmnetDeviceDisconnectedCallback	disconnected,
		RdmnetDeviceRdmCommandReceivedCallback	rdm_command_received,
		RdmnetDeviceLlrpRdmCommandReceivedCallback	llrp_rdm_command_received,
		RdmnetDeviceDynamicUidStatusCallback	dynamic_uid_status_received,
		void *	context
	)

Set the main callbacks in an RDMnet device configuration structure.

Items marked "optional" can be NULL.

Parameters

[out]	config	Config struct in which to set the callbacks.
[in]	connected	Callback called when the device has connected to a broker.
[in]	connect_failed	Callback called when a connection to a broker has failed.
[in]	disconnected	Callback called when a connection to a broker has disconnected.
[in]	rdm_command_received	Callback called when a device receives an RDM command.
[in]	llrp_rdm_command_received	Callback called when a device receives an RDM command over LLRP.
[in]	dynamic_uid_status_received	(optional) Callback called when a device receives dynamic UID assignments for one or more virtual responders.
[in]	context	(optional) Pointer to opaque data passed back with each callback.

Overview

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

◆ RDMNET_DEVICE_CONFIG_DEFAULT_INIT

◆ RDMNET_PHYSICAL_ENDPOINT_INIT

◆ RDMNET_VIRTUAL_ENDPOINT_INIT

Typedef Documentation

◆ RdmnetDeviceConnectedCallback

◆ RdmnetDeviceConnectFailedCallback

◆ RdmnetDeviceDisconnectedCallback

◆ RdmnetDeviceDynamicUidStatusCallback

◆ RdmnetDeviceLlrpRdmCommandReceivedCallback

◆ RdmnetDeviceRdmCommandReceivedCallback

◆ RdmnetPhysicalEndpointConfig

◆ RdmnetVirtualEndpointConfig

Function Documentation

◆ rdmnet_device_add_dynamic_responders()

◆ rdmnet_device_add_physical_endpoint()

◆ rdmnet_device_add_physical_endpoints()

◆ rdmnet_device_add_physical_responders()

◆ rdmnet_device_add_static_responders()

◆ rdmnet_device_add_virtual_endpoint()

◆ rdmnet_device_add_virtual_endpoints()

◆ rdmnet_device_change_scope()

◆ rdmnet_device_change_search_domain()

◆ rdmnet_device_config_init()

◆ rdmnet_device_create()

◆ rdmnet_device_destroy()

◆ rdmnet_device_get_scope()

◆ rdmnet_device_remove_dynamic_responders()

◆ rdmnet_device_remove_endpoint()

◆ rdmnet_device_remove_endpoints()

◆ rdmnet_device_remove_physical_responders()

◆ rdmnet_device_remove_static_responders()

◆ rdmnet_device_send_llrp_ack()

◆ rdmnet_device_send_llrp_nack()

◆ rdmnet_device_send_rdm_ack()

◆ rdmnet_device_send_rdm_nack()

◆ rdmnet_device_send_rdm_update()

◆ rdmnet_device_send_rdm_update_from_responder()

◆ rdmnet_device_send_status()

◆ rdmnet_device_set_callbacks()