RDMnet
0.3.0
Implementation of ANSI E1.33 (RDMnet)
|
View other versions:
|
An instance of RDMnet controller functionality.
See Using the Controller API for details of how to use this API.
#include <rdmnet/cpp/controller.h>
Data Structures | |
class | NotifyHandler |
A base class for a class that receives notification callbacks from a controller. More... | |
class | RdmCommandHandler |
A base class for a class that receives RDM commands addressed to a controller. More... | |
struct | RdmData |
A set of initial identifying RDM data to use for a controller. More... | |
struct | Settings |
A set of configuration settings that a controller needs to initialize. More... | |
Public Types | |
using | Handle = rdmnet_controller_t |
A handle type used by the RDMnet library to identify controller instances. | |
Public Member Functions | |
Controller (const Controller &other)=delete | |
Controller & | operator= (const Controller &other)=delete |
Controller (Controller &&other)=default | |
Move a controller instance. | |
Controller & | operator= (Controller &&other)=default |
Move a controller instance. | |
etcpal::Error | Startup (NotifyHandler ¬ify_handler, const Settings &settings, const RdmData &rdm_data) |
Allocate resources and start up this controller with the given configuration. More... | |
etcpal::Error | Startup (NotifyHandler ¬ify_handler, const Settings &settings, RdmCommandHandler &rdm_handler, uint8_t *rdm_response_buf=nullptr) |
Allocate resources and start up this controller with the given configuration. More... | |
void | Shutdown (rdmnet_disconnect_reason_t disconnect_reason=kRdmnetDisconnectShutdown) |
Shut down this controller and deallocate resources. More... | |
etcpal::Expected< ScopeHandle > | AddScope (const char *id, const etcpal::SockAddr &static_broker_addr=etcpal::SockAddr{}) |
Add a new scope to this controller instance. More... | |
etcpal::Expected< ScopeHandle > | AddScope (const std::string &id, const etcpal::SockAddr &static_broker_addr=etcpal::SockAddr{}) |
Add a new scope to this controller instance. More... | |
etcpal::Expected< ScopeHandle > | AddScope (const Scope &scope_config) |
Add a new scope to this controller instance. More... | |
etcpal::Expected< ScopeHandle > | AddDefaultScope (const etcpal::SockAddr &static_broker_addr=etcpal::SockAddr{}) |
Shortcut to add the default RDMnet scope to a controller instance. More... | |
etcpal::Error | RemoveScope (ScopeHandle scope_handle, rdmnet_disconnect_reason_t disconnect_reason) |
Remove a previously-added scope from this controller instance. More... | |
etcpal::Error | ChangeScope (ScopeHandle scope_handle, const char *new_scope_id_str, rdmnet_disconnect_reason_t disconnect_reason, const etcpal::SockAddr &new_static_broker_addr=etcpal::SockAddr{}) |
Change the configuration of a scope on a controller. More... | |
etcpal::Error | ChangeScope (ScopeHandle scope_handle, const Scope &new_scope_config, rdmnet_disconnect_reason_t disconnect_reason) |
Change the configuration of a scope on a controller. More... | |
etcpal::Error | ChangeSearchDomain (const char *new_search_domain, rdmnet_disconnect_reason_t disconnect_reason) |
Change the controller's DNS search domain. More... | |
etcpal::Expected< uint32_t > | SendRdmCommand (ScopeHandle scope_handle, const DestinationAddr &destination, rdmnet_command_class_t command_class, uint16_t param_id, const uint8_t *data=nullptr, uint8_t data_len=0) |
Send an RDM command from a controller on a scope. More... | |
etcpal::Expected< uint32_t > | SendGetCommand (ScopeHandle scope_handle, const DestinationAddr &destination, uint16_t param_id, const uint8_t *data=nullptr, uint8_t data_len=0) |
Send an RDM GET command from a controller on a scope. More... | |
etcpal::Expected< uint32_t > | SendSetCommand (ScopeHandle scope_handle, const DestinationAddr &destination, uint16_t param_id, const uint8_t *data=nullptr, uint8_t data_len=0) |
Send an RDM SET command from a controller on a scope. More... | |
etcpal::Error | RequestClientList (ScopeHandle scope_handle) |
Request a client list from a broker. More... | |
etcpal::Error | RequestResponderIds (ScopeHandle scope_handle, const rdm::Uid *uids, size_t num_uids) |
Request mappings from dynamic UIDs to Responder IDs (RIDs). More... | |
etcpal::Error | RequestResponderIds (ScopeHandle scope_handle, const std::vector< rdm::Uid > &uids) |
Request mappings from dynamic UIDs to Responder IDs (RIDs). More... | |
etcpal::Error | SendRdmAck (ScopeHandle scope_handle, 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 controller. More... | |
etcpal::Error | SendRdmNack (ScopeHandle scope_handle, const SavedRdmCommand &received_cmd, rdm_nack_reason_t nack_reason) |
Send a negative acknowledge (NACK) response to an RDM command received by a controller. More... | |
etcpal::Error | SendRdmNack (ScopeHandle scope_handle, const SavedRdmCommand &received_cmd, uint16_t raw_nack_reason) |
Send a negative acknowledge (NACK) response to an RDM command received by a controller. More... | |
etcpal::Error | SendRdmUpdate (ScopeHandle scope_handle, 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 | 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 LLRP RDM command received by a controller. More... | |
etcpal::Error | SendLlrpNack (const llrp::SavedRdmCommand &received_cmd, rdm_nack_reason_t nack_reason) |
Send a negative acknowledge (NACK) response to an LLRP RDM command received by a controller. More... | |
etcpal::Error | SendLlrpNack (const llrp::SavedRdmCommand &received_cmd, uint16_t raw_nack_reason) |
Send a negative acknowledge (NACK) response to an LLRP RDM command received by a controller. More... | |
Handle | handle () const |
Retrieve the handle of a controller instance. | |
const RdmData & | rdm_data () const |
Retrieve the RDM data that this controller was configured with on startup. More... | |
Controller::NotifyHandler * | notify_handler () const |
Retrieve the Controller::NotifyHandler reference that this controller was configured with. | |
Controller::RdmCommandHandler * | rdm_command_handler () const |
Retrieve the Controller::RdmCommandHandler reference that this controller was configured with. More... | |
etcpal::Expected< Scope > | scope (ScopeHandle scope_handle) const |
Retrieve the scope configuration associated with a given scope handle. More... | |
void | UpdateRdmData (const RdmData &new_data) |
Update the data used to identify this controller to other controllers. | |
Static Public Attributes | |
static constexpr Handle | kInvalidHandle = RDMNET_CONTROLLER_INVALID |
An invalid Handle value. | |
|
inline |
Shortcut to add the default RDMnet scope to a controller instance.
The library will 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 Controller::NotifyHandler.
static_broker_addr | [optional] A static broker address to configure for the default scope. |
|
inline |
Add a new scope to this 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 associated Controller::NotifyHandler.
id | The scope ID string. |
static_broker_addr | [optional] A static IP address and port at which to connect to the broker for this scope. |
|
inline |
Add a new scope to this 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 associated Controller::NotifyHandler.
scope_config | Configuration information for the new scope. |
|
inline |
Add a new scope to this 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 associated Controller::NotifyHandler.
id | The scope ID string. |
static_broker_addr | [optional] A static IP address and port at which to connect to the broker for this scope. |
|
inline |
Change the configuration of a scope on a controller.
Will disconnect from any connected brokers and attempt connection again using the new configuration given.
scope_handle | Handle to the scope for which to change the configuration. |
new_scope_id_str | ID string to use for the new scope. |
disconnect_reason | RDMnet protocol disconnect reason to send to the connected broker. |
new_static_broker_addr | [optional] New static IP address and port at which to connect to the broker for this scope. |
|
inline |
Change the configuration of a scope on a controller.
Will disconnect from any connected brokers and attempt connection again using the new configuration given.
scope_handle | Handle to the scope for which to change the configuration. |
new_scope_config | New configuration parameters for the scope. |
disconnect_reason | RDMnet protocol disconnect reason to send to the connected broker. |
|
inline |
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.
new_search_domain | New search domain to use for discovery. |
disconnect_reason | Disconnect reason to send to any connected brokers. |
|
inline |
Retrieve the Controller::RdmCommandHandler reference that this controller was configured with.
|
inline |
Retrieve the RDM data that this controller was configured with on startup.
|
inline |
Remove a previously-added scope from this controller instance.
After this call completes, scope_handle will no longer be valid.
scope_handle | Handle to scope to remove. |
disconnect_reason | RDMnet protocol disconnect reason to send to the connected broker. |
|
inline |
Request a client list from a broker.
The response will be delivered via the Controller::NotifyHandler::HandleClientListUpdate() callback.
scope_handle | Handle to the scope on which to request the client list. |
|
inline |
Request mappings from dynamic UIDs to Responder IDs (RIDs).
See Devices and Gateways for more information. A RID is a UUID that permanently identifies a virtual RDMnet responder.
scope_handle | Handle to the scope on which to request the responder IDs. |
uids | List of dynamic UIDs for which to request the corresponding responder ID. |
num_uids | Size of the uids array. |
|
inline |
Request mappings from dynamic UIDs to Responder IDs (RIDs).
See Devices and Gateways for more information. A RID is a UUID that permanently identifies a virtual RDMnet responder.
scope_handle | Handle to the scope on which to request the responder IDs. |
uids | List of dynamic UIDs for which to request the corresponding responder ID. |
|
inline |
Retrieve the scope configuration associated with a given scope handle.
|
inline |
Send an RDM GET command from a controller on a scope.
The response will be delivered via the Controller::NotifyHandler::HandleRdmResponse() callback.
scope_handle | Handle to the scope on which to send the RDM command. |
destination | The destination addressing information for the RDM command. |
param_id | The command's RDM parameter ID. |
data | [optional] The command's RDM parameter data, if it has any. |
data_len | [optional] The length of the RDM parameter data (or 0 if data is nullptr). |
|
inline |
Send an acknowledge (ACK) response to an LLRP RDM command received by a controller.
This function should only be used if a Controller::RdmCommandHandler was supplied when starting this controller.
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). |
|
inline |
Send a negative acknowledge (NACK) response to an LLRP RDM command received by a controller.
This function should only be used if a Controller::RdmCommandHandler was supplied when starting this controller.
received_cmd | The command to which this NACK is a response. |
nack_reason | The RDM NACK reason to send with the NACK response. |
|
inline |
Send a negative acknowledge (NACK) response to an LLRP RDM command received by a controller.
This function should only be used if a Controller::RdmCommandHandler was supplied when starting this controller.
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. |
|
inline |
Send an acknowledge (ACK) response to an RDM command received by a controller.
This function should only be used if a Controller::RdmCommandHandler was supplied when starting this controller.
scope_handle | Handle to the scope on which the corresponding command was received. |
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). |
|
inline |
Send an RDM command from a controller on a scope.
The response will be delivered via the Controller::NotifyHandler::HandleRdmResponse() callback.
scope_handle | Handle to the scope on which to send the RDM command. |
destination | The destination addressing information for the RDM command. |
command_class | The command's RDM command class (GET or SET). |
param_id | The command's RDM parameter ID. |
data | [optional] The command's RDM parameter data, if it has any. |
data_len | [optional] The length of the RDM parameter data (or 0 if data is nullptr). |
|
inline |
Send a negative acknowledge (NACK) response to an RDM command received by a controller.
This function should only be used if a Controller::RdmCommandHandler was supplied when starting this controller.
scope_handle | Handle to the scope on which the corresponding command was received. |
received_cmd | The command to which this NACK is a response. |
nack_reason | The RDM NACK reason to send with the NACK response. |
|
inline |
Send a negative acknowledge (NACK) response to an RDM command received by a controller.
This function should only be used if a Controller::RdmCommandHandler was supplied when starting this controller.
scope_handle | Handle to the scope on which the corresponding command was received. |
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. |
|
inline |
Send an asynchronous RDM GET response to update the value of a local parameter.
This function should only be used if a Controller::RdmCommandHandler was supplied when starting this controller.
scope_handle | Handle to the scope on which to send the RDM update. |
param_id | The RDM parameter ID that has been updated. |
data | The updated parameter data, if any. |
data_len | The length of the parameter data, if any. |
|
inline |
Send an RDM SET command from a controller on a scope.
The response will be delivered via the Controller::NotifyHandler::HandleRdmResponse() callback.
scope_handle | Handle to the scope on which to send the RDM command. |
destination | The destination addressing information for the RDM command. |
param_id | The command's RDM parameter ID. |
data | [optional] The command's RDM parameter data, if it has any. |
data_len | [optional] The length of the RDM parameter data (or 0 if data is nullptr). |
|
inline |
Shut down this controller and deallocate resources.
Will disconnect all scopes to which this controller is currently connected, sending the disconnect reason provided in the disconnect_reason parameter.
disconnect_reason | Reason code for disconnecting from each scope. |
|
inline |
Allocate resources and start up this controller with the given configuration.
This overload provides a set of RDM data to the library to use for the controller's RDM responder. RDM commands addressed to the controller will be handled internally by the library.
notify_handler | A class instance to handle callback notifications from this controller. |
settings | Configuration settings used by this controller. |
rdm_data | Data to identify this controller to other controllers on the network. |
|
inline |
Allocate resources and start up this controller with the given configuration.
This overload provides a notification handler to respond to RDM commands addressed to the controller. You must implement a core set of RDM commands - see Using the Controller API for more information.
notify_handler | A class instance to handle callback notifications from this controller. |
settings | Configuration settings used by this controller. |
rdm_handler | A class instance to handle RDM commands addressed to this controller. |
rdm_response_buf | (optional) A data buffer used to respond synchronously to RDM commands. See Handling RDM Commands for more information. |