Overview

An instance of RDMnet device functionality.

See Using the Device API for details of how to use this API.

#include <rdmnet/cpp/device.h>

Data Structures
class	NotifyHandler
	A base class for a class that receives notification callbacks from a device. More...

struct	Settings
	A set of configuration settings that a device needs to initialize. More...

Public Types
using	Handle = rdmnet_device_t
	A handle type used by the RDMnet library to identify device instances.

Public Member Functions
	Device (const Device &other)=delete

Device &	operator= (const Device &other)=delete

	Device (Device &&other)=default
	Move a device instance.

Device &	operator= (Device &&other)=default
	Move a device instance.

etcpal::Error	StartupWithDefaultScope (NotifyHandler &notify_handler, const Settings &settings, const etcpal::SockAddr &static_broker_addr=etcpal::SockAddr{})
	Allocate resources and start up this device with the given configuration on the default RDMnet scope. More...

etcpal::Error	Startup (NotifyHandler &notify_handler, const Settings &settings, const char *scope_id_str, const etcpal::SockAddr &static_broker_addr=etcpal::SockAddr{})
	Allocate resources and start up this device with the given configuration on the given RDMnet scope. More...

etcpal::Error	Startup (NotifyHandler &notify_handler, const Settings &settings, const Scope &scope_config)
	Allocate resources and start up this device with the given configuration on the given RDMnet scope. More...

void	Shutdown (rdmnet_disconnect_reason_t disconnect_reason=kRdmnetDisconnectShutdown)
	Shut down this device and deallocate resources. More...

etcpal::Error	ChangeScope (const char *new_scope_id_str, rdmnet_disconnect_reason_t disconnect_reason, const etcpal::SockAddr &static_broker_addr=etcpal::SockAddr{})
	Change the device's RDMnet scope. More...

etcpal::Error	ChangeScope (const Scope &new_scope_config, rdmnet_disconnect_reason_t disconnect_reason)
	Change the device's RDMnet scope. More...

etcpal::Error	ChangeSearchDomain (const char *new_search_domain, rdmnet_disconnect_reason_t disconnect_reason)
	Change the device's DNS search domain. More...

etcpal::Error	SendRdmAck (const SavedRdmCommand &received_cmd, const uint8_t *response_data=nullptr, size_t response_data_len=0)
	Send an acknowledge (ACK) response to an RDM command received by a device. More...

etcpal::Error	SendRdmNack (const SavedRdmCommand &received_cmd, rdm_nack_reason_t nack_reason)
	Send a negative acknowledge (NACK) response to an RDM command received by a device. More...

etcpal::Error	SendRdmNack (const SavedRdmCommand &received_cmd, uint16_t raw_nack_reason)
	Send a negative acknowledge (NACK) response to an RDM command received by a device. More...

etcpal::Error	SendRdmUpdate (uint16_t param_id, const uint8_t *data=nullptr, size_t data_len=0)
	Send an asynchronous RDM GET response to update the value of a local parameter. More...

etcpal::Error	SendRdmUpdate (uint16_t subdevice, uint16_t param_id, const uint8_t *data=nullptr, size_t data_len=0)
	Send an asynchronous RDM GET response to update the value of a local parameter. More...

etcpal::Error	SendRdmUpdate (const SourceAddr &source_addr, uint16_t param_id, const uint8_t *data=nullptr, size_t data_len=0)
	Send an asynchronous RDM GET response to update the value of a parameter on a sub-responder. More...

etcpal::Error	SendRptStatus (const SavedRdmCommand &received_cmd, rpt_status_code_t status_code, const char *status_string=nullptr)
	Send an RPT status message from a device. More...

etcpal::Error	SendLlrpAck (const llrp::SavedRdmCommand &received_cmd, const uint8_t *response_data=nullptr, uint8_t response_data_len=0)
	Send an acknowledge (ACK) response to an RDM command received by a device over LLRP. More...

etcpal::Error	SendLlrpNack (const llrp::SavedRdmCommand &received_cmd, rdm_nack_reason_t nack_reason)
	Send a negative acknowledge (NACK) response to an RDM command received by a device over LLRP. More...

etcpal::Error	SendLlrpNack (const llrp::SavedRdmCommand &received_cmd, uint16_t raw_nack_reason)
	Send a negative acknowledge (NACK) response to an RDM command received by a device over LLRP. More...

etcpal::Error	AddVirtualEndpoint (const VirtualEndpointConfig &endpoint_config)
	Add a virtual endpoint to a device. More...

etcpal::Error	AddVirtualEndpoints (const std::vector< VirtualEndpointConfig > &endpoint_configs)
	Add multiple virtual endpoints to a device. More...

etcpal::Error	AddPhysicalEndpoint (const PhysicalEndpointConfig &physical_config)
	Add a physical endpoint to a device. More...

etcpal::Error	AddPhysicalEndpoints (const std::vector< PhysicalEndpointConfig > &endpoint_configs)
	Add multiple physical endpoints to a device. More...

etcpal::Error	RemoveEndpoint (uint16_t endpoint_id)
	Remove an endpoint from a device. More...

etcpal::Error	RemoveEndpoints (const std::vector< uint16_t > &endpoint_ids)
	Remove multiple endpoints from a device. More...

etcpal::Error	AddVirtualResponder (uint16_t endpoint_id, const etcpal::Uuid &responder_id)
	Add a responder with a dynamic UID to a virtual endpoint. More...

etcpal::Error	AddVirtualResponder (uint16_t endpoint_id, const rdm::Uid &responder_static_uid)
	Add a responder with a static UID to a virtual endpoint. More...

etcpal::Error	AddVirtualResponders (uint16_t endpoint_id, const std::vector< etcpal::Uuid > &responder_ids)
	Add multiple responders with dynamic UIDs to a virtual endpoint. More...

etcpal::Error	AddVirtualResponders (uint16_t endpoint_id, const std::vector< rdm::Uid > &responder_static_uids)
	Add multiple responders with static UIDs to a virtual endpoint. More...

etcpal::Error	AddPhysicalResponder (uint16_t endpoint_id, const rdm::Uid &responder_uid, uint16_t control_field, const rdm::Uid &binding_uid=rdm::Uid{})
	Add a responder to a physical endpoint. More...

etcpal::Error	AddPhysicalResponder (uint16_t endpoint_id, const PhysicalEndpointResponder &responder)
	Add a responder to a physical endpoint. More...

etcpal::Error	AddPhysicalResponders (uint16_t endpoint_id, const std::vector< PhysicalEndpointResponder > &responders)
	Add multiple responders to a physical endpoint. More...

etcpal::Error	RemoveVirtualResponder (uint16_t endpoint_id, const etcpal::Uuid &responder_id)
	Remove a responder with a dynamic UID from a virtual endpoint. More...

etcpal::Error	RemoveVirtualResponder (uint16_t endpoint_id, const rdm::Uid &responder_static_uid)
	Remove a responder with a static UID from a virtual endpoint. More...

etcpal::Error	RemoveVirtualResponders (uint16_t endpoint_id, const std::vector< etcpal::Uuid > &responder_ids)
	Remove multiple responder with dynamic UIDs from a virtual endpoint. More...

etcpal::Error	RemoveVirtualResponders (uint16_t endpoint_id, const std::vector< rdm::Uid > &responder_static_uids)
	Remove multiple responders with static UIDs from a virtual endpoint. More...

etcpal::Error	RemovePhysicalResponder (uint16_t endpoint_id, const rdm::Uid &responder_uid)
	Remove a responder from a physical endpoint. More...

etcpal::Error	RemovePhysicalResponders (uint16_t endpoint_id, const std::vector< rdm::Uid > &responder_uids)
	Remove multiple responders from a physical endpoint. More...

constexpr Handle	handle () const
	Retrieve the handle of a device instance.

constexpr NotifyHandler *	notify_handler () const
	Retrieve the NotifyHandler reference that this device was configured with.

etcpal::Expected< Scope >	scope () const
	Retrieve the scope configuration associated with a device instance. More...

Static Public Attributes
static constexpr Handle	kInvalidHandle = RDMNET_DEVICE_INVALID
	An invalid Handle value.

Member Function Documentation

◆ AddPhysicalEndpoint()

etcpal::Error rdmnet::Device::AddPhysicalEndpoint ( const PhysicalEndpointConfig & endpoint_config )

inline

Add a physical endpoint to a device.

See Devices and Gateways for more information about endpoints.

Parameters

endpoint_config Configuration information for the new physical endpoint.

Returns: etcpal::Error::Ok(): Endpoint added successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Device not started - call Device::Startup() first.; kEtcPalErrSys: An internal library or system call error occurred.

◆ AddPhysicalEndpoints()

etcpal::Error rdmnet::Device::AddPhysicalEndpoints ( const std::vector< PhysicalEndpointConfig > & endpoint_configs )

inline

Add multiple physical endpoints to a device.

See Devices and Gateways for more information about endpoints.

Parameters

endpoint_configs Configuration information for the new physical endpoints.

Returns: etcpal::Error::Ok(): Endpoints added successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Device not started - call Device::Startup() first.; kEtcPalErrSys: An internal library or system call error occurred.

◆ AddPhysicalResponder() [1/2]

etcpal::Error rdmnet::Device::AddPhysicalResponder	(	uint16_t	endpoint_id,
		const PhysicalEndpointResponder &	responder
	)

inline

Add a responder to a physical endpoint.

Add the endpoint first with Device::AddPhysicalEndpoint(). See Devices and Gateways for more information on endpoints.

Parameters

endpoint_id	ID for the endpoint on which to add the responder.
responder	Identifying information for the responder to add.

Returns: etcpal::Error::Ok(): Responder added sucessfully.; kEtcPalErrInvalid: Invalid argument, or the endpoint is a virtual endpoint.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Device not started, or endpoint_id was not previously added.; kEtcPalErrSys: An internal library or system call error occurred.

◆ AddPhysicalResponder() [2/2]

etcpal::Error rdmnet::Device::AddPhysicalResponder	(	uint16_t	endpoint_id,
		const rdm::Uid &	responder_uid,
		uint16_t	control_field,
		const rdm::Uid &	binding_uid = `rdm::Uid{}`
	)

inline

Add a responder to a physical endpoint.

Add the endpoint first with Device::AddPhysicalEndpoint(). See Devices and Gateways for more information on endpoints.

Parameters

endpoint_id	ID for the endpoint on which to add the responder.
responder_uid	The responder's RDM UID.
control_field	The control field received in the DISC_MUTE message from this responder.
binding_uid	The binding UID received in the DISC_MUTE message from this responder.

Returns: etcpal::Error::Ok(): Responder added sucessfully.; kEtcPalErrInvalid: Invalid argument, or the endpoint is a virtual endpoint.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Device not started, or endpoint_id was not previously added.; kEtcPalErrSys: An internal library or system call error occurred.

◆ AddPhysicalResponders()

etcpal::Error rdmnet::Device::AddPhysicalResponders	(	uint16_t	endpoint_id,
		const std::vector< PhysicalEndpointResponder > &	responders
	)

inline

Add multiple responders to a physical endpoint.

Add the endpoint first with Device::AddPhysicalEndpoint(). See Devices and Gateways for more information on endpoints.

Parameters

endpoint_id	ID for the endpoint on which to add the responders.
responders	Identifying information for responders to add.

Returns: etcpal::Error::Ok(): Responders added sucessfully.; kEtcPalErrInvalid: Invalid argument, or the endpoint is a virtual endpoint.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Device not started, or endpoint_id was not previously added.; kEtcPalErrSys: An internal library or system call error occurred.

◆ AddVirtualEndpoint()

etcpal::Error rdmnet::Device::AddVirtualEndpoint ( const VirtualEndpointConfig & endpoint_config )

inline

Add a virtual endpoint to a device.

See Devices and Gateways for more information about endpoints.

Parameters

endpoint_config Configuration information for the new virtual endpoint.

Returns: etcpal::Error::Ok(): Endpoint added successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Device not started - call Device::Startup() first.; kEtcPalErrSys: An internal library or system call error occurred.

◆ AddVirtualEndpoints()

etcpal::Error rdmnet::Device::AddVirtualEndpoints ( const std::vector< VirtualEndpointConfig > & endpoint_configs )

inline

Add multiple virtual endpoints to a device.

See Devices and Gateways for more information about endpoints.

Parameters

endpoint_configs Configuration information for the new virtual endpoints.

Returns: etcpal::Error::Ok(): Endpoints added successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Device not started - call Device::Startup() first.; kEtcPalErrSys: An internal library or system call error occurred.

◆ AddVirtualResponder() [1/2]

etcpal::Error rdmnet::Device::AddVirtualResponder	(	uint16_t	endpoint_id,
		const etcpal::Uuid &	responder_id
	)

inline

Add a responder with a dynamic UID to a virtual endpoint.

This function can only be used on virtual endpoints. A dynamic UID for the responder will be requested from the broker and the assigned UID (or error code) will be delivered to NotifyHandler::HandleDynamicUidStatus(). Save this UID for comparison when handling RDM commands addressed to the dynamic responder. Add the endpoint first with Device::AddVirtualEndpoint(). See Devices and Gateways for more information on endpoints.

Parameters

endpoint_id	ID for the endpoint on which to add the responder.
responder_id	Responder ID (permanent UUID representing the responder) to add.

Returns: etcpal::Error::Ok(): Responder added sucessfully (pending dynamic UID assignment).; kEtcPalErrInvalid: Invalid argument, or the endpoint is a physical endpoint.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Device not started, or endpoint_id was not previously added.; kEtcPalErrSys: An internal library or system call error occurred.

◆ AddVirtualResponder() [2/2]

etcpal::Error rdmnet::Device::AddVirtualResponder	(	uint16_t	endpoint_id,
		const rdm::Uid &	responder_static_uid
	)

inline

Add a responder with a static UID to a virtual endpoint.

Add the endpoint first with Device::AddVirtualEndpoint(). See Devices and Gateways for more information on endpoints.

Parameters

endpoint_id	ID for the endpoint on which to add the responder.
responder_static_uid	Responder UID (permanent static RDM UID representing the responder) to add.

Returns: etcpal::Error::Ok(): Responder added sucessfully.; kEtcPalErrInvalid: Invalid argument, or the endpoint is a physical endpoint.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Device not started, or endpoint_id was not previously added.; kEtcPalErrSys: An internal library or system call error occurred.

◆ AddVirtualResponders() [1/2]

etcpal::Error rdmnet::Device::AddVirtualResponders	(	uint16_t	endpoint_id,
		const std::vector< etcpal::Uuid > &	responder_ids
	)

inline

Add multiple 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 NotifyHandler::HandleDynamicUidStatus(). Save these UIDs for comparison when handling RDM commands addressed to the dynamic responders. Add the endpoint first with Device::AddVirtualEndpoint(). See Devices and Gateways for more information on endpoints.

Parameters

endpoint_id	ID for the endpoint on which to add the responders.
responder_ids	Responder IDs (permanent UUIDs representing the responder) to add.

Returns: etcpal::Error::Ok(): Responders added sucessfully (pending dynamic UID assignment).; kEtcPalErrInvalid: Invalid argument, or the endpoint is a physical endpoint.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Device not started, or endpoint_id was not previously added.; kEtcPalErrSys: An internal library or system call error occurred.

◆ AddVirtualResponders() [2/2]

etcpal::Error rdmnet::Device::AddVirtualResponders	(	uint16_t	endpoint_id,
		const std::vector< rdm::Uid > &	responder_static_uids
	)

inline

Add multiple responders with static UIDs to a virtual endpoint.

Add the endpoint first with Device::AddVirtualEndpoint(). See Devices and Gateways for more information on endpoints.

Parameters

endpoint_id	ID for the endpoint on which to add the responder.
responder_static_uids	Responder UIDs (permanent static RDM UIDs representing the responder) to add.

Returns: etcpal::Error::Ok(): Responders added sucessfully.; kEtcPalErrInvalid: Invalid argument, or the endpoint is a physical endpoint.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Device not started, or endpoint_id was not previously added.; kEtcPalErrSys: An internal library or system call error occurred.

◆ ChangeScope() [1/2]

etcpal::Error rdmnet::Device::ChangeScope	(	const char *	new_scope_id_str,
		rdmnet_disconnect_reason_t	disconnect_reason,
		const etcpal::SockAddr &	static_broker_addr = `etcpal::SockAddr{}`
	)

inline

Change the device's RDMnet 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 associated NotifyHandler.

Parameters

new_scope_id_str	The ID string for the new scope.
disconnect_reason	Reason code for disconnecting from the current scope.
static_broker_addr	[optional] A static IP address and port at which to connect to the broker for the new scope.

Returns: etcpal::Error::Ok(): Scope changed successfully.; Errors forwarded from rdmnet_device_change_scope().

◆ ChangeScope() [2/2]

etcpal::Error rdmnet::Device::ChangeScope	(	const Scope &	new_scope_config,
		rdmnet_disconnect_reason_t	disconnect_reason
	)

inline

Change the device's RDMnet 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 associated NotifyHandler.

Parameters

new_scope_config	Configuration information for the new scope.
disconnect_reason	Reason code for disconnecting from the current scope.

Returns: etcpal::Error::Ok(): Scope changed successfully.; Errors forwarded from rdmnet_device_change_scope().

◆ ChangeSearchDomain()

etcpal::Error rdmnet::Device::ChangeSearchDomain	(	const char *	new_search_domain,
		rdmnet_disconnect_reason_t	disconnect_reason
	)

inline

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

new_search_domain	New search domain to use for discovery.
disconnect_reason	Disconnect reason to send to the broker, if connected.

Returns: etcpal::Error::Ok(): 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.

◆ RemoveEndpoint()

etcpal::Error rdmnet::Device::RemoveEndpoint ( uint16_t endpoint_id )

inline

Remove an endpoint from a device.

See Devices and Gateways for more information about endpoints.

Parameters

endpoint_id ID of the endpoint to remove.

Returns: etcpal::Error::Ok(): Endpoint removed successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Device not started or endpoint_id was not previously added.; kEtcPalErrSys: An internal library or system call error occurred.

◆ RemoveEndpoints()

etcpal::Error rdmnet::Device::RemoveEndpoints ( const std::vector< uint16_t > & endpoint_ids )

inline

Remove multiple endpoints from a device.

See Devices and Gateways for more information about endpoints.

Parameters

endpoint_ids IDs of the endpoints to remove.

Returns: etcpal::Error::Ok(): Endpoints removed successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Device not started, or one or more endpoint IDs was not previously added.; kEtcPalErrSys: An internal library or system call error occurred.

◆ RemovePhysicalResponder()

etcpal::Error rdmnet::Device::RemovePhysicalResponder	(	uint16_t	endpoint_id,
		const rdm::Uid &	responder_uid
	)

inline

Remove a responder from a physical endpoint.

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

Parameters

endpoint_id	ID for the endpoint on which to remove the responder.
responder_uid	RDM UID of responder to remove.

Returns: etcpal::Error::Ok(): Responder removed sucessfully.; kEtcPalErrInvalid: Invalid argument, or the endpoint is a virtual endpoint.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Device not started, endpoint_id was not previously added, or responder_uid was not previously added to the endpoint.; kEtcPalErrSys: An internal library or system call error occurred.

◆ RemovePhysicalResponders()

etcpal::Error rdmnet::Device::RemovePhysicalResponders	(	uint16_t	endpoint_id,
		const std::vector< rdm::Uid > &	responder_uids
	)

inline

Remove multiple responders from a physical endpoint.

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

Parameters

endpoint_id	ID for the endpoint on which to remove the responders.
responder_uids	RDM UIDs of responders to remove.

Returns: etcpal::Error::Ok(): Responders removed sucessfully.; kEtcPalErrInvalid: Invalid argument, or the endpoint is a virtual endpoint.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Device not started, endpoint_id was not previously added, or one or more responder UIDs were not previously added to the endpoint.; kEtcPalErrSys: An internal library or system call error occurred.

◆ RemoveVirtualResponder() [1/2]

etcpal::Error rdmnet::Device::RemoveVirtualResponder	(	uint16_t	endpoint_id,
		const etcpal::Uuid &	responder_id
	)

inline

Remove a responder with a dynamic UID from a virtual endpoint.

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

Parameters

endpoint_id	ID for the endpoint on which to remove the responder.
responder_id	Responder ID to remove.

Returns: etcpal::Error::Ok(): Responder removed sucessfully.; kEtcPalErrInvalid: Invalid argument, or the endpoint is a physical endpoint.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Device not started, endpoint_id was not previously added, or responder_id was not previously added to the endpoint.; kEtcPalErrSys: An internal library or system call error occurred.

◆ RemoveVirtualResponder() [2/2]

etcpal::Error rdmnet::Device::RemoveVirtualResponder	(	uint16_t	endpoint_id,
		const rdm::Uid &	responder_static_uid
	)

inline

Remove a responder with a static UID from a virtual endpoint.

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

Parameters

endpoint_id	ID for the endpoint on which to remove the responder.
responder_static_uid	RDM UID of responder to remove.

Returns: etcpal::Error::Ok(): Responder removed sucessfully.; kEtcPalErrInvalid: Invalid argument, or the endpoint is a physical endpoint.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Device not started, endpoint_id was not previously added, or responder_static_uid was not previously added to the endpoint.; kEtcPalErrSys: An internal library or system call error occurred.

◆ RemoveVirtualResponders() [1/2]

etcpal::Error rdmnet::Device::RemoveVirtualResponders	(	uint16_t	endpoint_id,
		const std::vector< etcpal::Uuid > &	responder_ids
	)

inline

Remove multiple responder 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

endpoint_id	ID for the endpoint on which to remove the responders.
responder_ids	Responder IDs to remove.

Returns: etcpal::Error::Ok(): Responders removed sucessfully.; kEtcPalErrInvalid: Invalid argument, or the endpoint is a physical endpoint.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Device not started, endpoint_id was not previously added, or one or more responder IDs were not previously added to the endpoint.; kEtcPalErrSys: An internal library or system call error occurred.

◆ RemoveVirtualResponders() [2/2]

etcpal::Error rdmnet::Device::RemoveVirtualResponders	(	uint16_t	endpoint_id,
		const std::vector< rdm::Uid > &	responder_static_uids
	)

inline

Remove multiple 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

endpoint_id	ID for the endpoint on which to remove the responders.
responder_static_uids	RDM UIDs of the responders to remove.

Returns: etcpal::Error::Ok(): Responders removed sucessfully.; kEtcPalErrInvalid: Invalid argument, or the endpoint is a physical endpoint.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Device not started, endpoint_id was not previously added, or one or more responder UIDs were not previously added to the endpoint.; kEtcPalErrSys: An internal library or system call error occurred.

◆ scope()

etcpal::Expected< Scope > rdmnet::Device::scope ( ) const

inline

Retrieve the scope configuration associated with a device instance.

Returns: The scope configuration on success.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Device not started.

◆ SendLlrpAck()

etcpal::Error rdmnet::Device::SendLlrpAck	(	const llrp::SavedRdmCommand &	received_cmd,
		const uint8_t *	response_data = `nullptr`,
		uint8_t	response_data_len = `0`
	)

inline

Send an acknowledge (ACK) response to an RDM command received by a device over LLRP.

Parameters

received_cmd	The command to which this ACK is a response.
response_data	[optional] The response's RDM parameter data, if it has any.
response_data_len	[optional] The length of the RDM parameter data (or 0 if data is nullptr).

Returns: etcpal::Error::Ok(): ACK sent successfully.; Error codes from rdmnet_device_send_llrp_ack().

◆ SendLlrpNack() [1/2]

etcpal::Error rdmnet::Device::SendLlrpNack	(	const llrp::SavedRdmCommand &	received_cmd,
		rdm_nack_reason_t	nack_reason
	)

inline

Send a negative acknowledge (NACK) response to an RDM command received by a device over LLRP.

Parameters

received_cmd	The command to which this NACK is a response.
nack_reason	The RDM NACK reason to send with the NACK response.

Returns: etcpal::Error::Ok(): NACK sent successfully.; Error codes from rdmnet_device_send_llrp_nack().

◆ SendLlrpNack() [2/2]

etcpal::Error rdmnet::Device::SendLlrpNack	(	const llrp::SavedRdmCommand &	received_cmd,
		uint16_t	raw_nack_reason
	)

inline

Send a negative acknowledge (NACK) response to an RDM command received by a device over LLRP.

Parameters

received_cmd	The command to which this NACK is a response.
raw_nack_reason	The NACK reason (either standard or manufacturer-specific) to send with the NACK response.

Returns: etcpal::Error::Ok(): NACK sent successfully.; Error codes from rdmnet_device_send_llrp_nack().

◆ SendRdmAck()

etcpal::Error rdmnet::Device::SendRdmAck	(	const SavedRdmCommand &	received_cmd,
		const uint8_t *	response_data = `nullptr`,
		size_t	response_data_len = `0`
	)

inline

Send an acknowledge (ACK) response to an RDM command received by a device.

Parameters

received_cmd	The command to which this ACK is a response.
response_data	[optional] The response's RDM parameter data, if it has any.
response_data_len	[optional] The length of the RDM parameter data (or 0 if data is nullptr).

Returns: etcpal::Error::Ok(): ACK sent successfully.; Error codes from rdmnet_device_send_rdm_ack().

◆ SendRdmNack() [1/2]

etcpal::Error rdmnet::Device::SendRdmNack	(	const SavedRdmCommand &	received_cmd,
		rdm_nack_reason_t	nack_reason
	)

inline

Send a negative acknowledge (NACK) response to an RDM command received by a device.

Parameters

received_cmd	The command to which this NACK is a response.
nack_reason	The RDM NACK reason to send with the NACK response.

Returns: etcpal::Error::Ok(): NACK sent successfully.; Error codes from rdmnet_device_send_rdm_nack().

◆ SendRdmNack() [2/2]

etcpal::Error rdmnet::Device::SendRdmNack	(	const SavedRdmCommand &	received_cmd,
		uint16_t	raw_nack_reason
	)

inline

Send a negative acknowledge (NACK) response to an RDM command received by a device.

Parameters

received_cmd	The command to which this NACK is a response.
raw_nack_reason	The NACK reason (either standard or manufacturer-specific) to send with the NACK response.

Returns: etcpal::Error::Ok(): NACK sent successfully.; Error codes from rdmnet_device_send_rdm_nack().

◆ SendRdmUpdate() [1/3]

etcpal::Error rdmnet::Device::SendRdmUpdate	(	const SourceAddr &	source_addr,
		uint16_t	param_id,
		const uint8_t *	data = `nullptr`,
		size_t	data_len = `0`
	)

inline

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

This overload is for updating a parameter on a physical or virtual 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

source_addr	The addressing information of the responder that has an updated parameter.
param_id	The RDM parameter ID that has been updated.
data	[optional] The updated parameter data, if any.
data_len	[optional] The length of the parameter data, if any.

Returns: etcpal::Error::Ok(): RDM update sent successfully.; Error codes from rdmnet_device_send_rdm_update_from_responder().

◆ SendRdmUpdate() [2/3]

etcpal::Error rdmnet::Device::SendRdmUpdate	(	uint16_t	param_id,
		const uint8_t *	data = `nullptr`,
		size_t	data_len = `0`
	)

inline

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

This overload is for updating a parameter on the device's default responder - see Devices and Gateways for more information.

Parameters

param_id	The RDM parameter ID that has been updated.
data	[optional] The updated parameter data, if any.
data_len	[optional] The length of the parameter data, if any.

Returns: etcpal::Error::Ok(): RDM update sent successfully.; Error codes from rdmnet_device_send_rdm_update().

◆ SendRdmUpdate() [3/3]

etcpal::Error rdmnet::Device::SendRdmUpdate	(	uint16_t	subdevice,
		uint16_t	param_id,
		const uint8_t *	data = `nullptr`,
		size_t	data_len = `0`
	)

inline

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

This overload is for updating a parameter on a subdevice of the device's default responder - see Devices and Gateways for more information.

Parameters

subdevice	The subdevice from which the update is being sent.
param_id	The RDM parameter ID that has been updated.
data	[optional] The updated parameter data, if any.
data_len	[optional] The length of the parameter data, if any.

Returns: etcpal::Error::Ok(): RDM update sent successfully.; Error codes from rdmnet_device_send_rdm_update().

◆ SendRptStatus()

etcpal::Error rdmnet::Device::SendRptStatus	(	const SavedRdmCommand &	received_cmd,
		rpt_status_code_t	status_code,
		const char *	status_string = `nullptr`
	)

inline

Send an RPT status message from a device.

All RPT status messages are handled internally except those associated with RDMnet gateways. If not implementing an RDMnet gateway, this method should not be used. See Handling RDM Commands for more information.

Parameters

received_cmd	The command to which this RPT status is a response.
status_code	A code indicating the result of the command.
status_string	[optional] A string with more information about the status condition.

Returns: etcpal::Error::Ok(): RPT status sent successfully.; Error codes from rdmnet_device_send_status().

◆ Shutdown()

void rdmnet::Device::Shutdown ( rdmnet_disconnect_reason_t disconnect_reason = kRdmnetDisconnectShutdown )

inline

Shut down this device and deallocate resources.

Will disconnect any scope to which this device is currently connected, sending the disconnect reason provided in the disconnect_reason parameter.

Parameters

disconnect_reason Reason code for disconnecting from the current scope.

◆ Startup() [1/2]

etcpal::Error rdmnet::Device::Startup	(	NotifyHandler &	notify_handler,
		const Settings &	settings,
		const char *	scope_id_str,
		const etcpal::SockAddr &	static_broker_addr = `etcpal::SockAddr{}`
	)

inline

Allocate resources and start up this device with the given configuration on the given RDMnet scope.

Will immediately attempt to discover and connect to a broker for the given scope (or just connect if a static broker address is given); the status of these attempts will be communicated via the associated NotifyHandler.

Parameters

notify_handler	A class instance to handle callback notifications from this device.
settings	Configuration settings used by this device.
scope_id_str	The scope ID string.
static_broker_addr	[optional] A static IP address and port at which to connect to a broker for this scope.

Returns: etcpal::Error::Ok(): Device started successfully.; kEtcPalErrInvalid: Invalid argument.; Errors forwarded from rdmnet_device_create().

◆ Startup() [2/2]

etcpal::Error rdmnet::Device::Startup	(	NotifyHandler &	notify_handler,
		const Settings &	settings,
		const Scope &	scope_config
	)

inline

Allocate resources and start up this device with the given configuration on the given RDMnet scope.

Will immediately attempt to discover and connect to a broker for the given scope (or just connect if a static broker address is given); the status of these attempts will be communicated via the associated NotifyHandler.

Parameters

notify_handler	A class instance to handle callback notifications from this device.
settings	Configuration settings used by this device.
scope_config	Configuration information for the device's RDMnet scope.

Returns: etcpal::Error::Ok(): Device started successfully.; kEtcPalErrInvalid: Invalid argument.; Errors forwarded from rdmnet_device_create().

◆ StartupWithDefaultScope()

etcpal::Error rdmnet::Device::StartupWithDefaultScope	(	NotifyHandler &	notify_handler,
		const Settings &	settings,
		const etcpal::SockAddr &	static_broker_addr = `etcpal::SockAddr{}`
	)

inline

Allocate resources and start up this device with the given configuration on the default RDMnet scope.

Will immediately attempt to discover and connect to a broker for the default scope (or just connect if a static broker address is given); the status of these attempts will be communicated via the associated NotifyHandler.

Parameters

notify_handler	A class instance to handle callback notifications from this device.
settings	Configuration settings used by this device.
static_broker_addr	[optional] A static IP address and port at which to connect to a broker for the default scope.

Returns: etcpal::Error::Ok(): Device started successfully.; kEtcPalErrInvalid: Invalid argument.; Errors forwarded from rdmnet_device_create().

The documentation for this class was generated from the following file:

include/rdmnet/cpp/device.h

Overview

Data Structures

Public Types

Public Member Functions

Static Public Attributes

Member Function Documentation

◆ AddPhysicalEndpoint()

◆ AddPhysicalEndpoints()

◆ AddPhysicalResponder() [1/2]

◆ AddPhysicalResponder() [2/2]

◆ AddPhysicalResponders()

◆ AddVirtualEndpoint()

◆ AddVirtualEndpoints()

◆ AddVirtualResponder() [1/2]

◆ AddVirtualResponder() [2/2]

◆ AddVirtualResponders() [1/2]

◆ AddVirtualResponders() [2/2]

◆ ChangeScope() [1/2]

◆ ChangeScope() [2/2]

◆ ChangeSearchDomain()

◆ RemoveEndpoint()

◆ RemoveEndpoints()

◆ RemovePhysicalResponder()

◆ RemovePhysicalResponders()

◆ RemoveVirtualResponder() [1/2]

◆ RemoveVirtualResponder() [2/2]

◆ RemoveVirtualResponders() [1/2]

◆ RemoveVirtualResponders() [2/2]

◆ scope()

◆ SendLlrpAck()

◆ SendLlrpNack() [1/2]

◆ SendLlrpNack() [2/2]

◆ SendRdmAck()

◆ SendRdmNack() [1/2]

◆ SendRdmNack() [2/2]

◆ SendRdmUpdate() [1/3]

◆ SendRdmUpdate() [2/3]

◆ SendRdmUpdate() [3/3]

◆ SendRptStatus()

◆ Shutdown()

◆ Startup() [1/2]

◆ Startup() [2/2]

◆ StartupWithDefaultScope()