Diff: ModbusSlaveRTU.h

Revision:

1:5efaa10b9a3f

Parent:

0:81fee41d95f1

Child:

2:f028bdcd4814

--- a/ModbusSlaveRTU.h	Mon Jan 19 03:29:36 2015 +0000
+++ b/ModbusSlaveRTU.h	Mon Jan 19 08:05:40 2015 +0000
@@ -1,3 +1,19 @@
+/* Modbus Slave RTU
+ * Copyright (c) 2015 Gabriel Rivas
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 #ifndef _MODBUS_SLAVE_RTU_H_
 #define _MODBUS_SLAVE_RTU_H_
 
@@ -16,33 +32,39 @@
 class ModbusSlaveRTU
 {
 public:
+
     /*! Modbus response message bytes indexes. */
-    enum MbResponseByteIndex_t {
-        ADDRESS    = 0,
-        FUNCTION   = 1,
-        BYTE_COUNT = 2,
-        DATA_START = 3
+    enum MbByteIndex_t {
+        ADDRESS         = 0, /**< Modbus address position.*/
+        FUNCTION        = 1, /**< Modbus function position.*/
+        BYTE_COUNT      = 2, /**< Byte count high byte position.*/
+        DATA_START      = 3, /**< Returned data start position.*/
+        BYTE_OFFSET     = 2, /**< Starting register in bytes, high byte position.*/
+        REGISTER_COUNT  = 4  /**< Number of registers to be read, high byte position.*/
     };
 
     /*! Modbus errors reported during message processing. */
     enum MbReceivedMessageErrors_t {
-        ADDRESS_ERROR    = 0x10,
-        CRC_ERROR        = 0x11,
-        OFFSET_ERROR     = 0x12,
-        BYTE_COUNT_ERROR = 0x13
+        NO_ERROR         = 0x10, /**< No error.*/
+        ADDRESS_ERROR    = 0x11, /**< Wrong slave address.*/
+        CRC_ERROR        = 0x12, /**< CRC from received message doesn't match with locally calculated CRC.*/
+        OFFSET_ERROR     = 0x13, /**< Offset is out of range.*/
+        BYTE_COUNT_ERROR = 0x14  /**< Byte count requested is out of range.*/
     };
 
+    /*! Status of the internal modbus FSM. */
     enum MbStatusTypes_t {
-        MESSAGE_LISTENING  = 0x20,
-        MESSAGE_PROCESSING = 0x21,
-        MESSAGE_SENDING    = 0x23
+        LISTENING  = 0x20, /**< Listening for incomming requests.*/
+        PROCESSING = 0x21, /**< Processing received request.*/
+        SENDING    = 0x23  /**< Sending generated response.*/
     };
 
+    /*! Internal modbus FSM states. */
     enum MbSlaveRTUStates_t {
-        WAIT_REQUEST_MESSAGE      = 0x00,
-        GET_RECEIVED_BYTES        = 0x01,
-        BUILD_RESPONSE_MESSAGE    = 0x02,
-        TRANSMIT_RESPONSE_MESSAGE = 0x03
+        WAIT_REQUEST_MESSAGE      = 0x00, /**< Idle while bytes are being received.*/
+        GET_RECEIVED_BYTES        = 0x01, /**< Copy received bytes into the internal buffer.*/
+        BUILD_RESPONSE_MESSAGE    = 0x02, /**< Building response message.*/
+        TRANSMIT_RESPONSE_MESSAGE = 0x03  /**< Transmitting response message.*/
     };
 
     /*! Modbus function codes. */
@@ -63,30 +85,25 @@
         uint8_t mAddress;             /**< Slave device address.*/
         MbFunctionCodes_t mFunction;  /**< Requested function of type MbFunctionCodes_t.*/
         uint16_t mOffset;             /**< Offset in bytes from the starting address.*/
-        uint16_t mByteCount;
-        uint8_t mCRCH;
-        uint8_t  mCRCL;
-        uint16_t mSize;
+        uint16_t mByteCount;          /**< Number of bytes to respond.*/
+        uint8_t mCRCH;                /**< CRC high byte.*/
+        uint8_t  mCRCL;               /**< CRC low byte.*/
+        uint16_t mSize;               /**< Size of the frame in bytes.*/
     };
 
+    /*! Memory map structure. */
     struct MemoryMap_t {
-        ThreadSafeArray_t *coilRegisters;
-        ThreadSafeArray_t *holdingRegisters;
-        ThreadSafeArray_t *inputRegisters;
+        ThreadSafeArray_t *coilRegisters;    /**< Pointer to the coil registers array.*/
+        ThreadSafeArray_t *holdingRegisters; /**< Pointer to the holding registers array.*/
+        ThreadSafeArray_t *inputRegisters;   /**< Pointer to the input registers array.*/
     };
 
-    typedef struct MbSlaveRTUControl {
-        uint8_t MbAddress;
-        uint8_t rxByte;
-        uint32_t receiveIndex;
-        MbStatusTypes_t status;
-    } MbSlaveRTUControl_t;
-
-
 public:
     /**
-     * @brief Initialization function for the Modbus RTU Slave.
-     * @param id.
+     * Creates a Modbus Slave RTU object.
+     * @param id Mosbus address.
+     * @param txQueue Message queue to write modbus responses into.
+     * @param rxQueue Message queue to read modbus requests from.     
      * @param *coilRegisters Pointer to the memory space reserved for the coil registers.
      * @param *inputRegisters Pointer to the memory space reserved for the input registers.
      * @param *inputRegisters Pointer to the memory space reserved for the holding registers.
@@ -101,25 +118,42 @@
 
 public:
     /**
-     * @brief Function to start the Modbus RTU Slave engine.
-     * @return void
+     * Function to start the Modbus RTU Slave engine.
      */
     void trigger(void);
 
     /**
-     * @brief Function to start the Modbus RTU Slave engine.
-     * @return MbStatusTypes_t
+     * Gets the status of the internal FSM.
+     * @return Status value as defined in MbStatusTypes_t.
      */
     MbStatusTypes_t getStatus(void);
+    
+    /**
+     * Internal FSM process.
+     */    
     void FSM(void);
 
 private:
-    uint8_t readHoldingRegistersHandler(void);
-    uint8_t readCoilRegistersHandler(void);
-    uint8_t buildResponse(void);
+    /**
+     * Handler for read holding registers function request.
+     * @return Error or success code as defined in MbReceivedMessageErrors_t.
+     */
+    MbReceivedMessageErrors_t readHoldingRegistersHandler(void);
+    
+    /**
+     * Handler for read coil registers function request.
+     * @return Error or success code as defined in MbReceivedMessageErrors_t.
+     */    
+    MbReceivedMessageErrors_t readCoilRegistersHandler(void);
+    
+    /**
+     * Builds response message.
+     * @return Error or success code as defined in MbReceivedMessageErrors_t.
+     */    
+    MbReceivedMessageErrors_t buildResponse(void);
 
     /**
-     * @brief Function that computes the CRC of a Modbus message.
+     * Function that computes the CRC of a Modbus message.
      * @param *data Pointer to the message data.
      * @param uint8_t Length of the message.
      * @return The CRC Code.
@@ -127,33 +161,60 @@
     uint16_t getCRC(uint8_t *  data,uint8_t len);
 
     /**
-     * @brief Verifies the CRC value of a message to determine it has been received correctly.
+     * Verifies the CRC value of a message to determine it has been received correctly.
      * @param *data Pointer to the message data.
      * @return Returns 1 if the message has been well received, 0 otherwise.
      */
     uint8_t checkMessageCRC(uint8_t *  data);
 
     /**
-     * @brief Function that appends the header and tail bytes for a response message.
+     * Function that appends the header and tail bytes for a response message.
      * @return void.
      */
     void appendHeaderAndTailToMessage(void);
 
     /**
-     * @brief Function that checks for error in the received message.
+     * Function that checks for error in the received message.
      * @param *array Safe array being processed depending on the modbus function.
-     * @return uint8_t the error or success code.
+     * @return The error or success code as defined in MbReceivedMessageErrors_t.
      */
-    uint8_t checkReceivedMessageErrors(ThreadSafeArray_t *array);
+    MbReceivedMessageErrors_t checkReceivedMessageErrors(ThreadSafeArray_t *array);
 
 private:
+    /** Internal state of the modbus FSM.
+     */
     MbSlaveRTUStates_t m_state;
+    
+    /** Response frame.
+     */    
     MbSlaveRTUFrame_t m_frame;
-    MbSlaveRTUControl_t m_control;
+    
+    /** Modbus address.
+     */
+    uint8_t m_address;
+    
+    /** Modbus process status.
+     */
+    MbStatusTypes_t m_status;
+    
+    /** Memory map for registers.
+     */
     MemoryMap_t m_memoryMap;
+    
+    /** Queue to write response data.
+     */
     MessageQueue<uint8_t>* m_bTxQueue;
+    
+    /** Queue to read incomming requests from.
+     */
     MessageQueue<uint8_t>* m_bRxQueue;
+    
+    /** Internal byte array to copy incomming requests.
+     */
     uint8_t m_receivedMessage[MODBUS_MAX_LEN];
+    
+    /** Internal byte array to generate responses.
+     */   
     uint8_t m_responseMessage[MODBUS_MAX_LEN];
 };
 #endif