From 8fbdca445280ac41de0c62b333507595c518533b Mon Sep 17 00:00:00 2001 From: Mikael Falkvidd Date: Tue, 30 Jan 2018 20:47:11 +0100 Subject: [PATCH] Doxygenize MyMessage / Message manipulation (#1035) * Fix cppcheck issues Fixes the following cppcheck issues: examples/SecretKnockSensor/SecretKnockSensor.ino 305 variableScope 398 style The scope of the variable 'timeDiff' can be reduced. examples/SensebenderGatewaySerial/SensebenderGatewaySerial.ino 127 variableScope 398 style The scope of the variable 'led_state' can be reduced. * Doxygenize MyMessage / Message manipulation This should replace the static documentation at http://korturl.nu/stupid I have enabled existing comments and added new comments where necessary. Feedback on syntax and contents is welcome. --- core/MyMessage.cpp | 1 - core/MyMessage.h | 217 +++++++++++++++++++++++++++++++++++++-------- 2 files changed, 179 insertions(+), 39 deletions(-) diff --git a/core/MyMessage.cpp b/core/MyMessage.cpp index 1cea592..8382725 100644 --- a/core/MyMessage.cpp +++ b/core/MyMessage.cpp @@ -76,7 +76,6 @@ const char* MyMessage::getString() const } } -// handles single character hex (0 - 15) char MyMessage::i2h(uint8_t i) const { uint8_t k = i & 0x0F; diff --git a/core/MyMessage.h b/core/MyMessage.h index 91c08cb..ad10e34 100644 --- a/core/MyMessage.h +++ b/core/MyMessage.h @@ -50,6 +50,7 @@ typedef enum { C_STREAM = 4 //!< For firmware and other larger chunks of data that need to be divided into pieces. } mysensor_command; +#if !DOXYGEN // Hide until we migrate /// @brief Type of sensor (used when presenting sensors) typedef enum { S_DOOR = 0, //!< Door sensor, V_TRIPPED, V_ARMED @@ -158,6 +159,7 @@ typedef enum { V_VA = 55, //!< S_POWER, Apparent power: volt-ampere (VA) V_POWER_FACTOR = 56, //!< S_POWER, Ratio of real power to apparent power: floating point value in the range [-1,..,1] } mysensor_data; +#endif /// @brief Type of internal messages (for internal messages) @@ -275,23 +277,37 @@ typedef enum { #define miGetPayloadType() (uint8_t)BF_GET(command_ack_payload, 5, 3) //!< Internal getter for payload type field -#if !DOXYGEN -#ifdef __cplusplus +#if defined(__cplusplus) || defined(DOXYGEN) +/** + * @brief MyMessage is used to create, manipulate, send and read MySensors messages + */ class MyMessage { private: char* getCustomString(char *buffer) const; public: - // Constructors + /** + * Default constructor + */ MyMessage(); + /** + * Constructor + * @param sensor id of the child sensor for this message + * @param type see http://korturl.nu/stupidurl + */ MyMessage(uint8_t sensor, uint8_t type); + /** + * Single character hex (0 - 15) conversion + * @param i byte (only lower 4 bits will be considered) + * @return single char with the hex representation (0 to F) of the parameter + */ char i2h(uint8_t i) const; /** - * Clear message contents. + * @brief Clear message contents. */ void clear(); @@ -299,42 +315,158 @@ public: * If payload is something else than P_STRING you can have the payload value converted * into string representation by supplying a buffer with the minimum size of * 2*MAX_PAYLOAD+1. This is to be able to fit hex-conversion of a full binary payload. + * @param buffer pointer to a buffer that's at least 2*MAX_PAYLOAD+1 bytes large */ char* getStream(char *buffer) const; + + /** + * @brief Copy the payload into the supplied buffer + */ char* getString(char *buffer) const; + + /** + * @brief Get payload as string + * @return pointer to a char array storing the string + */ const char* getString() const; + + /** + * @brief Get custom payload + * @return pointer to the raw payload + */ void* getCustom() const; + + /** + * @brief Get bool payload + * @return a bool with the value of the payload (true/false) + */ bool getBool() const; + + /** + * @brief Get unsigned 8-bit integer payload + * @return the value of the payload, 0 to 255 + */ uint8_t getByte() const; + + /** + * @brief Get float payload + * @return the floating-point value of the payload + */ float getFloat() const; + + /** + * @brief Get signed 16-bit integer payload + * @return the value of the payload, –32768 to 32767 + */ int16_t getInt() const; + + /** + * @brief Get unsigned 16-bit integer payload + * @return the value of the payload, 0 to 65535 + */ uint16_t getUInt() const; + + /** + * @brief Get signed 32-bit integer payload + * @return the value of the payload, –2147483648 to 2147483647 + */ int32_t getLong() const; + + /** + * @brief Get unsigned 32-bit integer payload + * @return the value of the payload, 0 to 4294967295 + */ uint32_t getULong() const; - // Getter for command type + /** + * @brief Getter for command type + * @return #mysensor_command + */ uint8_t getCommand() const; - // Getter for ack-flag. True if this is an ack message. + /** + * @brief Getter for ack-flag. + * @return true if this is an ack message + */ bool isAck() const; - // Setters for building message "on the fly" + /** + * @brief Set message type + * @param type see http://korturl.nu/stupidurl + */ MyMessage& setType(uint8_t type); + + /** + * @brief Set which child sensor this message belongs to + */ MyMessage& setSensor(uint8_t sensor); + + /** + * @brief Set final destination node id for this message + */ MyMessage& setDestination(uint8_t destination); - // Setters for payload + /** + * @brief Set entire payload + * @param payload pointer to the buffer where the payload is stored + * @param length of the payload + */ MyMessage& set(void* payload, uint8_t length); + + /** + * @brief Set payload to character array + * @param value pointer to the character array. The array must be null-terminated. + */ MyMessage& set(const char* value); #if !defined(__linux__) + /** + * @brief Set payload to character array from flash + * @param value pointer to the character array. The array must be null-terminated. + */ MyMessage& set(const __FlashStringHelper* value); #endif + + /** + * @brief Set payload to decimal number + * @param value float + * @param decimals number of decimals to include + */ MyMessage& set(float value, uint8_t decimals); + + /** + * @brief Set payload to bool value + * @param value true or false + */ MyMessage& set(bool value); + + /** + * @brief Set payload to unsigned 8-bit integer value + * @param value (0 to 255) + */ MyMessage& set(uint8_t value); + + /** + * @brief Set payload to unsigned 32-bit integer value + * @param value (0 to 4294967295) + */ MyMessage& set(uint32_t value); + + /** + * @brief Set payload to signed 32-bit integer value + * @param value (–2147483648 to 2147483647) + */ MyMessage& set(int32_t value); + + /** + * @brief Set payload to unsigned 16-bit integer value + * @param value (0 to 65535) + */ MyMessage& set(uint16_t value); + + /** + * @brief Set payload to signed 16-bit integer value + * @param value (–32768 to 32767) + */ MyMessage& set(int16_t value); #else @@ -343,47 +475,56 @@ typedef union { struct { #endif - uint8_t last; // 8 bit - Id of last node this message passed - uint8_t sender; // 8 bit - Id of sender node (origin) - uint8_t destination; // 8 bit - Id of destination node + uint8_t last; ///< 8 bit - Id of last node this message passed + uint8_t sender; ///< 8 bit - Id of sender node (origin) + uint8_t destination; ///< 8 bit - Id of destination node - uint8_t version_length; // 2 bit - Protocol version - // 1 bit - Signed flag - // 5 bit - Length of payload - uint8_t command_ack_payload; // 3 bit - Command type - // 1 bit - Request an ack - Indicator that receiver should send an ack back. - // 1 bit - Is ack message - Indicator that this is the actual ack message. - // 3 bit - Payload data type - uint8_t type; // 8 bit - Type varies depending on command - uint8_t sensor; // 8 bit - Id of sensor that this message concerns. + /** + * 2 bit - Protocol version
+ * 1 bit - Signed flag
+ * 5 bit - Length of payload + */ + uint8_t version_length; - // Each message can transfer a payload. We add one extra byte for string - // terminator \0 to be "printable" this is not transferred OTA - // This union is used to simplify the construction of the binary data types transferred. + /** + * 3 bit - Command type
+ * 1 bit - Request an ack - Indicator that receiver should send an ack back
+ * 1 bit - Is ack message - Indicator that this is the actual ack message
+ * 3 bit - Payload data type + */ + uint8_t command_ack_payload; + + uint8_t type; ///< 8 bit - Type varies depending on command + uint8_t sensor; ///< 8 bit - Id of sensor that this message concerns. + + /* + * Each message can transfer a payload. We add one extra byte for string + * terminator \0 to be "printable" this is not transferred OTA + * This union is used to simplify the construction of the binary data types transferred. + */ union { - uint8_t bValue; - uint16_t uiValue; - int16_t iValue; - uint32_t ulValue; - int32_t lValue; - struct { // Float messages + uint8_t bValue; ///< unsigned byte value (8-bit) + uint16_t uiValue; ///< unsigned integer value (16-bit) + int16_t iValue; ///< signed integer value (16-bit) + uint32_t ulValue; ///< unsigned long value (32-bit) + int32_t lValue; ///< signed long value (32-bit) + struct { //< Float messages float fValue; - uint8_t fPrecision; // Number of decimals when serializing + uint8_t fPrecision; ///< Number of decimals when serializing }; - struct { // Presentation messages - uint8_t version; // Library version - uint8_t sensorType; // Sensor type hint for controller, see table above + struct { //< Presentation messages + uint8_t version; ///< Library version + uint8_t sensorType; ///< Sensor type hint for controller, see table above }; - char data[MAX_PAYLOAD + 1]; - } __attribute__((packed)); -#ifdef __cplusplus + char data[MAX_PAYLOAD + 1]; ///< Buffer for raw payload data + } __attribute__((packed)); ///< Doxygen will complain without this comment +#if defined(__cplusplus) || defined(DOXYGEN) } __attribute__((packed)); #else }; -uint8_t array[HEADER_SIZE + MAX_PAYLOAD + 1]; +uint8_t array[HEADER_SIZE + MAX_PAYLOAD + 1]; ///< buffer for entire message } __attribute__((packed)) MyMessage; #endif -#endif #endif /** @}*/