From 0df27b07164d4e4c69b39b3617151596b2009563 Mon Sep 17 00:00:00 2001 From: Peter M. Groen Date: Mon, 6 Jun 2022 11:51:25 +0200 Subject: [PATCH] Added doxygen comments --- CMakeLists.txt | 2 +- src/ConnectionConfig.h | 66 ++++++++++++++++++++++++++++++++++++++++++------------------------ src/IModbusAdapter.h | 58 +++++++++++++++++++++++++++++++++++----------------------- src/ModbusAdapter.h | 57 ++++++++++++++++++++++++++++++++------------------------- src/ModbusConnections.h | 74 ++++++++++++++++++++++++++++++++++++++++---------------------------------- 5 files changed, 150 insertions(+), 107 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 440621b..eb83997 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,4 +1,4 @@ -cmake_minimum_required(VERSION 3.2) +cmake_minimum_required(VERSION 3.10) project(modbus) set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++17") diff --git a/src/ConnectionConfig.h b/src/ConnectionConfig.h index c261fc3..a2ffca6 100644 --- a/src/ConnectionConfig.h +++ b/src/ConnectionConfig.h @@ -1,10 +1,16 @@ +/**************************************************************************** + * Copyright (c) 2022 Priva b.v. + ****************************************************************************/ #pragma once #include #include /*! - * \brief The ConnectionPort enum + * \brief The ConnectionPort enum. + * CP_EXTERNAL - the first serial port + * CP_IOBUS - The second serial port through RJ45 connector + * CP_TCP - TCP Connections */ enum class ConnectionPort : unsigned int { @@ -14,7 +20,8 @@ enum class ConnectionPort : unsigned int }; /*! - * \brief The Parity enum + * \brief The Parity enum. + * Used in a serial port context */ enum class Parity : unsigned int { @@ -24,7 +31,8 @@ enum class Parity : unsigned int }; /*! - * \brief The ConnectionType enum + * \brief The ConnectionType enum. + * Added for convenience, to distinguish between types. */ enum class ConnectionType : unsigned int { @@ -33,17 +41,25 @@ enum class ConnectionType : unsigned int CT_UNKNOWN }; +/*! + * \brief The ConnectionConfig class holds all the information we need to establish a proper connection. + * It can be created by a configuration object and passed on to the ModBus stack. + * By using this class, all the connectioninfo is within its context for convenience. + * + * Data can be accessed by their resp. getter-methods to avoid internal data-exposure + * according to the basic principles of object oriented programming. ( Abstraction, Encapsulation, Inheritance, and Polymorphism ) + */ class ConnectionConfig { public: /*! - * \brief ConnectionConfig - * \param port - * \param baud - * \param parity - * \param dataBits - * \param stopBits - * \param timeOut + * \brief ConnectionConfig Constructor. Used to create a new serial connection. + * \param port - The portname given by its enum. + * \param baud - The port speed in a serial port context ( default = 115200 ) + * \param parity - The parity. ( Default : None, no parity ) + * \param dataBits - The number of databits. RTU uses 8 (0 - 255), ASCII uses 7 (0 - 127). Default is RTU + * \param stopBits - The number of stopbits used to detect the end of the frame. ( Default = 1 ) + * \param timeOut - Timeout in .1 secs. See the termios documentation for deviations on this. */ ConnectionConfig( ConnectionPort port, int baud = 115200, Parity parity = Parity::PAR_NONE, int dataBits = 8, int stopBits = 1, int timeOut = -1 ) : m_port( port ) @@ -58,11 +74,11 @@ public: {} /*! - * \brief ConnectionConfig - * \param port - * \param ip - * \param portnum - * \param timeOut + * \brief ConnectionConfig Constructor. Used to create a new TCP connection. + * \param port - The portname given by its enaum. ( Should be CP_TCP ) + * \param ip - The ip address of the ModBus device we want to connect to. + * \param portnum - The portnumber the ModBus device is using + * \param timeOut - Timeout in which a modbus device should respond. */ ConnectionConfig( ConnectionPort port, const std::string &ip, int portnum, int timeOut = -1 ) : m_port( port ) @@ -81,6 +97,7 @@ public: ConnectionPort getPortEnum() const { return m_port; } ///< Get the portname Enum int getBaudRate() const { return m_baudRate; } ///< Get the given baudrate as int. char getParity() const { return m_parityMap.at(m_parity); } ///< Get the translated parity. + Parity getParityEnum() const { return m_parity; } ///< Get the parity Enum int getDataBits() const { return m_dataBits; } ///< Get the number of databits ( 7 for ASCII, 8 for RTU ) int getStopBits() const { return m_stopBits; } ///< Get the number of stopBits. ( de-facto = 1 ) @@ -93,20 +110,21 @@ public: private: /// Serial connections - ConnectionPort m_port; - int m_baudRate; - Parity m_parity; - int m_dataBits; - int m_stopBits; + ConnectionPort m_port; ///< Member variable holding the portName Enum + int m_baudRate; ///< Member variable holding the Serial port Baudrate + Parity m_parity; ///< Member variable holding the Serial port Parity + int m_dataBits; ///< Member variable holding the number of databits + int m_stopBits; ///< Member variable holding the number of stopbits /// TCP connections - std::string m_ipaddress; - int m_portnumber; + std::string m_ipaddress; ///< Member variable holding the ip-address of the TCP-connection + int m_portnumber; ///< Member variable holding the portnumber of the TCP-connection /// Generic - int m_timeOut; - ConnectionType m_conType; + int m_timeOut; ///< Member variable holding the timeOut value + ConnectionType m_conType; ///< Member variable holding the connection type. + /// Translation tables for portnames and parity. // ============================================================ // == Change accordingly to the devicenames on your platform == // ============================================================ diff --git a/src/IModbusAdapter.h b/src/IModbusAdapter.h index e546bf2..b496cf0 100644 --- a/src/IModbusAdapter.h +++ b/src/IModbusAdapter.h @@ -15,58 +15,70 @@ using modbusData = std::vector>; class ConnectionConfig; /*! - * \brief The IModbusAdapter class + * \brief The IModbusAdapter class provides an abstract way of using + * the modbus stack. Implemented as a pure virtual, it cannot be instantiated. + * This represents a unique connection to either a serial bus or a TCP connection. */ class IModbusAdapter { public: - virtual ~IModbusAdapter() {} + /// Default DTor. + virtual ~IModbusAdapter() = default; + /// Create a modbus connection, accepting a configuration object. virtual bool ModbusConnect( const ConnectionConfig &conncfg ) = 0; /*! - * \brief ModbusDisconnect + * \brief ModbusDisconnect + * Disconnect from the serial bus or the TCP connection, freeing its resources */ virtual bool ModbusDisconnect() = 0; /*! - * \brief ModbusReadData - * \param slaveId - * \param startAddress - * \param noOfItems + * \brief Read data from a modbus device given by its parameters. + * \param slaveId - The Id of the ModbusDevice. + * \param functionCode - The code describing the action we want to perform on the device. + * Given by an enum, provided by the modbus-stack. + * \param startAddress - Startaddres of the register we want to read. + * \param noOfItems - The number of items we expect back. + * \returns modbusData - A vector holding each register in an entry in the same order as they are received. + * Empty if no data was received. */ virtual modbusData ModbusReadData( int slaveId, int functionCode, int startAddress, int noOfItems ) = 0; /*! - * \brief ModbusReadHoldReg - * \param slaveId - * \param startAddress - * \param noOfItems - * \return + * \brief Read data from the holdregisters ( or keep-registers ) of a modbus device. + * \param slaveId - The Id of the ModbusDevice. + * \param startAddress - Startaddres of the register we want to read. + * \param noOfItems - The number of items we expect back. + * \returns modbusData - A vector holding each register in an entry in the same order as they are received. + * Empty if no data was received. */ virtual modbusData ModbusReadHoldReg( int slaveId, int startAddress, int noOfItems ) = 0; /*! - * \brief ModBusWriteData - * \param slaveId - * \param funtionCode - * \param startAddress - * \param noOfItems - * \param values + * \brief Write data to the device. + * \param slaveId - The Id of the Modbus device + * \param funtionCode - The code describing the action we want to perform on the device + * given by an enum, provided by the modbus-stack. + * \param startAddress - Startaddres of the register we want to read. + * \param noOfItems - The number of items we expect to be written + * \param values - The values we want to write to the given device. Each vector-entry represents a single byte + * and they will be sent in sequence. */ virtual void ModBusWriteData( int slaveId, int functionCode, int startAddress, int noOfItems, std::vectorvalues ) = 0; /*! - * \brief isConnected - * \return + * \brief Indicates if this connection is alive. + * \return True if alive, false if not. */ virtual bool isConnected() const = 0; /*! - * \brief ErrorString - * \param errnum - * \return + * \brief returns the translated error code coming from the modbus stack. + * \param errnum - error Number coming from the stack. + * \return The translated error as a string. Empty if not resolvable. */ virtual std::string ErrorString( int errnum ) const = 0; }; diff --git a/src/ModbusAdapter.h b/src/ModbusAdapter.h index 9128e8f..4708f34 100644 --- a/src/ModbusAdapter.h +++ b/src/ModbusAdapter.h @@ -21,63 +21,70 @@ class ModbusAdapter : public IModbusAdapter { public: /*! - * \brief ModbusAdapter + * \brief Default constructor */ explicit ModbusAdapter(); /*! - * \brief ~ModbusAdapter + * \brief Default destructor */ virtual ~ModbusAdapter(); /*! - * \brief ModbusConnect - * \param conncfg + * \brief /// Create a modbus connection, accepting a configuration object. */ bool ModbusConnect( const ConnectionConfig &conncfg ) override; /*! - * \brief ModbusDisconnect + * \brief ModbusDisconnect + * Disconnect from the serial bus or the TCP connection, freeing its resources */ bool ModbusDisconnect() override; /*! - * \brief ModbusReadData - * \param slaveId - * \param startAddress - * \param noOfItems + * \brief Read data from a modbus device given by its parameters. + * \param slaveId - The Id of the ModbusDevice. + * \param functionCode - The code describing the action we want to perform on the device. + * Given by an enum, provided by the modbus-stack. + * \param startAddress - Startaddres of the register we want to read. + * \param noOfItems - The number of items we expect back. + * \returns modbusData - A vector holding each register in an entry in the same order as they are received. + * Empty if no data was received. */ modbusData ModbusReadData( int slaveId, int functionCode, int startAddress, int noOfItems ) override; /*! - * \brief ModbusReadHoldReg - * \param slaveId - * \param startAddress - * \param noOfItems - * \return + * \brief Read data from the holdregisters ( or keep-registers ) of a modbus device. + * \param slaveId - The Id of the ModbusDevice. + * \param startAddress - Startaddres of the register we want to read. + * \param noOfItems - The number of items we expect back. + * \returns modbusData - A vector holding each register in an entry in the same order as they are received. + * Empty if no data was received. */ modbusData ModbusReadHoldReg( int slaveId, int startAddress, int noOfItems ) override; /*! - * \brief ModBusWriteData - * \param slaveId - * \param funtionCode - * \param startAddress - * \param noOfItems - * \param values + * \brief Write data to the device. + * \param slaveId - The Id of the Modbus device + * \param funtionCode - The code describing the action we want to perform on the device + * given by an enum, provided by the modbus-stack. + * \param startAddress - Startaddres of the register we want to read. + * \param noOfItems - The number of items we expect to be written + * \param values - The values we want to write to the given device. Each vector-entry represents a single byte + * and they will be sent in sequence. */ void ModBusWriteData( int slaveId, int functionCode, int startAddress, int noOfItems, std::vectorvalues ) override; /*! - * \brief isConnected - * \return + * \brief Indicates if this connection is alive. + * \return True if alive, false if not. */ bool isConnected() const override; /*! - * \brief ErrorString - * \param errnum - * \return + * \brief returns the translated error code coming from the modbus stack. + * \param errnum - error Number coming from the stack. + * \return The translated error as a string. Empty if not resolvable. */ std::string ErrorString( int errnum ) const override; diff --git a/src/ModbusConnections.h b/src/ModbusConnections.h index 171e4cb..46a7941 100644 --- a/src/ModbusConnections.h +++ b/src/ModbusConnections.h @@ -13,91 +13,97 @@ #include #include -/// +/// Easy replacement of template construction using AdapterList = std::vector>; /*! - * \brief The ModbusConnections class + * \brief The ModbusConnections class conatins a list of all modbus connections, Serial and TCP. + * To access a specific connection, use its portname and / or endpoint to return it's interface. */ class ModbusConnections { public: /*! - * \brief ModbusConnections + * \brief Default CTor */ explicit ModbusConnections(); /*! - * \brief ~ModbusConnections + * \brief Default DTor */ virtual ~ModbusConnections(); /*! - * \brief CreateConnection - * \param config - * \return + * \brief Create a modbus connection as described by the connection object. + * \param config - The connection object describing the connection in detail. + * \return The result of the creation. + * True = succesful. + * False = Failed. */ bool CreateConnection( const ConnectionConfig &config ); /*! - * \brief DeleteConnection - * \param portName - * \param endpoint + * \brief Remove the connection described by its portname and/or endpoint. + * \param portName - The portname as its enum + * \param endpoint - combination of ip-address and portname in endpoint-format + * ( tcp://: ) + * ( i.e. tcp://127.0.0.1:501 ) * \return */ bool DeleteConnection( const ConnectionPort portName, const std::string &endpoint = std::string() ); /*! - * \brief ConnectionCount - * \return + * \brief Give the number of registered serial and tcp-connections combined. */ int ConnectionCount(); /*! - * \brief getConnection - * \param portName - * \param endpoint - * \return + * \brief Get the connection give by its parameters. + * \param portName - The portname by its enum + * \param endpoint - combination of ip-address and portname in endpoint-format + * ( tcp://: ) + * ( i.e. tcp://127.0.0.1:501 ) + * \return Valid Pointer to the Modbus Connection Interface. nullptr if the connection wasn't found. */ std::shared_ptr getConnection( const ConnectionPort portName, const std::string &endpoint = std::string() ); // Convenient functions /*! - * \brief getConnection - * \param portName - * \param ipAddress - * \param tcpPortNumber - * \return + * \brief Get the connection given by its parameters. If applicable, ipaddress and portnumber will be used to create the endpoint. + * \param portName - The portname by its enum + * \param ipAddress - The ipaddress of the TCP-connection + * \param tcpPortNumber - The portnumber of the TCP-connection + * \return Valid Pointer to the Modbus Connection Interface. nullptr if the connection wasn't found. */ std::shared_ptr getConnection( const ConnectionPort portName, const std::string &ipAddress, int tcpPortNumber ); /*! - * \brief getConnections - * \return + * \brief Returns a list of all registered connections by their interfaces. This is a mix of Serial and TCP-connections. */ AdapterList getConnections(); private: /*! - * \brief connectionExist - * \param portName - * \param endpoint - * \return + * \brief Check if a connection already exist. + * \param portName - The portName by its enum + * \param endpoint - The endpoint this connection was registered with. + * \return A valid pointer to the Interface if the connection exist. If the connection is unknown, it will return a nullptr. + * shared_ptr can manifest themselves as booleans, so "!ptr" is sufficient to check. */ std::shared_ptr connectionExist( const ConnectionPort portName, const std::string &endpoint = std::string() ); /*! - * \brief createEndPoint - * \param ipAddress - * \param portNumber - * \return + * \brief Create the TCP endpoint based on the connections IP-address and portnumber + * \param ipAddress - The ipAddress as string. + * \param portNumber - The portnumber as integer. + * \return The endpoint in format : tcp://: i.e. tcp://127.0.0.1:501 */ std::string createEndPoint( const std::string &ipAddress, int portNumber ); /*! - * \brief createEndPoint - * \param config - * \return + * \brief Create the TCP endpoint based on the connections IP-address and portnumber extracted from the connection configuration. + * \param config - The configuration object used to create the connection. + * \return The endpoint in format : tcp://: i.e. tcp://127.0.0.1:501 */ std::string createEndPoint( const ConnectionConfig &config ); -- libgit2 0.21.4