LLRP Target API

Overview

Implement the functionality required by an LLRP Target in E1.33.

Typically, this API is called automatically when using the role APIs:

• Controller API
• Device API
• Broker API

And thus these functions should not typically need to be used directly.

Data Structures
struct	LlrpTargetCallbacks
	A set of notification callbacks received about an LLRP target. More...
struct	LlrpTargetConfig
	A set of information that defines the startup parameters of an LLRP Target. More...

Macros
#define	LLRP_TARGET_INVALID   -1
	An invalid LLRP target handle value.
#define	LLRP_TARGET_CONFIG_DEFAULT_INIT(manu_id)
	A default-value initializer for an LlrpTargetConfig struct. More...

Typedefs
typedef int	llrp_target_t
	A handle for an instance of LLRP Target functionality.
typedef void(*	LlrpTargetRdmCommandReceivedCallback) (llrp_target_t handle, const LlrpRdmCommand *cmd, RdmnetSyncRdmResponse *response, void *context)
	An RDM command has been received addressed to an LLRP target. More...
typedef struct LlrpTargetCallbacks	LlrpTargetCallbacks
	A set of notification callbacks received about an LLRP target.
typedef struct LlrpTargetConfig	LlrpTargetConfig
	A set of information that defines the startup parameters of an LLRP Target.

Functions
void	llrp_target_config_init (LlrpTargetConfig *config, uint16_t manufacturer_id)
	Initialize an LlrpTargetConfig with default values for the optional config options. More...
etcpal_error_t	llrp_target_create (const LlrpTargetConfig *config, llrp_target_t *handle)
	Create a new LLRP target instance. More...
etcpal_error_t	llrp_target_destroy (llrp_target_t handle)
	Destroy an LLRP target instance. More...
etcpal_error_t	llrp_target_send_ack (llrp_target_t handle, const LlrpSavedRdmCommand *received_cmd, const uint8_t *response_data, uint8_t response_data_len)
	Send an RDM ACK response from an LLRP target. More...
etcpal_error_t	llrp_target_send_nack (llrp_target_t handle, const LlrpSavedRdmCommand *received_cmd, rdm_nack_reason_t nack_reason)
	Send an RDM NACK response from an LLRP target. More...

Macro Definition Documentation

LLRP_TARGET_CONFIG_DEFAULT_INIT

#define LLRP_TARGET_CONFIG_DEFAULT_INIT

(

manu_id

)

Value:

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

A default-value initializer for an LlrpTargetConfig struct.

Usage:

LlrpTargetConfig config = LLRP_TARGET_CONFIG_DEFAULT_INIT(MY_ESTA_MANUFACTURER_ID);
// Now fill in the required portions as necessary with your data...

Parameters

manu_id

Your ESTA manufacturer ID.

Typedef Documentation

LlrpTargetRdmCommandReceivedCallback

typedef void(* LlrpTargetRdmCommandReceivedCallback) (llrp_target_t handle, const LlrpRdmCommand *cmd, RdmnetSyncRdmResponse *response, void *context)

An RDM command has been received addressed to an LLRP target.

Parameters

[in]	handle	Handle to the LLRP target 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 LLRP target instance.

Function Documentation

llrp_target_config_init()

void llrp_target_config_init	(	LlrpTargetConfig *	config,
		uint16_t	manufacturer_id
	)

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

LlrpTargetConfig config;
llrp_target_config_init(&config, 0x6574);

Parameters

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

llrp_target_create()

etcpal_error_t llrp_target_create	(	const LlrpTargetConfig *	config,
		llrp_target_t *	handle
	)

Create a new LLRP target instance.

Parameters

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

Returns

kEtcPalErrOk: Target created successfully.

kEtcPalErrInvalid: Invalid argument provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNoMem: No memory to allocate additional target instance.

kEtcPalErrSys: An internal library or system call error occurred.

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

llrp_target_destroy()

etcpal_error_t llrp_target_destroy

(

llrp_target_t

handle

)

Destroy an LLRP target instance.

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

Parameters

[in]

handle

Handle to target to destroy.

Returns

kEtcPalErrOk: LLRP target destroyed successfully.

kEtcPalErrInvalid: Invalid argument.

kEtcPalErrNotInit: Module not initialized.

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

kEtcPalErrSys: An internal library or system call error occurred.

llrp_target_send_ack()

etcpal_error_t llrp_target_send_ack	(	llrp_target_t	handle,
		const LlrpSavedRdmCommand *	received_cmd,
		const uint8_t *	response_data,
		uint8_t	response_data_len
	)

Send an RDM ACK response from an LLRP target.

Parameters

[in]	handle	Handle to LLRP target from which to send the 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 sent successfully.

kEtcPalErrInvalid: Invalid argument provided.

kEtcPalErrNotInit: Module not initialized.

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

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

llrp_target_send_nack()

etcpal_error_t llrp_target_send_nack	(	llrp_target_t	handle,
		const LlrpSavedRdmCommand *	received_cmd,
		rdm_nack_reason_t	nack_reason
	)

Send an RDM NACK response from an LLRP target.

Parameters

[in]	handle	Handle to LLRP target from which to send the 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 sent successfully.

kEtcPalErrInvalid: Invalid argument provided.

kEtcPalErrNotInit: Module not initialized.

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

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