official
/
OpenLCP
1
0
Fork 0
Code Releases 1 Activity

cite multi-line quotes

This commit is contained in:
Kevin Matz 2021-08-26 12:30:44 -04:00
parent 60ac42d024
commit 390b2eadf6
4 changed files with 100 additions and 100 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
protocols/rdm/device.cpp
View File

@ -47,7 +47,7 @@ Device::Device(UID id, Device* parent)
queued_statuses_.emplace(STATUS_WARNING, std::queue<StatusPtr>());
queued_statuses_.emplace(STATUS_ERROR, std::queue<StatusPtr>());
/// 9.2.3 Required Sub-Device Messages
/// \cite RDM 9.2.3 Required Sub-Device Messages
/// Devices supporting the use of sub-devices shall support the
/// SUPPORTED_PARAMETERS message in order for the controller to determine
/// which additional messages are supported by the sub-devices.
@ -56,14 +56,14 @@ Device::Device(UID id, Device* parent)
&Device::actionGetSupportedParameters,
this, std::placeholders::_1,
std::placeholders::_2));
/// 10.3.4 Clear Status ID (CLEAR_STATUS_ID)
/// \cite RDM 10.3.4 Clear Status ID (CLEAR_STATUS_ID)
/// This parameter is used to clear the status message queue.
parameters_.try_emplace(CLEAR_STATUS_ID, new Parameter());
parameters_.at(SUPPORTED_PARAMETERS)->setAction(std::bind(
&Device::actionSetClearStatusId,
this, std::placeholders::_1,
std::placeholders::_2));
///10.3.5 Get/Set Sub-Device Status Reporting Threshold
/// \cite RDM 10.3.5 Get/Set Sub-Device Status Reporting Threshold
/// (SUB_DEVICE_STATUS_REPORT_THRESHOLD)
/// This parameter is used to set the verbosity of Sub-Device reporting using
/// the Status Type codes as enumerated in Table A-4 .
@ -76,7 +76,7 @@ Device::Device(UID id, Device* parent)
&Device::actionSetSubdeviceThreshold,
this, std::placeholders::_1,
std::placeholders::_2));
/// 10.5.1 Get Device Info (DEVICE_INFO)
/// \cite RDM 10.5.1 Get Device Info (DEVICE_INFO)
/// This parameter is used to retrieve a variety of information about the
/// device that is normally required by a controller.
parameters_.try_emplace(DEVICE_INFO, new Parameter());
@ -84,7 +84,7 @@ Device::Device(UID id, Device* parent)
&Device::actionGetDeviceInfo,
this, std::placeholders::_1,
std::placeholders::_2));
/// 10.5.2 Get Product Detail ID List (PRODUCT_DETAIL_ID_LIST)
/// \cite RDM 10.5.2 Get Product Detail ID List (PRODUCT_DETAIL_ID_LIST)
/// This parameter shall be used for requesting technology details for a
/// device.
parameters_.try_emplace(PRODUCT_DETAIL_ID_LIST, new Parameter());
@ -92,7 +92,7 @@ Device::Device(UID id, Device* parent)
&Device::actionGetProductDetailIdList,
this, std::placeholders::_1,
std::placeholders::_2));
/// 10.5.3 Get Device Model Description (DEVICE_MODEL_DESCRIPTION)
/// \cite RDM 10.5.3 Get Device Model Description (DEVICE_MODEL_DESCRIPTION)
/// This parameter provides a text description of up to 32 characters for the
/// device model type.
parameters_.try_emplace(DEVICE_MODEL_DESCRIPTION, new Parameter());
@ -100,7 +100,7 @@ Device::Device(UID id, Device* parent)
&Device::actionGetDevModelDescription,
this, std::placeholders::_1,
std::placeholders::_2));
/// 10.5.4 Get Manufacturer Label (MANUFACTURER_LABEL)
/// \cite RDM 10.5.4 Get Manufacturer Label (MANUFACTURER_LABEL)
/// This parameter provides an ASCII text response with the Manufacturer name
/// for the device of up to 32 characters.
parameters_.try_emplace(MANUFACTURER_LABEL, new Parameter());
@ -108,7 +108,7 @@ Device::Device(UID id, Device* parent)
&Device::actionGetManufacturerLabel,
this, std::placeholders::_1,
std::placeholders::_2));
/// 10.5.7 Get Language Capabilities (LANGUAGE_CAPABILITIES)
/// \cite RDM 10.5.7 Get Language Capabilities (LANGUAGE_CAPABILITIES)
/// This parameter is used to identify languages that the device supports for
/// using the LANGUAGE parameter.
parameters_.try_emplace(LANGUAGE_CAPABILITIES, new Parameter());
@ -116,7 +116,7 @@ Device::Device(UID id, Device* parent)
&Device::actionGetLanguage,
this, std::placeholders::_1,
std::placeholders::_2));
/// 10.5.8 Get/Set Language (LANGUAGE)
/// \cite RDM 10.5.8 Get/Set Language (LANGUAGE)
/// This parameter is used to change the language of the messages from
/// the device.
parameters_.try_emplace(LANGUAGE, new Parameter());
@ -128,7 +128,7 @@ Device::Device(UID id, Device* parent)
&Device::actionSetLanguage,
this, std::placeholders::_1,
std::placeholders::_2));
/// 10.5.9 Get Software Version Label (SOFTWARE_VERSION_LABEL)
/// \cite RDM 10.5.9 Get Software Version Label (SOFTWARE_VERSION_LABEL)
/// This parameter is used to get a descriptive ASCII text label for the
/// device’s operating software version.
parameters_.try_emplace(SOFTWARE_VERSION_LABEL, new Parameter());
@ -136,7 +136,7 @@ Device::Device(UID id, Device* parent)
&Device::actionGetSoftwareVersionLabel,
this, std::placeholders::_1,
std::placeholders::_2));
///10.6.1 Get/Set DMX512 Personality (DMX_PERSONALITY)
/// \cite RDM 10.6.1 Get/Set DMX512 Personality (DMX_PERSONALITY)
/// This parameter is used to set the responder’s DMX512 Personality.
parameters_.try_emplace(DMX_PERSONALITY, new Parameter());
parameters_.at(DMX_PERSONALITY)->getAction(std::bind(
@ -147,7 +147,7 @@ Device::Device(UID id, Device* parent)
&Device::actionSetDmxPersonality,
this, std::placeholders::_1,
std::placeholders::_2));
/// 10.6.2 Get DMX512 Personality Description (DMX_PERSONALITY_DESCRIPTION)
/// \cite RDM 10.6.2 Get DMX512 Personality Description (DMX_PERSONALITY_DESCRIPTION)
/// This parameter is used to get a descriptive ASCII text label for a given
/// DMX512 Personality.
parameters_.try_emplace(DMX_PERSONALITY_DESCRIPTION, new Parameter());
@ -155,7 +155,7 @@ Device::Device(UID id, Device* parent)
&Device::actionGetDmxPersonalityDesc,
this, std::placeholders::_1,
std::placeholders::_2));
/// 10.6.3 Get/Set DMX512 Starting Address (DMX_START_ADDRESS)
/// \cite RDM 10.6.3 Get/Set DMX512 Starting Address (DMX_START_ADDRESS)
/// This parameter is used to set or get the DMX512 start address.
parameters_.try_emplace(DMX_START_ADDRESS, new Parameter());
parameters_.at(DMX_START_ADDRESS)->getAction(std::bind(
@ -166,14 +166,14 @@ Device::Device(UID id, Device* parent)
&Device::actionSetDmxStartAddress,
this, std::placeholders::_1,
std::placeholders::_2));
/// 10.7.1 Get Sensor Definition (SENSOR_DEFINITION)
/// \cite RDM 10.7.1 Get Sensor Definition (SENSOR_DEFINITION)
/// This parameter is used to retrieve the definition of a specific sensor.
parameters_.try_emplace(SENSOR_DEFINITION, new Parameter());
parameters_.at(SENSOR_DEFINITION)->getAction(std::bind(
&Device::actionSensorDispatch,
this, std::placeholders::_1,
std::placeholders::_2));
/// 10.7.2 Get/Set Sensor (SENSOR_VALUE)
/// \cite RDM 10.7.2 Get/Set Sensor (SENSOR_VALUE)
/// This parameter shall be used to retrieve or reset sensor data.
parameters_.try_emplace(SENSOR_VALUE, new Parameter());
parameters_.at(SENSOR_VALUE)->getAction(std::bind(
@ -184,7 +184,7 @@ Device::Device(UID id, Device* parent)
&Device::actionSensorDispatch,
this, std::placeholders::_1,
std::placeholders::_2));
/// 10.7.3 Record Sensors (RECORD_SENSORS)
/// \cite RDM 10.7.3 Record Sensors (RECORD_SENSORS)
/// This parameter instructs devices such as dimming racks that monitor load
/// changes to store the current value for monitoring sensor changes.
parameters_.try_emplace(RECORD_SENSORS, new Parameter());
@ -192,7 +192,7 @@ Device::Device(UID id, Device* parent)
&Device::actionSensorDispatch,
this, std::placeholders::_1,
std::placeholders::_2));
/// 10.11.1 Get/Set Identify Device (IDENTIFY_DEVICE)
/// \cite RDM 10.11.1 Get/Set Identify Device (IDENTIFY_DEVICE)
/// This parameter is used for the user to physically identify the device
/// represented by the UID.
parameters_.try_emplace(IDENTIFY_DEVICE, new Parameter());
@ -204,7 +204,7 @@ Device::Device(UID id, Device* parent)
&Device::actionSetIdentifyDevice,
this, std::placeholders::_1,
std::placeholders::_2));
/// 10.11.2 Reset Device (RESET_DEVICE)
/// \cite RDM 10.11.2 Reset Device (RESET_DEVICE)
/// This parameter is used to instruct the responder to reset itself.
parameters_.try_emplace(RESET_DEVICE, new Parameter());
parameters_.at(RESET_DEVICE)->setAction(std::bind(
@ -339,7 +339,7 @@ void Device::reset(bool hard)
*/
void Device::enqueueMessage(MsgPtr message, bool urgent)
{
/// only root devices have a message queue
// only root devices have a message queue
if (parent_)
return;

124
protocols/rdm/message.cpp
View File

@ -77,34 +77,34 @@ void Message::read(const std::vector<uint8_t> &data)
return;
}
// 6.2.1 START Code
// This field shall contain the defined RDM START Code (SC_RDM). Controllers
// and Responders shall always send SC_RDM in this slot, and any packet
// containing a value other than SC_RDM is outside the scope of this standard.
/// \cite RDM 6.2.1 START Code
/// This field shall contain the defined RDM START Code (SC_RDM). Controllers
/// and Responders shall always send SC_RDM in this slot, and any packet
/// containing a value other than SC_RDM is outside the scope of this standard.
if (data[0] != SC_RDM)
{
incorrect_sc = true;
return;
}
// 6.2.2 Sub START Code
// This field shall contain the Sub-START Code within RDM that defines this
// packet structure (SC_SUB_MESSAGE). Future versions of this standard which
// may have additional or different packet structures would use this field to
// identify the packet structure being used.
// Controllers shall always send SC_SUB_MESSAGE in this slot, and Responders
// shall ignore any packets containing other values.
/// \cite RDM 6.2.2 Sub START Code
/// This field shall contain the Sub-START Code within RDM that defines this
/// packet structure (SC_SUB_MESSAGE). Future versions of this standard which
/// may have additional or different packet structures would use this field to
/// identify the packet structure being used.
/// Controllers shall always send SC_SUB_MESSAGE in this slot, and Responders
/// shall ignore any packets containing other values.
if (data[1] != SC_SUB_MESSAGE)
{
incorrect_sub_sc = true;
return;
}
// 6.2.3 Message Length
// The Message Length value is defined as the number of slots in the RDM
// Packet including the START Code and excluding the Checksum. Each slot is
// an 8-bit value.
// The Message Length field points to the Checksum High Slot.
/// \cite RDM 6.2.3 Message Length
/// The Message Length value is defined as the number of slots in the RDM
/// Packet including the START Code and excluding the Checksum. Each slot is
/// an 8-bit value.
/// The Message Length field points to the Checksum High Slot.
uint8_t length = data[2];
if (length + 2 != data.size())
{
@ -112,75 +112,75 @@ void Message::read(const std::vector<uint8_t> &data)
return;
}
// 6.2.4 Destination UID
// The Destination UID is the UID of the target device(s).
/// \cite RDM 6.2.4 Destination UID
/// The Destination UID is the UID of the target device(s).
destination.manufacturer = readType<uint16_t>(data, 3);
destination.device = readType<uint32_t>(data, 5);
// 6.2.5 Source UID
// The Source UID is the UID of the device originating this packet.
/// \cite RDM 6.2.5 Source UID
/// The Source UID is the UID of the device originating this packet.
source.manufacturer = readType<uint16_t>(data, 9);
source.device = readType<uint32_t>(data, 11);
// 6.2.6 Transaction Number (TN)
// Controller generated packets increment this field every time an RDM packet
// is transmitted.
// Responders shall reply with their Transaction Number set to the Transaction
// Number contained in the controller packet to which they are responding.
/// \cite RDM 6.2.6 Transaction Number (TN)
/// Controller generated packets increment this field every time an RDM packet
/// is transmitted.
/// Responders shall reply with their Transaction Number set to the Transaction
/// Number contained in the controller packet to which they are responding.
transaction = data[15];
// 6.2.7 Port ID / Response Type
// This field serves different functions depending on whether the message is
// being generated by the controller or the responder.
/// \cite RDM 6.2.7 Port ID / Response Type
/// This field serves different functions depending on whether the message is
/// being generated by the controller or the responder.
portID = data[16];
// 6.2.8 Message Count
// The message count field is used by a responder to indicate that additional
// data is now available for collection by a controller. This data (which
// might be unrelated to the current message transaction) should be collected
// by the controller using the GET:QUEUED_MESSAGE command.
/// \cite RDM 6.2.8 Message Count
/// The message count field is used by a responder to indicate that additional
/// data is now available for collection by a controller. This data (which
/// might be unrelated to the current message transaction) should be collected
/// by the controller using the GET:QUEUED_MESSAGE command.
messageCount = data[17];
// 6.2.9 Sub-Device Field
// Sub-devices should be used in devices containing a repetitive number of
// similar modules, such as a dimmer rack. The Sub-Device field allows
// Parameter messages to be addressed to a specific module within the device
// to set or get properties of that module.
// The 16-bit sub-device field provides a range of 512 valid sub-devices,
// addressed from 1 - 512.
// The value of 0xFFFF is reserved as a SUB_DEVICE_ALL_CALL. A value of 0x0000
// shall be used to address the root or base properties of the device that do
// not belong to any sub-device module.
// The Parameter ID designates which parameter on the sub-device is being
// addressed. The use of Sub-Devices is described further in Section 9.
/// \cite RDM 6.2.9 Sub-Device Field
/// Sub-devices should be used in devices containing a repetitive number of
/// similar modules, such as a dimmer rack. The Sub-Device field allows
/// Parameter messages to be addressed to a specific module within the device
/// to set or get properties of that module.
/// The 16-bit sub-device field provides a range of 512 valid sub-devices,
/// addressed from 1 - 512.
/// The value of 0xFFFF is reserved as a SUB_DEVICE_ALL_CALL. A value of 0x0000
/// shall be used to address the root or base properties of the device that do
/// not belong to any sub-device module.
/// The Parameter ID designates which parameter on the sub-device is being
/// addressed. The use of Sub-Devices is described further in Section 9.
subDevice = readType<uint16_t>(data, 18);
// 6.2.10.1 Command Class (CC)
/// \cite RDM 6.2.10.1 Command Class (CC)
commandClass = data[20];
// 6.2.10.2 Parameter ID (PID)
// The Parameter ID is a 16-bit number that identifies a specific type of
// Parameter Data. The Parameter ID (PID) may represent either a well known
// Parameter such as those defined in this document, or a
// Manufacturer-specific parameter whose details are either published by the
// Manufacturer for third-party support or proprietary for the Manufacturer’s
// own use.
/// \cite RDM 6.2.10.2 Parameter ID (PID)
/// The Parameter ID is a 16-bit number that identifies a specific type of
/// Parameter Data. The Parameter ID (PID) may represent either a well known
/// Parameter such as those defined in this document, or a
/// Manufacturer-specific parameter whose details are either published by the
/// Manufacturer for third-party support or proprietary for the Manufacturer’s
/// own use.
parameterId = readType<uint16_t>(data, 21);
// 6.2.10.3 Parameter Data Length (PDL)
// The Parameter Data Length (PDL) is the number of slots included in the
// Parameter Data area that it precedes. When this field is set to 0x00 it
// indicates that there is no Parameter Data following.
/// \cite RDM 6.2.10.3 Parameter Data Length (PDL)
/// The Parameter Data Length (PDL) is the number of slots included in the
/// Parameter Data area that it precedes. When this field is set to 0x00 it
/// indicates that there is no Parameter Data following.
uint8_t pdl = data[23];
// 6.2.10.4 Parameter Data (PD)
// The Parameter Data is of variable length.
/// \cite RDM 6.2.10.4 Parameter Data (PD)
/// The Parameter Data is of variable length.
for (int i = 0; i < pdl; i++)
appendData(data[24+i]);
// 6.2.11 Checksum
// If the checksum field in the packet does not match the calculated checksum,
// then the packet shall be discarded and no response sent.
/// \cite RDM 6.2.11 Checksum
/// If the checksum field in the packet does not match the calculated checksum,
/// then the packet shall be discarded and no response sent.
auto chksum = readType<uint16_t>(data, data.size() - 2);
if (chksum != checksum())
{

2
protocols/rdm/rdm.h
View File

@ -34,7 +34,7 @@ namespace RDM {
using PID = uint16_t; //!< Parameter Identification number
/// 10.5.1 Get Device Info (DEVICE_INFO)
/// \cite RDM 10.5.1 Get Device Info (DEVICE_INFO)
/// RDM Protocol Version:
/// The version of this standard is 1.0
static const uint16_t RDM_PROTOCOL_VERSION = 0x0100;

36
protocols/rdm/responder.cpp
View File

@ -41,13 +41,13 @@ Responder::Responder(UID id, Device* parent)
deviceModelDescription = "Basic RDM Responder";
subdevice_flag = true;
/// 7.5 Discovery Unique Branch Message (DISC_UNIQUE_BRANCH)
/// \cite RDM 7.5 Discovery Unique Branch Message (DISC_UNIQUE_BRANCH)
parameters_.try_emplace(DISC_UNIQUE_BRANCH, new Parameter());
parameters_.at(DISC_UNIQUE_BRANCH)->discAction(std::bind(
&Responder::actionDiscoverUniqueBranch,
this, std::placeholders::_1,
std::placeholders::_2));
/// 7.6.3 Discovery Mute Message (DISC_MUTE)
/// \cite RDM 7.6.3 Discovery Mute Message (DISC_MUTE)
/// A responder port shall set its Mute flag when it receives this message
/// containing its UID, or a broadcast address.
parameters_.try_emplace(DISC_MUTE, new Parameter());
@ -55,7 +55,7 @@ Responder::Responder(UID id, Device* parent)
&Responder::actionDiscoveryMute,
this, std::placeholders::_1,
std::placeholders::_2));
/// 7.6.4 Discovery Un-Mute Message (DISC_UN_MUTE)
/// \cite RDM 7.6.4 Discovery Un-Mute Message (DISC_UN_MUTE)
/// A responder port shall clear its Mute flag when it receives this message
/// containing its UID, or a broadcast address.
parameters_.try_emplace(DISC_UN_MUTE, new Parameter());
@ -63,7 +63,7 @@ Responder::Responder(UID id, Device* parent)
&Responder::actionDiscoveryUnmute,
this, std::placeholders::_1,
std::placeholders::_2));
/// 10.2.1 Communication Status (COMMS_STATUS)
/// \cite RDM 10.2.1 Communication Status (COMMS_STATUS)
/// The COMMS_STATUS parameter is used to collect information that may be
/// useful in analyzing the integrity of the communication system.
parameters_.try_emplace(COMMS_STATUS, new Parameter());
@ -75,7 +75,7 @@ Responder::Responder(UID id, Device* parent)
&Responder::actionSetCommsStatus,
this, std::placeholders::_1,
std::placeholders::_2));
/// 10.3.1 Get Queued Message (QUEUED_MESSAGE)
/// \cite RDM 10.3.1 Get Queued Message (QUEUED_MESSAGE)
/// The QUEUED_MESSAGE parameter shall be used to retrieve a message from the
/// responder’s message queue. The Message Count field of all response
/// messages defines the number of messages that are queued in the responder.
@ -85,7 +85,7 @@ Responder::Responder(UID id, Device* parent)
&Responder::actionGetQueuedMessage,
this, std::placeholders::_1,
std::placeholders::_2));
/// 10.3.2 Get Status Messages (STATUS_MESSAGES)
/// \cite RDM 10.3.2 Get Status Messages (STATUS_MESSAGES)
/// This parameter is used to collect Status or Error information
/// from a device.
parameters_.try_emplace(STATUS_MESSAGES, new Parameter());
@ -93,7 +93,7 @@ Responder::Responder(UID id, Device* parent)
&Responder::actionGetStatusMessages,
this, std::placeholders::_1,
std::placeholders::_2));
/// 10.3.3 Get Status ID Description (STATUS_ID_DESCRIPTION)
/// \cite RDM 10.3.3 Get Status ID Description (STATUS_ID_DESCRIPTION)
/// This parameter is used to request an ASCII text description of a given
/// Status ID. The description may be up to 32 characters.
parameters_.try_emplace(STATUS_ID_DESCRIPTION, new Parameter());
@ -134,10 +134,10 @@ void Responder::send(MsgPtr response)
if (response->do_not_send)
return;
// 6.2.8.2 Message Count field for Responder Generated Messages
// If a responder has more than 255 messages queued, then the Message Count
// field shall remain at 255 until the number of queued messages is reduced
// below that number.
/// \cite RDM 6.2.8.2 Message Count field for Responder Generated Messages
/// If a responder has more than 255 messages queued, then the Message Count
/// field shall remain at 255 until the number of queued messages is reduced
/// below that number.
response->messageCount = std::min(queued_messages_.size(),
(size_t)std::numeric_limits<uint8_t>::max());
std::vector<uint8_t> data;
@ -207,7 +207,7 @@ void Responder::receive(const MsgPtr message)
response->parameterId = message->parameterId;
response->transaction = message->transaction;
/// 5.3 Broadcast Message Addressing
/// \cite RDM 5.3 Broadcast Message Addressing
/// When Broadcast Addressing is used for non-Discovery messages, the
/// responders shall not send a response.
if (message->destination.isBroadcast() &&
@ -249,7 +249,7 @@ void Responder::reset(bool hard)
{
(void)hard;
/// 10.11.2 Reset Device (RESET_DEVICE)
/// \cite RDM 10.11.2 Reset Device (RESET_DEVICE)
/// This parameter shall also clear the Discovery Mute flag.
discovery_mute_flag_ = false;
}
@ -282,11 +282,11 @@ void Responder::rxDiscovery(const MsgPtr message, MsgPtr response)
*/
void Responder::rxGet(const MsgPtr message, MsgPtr response)
{
// 9.2.2 Using Sub-Devices
// Broadcast GET commands sent to the SUB_DEVICE_ALL_CALL Sub-Device ID are
// not allowed. Any responder receiving a GET command sent to this Sub-Device
// ID shall respond with a NACK with a NACK Reason Code of
// NR_SUB_DEVICE_OUT_OF_RANGE.
/// \cite RDM 9.2.2 Using Sub-Devices
/// Broadcast GET commands sent to the SUB_DEVICE_ALL_CALL Sub-Device ID are
/// not allowed. Any responder receiving a GET command sent to this Sub-Device
/// ID shall respond with a NACK with a NACK Reason Code of
/// NR_SUB_DEVICE_OUT_OF_RANGE.
if (message->subDevice == SUB_DEVICE_ALL_CALL)
{
response->nak(NR_SUB_DEVICE_OUT_OF_RANGE);