open_source / modbus

Commit 0df27b07164d4e4c69b39b3617151596b2009563

Authored by Peter M. Groen
1 parent 91724967

Added doxygen comments

Inline Side-by-side
Showing 5 changed files with 150 additions and 107 deletions
CMakeLists.txt
  View file @0df27b0
1   -cmake_minimum_required(VERSION 3.2)
  1 +cmake_minimum_required(VERSION 3.10)
2 2 project(modbus)
3 3  
4 4 set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++17")
... ...
src/ConnectionConfig.h
  View file @0df27b0
  1 +/****************************************************************************
  2 + * Copyright (c) 2022 Priva b.v.
  3 + ****************************************************************************/
1 4 #pragma once
2 5  
3 6 #include <string>
4 7 #include <unordered_map>
5 8  
6 9 /*!
7   - * \brief The ConnectionPort enum
  10 + * \brief The ConnectionPort enum.
  11 + * CP_EXTERNAL - the first serial port
  12 + * CP_IOBUS - The second serial port through RJ45 connector
  13 + * CP_TCP - TCP Connections
8 14 */
9 15 enum class ConnectionPort : unsigned int
10 16 {
... ... @@ -14,7 +20,8 @@ enum class ConnectionPort : unsigned int
14 20 };
15 21  
16 22 /*!
17   - * \brief The Parity enum
  23 + * \brief The Parity enum.
  24 + * Used in a serial port context
18 25 */
19 26 enum class Parity : unsigned int
20 27 {
... ... @@ -24,7 +31,8 @@ enum class Parity : unsigned int
24 31 };
25 32  
26 33 /*!
27   - * \brief The ConnectionType enum
  34 + * \brief The ConnectionType enum.
  35 + * Added for convenience, to distinguish between types.
28 36 */
29 37 enum class ConnectionType : unsigned int
30 38 {
... ... @@ -33,17 +41,25 @@ enum class ConnectionType : unsigned int
33 41 CT_UNKNOWN
34 42 };
35 43  
  44 +/*!
  45 + * \brief The ConnectionConfig class holds all the information we need to establish a proper connection.
  46 + * It can be created by a configuration object and passed on to the ModBus stack.
  47 + * By using this class, all the connectioninfo is within its context for convenience.
  48 + *
  49 + * Data can be accessed by their resp. getter-methods to avoid internal data-exposure
  50 + * according to the basic principles of object oriented programming. ( Abstraction, Encapsulation, Inheritance, and Polymorphism )
  51 + */
36 52 class ConnectionConfig
37 53 {
38 54 public:
39 55 /*!
40   - * \brief ConnectionConfig
41   - * \param port
42   - * \param baud
43   - * \param parity
44   - * \param dataBits
45   - * \param stopBits
46   - * \param timeOut
  56 + * \brief ConnectionConfig Constructor. Used to create a new serial connection.
  57 + * \param port - The portname given by its enum.
  58 + * \param baud - The port speed in a serial port context ( default = 115200 )
  59 + * \param parity - The parity. ( Default : None, no parity )
  60 + * \param dataBits - The number of databits. RTU uses 8 (0 - 255), ASCII uses 7 (0 - 127). Default is RTU
  61 + * \param stopBits - The number of stopbits used to detect the end of the frame. ( Default = 1 )
  62 + * \param timeOut - Timeout in .1 secs. See the termios documentation for deviations on this.
47 63 */
48 64 ConnectionConfig( ConnectionPort port, int baud = 115200, Parity parity = Parity::PAR_NONE, int dataBits = 8, int stopBits = 1, int timeOut = -1 )
49 65 : m_port( port )
... ... @@ -58,11 +74,11 @@ public:
58 74 {}
59 75  
60 76 /*!
61   - * \brief ConnectionConfig
62   - * \param port
63   - * \param ip
64   - * \param portnum
65   - * \param timeOut
  77 + * \brief ConnectionConfig Constructor. Used to create a new TCP connection.
  78 + * \param port - The portname given by its enaum. ( Should be CP_TCP )
  79 + * \param ip - The ip address of the ModBus device we want to connect to.
  80 + * \param portnum - The portnumber the ModBus device is using
  81 + * \param timeOut - Timeout in which a modbus device should respond.
66 82 */
67 83 ConnectionConfig( ConnectionPort port, const std::string &ip, int portnum, int timeOut = -1 )
68 84 : m_port( port )
... ... @@ -81,6 +97,7 @@ public:
81 97 ConnectionPort getPortEnum() const { return m_port; } ///< Get the portname Enum
82 98 int getBaudRate() const { return m_baudRate; } ///< Get the given baudrate as int.
83 99 char getParity() const { return m_parityMap.at(m_parity); } ///< Get the translated parity.
  100 + Parity getParityEnum() const { return m_parity; } ///< Get the parity Enum
84 101 int getDataBits() const { return m_dataBits; } ///< Get the number of databits ( 7 for ASCII, 8 for RTU )
85 102 int getStopBits() const { return m_stopBits; } ///< Get the number of stopBits. ( de-facto = 1 )
86 103  
... ... @@ -93,20 +110,21 @@ public:
93 110 private:
94 111  
95 112 /// Serial connections
96   - ConnectionPort m_port;
97   - int m_baudRate;
98   - Parity m_parity;
99   - int m_dataBits;
100   - int m_stopBits;
  113 + ConnectionPort m_port; ///< Member variable holding the portName Enum
  114 + int m_baudRate; ///< Member variable holding the Serial port Baudrate
  115 + Parity m_parity; ///< Member variable holding the Serial port Parity
  116 + int m_dataBits; ///< Member variable holding the number of databits
  117 + int m_stopBits; ///< Member variable holding the number of stopbits
101 118  
102 119 /// TCP connections
103   - std::string m_ipaddress;
104   - int m_portnumber;
  120 + std::string m_ipaddress; ///< Member variable holding the ip-address of the TCP-connection
  121 + int m_portnumber; ///< Member variable holding the portnumber of the TCP-connection
105 122  
106 123 /// Generic
107   - int m_timeOut;
108   - ConnectionType m_conType;
  124 + int m_timeOut; ///< Member variable holding the timeOut value
  125 + ConnectionType m_conType; ///< Member variable holding the connection type.
109 126  
  127 + /// Translation tables for portnames and parity.
110 128 // ============================================================
111 129 // == Change accordingly to the devicenames on your platform ==
112 130 // ============================================================
... ...
src/IModbusAdapter.h
  View file @0df27b0
... ... @@ -15,58 +15,70 @@ using modbusData = std::vector&lt;std::variant&lt;uint8_t, uint16_t&gt;&gt;;
15 15 class ConnectionConfig;
16 16  
17 17 /*!
18   - * \brief The IModbusAdapter class
  18 + * \brief The IModbusAdapter class provides an abstract way of using
  19 + * the modbus stack. Implemented as a pure virtual, it cannot be instantiated.
  20 + * This represents a unique connection to either a serial bus or a TCP connection.
19 21 */
20 22 class IModbusAdapter
21 23 {
22 24  
23 25 public:
24   - virtual ~IModbusAdapter() {}
  26 + /// Default DTor.
  27 + virtual ~IModbusAdapter() = default;
25 28  
  29 + /// Create a modbus connection, accepting a configuration object.
26 30 virtual bool ModbusConnect( const ConnectionConfig &conncfg ) = 0;
27 31  
28 32 /*!
29   - * \brief ModbusDisconnect
  33 + * \brief ModbusDisconnect
  34 + * Disconnect from the serial bus or the TCP connection, freeing its resources
30 35 */
31 36 virtual bool ModbusDisconnect() = 0;
32 37  
33 38 /*!
34   - * \brief ModbusReadData
35   - * \param slaveId
36   - * \param startAddress
37   - * \param noOfItems
  39 + * \brief Read data from a modbus device given by its parameters.
  40 + * \param slaveId - The Id of the ModbusDevice.
  41 + * \param functionCode - The code describing the action we want to perform on the device.
  42 + * Given by an enum, provided by the modbus-stack.
  43 + * \param startAddress - Startaddres of the register we want to read.
  44 + * \param noOfItems - The number of items we expect back.
  45 + * \returns modbusData - A vector holding each register in an entry in the same order as they are received.
  46 + * Empty if no data was received.
38 47 */
39 48 virtual modbusData ModbusReadData( int slaveId, int functionCode, int startAddress, int noOfItems ) = 0;
40 49  
41 50 /*!
42   - * \brief ModbusReadHoldReg
43   - * \param slaveId
44   - * \param startAddress
45   - * \param noOfItems
46   - * \return
  51 + * \brief Read data from the holdregisters ( or keep-registers ) of a modbus device.
  52 + * \param slaveId - The Id of the ModbusDevice.
  53 + * \param startAddress - Startaddres of the register we want to read.
  54 + * \param noOfItems - The number of items we expect back.
  55 + * \returns modbusData - A vector holding each register in an entry in the same order as they are received.
  56 + * Empty if no data was received.
47 57 */
48 58 virtual modbusData ModbusReadHoldReg( int slaveId, int startAddress, int noOfItems ) = 0;
49 59  
50 60 /*!
51   - * \brief ModBusWriteData
52   - * \param slaveId
53   - * \param funtionCode
54   - * \param startAddress
55   - * \param noOfItems
56   - * \param values
  61 + * \brief Write data to the device.
  62 + * \param slaveId - The Id of the Modbus device
  63 + * \param funtionCode - The code describing the action we want to perform on the device
  64 + * given by an enum, provided by the modbus-stack.
  65 + * \param startAddress - Startaddres of the register we want to read.
  66 + * \param noOfItems - The number of items we expect to be written
  67 + * \param values - The values we want to write to the given device. Each vector-entry represents a single byte
  68 + * and they will be sent in sequence.
57 69 */
58 70 virtual void ModBusWriteData( int slaveId, int functionCode, int startAddress, int noOfItems, std::vector<int>values ) = 0;
59 71  
60 72 /*!
61   - * \brief isConnected
62   - * \return
  73 + * \brief Indicates if this connection is alive.
  74 + * \return True if alive, false if not.
63 75 */
64 76 virtual bool isConnected() const = 0;
65 77  
66 78 /*!
67   - * \brief ErrorString
68   - * \param errnum
69   - * \return
  79 + * \brief returns the translated error code coming from the modbus stack.
  80 + * \param errnum - error Number coming from the stack.
  81 + * \return The translated error as a string. Empty if not resolvable.
70 82 */
71 83 virtual std::string ErrorString( int errnum ) const = 0;
72 84 };
... ...
src/ModbusAdapter.h
  View file @0df27b0
... ... @@ -21,63 +21,70 @@ class ModbusAdapter : public IModbusAdapter
21 21 {
22 22 public:
23 23 /*!
24   - * \brief ModbusAdapter
  24 + * \brief Default constructor
25 25 */
26 26 explicit ModbusAdapter();
27 27  
28 28 /*!
29   - * \brief ~ModbusAdapter
  29 + * \brief Default destructor
30 30 */
31 31 virtual ~ModbusAdapter();
32 32  
33 33 /*!
34   - * \brief ModbusConnect
35   - * \param conncfg
  34 + * \brief /// Create a modbus connection, accepting a configuration object.
36 35 */
37 36 bool ModbusConnect( const ConnectionConfig &conncfg ) override;
38 37  
39 38 /*!
40   - * \brief ModbusDisconnect
  39 + * \brief ModbusDisconnect
  40 + * Disconnect from the serial bus or the TCP connection, freeing its resources
41 41 */
42 42 bool ModbusDisconnect() override;
43 43  
44 44 /*!
45   - * \brief ModbusReadData
46   - * \param slaveId
47   - * \param startAddress
48   - * \param noOfItems
  45 + * \brief Read data from a modbus device given by its parameters.
  46 + * \param slaveId - The Id of the ModbusDevice.
  47 + * \param functionCode - The code describing the action we want to perform on the device.
  48 + * Given by an enum, provided by the modbus-stack.
  49 + * \param startAddress - Startaddres of the register we want to read.
  50 + * \param noOfItems - The number of items we expect back.
  51 + * \returns modbusData - A vector holding each register in an entry in the same order as they are received.
  52 + * Empty if no data was received.
49 53 */
50 54 modbusData ModbusReadData( int slaveId, int functionCode, int startAddress, int noOfItems ) override;
51 55  
52 56 /*!
53   - * \brief ModbusReadHoldReg
54   - * \param slaveId
55   - * \param startAddress
56   - * \param noOfItems
57   - * \return
  57 + * \brief Read data from the holdregisters ( or keep-registers ) of a modbus device.
  58 + * \param slaveId - The Id of the ModbusDevice.
  59 + * \param startAddress - Startaddres of the register we want to read.
  60 + * \param noOfItems - The number of items we expect back.
  61 + * \returns modbusData - A vector holding each register in an entry in the same order as they are received.
  62 + * Empty if no data was received.
58 63 */
59 64 modbusData ModbusReadHoldReg( int slaveId, int startAddress, int noOfItems ) override;
60 65  
61 66 /*!
62   - * \brief ModBusWriteData
63   - * \param slaveId
64   - * \param funtionCode
65   - * \param startAddress
66   - * \param noOfItems
67   - * \param values
  67 + * \brief Write data to the device.
  68 + * \param slaveId - The Id of the Modbus device
  69 + * \param funtionCode - The code describing the action we want to perform on the device
  70 + * given by an enum, provided by the modbus-stack.
  71 + * \param startAddress - Startaddres of the register we want to read.
  72 + * \param noOfItems - The number of items we expect to be written
  73 + * \param values - The values we want to write to the given device. Each vector-entry represents a single byte
  74 + * and they will be sent in sequence.
68 75 */
69 76 void ModBusWriteData( int slaveId, int functionCode, int startAddress, int noOfItems, std::vector<int>values ) override;
70 77  
71 78 /*!
72   - * \brief isConnected
73   - * \return
  79 + * \brief Indicates if this connection is alive.
  80 + * \return True if alive, false if not.
74 81 */
75 82 bool isConnected() const override;
76 83  
77 84 /*!
78   - * \brief ErrorString
79   - * \param errnum
80   - * \return
  85 + * \brief returns the translated error code coming from the modbus stack.
  86 + * \param errnum - error Number coming from the stack.
  87 + * \return The translated error as a string. Empty if not resolvable.
81 88 */
82 89 std::string ErrorString( int errnum ) const override;
83 90  
... ...
src/ModbusConnections.h
  View file @0df27b0
... ... @@ -13,91 +13,97 @@
13 13 #include <string>
14 14 #include <unordered_map>
15 15  
16   -///
  16 +/// Easy replacement of template construction
17 17 using AdapterList = std::vector<std::shared_ptr<IModbusAdapter>>;
18 18  
19 19 /*!
20   - * \brief The ModbusConnections class
  20 + * \brief The ModbusConnections class conatins a list of all modbus connections, Serial and TCP.
  21 + * To access a specific connection, use its portname and / or endpoint to return it's interface.
21 22 */
22 23 class ModbusConnections
23 24 {
24 25 public:
25 26 /*!
26   - * \brief ModbusConnections
  27 + * \brief Default CTor
27 28 */
28 29 explicit ModbusConnections();
29 30  
30 31 /*!
31   - * \brief ~ModbusConnections
  32 + * \brief Default DTor
32 33 */
33 34 virtual ~ModbusConnections();
34 35  
35 36 /*!
36   - * \brief CreateConnection
37   - * \param config
38   - * \return
  37 + * \brief Create a modbus connection as described by the connection object.
  38 + * \param config - The connection object describing the connection in detail.
  39 + * \return The result of the creation.
  40 + * True = succesful.
  41 + * False = Failed.
39 42 */
40 43 bool CreateConnection( const ConnectionConfig &config );
41 44  
42 45 /*!
43   - * \brief DeleteConnection
44   - * \param portName
45   - * \param endpoint
  46 + * \brief Remove the connection described by its portname and/or endpoint.
  47 + * \param portName - The portname as its enum
  48 + * \param endpoint - combination of ip-address and portname in endpoint-format
  49 + * ( tcp://<ip_address>:<portNumber> )
  50 + * ( i.e. tcp://127.0.0.1:501 )
46 51 * \return
47 52 */
48 53 bool DeleteConnection( const ConnectionPort portName, const std::string &endpoint = std::string() );
49 54  
50 55 /*!
51   - * \brief ConnectionCount
52   - * \return
  56 + * \brief Give the number of registered serial and tcp-connections combined.
53 57 */
54 58 int ConnectionCount();
55 59  
56 60 /*!
57   - * \brief getConnection
58   - * \param portName
59   - * \param endpoint
60   - * \return
  61 + * \brief Get the connection give by its parameters.
  62 + * \param portName - The portname by its enum
  63 + * \param endpoint - combination of ip-address and portname in endpoint-format
  64 + * ( tcp://<ip_address>:<portNumber> )
  65 + * ( i.e. tcp://127.0.0.1:501 )
  66 + * \return Valid Pointer to the Modbus Connection Interface. nullptr if the connection wasn't found.
61 67 */
62 68 std::shared_ptr<IModbusAdapter> getConnection( const ConnectionPort portName, const std::string &endpoint = std::string() );
63 69  
64 70 // Convenient functions
65 71 /*!
66   - * \brief getConnection
67   - * \param portName
68   - * \param ipAddress
69   - * \param tcpPortNumber
70   - * \return
  72 + * \brief Get the connection given by its parameters. If applicable, ipaddress and portnumber will be used to create the endpoint.
  73 + * \param portName - The portname by its enum
  74 + * \param ipAddress - The ipaddress of the TCP-connection
  75 + * \param tcpPortNumber - The portnumber of the TCP-connection
  76 + * \return Valid Pointer to the Modbus Connection Interface. nullptr if the connection wasn't found.
71 77 */
72 78 std::shared_ptr<IModbusAdapter> getConnection( const ConnectionPort portName, const std::string &ipAddress, int tcpPortNumber );
73 79  
74 80 /*!
75   - * \brief getConnections
76   - * \return
  81 + * \brief Returns a list of all registered connections by their interfaces. This is a mix of Serial and TCP-connections.
77 82 */
78 83 AdapterList getConnections();
79 84  
80 85 private:
81 86 /*!
82   - * \brief connectionExist
83   - * \param portName
84   - * \param endpoint
85   - * \return
  87 + * \brief Check if a connection already exist.
  88 + * \param portName - The portName by its enum
  89 + * \param endpoint - The endpoint this connection was registered with.
  90 + * \return A valid pointer to the Interface if the connection exist. If the connection is unknown, it will return a nullptr.
  91 + * shared_ptr can manifest themselves as booleans, so "!ptr" is sufficient to check.
86 92 */
87 93 std::shared_ptr<IModbusAdapter> connectionExist( const ConnectionPort portName, const std::string &endpoint = std::string() );
88 94  
89 95 /*!
90   - * \brief createEndPoint
91   - * \param ipAddress
92   - * \param portNumber
93   - * \return
  96 + * \brief Create the TCP endpoint based on the connections IP-address and portnumber
  97 + * \param ipAddress - The ipAddress as string.
  98 + * \param portNumber - The portnumber as integer.
  99 + * \return The endpoint in format : tcp://<ip_address>:<portNumber> i.e. tcp://127.0.0.1:501
94 100 */
95 101 std::string createEndPoint( const std::string &ipAddress, int portNumber );
96 102  
97 103 /*!
98   - * \brief createEndPoint
99   - * \param config
100   - * \return
  104 + * \brief Create the TCP endpoint based on the connections IP-address and portnumber extracted from the connection configuration.
  105 + * \param config - The configuration object used to create the connection.
  106 + * \return The endpoint in format : tcp://<ip_address>:<portNumber> i.e. tcp://127.0.0.1:501
101 107 */
102 108 std::string createEndPoint( const ConnectionConfig &config );
103 109  
... ...