Overview

Implementation of RDMnet controller functionality; see Using the Controller API.

RDMnet controllers are clients which originate RDM commands and receive responses. Controllers can participate in multiple scopes; the default scope string "default" must be configured as a default setting.

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

Data Structures
struct	RdmnetControllerCallbacks
	A set of notification callbacks received about a controller. More...

struct	RdmnetControllerRdmCmdHandler
	A buffer and set of callbacks which can be optionally provided to handle RDM commands addressed to a controller. More...

struct	RdmnetControllerRdmData
	A set of data for the controller library to use for handling RDM commands internally. More...

struct	RdmnetControllerConfig
	A set of information that defines the startup parameters of an RDMnet Controller. More...

Macros
#define	RDMNET_CONTROLLER_INVALID -1
	An invalid RDMnet controller handle value.

#define	RDMNET_CONTROLLER_RDM_DATA_DEFAULT_INIT
	A default-value initializer for an RdmnetControllerRdmData struct. More...

#define	RDMNET_CONTROLLER_CONFIG_DEFAULT_INIT(manu_id)
	A default-value initializer for an RdmnetControllerConfig struct. More...

Typedefs
typedef int	rdmnet_controller_t
	A handle to an RDMnet controller.

typedef void(*	RdmnetControllerConnectedCallback) (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, const RdmnetClientConnectedInfo info, void context)
	A controller has successfully connected to a broker. More...

typedef void(*	RdmnetControllerConnectFailedCallback) (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, const RdmnetClientConnectFailedInfo info, void context)
	A connection attempt failed between a controller and a broker. More...

typedef void(*	RdmnetControllerDisconnectedCallback) (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, const RdmnetClientDisconnectedInfo info, void context)
	A controller which was previously connected to a broker has disconnected. More...

typedef void(*	RdmnetControllerClientListUpdateReceivedCallback) (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, client_list_action_t list_action, const RdmnetRptClientList client_list, void context)
	A client list update has been received from a broker. More...

typedef void(*	RdmnetControllerRdmResponseReceivedCallback) (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, const RdmnetRdmResponse resp, void context)
	An RDM response has been received. More...

typedef void(*	RdmnetControllerStatusReceivedCallback) (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, const RdmnetRptStatus status, void context)
	An RPT status message has been received in response to a previously-sent RDM command. More...

typedef void(*	RdmnetControllerResponderIdsReceivedCallback) (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, const RdmnetDynamicUidAssignmentList list, void context)
	A set of previously-requested mappings of dynamic UIDs to responder IDs has been received. More...

typedef struct RdmnetControllerCallbacks	RdmnetControllerCallbacks
	A set of notification callbacks received about a controller.

typedef void(*	RdmnetControllerRdmCommandReceivedCallback) (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, const RdmnetRdmCommand cmd, RdmnetSyncRdmResponse response, void *context)
	An RDM command has been received addressed to a controller. More...

typedef void(*	RdmnetControllerLlrpRdmCommandReceivedCallback) (rdmnet_controller_t controller_handle, const LlrpRdmCommand cmd, RdmnetSyncRdmResponse response, void *context)
	An RDM command has been received over LLRP, addressed to a controller. More...

typedef struct RdmnetControllerRdmCmdHandler	RdmnetControllerRdmCmdHandler
	A buffer and set of callbacks which can be optionally provided to handle RDM commands addressed to a controller. More...

typedef struct RdmnetControllerRdmData	RdmnetControllerRdmData
	A set of data for the controller library to use for handling RDM commands internally.

typedef struct RdmnetControllerConfig	RdmnetControllerConfig
	A set of information that defines the startup parameters of an RDMnet Controller.

Functions
void	rdmnet_controller_config_init (RdmnetControllerConfig *config, uint16_t manufacturer_id)
	Initialize an RdmnetControllerConfig with default values for the optional config options. More...

void	rdmnet_controller_set_callbacks (RdmnetControllerConfig config, RdmnetControllerConnectedCallback connected, RdmnetControllerConnectFailedCallback connect_failed, RdmnetControllerDisconnectedCallback disconnected, RdmnetControllerClientListUpdateReceivedCallback client_list_update_received, RdmnetControllerRdmResponseReceivedCallback rdm_response_received, RdmnetControllerStatusReceivedCallback status_received, RdmnetControllerResponderIdsReceivedCallback responder_ids_received, void context)
	Set the main callbacks in an RDMnet controller configuration structure. More...

void	rdmnet_controller_set_rdm_cmd_callbacks (RdmnetControllerConfig config, RdmnetControllerRdmCommandReceivedCallback rdm_command_received, RdmnetControllerLlrpRdmCommandReceivedCallback llrp_rdm_command_received, uint8_t response_buf, void *context)
	Set callbacks to handle RDM commands in an RDMnet controller configuration structure. More...

etcpal_error_t	rdmnet_controller_create (const RdmnetControllerConfig config, rdmnet_controller_t handle)
	Create a new instance of RDMnet controller functionality. More...

etcpal_error_t	rdmnet_controller_destroy (rdmnet_controller_t controller_handle, rdmnet_disconnect_reason_t reason)
	Destroy a controller instance. More...

etcpal_error_t	rdmnet_controller_add_scope (rdmnet_controller_t controller_handle, const RdmnetScopeConfig scope_config, rdmnet_client_scope_t scope_handle)
	Add a new scope to a controller instance. More...

etcpal_error_t	rdmnet_controller_add_default_scope (rdmnet_controller_t controller_handle, rdmnet_client_scope_t *scope_handle)
	Add a new scope representing the default RDMnet scope to a controller instance. More...

etcpal_error_t	rdmnet_controller_remove_scope (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, rdmnet_disconnect_reason_t reason)
	Remove a previously-added scope from a controller instance. More...

etcpal_error_t	rdmnet_controller_change_scope (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, const RdmnetScopeConfig *new_scope_config, rdmnet_disconnect_reason_t disconnect_reason)
	Change the configuration of a scope on a controller. More...

etcpal_error_t	rdmnet_controller_get_scope (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, char scope_str_buf, EtcPalSockAddr static_broker_addr)
	Retrieve the scope configuration of a previously-added scope. More...

etcpal_error_t	rdmnet_controller_change_search_domain (rdmnet_controller_t controller_handle, const char *new_search_domain, rdmnet_disconnect_reason_t disconnect_reason)
	Change the controller's DNS search domain. More...

etcpal_error_t	rdmnet_controller_request_client_list (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle)
	Request a client list from a broker. More...

etcpal_error_t	rdmnet_controller_request_responder_ids (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, const RdmUid *uids, size_t num_uids)
	Request a set of responder IDs corresponding with dynamic responder UIDs from a broker. More...

etcpal_error_t	rdmnet_controller_send_rdm_command (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, const RdmnetDestinationAddr destination, rdmnet_command_class_t command_class, uint16_t param_id, const uint8_t data, uint8_t data_len, uint32_t *seq_num)
	Send an RDM command from a controller on a scope. More...

etcpal_error_t	rdmnet_controller_send_get_command (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, const RdmnetDestinationAddr destination, uint16_t param_id, const uint8_t data, uint8_t data_len, uint32_t *seq_num)
	Send an RDM GET command from a controller on a scope. More...

etcpal_error_t	rdmnet_controller_send_set_command (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, const RdmnetDestinationAddr destination, uint16_t param_id, const uint8_t data, uint8_t data_len, uint32_t *seq_num)
	Send an RDM SET command from a controller on a scope. More...

etcpal_error_t	rdmnet_controller_send_rdm_ack (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, const RdmnetSavedRdmCommand received_cmd, const uint8_t response_data, size_t response_data_len)
	Send an RDM ACK response from a controller on a scope. More...

etcpal_error_t	rdmnet_controller_send_rdm_nack (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, const RdmnetSavedRdmCommand *received_cmd, rdm_nack_reason_t nack_reason)
	Send an RDM NACK response from a controller on a scope. More...

etcpal_error_t	rdmnet_controller_send_rdm_update (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_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_controller_send_llrp_ack (rdmnet_controller_t controller_handle, const LlrpSavedRdmCommand received_cmd, const uint8_t response_data, uint8_t response_data_len)
	Send an LLRP RDM ACK response from a controller. More...

etcpal_error_t	rdmnet_controller_send_llrp_nack (rdmnet_controller_t controller_handle, const LlrpSavedRdmCommand *received_cmd, rdm_nack_reason_t nack_reason)
	Send an LLRP RDM NACK response from a controller. More...

Macro Definition Documentation

◆ RDMNET_CONTROLLER_CONFIG_DEFAULT_INIT

#define RDMNET_CONTROLLER_CONFIG_DEFAULT_INIT ( manu_id )

Value:

  {                                                                                            \
    {{0}}, {NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}, {NULL, NULL, NULL, NULL},         \
        RDMNET_CONTROLLER_RDM_DATA_DEFAULT_INIT, {(0x8000 | manu_id), 0}, NULL, false, NULL, 0 \
  }

A default-value initializer for an RdmnetControllerConfig struct.

Usage:

RdmnetControllerConfig config = RDMNET_CONTROLLER_CONFIG_DEFAULT_INIT(MY_ESTA_MANUFACTURER_ID);

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

RDMNET_CONTROLLER_CONFIG_DEFAULT_INIT

#define RDMNET_CONTROLLER_CONFIG_DEFAULT_INIT(manu_id)

A default-value initializer for an RdmnetControllerConfig struct.

Definition: controller.h:329

RdmnetControllerConfig

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

Definition: controller.h:266

Parameters

manu_id Your ESTA manufacturer ID.

◆ RDMNET_CONTROLLER_RDM_DATA_DEFAULT_INIT

#define RDMNET_CONTROLLER_RDM_DATA_DEFAULT_INIT

Value:

  {                                                                               \
    0, 0, NULL, NULL, NULL, NULL, E120_PRODUCT_CATEGORY_CONTROL_CONTROLLER, false \
  }

A default-value initializer for an RdmnetControllerRdmData struct.

Usage:

RdmnetControllerRdmData config = RDMNET_CONTROLLER_RDM_DATA_DEFAULT_INIT;

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

RDMNET_CONTROLLER_RDM_DATA_DEFAULT_INIT

#define RDMNET_CONTROLLER_RDM_DATA_DEFAULT_INIT

A default-value initializer for an RdmnetControllerRdmData struct.

Definition: controller.h:259

RdmnetControllerRdmData

A set of data for the controller library to use for handling RDM commands internally.

Definition: controller.h:208

Typedef Documentation

◆ RdmnetControllerClientListUpdateReceivedCallback

typedef void(* RdmnetControllerClientListUpdateReceivedCallback) (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, client_list_action_t list_action, const RdmnetRptClientList *client_list, void *context)

A client list update has been received from a broker.

Parameters

[in]	controller_handle	Handle to the controller which has received the client list update.
[in]	scope_handle	Handle to the scope on which the client list update was received.
[in]	list_action	The way the updates in client_list should be applied to the controller's cached list.
[in]	client_list	The list of updates.
[in]	context	Context pointer that was given at the creation of the controller instance.

◆ RdmnetControllerConnectedCallback

typedef void(* RdmnetControllerConnectedCallback) (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, const RdmnetClientConnectedInfo *info, void *context)

A controller has successfully connected to a broker.

Parameters

[in]	controller_handle	Handle to the controller which has connected.
[in]	scope_handle	Handle to the scope on which the controller has connected.
[in]	info	More information about the successful connection.
[in]	context	Context pointer that was given at the creation of the controller instance.

◆ RdmnetControllerConnectFailedCallback

typedef void(* RdmnetControllerConnectFailedCallback) (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, const RdmnetClientConnectFailedInfo *info, void *context)

A connection attempt failed between a controller and a broker.

Parameters

[in]	controller_handle	Handle to the controller which has failed to connect.
[in]	scope_handle	Handle to the scope on which the connection failed.
[in]	info	More information about the failed connection.
[in]	context	Context pointer that was given at the creation of the controller instance.

◆ RdmnetControllerDisconnectedCallback

typedef void(* RdmnetControllerDisconnectedCallback) (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, const RdmnetClientDisconnectedInfo *info, void *context)

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

Parameters

[in]	controller_handle	Handle to the controller which has disconnected.
[in]	scope_handle	Handle to the scope on which the disconnect occurred.
[in]	info	More information about the disconnect event.
[in]	context	Context pointer that was given at the creation of the controller instance.

◆ RdmnetControllerLlrpRdmCommandReceivedCallback

typedef void(* RdmnetControllerLlrpRdmCommandReceivedCallback) (rdmnet_controller_t controller_handle, const LlrpRdmCommand *cmd, RdmnetSyncRdmResponse *response, void *context)

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

Parameters

[in]	controller_handle	Handle to the controller 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 controller instance.

◆ RdmnetControllerRdmCmdHandler

typedef struct RdmnetControllerRdmCmdHandler RdmnetControllerRdmCmdHandler

A buffer and set of callbacks which can be optionally provided to handle RDM commands addressed to a controller.

See Handling RDM Commands for more information.

◆ RdmnetControllerRdmCommandReceivedCallback

typedef void(* RdmnetControllerRdmCommandReceivedCallback) (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, const RdmnetRdmCommand *cmd, RdmnetSyncRdmResponse *response, void *context)

An RDM command has been received addressed to a controller.

Parameters

[in]	controller_handle	Handle to the controller which has received the RDM command.
[in]	scope_handle	Handle to the scope on which the RDM command was received.
[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 controller instance.

◆ RdmnetControllerRdmResponseReceivedCallback

typedef void(* RdmnetControllerRdmResponseReceivedCallback) (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, const RdmnetRdmResponse *resp, void *context)

An RDM response has been received.

Parameters

[in]	controller_handle	Handle to the controller which has received the RDM response.
[in]	scope_handle	Handle to the scope on which the RDM response was received.
[in]	resp	The RDM response data.
[in]	context	Context pointer that was given at the creation of the controller instance.

◆ RdmnetControllerResponderIdsReceivedCallback

typedef void(* RdmnetControllerResponderIdsReceivedCallback) (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, const RdmnetDynamicUidAssignmentList *list, void *context)

A set of previously-requested mappings of dynamic UIDs to responder IDs has been received.

This callback does not need to be implemented if the controller implementation never intends to request dynamic UID mappings.

Parameters

[in]	controller_handle	Handle to the controller which has received the dynamic UID mappings.
[in]	scope_handle	Handle to the scope on which the dynamic UID mappings were received.
[in]	list	The list of dynamic UID mappings.
[in]	context	Context pointer that was given at the creation of the controller instance.

◆ RdmnetControllerStatusReceivedCallback

typedef void(* RdmnetControllerStatusReceivedCallback) (rdmnet_controller_t controller_handle, rdmnet_client_scope_t scope_handle, const RdmnetRptStatus *status, void *context)

An RPT status message has been received in response to a previously-sent RDM command.

Parameters

[in]	controller_handle	Handle to the controller which has received the RPT status message.
[in]	scope_handle	Handle to the scope on which the RPT status message was received.
[in]	status	The RPT status data.
[in]	context	Context pointer that was given at the creation of the controller instance.

Function Documentation

◆ rdmnet_controller_add_default_scope()

etcpal_error_t rdmnet_controller_add_default_scope	(	rdmnet_controller_t	controller_handle,
		rdmnet_client_scope_t *	scope_handle
	)

Add a new scope representing the default RDMnet scope to a controller instance.

This is a shortcut to easily add the default RDMnet scope to a controller. The default behavior is to not use a statically-configured broker. If a static broker is needed on the default scope, rdmnet_controller_add_scope() must be used.

Parameters

[in]	controller_handle	Handle to controller to which to add the default scope.
[out]	scope_handle	Filled in on success with a handle to the new scope.

Returns: kEtcPalErrOk: Default scope added successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: controller_handle is not associated with a valid controller instance.; kEtcPalErrNoMem: No memory to allocate new scope.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_controller_add_scope()

etcpal_error_t rdmnet_controller_add_scope	(	rdmnet_controller_t	controller_handle,
		const RdmnetScopeConfig *	scope_config,
		rdmnet_client_scope_t *	scope_handle
	)

Add a new scope to a controller instance.

The library will attempt to discover and connect to a broker for the scope (or just connect if a static broker address is given); the status of these attempts will be communicated via the callbacks associated with the controller instance.

Parameters

[in]	controller_handle	Handle to controller to which to add a new scope.
[in]	scope_config	Configuration parameters for the new scope.
[out]	scope_handle	Filled in on success with a handle to the new scope.

Returns: kEtcPalErrOk: New scope added successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: controller_handle is not associated with a valid controller instance.; kEtcPalErrNoMem: No memory to allocate new scope.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_controller_change_scope()

etcpal_error_t rdmnet_controller_change_scope	(	rdmnet_controller_t	controller_handle,
		rdmnet_client_scope_t	scope_handle,
		const RdmnetScopeConfig *	new_scope_config,
		rdmnet_disconnect_reason_t	disconnect_reason
	)

Change the configuration of a scope on a controller.

Will disconnect from any connected brokers and attempt connection again using the new configuration given.

Parameters

[in]	controller_handle	Handle to the controller on which to change a scope.
[in]	scope_handle	Handle to the scope for which to change the configuration.
[in]	new_scope_config	New configuration parameters for the scope.
[in]	disconnect_reason	RDMnet protocol disconnect reason to send to the connected broker.

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

◆ rdmnet_controller_change_search_domain()

etcpal_error_t rdmnet_controller_change_search_domain	(	rdmnet_controller_t	controller_handle,
		const char *	new_search_domain,
		rdmnet_disconnect_reason_t	disconnect_reason
	)

Change the controller's DNS search domain.

Non-default search domains are considered advanced usage. Any added scopes which do not have a static broker configuration 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

controller_handle	Handle to the controller for which to change the search domain.
new_search_domain	New search domain to use for discovery.
disconnect_reason	Disconnect reason to send to any connected brokers.

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

◆ rdmnet_controller_config_init()

void rdmnet_controller_config_init	(	RdmnetControllerConfig *	config,
		uint16_t	manufacturer_id
	)

Initialize an RdmnetControllerConfig with default values for the optional config options.

The config struct members not marked 'optional' are not meaningfully 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:

RdmnetControllerConfig config;

rdmnet_controller_config_init(&config, 0x6574);

rdmnet_controller_config_init

void rdmnet_controller_config_init(RdmnetControllerConfig *config, uint16_t manufacturer_id)

Initialize an RdmnetControllerConfig with default values for the optional config options.

Definition: controller.c:148

Parameters

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

◆ rdmnet_controller_create()

etcpal_error_t rdmnet_controller_create	(	const RdmnetControllerConfig *	config,
		rdmnet_controller_t *	handle
	)

Create a new instance of RDMnet controller functionality.

Each controller is identified by a single component ID (CID). Typical controller applications will only need one controller instance. RDMnet connection will not be attempted until at least one scope is added using rdmnet_controller_add_scope().

Parameters

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

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

◆ rdmnet_controller_destroy()

etcpal_error_t rdmnet_controller_destroy	(	rdmnet_controller_t	controller_handle,
		rdmnet_disconnect_reason_t	disconnect_reason
	)

Destroy a controller instance.

Will disconnect from all brokers to which this controller is currently connected, sending the disconnect reason provided in the disconnect_reason parameter.

Parameters

[in]	controller_handle	Handle to controller to destroy, no longer valid after this function returns.
[in]	disconnect_reason	Disconnect reason code to send on all connected scopes.

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

◆ rdmnet_controller_get_scope()

etcpal_error_t rdmnet_controller_get_scope	(	rdmnet_controller_t	controller_handle,
		rdmnet_client_scope_t	scope_handle,
		char *	scope_str_buf,
		EtcPalSockAddr *	static_broker_addr
	)

Retrieve the scope configuration of a previously-added scope.

Parameters

[in]	controller_handle	Handle to the controller from which to retrieve the scope configuration.
[in]	scope_handle	Handle to the scope for 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: controller_handle is not associated with a valid controller instance, or scope_handle is not associated with a valid scope instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_controller_remove_scope()

etcpal_error_t rdmnet_controller_remove_scope	(	rdmnet_controller_t	controller_handle,
		rdmnet_client_scope_t	scope_handle,
		rdmnet_disconnect_reason_t	disconnect_reason
	)

Remove a previously-added scope from a controller instance.

After this call completes, scope_handle will no longer be valid.

Parameters

[in]	controller_handle	Handle to the controller from which to remove a scope.
[in]	scope_handle	Handle to scope to remove.
[in]	disconnect_reason	RDMnet protocol disconnect reason to send to the connected broker.

Returns: kEtcPalErrOk: Scope removed successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: controller_handle is not associated with a valid controller instance, or scope_handle is not associated with a valid scope instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_controller_request_client_list()

etcpal_error_t rdmnet_controller_request_client_list	(	rdmnet_controller_t	controller_handle,
		rdmnet_client_scope_t	scope_handle
	)

Request a client list from a broker.

The response will be delivered via the RdmnetControllerClientListUpdateReceivedCallback.

Parameters

[in]	controller_handle	Handle to the controller from which to request the client list.
[in]	scope_handle	Handle to the scope on which to request the client list.

Returns: kEtcPalErrOk: Request sent successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: controller_handle is not associated with a valid controller instance, or scope_handle is not associated with a valid scope instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_controller_request_responder_ids()

etcpal_error_t rdmnet_controller_request_responder_ids	(	rdmnet_controller_t	controller_handle,
		rdmnet_client_scope_t	scope_handle,
		const RdmUid *	uids,
		size_t	num_uids
	)

Request a set of responder IDs corresponding with dynamic responder UIDs from a broker.

The response will be delivered via the RdmnetControllerResponderIdsReceivedCallback.

Parameters

[in]	controller_handle	Handle to the controller from which to request the responder IDs.
[in]	scope_handle	Handle to the scope on which to request the responder IDs.
[in]	uids	Array of dynamic RDM UIDs for which to request the corresponding responder IDs.
[in]	num_uids	Size of the uids array.

Returns: kEtcPalErrOk: Request sent successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: controller_handle is not associated with a valid controller instance, or scope_handle is not associated with a valid scope instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_controller_send_get_command()

etcpal_error_t rdmnet_controller_send_get_command	(	rdmnet_controller_t	controller_handle,
		rdmnet_client_scope_t	scope_handle,
		const RdmnetDestinationAddr *	destination,
		uint16_t	param_id,
		const uint8_t *	data,
		uint8_t	data_len,
		uint32_t *	seq_num
	)

Send an RDM GET command from a controller on a scope.

The response will be delivered via either the RdmnetControllerRdmResponseReceived callback or the RdmnetControllerStatusReceivedCallback, depending on the outcome of the command.

Parameters

[in]	controller_handle	Handle to the controller from which to send the GET command.
[in]	scope_handle	Handle to the scope on which to send the GET command.
[in]	destination	Addressing information for the RDMnet client and responder to which to send the command.
[in]	param_id	The command's RDM parameter ID.
[in]	data	Any RDM parameter data associated with the command (NULL for no data).
[in]	data_len	Length of any RDM parameter data associated with the command (0 for no data).
[out]	seq_num	Filled in on success with a sequence number which can be used to match the command with a response.

Returns: kEtcPalErrOk: Command sent successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: controller_handle is not associated with a valid controller instance, or scope_handle is not associated with a valid scope instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_controller_send_llrp_ack()

etcpal_error_t rdmnet_controller_send_llrp_ack	(	rdmnet_controller_t	controller_handle,
		const LlrpSavedRdmCommand *	received_cmd,
		const uint8_t *	response_data,
		uint8_t	response_data_len
	)

Send an LLRP RDM ACK response from a controller.

Parameters

[in]	controller_handle	Handle to the controller from which to send the LLRP RDM ACK response.
[in]	received_cmd	Previously-received LLRP RDM 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: controller_handle is not associated with a valid controller instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_controller_send_llrp_nack()

etcpal_error_t rdmnet_controller_send_llrp_nack	(	rdmnet_controller_t	controller_handle,
		const LlrpSavedRdmCommand *	received_cmd,
		rdm_nack_reason_t	nack_reason
	)

Send an LLRP RDM NACK response from a controller.

Parameters

[in]	controller_handle	Handle to the controller from which to send the LLRP RDM NACK response.
[in]	received_cmd	Previously-received LLRP RDM command that the NACK 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: controller_handle is not associated with a valid controller instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_controller_send_rdm_ack()

etcpal_error_t rdmnet_controller_send_rdm_ack	(	rdmnet_controller_t	controller_handle,
		rdmnet_client_scope_t	scope_handle,
		const RdmnetSavedRdmCommand *	received_cmd,
		const uint8_t *	response_data,
		size_t	response_data_len
	)

Send an RDM ACK response from a controller on a scope.

This function should only be used if a valid RdmnetControllerRdmCmdHandler was provided with the associated config struct.

Parameters

[in]	controller_handle	Handle to the controller from which to send the RDM ACK response.
[in]	scope_handle	Handle to the scope on 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: controller_handle is not associated with a valid controller instance, or scope_handle is not associated with a valid scope instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_controller_send_rdm_command()

etcpal_error_t rdmnet_controller_send_rdm_command	(	rdmnet_controller_t	controller_handle,
		rdmnet_client_scope_t	scope_handle,
		const RdmnetDestinationAddr *	destination,
		rdmnet_command_class_t	command_class,
		uint16_t	param_id,
		const uint8_t *	data,
		uint8_t	data_len,
		uint32_t *	seq_num
	)

Send an RDM command from a controller on a scope.

The response will be delivered via either the RdmnetControllerRdmResponseReceived callback or the RdmnetControllerStatusReceivedCallback, depending on the outcome of the command.

Parameters

[in]	controller_handle	Handle to the controller from which to send the RDM command.
[in]	scope_handle	Handle to the scope on which to send the RDM command.
[in]	destination	Addressing information for the RDMnet client and responder to which to send the command.
[in]	command_class	Whether this is a GET or a SET command.
[in]	param_id	The command's RDM parameter ID.
[in]	data	Any RDM parameter data associated with the command (NULL for no data).
[in]	data_len	Length of any RDM parameter data associated with the command (0 for no data).
[out]	seq_num	Filled in on success with a sequence number which can be used to match the command with a response.

Returns: kEtcPalErrOk: Command sent successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: controller_handle is not associated with a valid controller instance, or scope_handle is not associated with a valid scope instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_controller_send_rdm_nack()

etcpal_error_t rdmnet_controller_send_rdm_nack	(	rdmnet_controller_t	controller_handle,
		rdmnet_client_scope_t	scope_handle,
		const RdmnetSavedRdmCommand *	received_cmd,
		rdm_nack_reason_t	nack_reason
	)

Send an RDM NACK response from a controller on a scope.

This function should only be used if a valid RdmnetControllerRdmCmdHandler was provided with the associated config struct.

Parameters

[in]	controller_handle	Handle to the controller from which to send the RDM NACK response.
[in]	scope_handle	Handle to the scope on 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: controller_handle is not associated with a valid controller instance, or scope_handle is not associated with a valid scope instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_controller_send_rdm_update()

etcpal_error_t rdmnet_controller_send_rdm_update	(	rdmnet_controller_t	controller_handle,
		rdmnet_client_scope_t	scope_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 function should only be used if a valid RdmnetControllerRdmCmdHandler was provided with the associated config struct.

Parameters

[in]	controller_handle	Handle to the controller from which to send the RDM update.
[in]	scope_handle	Handle to the scope on which to send the RDM update.
[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 if no data.
[in]	data_len	The length of the updated parameter data, or NULL if no data.

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

◆ rdmnet_controller_send_set_command()

etcpal_error_t rdmnet_controller_send_set_command	(	rdmnet_controller_t	controller_handle,
		rdmnet_client_scope_t	scope_handle,
		const RdmnetDestinationAddr *	destination,
		uint16_t	param_id,
		const uint8_t *	data,
		uint8_t	data_len,
		uint32_t *	seq_num
	)

Send an RDM SET command from a controller on a scope.

The response will be delivered via either the RdmnetControllerRdmResponseReceived callback or the RdmnetControllerStatusReceivedCallback, depending on the outcome of the command.

Parameters

[in]	controller_handle	Handle to the controller from which to send the SET command.
[in]	scope_handle	Handle to the scope on which to send the SET command.
[in]	destination	Addressing information for the RDMnet client and responder to which to send the command.
[in]	param_id	The command's RDM parameter ID.
[in]	data	Any RDM parameter data associated with the command (NULL for no data).
[in]	data_len	Length of any RDM parameter data associated with the command (0 for no data).
[out]	seq_num	Filled in on success with a sequence number which can be used to match the command with a response.

Returns: kEtcPalErrOk: Command sent successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: controller_handle is not associated with a valid controller instance, or scope_handle is not associated with a valid scope instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_controller_set_callbacks()

void rdmnet_controller_set_callbacks	(	RdmnetControllerConfig *	config,
		RdmnetControllerConnectedCallback	connected,
		RdmnetControllerConnectFailedCallback	connect_failed,
		RdmnetControllerDisconnectedCallback	disconnected,
		RdmnetControllerClientListUpdateReceivedCallback	client_list_update_received,
		RdmnetControllerRdmResponseReceivedCallback	rdm_response_received,
		RdmnetControllerStatusReceivedCallback	status_received,
		RdmnetControllerResponderIdsReceivedCallback	responder_ids_received,
		void *	context
	)

Set the main callbacks in an RDMnet controller 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 controller 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]	client_list_update_received	Callback called when a controller receives an updated RDMnet client list.
[in]	rdm_response_received	Callback called when a controller receives a response to an RDM command.
[in]	status_received	Callback called when a controller receives a status message in response to an RDM command.
[in]	responder_ids_received	(optional) Callback called when a controller receives a set of dynamic UID mappings.
[in]	context	(optional) Pointer to opaque data passed back with each callback.

◆ rdmnet_controller_set_rdm_cmd_callbacks()

void rdmnet_controller_set_rdm_cmd_callbacks	(	RdmnetControllerConfig *	config,
		RdmnetControllerRdmCommandReceivedCallback	rdm_command_received,
		RdmnetControllerLlrpRdmCommandReceivedCallback	llrp_rdm_command_received,
		uint8_t *	response_buf,
		void *	context
	)

Set callbacks to handle RDM commands in an RDMnet controller configuration structure.

RDMnet controllers are required to respond to a basic set of RDM commands. This library provides two possible approaches to this. With this approach, the library forwards RDM commands received via callbacks to the application to handle. GET requests for COMPONENT_SCOPE, SEARCH_DOMAIN, and TCP_COMMS_STATUS will still be consumed internally. See Using the Controller API for more information.

Items marked "optional" can be NULL.

Parameters

[out]	config	Config struct in which to set the callbacks.
[in]	rdm_command_received	Callback called when a controller receives an RDM command.
[in]	llrp_rdm_command_received	Callback called when a controller receives an RDM command over LLRP. Only required if `create_llrp_target == true` in the config struct.
[in]	response_buf	(optional) A data buffer used to respond synchronously to RDM commands. See Handling RDM Commands for more information.
[in]	context	(optional) Pointer to opaque data passed back with each callback.

Overview

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

◆ RDMNET_CONTROLLER_CONFIG_DEFAULT_INIT

◆ RDMNET_CONTROLLER_RDM_DATA_DEFAULT_INIT

Typedef Documentation

◆ RdmnetControllerClientListUpdateReceivedCallback

◆ RdmnetControllerConnectedCallback

◆ RdmnetControllerConnectFailedCallback

◆ RdmnetControllerDisconnectedCallback

◆ RdmnetControllerLlrpRdmCommandReceivedCallback

◆ RdmnetControllerRdmCmdHandler

◆ RdmnetControllerRdmCommandReceivedCallback

◆ RdmnetControllerRdmResponseReceivedCallback

◆ RdmnetControllerResponderIdsReceivedCallback

◆ RdmnetControllerStatusReceivedCallback

Function Documentation

◆ rdmnet_controller_add_default_scope()

◆ rdmnet_controller_add_scope()

◆ rdmnet_controller_change_scope()

◆ rdmnet_controller_change_search_domain()

◆ rdmnet_controller_config_init()

◆ rdmnet_controller_create()

◆ rdmnet_controller_destroy()

◆ rdmnet_controller_get_scope()

◆ rdmnet_controller_remove_scope()

◆ rdmnet_controller_request_client_list()

◆ rdmnet_controller_request_responder_ids()

◆ rdmnet_controller_send_get_command()

◆ rdmnet_controller_send_llrp_ack()

◆ rdmnet_controller_send_llrp_nack()

◆ rdmnet_controller_send_rdm_ack()

◆ rdmnet_controller_send_rdm_command()

◆ rdmnet_controller_send_rdm_nack()

◆ rdmnet_controller_send_rdm_update()

◆ rdmnet_controller_send_set_command()

◆ rdmnet_controller_set_callbacks()

◆ rdmnet_controller_set_rdm_cmd_callbacks()