LLRP Manager API

Overview

Implementation of LLRP manager funtionality; see Using the LLRP Manager API.

LLRP managers perform the discovery and command functionality of RDMnet's Low Level Recovery Protocol (LLRP). See Using the LLRP Manager API for details of how to use this API.

Data Structures
struct	LlrpManagerCallbacks
	A set of notification callbacks received about an LLRP manager. More...
struct	LlrpManagerConfig
	A set of information that defines the startup parameters of an LLRP Manager. More...

Macros
#define	LLRP_MANAGER_INVALID   -1
	An invalid LLRP manager handle value.
#define	LLRP_MANAGER_CONFIG_DEFAULT_INIT
	A default-value initializer for an LlrpManagerConfig struct. More...

Typedefs
typedef int	llrp_manager_t
	A handle for an instance of LLRP Manager functionality.
typedef void(*	LlrpManagerTargetDiscoveredCallback) (llrp_manager_t handle, const LlrpDiscoveredTarget *target, void *context)
	An LLRP target has been discovered. More...
typedef void(*	LlrpManagerRdmResponseReceivedCallback) (llrp_manager_t handle, const LlrpRdmResponse *resp, void *context)
	An RDM response has been received from an LLRP target. More...
typedef void(*	LlrpManagerDiscoveryFinishedCallback) (llrp_manager_t handle, void *context)
	The previously-started LLRP discovery process has finished. More...
typedef struct LlrpManagerCallbacks	LlrpManagerCallbacks
	A set of notification callbacks received about an LLRP manager.
typedef struct LlrpManagerConfig	LlrpManagerConfig
	A set of information that defines the startup parameters of an LLRP Manager.

Functions
void	llrp_manager_config_init (LlrpManagerConfig *config, uint16_t manufacturer_id)
	Initialize an LlrpManagerConfig with default values for the optional config options. More...
void	llrp_manager_config_set_callbacks (LlrpManagerConfig *config, LlrpManagerTargetDiscoveredCallback target_discovered, LlrpManagerRdmResponseReceivedCallback rdm_response_received, LlrpManagerDiscoveryFinishedCallback discovery_finished, void *context)
	Set the callbacks in an LLRP manager configuration structure. More...
etcpal_error_t	llrp_manager_create (const LlrpManagerConfig *config, llrp_manager_t *handle)
	Create a new LLRP manager instance. More...
etcpal_error_t	llrp_manager_destroy (llrp_manager_t handle)
	Destroy an LLRP manager instance. More...
etcpal_error_t	llrp_manager_start_discovery (llrp_manager_t handle, uint16_t filter)
	Start discovery on an LLRP manager. More...
etcpal_error_t	llrp_manager_stop_discovery (llrp_manager_t handle)
	Stop discovery on an LLRP manager. More...
etcpal_error_t	llrp_manager_send_rdm_command (llrp_manager_t handle, const LlrpDestinationAddr *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 an LLRP manager. More...
etcpal_error_t	llrp_manager_send_get_command (llrp_manager_t handle, const LlrpDestinationAddr *destination, uint16_t param_id, const uint8_t *data, uint8_t data_len, uint32_t *seq_num)
	Send an RDM GET command from an LLRP manager. More...
etcpal_error_t	llrp_manager_send_set_command (llrp_manager_t handle, const LlrpDestinationAddr *destination, uint16_t param_id, const uint8_t *data, uint8_t data_len, uint32_t *seq_num)
	Send an RDM SET command from an LLRP manager. More...

Macro Definition Documentation

LLRP_MANAGER_CONFIG_DEFAULT_INIT

#define LLRP_MANAGER_CONFIG_DEFAULT_INIT

Value:

  {                                                                 \
    {{0}}, {kEtcPalIpTypeInvalid, 0}, 0, { NULL, NULL, NULL, NULL } \
  }

A default-value initializer for an LlrpManagerConfig struct.

Usage:

LlrpManagerConfig config = LLRP_MANAGER_CONFIG_DEFAULT_INIT;
// Now fill in the required portions as necessary with your data...

Typedef Documentation

LlrpManagerDiscoveryFinishedCallback

typedef void(* LlrpManagerDiscoveryFinishedCallback) (llrp_manager_t handle, void *context)

The previously-started LLRP discovery process has finished.

Parameters

handle	Handle to the LLRP manager which has finished discovery.
context	Context pointer that was given at the creation of the LLRP manager instance.

LlrpManagerRdmResponseReceivedCallback

typedef void(* LlrpManagerRdmResponseReceivedCallback) (llrp_manager_t handle, const LlrpRdmResponse *resp, void *context)

An RDM response has been received from an LLRP target.

Parameters

handle	Handle the LLRP manager which has received the RDM response.
resp	The RDM response data.
context	Context pointer that was given at the creation of the LLRP manager instance.

LlrpManagerTargetDiscoveredCallback

typedef void(* LlrpManagerTargetDiscoveredCallback) (llrp_manager_t handle, const LlrpDiscoveredTarget *target, void *context)

An LLRP target has been discovered.

Parameters

handle	Handle to the LLRP manager which has discovered the target.
target	Information about the target which has been discovered.
context	Context pointer that was given at the creation of the LLRP manager instance.

Function Documentation

llrp_manager_config_init()

void llrp_manager_config_init	(	LlrpManagerConfig *	config,
		uint16_t	manufacturer_id
	)

Initialize an LlrpManagerConfig 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:

LlrpManagerConfig config;
llrp_manager_config_init(&config, 0x6574);

Parameters

[out]	config	Pointer to LlrpManagerConfig to init.
[in]	manufacturer_id	ESTA manufacturer ID. All LLRP managers must have one.

llrp_manager_config_set_callbacks()

void llrp_manager_config_set_callbacks	(	LlrpManagerConfig *	config,
		LlrpManagerTargetDiscoveredCallback	target_discovered,
		LlrpManagerRdmResponseReceivedCallback	rdm_response_received,
		LlrpManagerDiscoveryFinishedCallback	discovery_finished,
		void *	context
	)

Set the callbacks in an LLRP manager configuration structure.

Items marked "optional" can be NULL.

Parameters

[out]	config	Config struct in which to set the callbacks.
[in]	target_discovered	Callback called when a new LLRP target has been discovered.
[in]	rdm_response_received	Callback called when an LLRP manager receives a response to an RDM command.
[in]	discovery_finished	(optional) Callback called when LLRP discovery has finished.
[in]	context	(optional) Pointer to opaque data passed back with each callback.

llrp_manager_create()

etcpal_error_t llrp_manager_create	(	const LlrpManagerConfig *	config,
		llrp_manager_t *	handle
	)

Create a new LLRP manager instance.

LLRP managers can only be created when RDMNET_DYNAMIC_MEM is defined nonzero. Otherwise, this function will always fail.

Parameters

[in]	config	Configuration parameters for the LLRP manager to be created.
[out]	handle	Handle to the newly-created manager instance.

Returns

kEtcPalErrOk: Manager created successfully.

kEtcPalErrInvalid: Invalid argument provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNoMem: No memory to allocate additional manager instance.

kEtcPalErrSys: An internal library or system call error occurred.

Note: Other error codes might be propagated from underlying socket calls.

llrp_manager_destroy()

etcpal_error_t llrp_manager_destroy

(

llrp_manager_t

handle

)

Destroy an LLRP manager instance.

The handle will be invalidated for any future calls to API functions.

Parameters

[in]

handle

Handle to manager to destroy.

Returns

kEtcPalErrOk: LLRP manager destroyed successfully.

kEtcPalErrInvalid: Invalid argument.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNotFound: Handle is not associated with a valid LLRP manager instance.

kEtcPalErrSys: An internal library or system call error occurred.

llrp_manager_send_get_command()

etcpal_error_t llrp_manager_send_get_command	(	llrp_manager_t	handle,
		const LlrpDestinationAddr *	destination,
		uint16_t	param_id,
		const uint8_t *	data,
		uint8_t	data_len,
		uint32_t *	seq_num
	)

Send an RDM GET command from an LLRP manager.

On success, provides the sequence number to correlate with a response.

Parameters

[in]	handle	Handle to LLRP manager from which to send the GET command.
[in]	destination	Addressing information for LLRP target 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 the LLRP sequence number of the command.

Returns

kEtcPalErrOk: Command sent successfully.

kEtcPalErrInvalid: Invalid argument provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNotFound: Handle is not associated with a valid LLRP manager instance.

Note: Other error codes might be propagated from underlying socket calls.

llrp_manager_send_rdm_command()

etcpal_error_t llrp_manager_send_rdm_command	(	llrp_manager_t	handle,
		const LlrpDestinationAddr *	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 an LLRP manager.

On success, provides the sequence number to correlate with a response.

Parameters

[in]	handle	Handle to LLRP manager from which to send the RDM command.
[in]	destination	Addressing information for LLRP target 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 the LLRP sequence number of the command.

Returns

kEtcPalErrOk: Command sent successfully.

kEtcPalErrInvalid: Invalid argument provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNotFound: Handle is not associated with a valid LLRP manager instance.

Note: Other error codes might be propagated from underlying socket calls.

llrp_manager_send_set_command()

etcpal_error_t llrp_manager_send_set_command	(	llrp_manager_t	handle,
		const LlrpDestinationAddr *	destination,
		uint16_t	param_id,
		const uint8_t *	data,
		uint8_t	data_len,
		uint32_t *	seq_num
	)

Send an RDM SET command from an LLRP manager.

On success, provides the sequence number to correlate with a response.

Parameters

[in]	handle	Handle to LLRP manager from which to send the SET command.
[in]	destination	Addressing information for LLRP target 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 the LLRP sequence number of the command.

Returns

kEtcPalErrOk: Command sent successfully.

kEtcPalErrInvalid: Invalid argument provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNotFound: Handle is not associated with a valid LLRP manager instance.

Note: Other error codes might be propagated from underlying socket calls.

llrp_manager_start_discovery()

etcpal_error_t llrp_manager_start_discovery	(	llrp_manager_t	handle,
		uint16_t	filter
	)

Start discovery on an LLRP manager.

Configure a manager to start discovery and send the first discovery message. Fails if a previous discovery process is still ongoing.

Parameters

[in]	handle	Handle to LLRP manager on which to start discovery.
[in]	filter	Discovery filter, made up of one or more of the LLRP_FILTERVAL_* constants defined in rdmnet/defs.h

Returns

kEtcPalErrOk: Discovery started successfully.

kEtcPalErrInvalid: Invalid argument provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNotFound: Handle is not associated with a valid LLRP manager instance.

kEtcPalErrAlready: A discovery operation is already in progress.

kEtcPalErrSys: An internal library or system call error occurred.

llrp_manager_stop_discovery()

etcpal_error_t llrp_manager_stop_discovery

(

llrp_manager_t

handle

)

Stop discovery on an LLRP manager.

Clears all discovery state and known discovered targets.

Parameters

[in]

handle

Handle to LLRP manager on which to stop discovery.

Returns

kEtcPalErrOk: Discovery stopped successfully.

kEtcPalErrInvalid: Invalid argument provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNotFound: Handle is not associated with a valid LLRP manager instance.