official
/
OpenLCP
1
0
Fork 0
Code Releases 1 Activity

Documentation improvement and cleanup

This commit is contained in:
Kevin Matz 2022-11-15 11:32:29 -05:00
parent 248aca3f70
commit bca742c37f
16 changed files with 89 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
protocol/acn/component.h
View File

@ -27,20 +27,29 @@
#include <string>
/**
* @brief @cite ACN Architecture for Control Networks
*/
namespace ACN {
/**
* @brief The Component class
* The process, program or application corresponding to a single ACN endpoint.
* All messages in ACN are sent and received by a component.
* @brief The process, program or application corresponding to a single ACN endpoint.
*
* See [Arch] for a more complete definition.
* All messages in ACN are sent and received by a component.
* See @cite ACN [Arch] for a more complete definition.
*
* @cite epi19 **EPI 19: ACN Discovery on IP Networks**
*
* (3) Component Name Strings
* Each component shall maintain two text identifier strings intended to
* indicate the function of the component in human readable terms for
* browsing purposes.
*/
class Component {
public:
/**
* @brief Component
* @param cid
* @param cid the Component Identifier
*/
Component(UUID::uuid cid = UUID::uuid())
: fctn_(std::string("OpenLCP ACN Component"))
@ -49,51 +58,46 @@ public:
{};
/**
* @brief cid
* @return
* @brief Component Identifier
* @return the CID
*
* @cite ACN 1.2.3: In ACN each distinct endpoint transmitting and receiving ACN data is called a
* Component and all ACN communications take place between components. Each ACN component has a
* component identifier or CID which is unique not just within the system but across the whole
* world and does not change with time.
*/
const UUID::uuid cid() const { return cid_; }
/**
* @brief fixedName fixed component name
* @return
* @brief @cite epi19 3.1 Fixed Component Type Name (FCTN)
* @return the FCTN
*
* Shall be a UTF-8 string that is assigned during manufacture.
*/
const std::string fixedName() const { return fctn_; }
/**
* @brief userName user-asigned name
* @return
* @brief @cite epi19 3.2 User Assigned Component Name (UACN)
* @return the UACN
*
* Shall be a UTF-8 string that may be assigned by the user.
*/
const std::string userName() const { return uacn_; }
/**
* @brief component name, either user asigned or fixed.
* @return
* @brief Component Name, either User Asigned or Fixed.
* @return a name
*/
const std::string name() const { return uacn_.empty() ? fctn_ : uacn_; }
/**
* @brief set the user asigned name
* @param s
* @brief Set the User Asigned Component Name (UACN).
* @param s UACN Name string
*
* If not an empty string, will be prefered over the FCTN.
*/
void assignUserName(const std::string s) { uacn_ = s; }
protected:
/**
* EPI 19: ACN Discovery on IP Networks
* 3. Component Name Strings
* Each component shall maintain two text identifier strings intended to
* indicate the function of the component in human readable terms for
* browsing purposes.
*/
/**
* @brief 3.1. Fixed Component Type Name (FCTN)
* shall be a UTF-8 string that is assigned during manufacture.
*/
std::string fctn_;
/**
* @brief 3.2. User Assigned Component Name (UACN)
* shall be a UTF-8 string that may be assigned by the user.
*/
std::string uacn_;
std::string fctn_; //!< Fixed Component Type Name (FCTN)
std::string uacn_; //!< User Assigned Component Name (UACN)
private:
const UUID::uuid cid_;

7
protocol/acn/pdu-stream.h
View File

@ -30,7 +30,7 @@
namespace ACN::PDU {
struct pdu_stream_object;
struct pdu_stream_object; // forward declare
/**
* @brief Input/Output stream of nested PDU
@ -118,11 +118,14 @@ public:
};
/**
* @brief A shared pointer to pdu_stream.
*/
using Stream = std::shared_ptr<pdu_stream>;
/**
* @brief The pdu_stream_object struct
* @brief The inheritable base of data objects that can be read from and written to a pdu_stream.
*/
struct pdu_stream_object
{

10
protocol/acn/pdu.h
View File

@ -28,6 +28,14 @@
#include <vector>
#include "pdu-stream.h"
/**
* @brief @cite ACN 1.2.8.1 Common Packet Format
*
* In developing SDT and DMP it was recognized that the messages in both protocols have many
* similarities and that by using a common message format across all the ACN protocols, the code to
* recognize and decode messages can be shared across different message types. This is why ACN
* defines a common message format the Protocol Data Unit or PDU.
*/
namespace ACN::PDU {
class Pdu; // forward declare
@ -111,7 +119,7 @@ struct Block
/**
* @brief 2.4.1. Flags
* @brief @cite ACN 2.4.1 Flags
*
* Flags is a 4-bit field containing flags L, V, H and D which declare how
* the PDU is packed.

4
protocol/dmp/dmp.h
View File

@ -28,7 +28,9 @@
#include <vector>
#include "acn/pdu.h"
// Architecture for Control Networks – Device Management Protocol
/**
* @brief @cite DMP Architecture for Control Networks – Device Management Protocol
*/
namespace ACN::DMP {
/**

3
protocol/dmx/dmx.h
View File

@ -25,6 +25,9 @@
#include <cstdint>
/**
* @brief @cite DMX The Digital Multiplex Protocol
*/
namespace DMX {
/// \cite DMX

4
protocol/dmx/universe.h
View File

@ -36,8 +36,8 @@
namespace DMX {
class Universe; // forward declare the Univserse class
using DimmerData = std::array<uint8_t, E111_LAST_SLOT + 1>;
using DataHandler = std::function<void(Universe *)>;
using DimmerData = std::array<uint8_t, E111_LAST_SLOT + 1>; //!< Array of 513 bytes for basic data.
using DataHandler = std::function<void(Universe *)>; //!< Callback function for data handling.
/**
* @brief The Universe class

3
protocol/otp/otp.h
View File

@ -25,6 +25,9 @@
#include <cstdint>
/**
* @brief @cite OTP The Object Transform Protocol
*/
namespace OTP {
static const uint8_t OTP_PACKET_IDENTIFIER[] = { 0x4f, 0x54, 0x50, 0x2d,
0x45, 0x31, 0x2e, 0x35,

3
protocol/rdm/E1.37-1.h
View File

@ -26,7 +26,8 @@
#include <cstdint>
/**
* @brief ANSI E1.37-1 – 2012 (R2017)
* \ingroup RDM
* \details ANSI E1.37-1 – 2012 (R2017)
* Additional Message Sets for ANSI E1.20 (RDM) – Part 1,
* Dimmer Message Sets
*/

3
protocol/rdm/E1.37-2.h
View File

@ -26,7 +26,8 @@
#include <cstdint>
/**
* @brief ANSI E1.37-2 – 2015 Entertainment Technology
* \ingroup RDM
* \details ANSI E1.37-2 – 2015 Entertainment Technology
* Additional Message Sets for ANSI E1.20 (RDM) – Part 2,
* IPv4 & DNS Configuration Messages
*/

3
protocol/rdm/E1.37-7.h
View File

@ -26,7 +26,8 @@
#include <cstdint>
/**
* @brief ANSI E1.37-7
* \ingroup RDM
* \details ANSI E1.37-7
* Additional Message Sets for ANSI E1.20 (RDM) -
* Gateway & Splitter Configuration Messages
*/

3
protocol/rdm/rdm.h
View File

@ -30,6 +30,9 @@
#include <string>
/**
* @brief \cite RDM The Remote Device Management Protocol
*/
namespace RDM {
using PID = uint16_t; //!< Parameter Identification number

3
protocol/rdmnet/rdmnet.h
View File

@ -25,6 +25,9 @@
#include "rdm/rdm.h"
/**
* @brief @cite RDMnet The RDMnet Protocol
*/
namespace RDMnet {
using RDM::PID;

7
protocol/rlp/rlp.h
View File

@ -28,6 +28,13 @@
#include "acn/pdu.h"
#include "uuid/uuid.h"
/**
* @brief @cite ACN 2.3.2 The Root Layer Protocol
*
* The lowest ACN layer above the underlying transport (e.g. the contents of a UDP packet) is
* handled by the ACN Root Layer Protocol. The Root Layer protocol may be tailored to fit higher
* ACN protocols onto each individual transport.
*/
namespace ACN::RLP {
/**

6
protocol/sdt/sdt.h
View File

@ -26,8 +26,10 @@
#include "acn/pdu.h"
#include "udp.h" // EPI 18
// ANSI E1.17- 2015, Architecture for Control Networks–
// Session Data Transport Protocol
/**
* @brief @cite SDT ANSI E1.17- 2015, Architecture for Control Networks–
* Session Data Transport Protocol
*/
namespace ACN::SDT {
/**

2
protocol/sdt/udp.h
View File

@ -23,7 +23,7 @@
*/
#pragma once
#include "acn/pdu.h"
#include "acn/pdu-stream.h"
#include <cstdint>
// ACN EPI 18 - Operation of SDT on UDP Networks

4
protocol/uuid/uuid.h
View File

@ -30,9 +30,9 @@
#define UUID_LENGTH 16
/**
* @brief RFC4122 A Universally Unique IDentifier (UUID) URN Namespace
* @brief \cite uuid RFC4122 A Universally Unique IDentifier (UUID) URN Namespace
*
* > \cite uuid This specification defines a Uniform Resource Name namespace
* > This specification defines a Uniform Resource Name namespace
* > for UUIDs (Universally Unique IDentifier), also known as GUIDs (Globally
* > Unique IDentifier). A UUID is 128 bits long, and can guarantee uniqueness
* > across space and time. UUIDs were originally used in the Apollo Network