Add documentation for MyCapabilities (#989)

Also fixed spelling error in the MySigning documentation. Fixes #902
2026-02-20 01:21:27 +01:00 · 2017-11-13 12:34:50 +01:00
parent d44ecd95dd
commit 1f8d810ff4
4 changed files with 203 additions and 5 deletions
--- a/MyConfig.h
+++ b/MyConfig.h
@@ -408,6 +408,14 @@
 * @{
 */

+/**
+ * @def MY_RADIO_NRF5_ESB
+ * @brief Define this to use nRF5 based radios for sensor network communication.
+ *
+ * @see ARDUINO_ARCH_NRF5
+ */
+//#define MY_RADIO_NRF5_ESB
+
 /**
 * @def MY_NRF5_ESB_ENABLE_ENCRYPTION
 * @brief Define this to enable software based (RF24 compatible) %AES encryption.
@@ -527,6 +535,12 @@
 * @{
 */

+/**
+ * @def MY_RADIO_RFM69
+ * @brief Define this to use RFM69 based radios for sensor network communication.
+ */
+//#define MY_RADIO_RFM69
+
 /**
 * @def MY_DEBUG_VERBOSE_RFM69
 * @brief Define this for verbose debug prints related to the %RFM69 driver.
@@ -750,6 +764,12 @@
 * @{
 */

+/**
+ * @def MY_RADIO_RFM95
+ * @brief Define this to use RFM95 based radios for sensor network communication.
+ */
+//#define MY_RADIO_RFM95
+
 /**
 * @def MY_DEBUG_VERBOSE_RFM95
 * @brief Define this for verbose debug prints related to the RFM95 driver.
@@ -1802,6 +1822,42 @@
 // Doxygen specific constructs, not included when built normally
 // This is used to enable disabled macros/definitions to be included in the documentation as well.
 #if DOXYGEN
+/**
+ * @def ARDUINO_ARCH_SAMD
+ * @brief Automatically set when building for SAMD targets
+ */
+#define ARDUINO_ARCH_SAMD
+
+/**
+ * @def ARDUINO_ARCH_NRF5
+ * @brief Automatically set when building for nRF5 targets
+ */
+#define ARDUINO_ARCH_NRF5
+
+/**
+ * @def ARDUINO_ARCH_ESP8266
+ * @brief Automatically set when building for ESP8266 targets
+ */
+#define ARDUINO_ARCH_ESP8266
+
+/**
+ * @def ARDUINO_ARCH_AVR
+ * @brief Automatically set when building for AVR targets
+ */
+#define ARDUINO_ARCH_AVR
+
+/**
+ * @def ARDUINO_ARCH_STM32F1
+ * @brief Automatically set when building for STM32F1 targets
+ */
+#define ARDUINO_ARCH_STM32F1
+
+/**
+ * @def TEENSYDUINO
+ * @brief Automatically set when building for Teensy targets
+ */
+#define TEENSYDUINO
+
 // debug
 #define MY_DEBUG
 #define MY_DEBUG_OTA
@@ -1859,6 +1915,7 @@
 #define MY_SIGNING_FEATURE
 #define MY_ENCRYPTION_FEATURE
 // RS485
+#define MY_RS485
 #define MY_RS485_HWSERIAL (Serial1)
 // RF24
 #define MY_RADIO_RF24
@@ -1869,11 +1926,13 @@
 #define MY_RX_MESSAGE_BUFFER_FEATURE
 #define MY_RX_MESSAGE_BUFFER_SIZE
 // NRF5_ESB
+#define MY_RADIO_NRF5_ESB
 #define MY_NRF5_ESB_ENABLE_ENCRYPTION
 #define MY_DEBUG_VERBOSE_NRF5_ESB
 #define MY_NRF5_ESB_REVERSE_ACK_RX
 #define MY_NRF5_ESB_REVERSE_ACK_TX
 // RFM69
+#define MY_RADIO_RFM69
 #define MY_IS_RFM69HW
 #define MY_RFM69_NEW_DRIVER
 #define MY_RFM69_POWER_PIN
@@ -1885,6 +1944,7 @@
 #define MY_DEBUG_VERBOSE_RFM69_REGISTERS
 #define MY_RFM69_ENABLE_LISTENMODE
 // RFM95
+#define MY_RADIO_RFM95
 #define MY_DEBUG_VERBOSE_RFM95
 #define MY_RFM95_ATC_MODE_DISABLED
 #define MY_RFM95_RST_PIN
--- a/MySensors.h
+++ b/MySensors.h
@@ -286,6 +286,15 @@ MY_DEFAULT_RX_LED_PIN in your sketch instead to enable LEDs
 #endif // __avr_atmega1280__, __avr_atmega1284__, __avr_atmega2560__
 #endif // ARDUINO_ARCH_AVR
 #endif
+#ifdef DOXYGEN
+/**
+ * @def MY_RAM_ROUTING_TABLE_ENABLED
+ * @brief Automatically set if RAM routing table is enabled
+ *
+ * @see MY_RAM_ROUTING_TABLE_FEATURE
+ */
+#define MY_RAM_ROUTING_TABLE_ENABLED
+#endif

 // SOFTSPI
 #ifdef MY_SOFTSPI
--- a/core/MyCapabilities.h
+++ b/core/MyCapabilities.h
@@ -16,19 +16,62 @@
 * modify it under the terms of the GNU General Public License
 * version 2 as published by the Free Software Foundation.
 */
-
+/**
+ * @file MyCapabilities.h
+ * @ingroup MyCapabilities
+ */

 #ifndef MyCapabilities_h
 #define MyCapabilities_h
+/**
+ * @defgroup MyCapabilities Node capabilities indicator
+ * @ingroup MyConfigGrp
+ *
+ * @brief MySensors capabilities indications.
+ *
+ * At node startup, a capabilities string is shown as part of the initialization logs.
+ * This string indicate what configuration the node is running with.
+ *
+ * The string symbols are ordered in the following way:
+ * | Setting   |       Reset       |       Radio       |         OTA        |       Node       |   Architecture   |      Signing     |     Buffering     |   Encryption
+ * |-----------|-------------------|-------------------|--------------------|------------------|------------------|------------------|-------------------|-----------------
+ * | Indicator | @ref MY_CAP_RESET | @ref MY_CAP_RADIO | @ref MY_CAP_OTA_FW | @ref MY_CAP_TYPE | @ref MY_CAP_ARCH | @ref MY_CAP_SIGN | @ref MY_CAP_RXBUF | @ref MY_CAP_ENCR
+ *
+ * @see MY_CAPABILITIES
+ *
+ * @{
+ */

 // Remote reset
+/**
+ * @def MY_CAP_RESET
+ * @brief Indicate the remote reset setting.
+ *
+ * @see MY_DISABLE_REMOTE_RESET
+ *
+ * | Setting    | Indicator
+ * |------------|----------
+ * | Enabled    | R
+ * | Disabled   | N
+ */
 #if defined(MY_DISABLE_REMOTE_RESET)
 #define MY_CAP_RESET "N"
 #else
 #define MY_CAP_RESET "R"
 #endif

-// OTA firmware uodate feature
+// OTA firmware update feature
+/**
+ * @def MY_CAP_OTA_FW
+ * @brief Indicate the OTA update setting.
+ *
+ * @see MY_OTA_FIRMWARE_FEATURE
+ *
+ * | Setting    | Indicator
+ * |------------|----------
+ * | Enabled    | O
+ * | Disabled   | N
+ */
 #if defined(MY_OTA_FIRMWARE_FEATURE)
 #define MY_CAP_OTA_FW "O"
 #else
@@ -36,7 +79,22 @@
 #endif

 // Transport
-#if defined(MY_RADIO_NRF24) || defined(MY_RADIO_NRF5_ESB)
+/**
+ * @def MY_CAP_RADIO
+ * @brief Indicate the type of transport selected.
+ *
+ * @see MY_RADIO_RF24, MY_RADIO_NRF5_ESB, MY_RADIO_RFM69, MY_RFM69_NEW_DRIVER, MY_RADIO_RFM95, MY_RS485
+ *
+ * | Radio        | Indicator
+ * |--------------|----------
+ * | nRF24/nRF5   | N
+ * | %RFM69 (old) | R
+ * | %RFM69 (new) | P
+ * | RFM95        | L
+ * | RS485        | S
+ * | None         | -
+ */
+#if defined(MY_RADIO_RF24) || defined(MY_RADIO_NRF5_ESB)
 #define MY_CAP_RADIO "N"
 #elif defined(MY_RADIO_RFM69)
 #if !defined(MY_RFM69_NEW_DRIVER)
@@ -55,6 +113,19 @@
 #endif

 // Node type
+/**
+ * @def MY_CAP_TYPE
+ * @brief Indicate the type of node.
+ *
+ * @see MY_GATEWAY_FEATURE, MY_REPEATER_FEATURE, MY_PASSIVE_NODE
+ *
+ * | Node type | Indicator
+ * |-----------|----------
+ * | Gateway   | G
+ * | Repeater  | R
+ * | Passive   | P
+ * | Node      | N
+ */
 #if defined(MY_GATEWAY_FEATURE)
 #define MY_CAP_TYPE "G"
 #elif defined(MY_REPEATER_FEATURE)
@@ -66,6 +137,23 @@
 #endif

 // Architecture
+/**
+ * @def MY_CAP_ARCH
+ * @brief Indicate the architecture.
+ *
+ * @see ARDUINO_ARCH_SAMD, ARDUINO_ARCH_NRF5, ARDUINO_ARCH_ESP8266, ARDUINO_ARCH_AVR, ARDUINO_ARCH_STM32F1, TEENSYDUINO
+ *
+ * | Architecture | Indicator
+ * |--------------|----------
+ * | SAMD         | S
+ * | nRF5         | N
+ * | ESP8266      | E
+ * | AVR          | A
+ * | STM32F1      | F
+ * | TEENSY       | T
+ * | Linux        | L
+ * | Unknown      | -
+ */
 #if defined(ARDUINO_ARCH_SAMD)
 #define MY_CAP_ARCH "S"
 #elif defined(ARDUINO_ARCH_NRF5)
@@ -85,6 +173,18 @@
 #endif

 // Signing
+/**
+ * @def MY_CAP_SIGN
+ * @brief Indicate the signing backend used.
+ *
+ * @see MY_SIGNING_ATSHA204, MY_SIGNING_SOFT
+ *
+ * | Signing backend | Indicator
+ * |-----------------|----------
+ * | ATSHA204        | A
+ * | Software        | S
+ * | No signing      | -
+ */
 #if defined(MY_SIGNING_ATSHA204)
 #define MY_CAP_SIGN "A"
 #elif defined(MY_SIGNING_SOFT)
@@ -94,6 +194,17 @@
 #endif

 // RX queue
+/**
+ * @def MY_CAP_RXBUF
+ * @brief Indicate the rx message buffer setting.
+ *
+ * @see MY_RX_MESSAGE_BUFFER_FEATURE
+ *
+ * | Setting    | Indicator
+ * |------------|----------
+ * | Enabled    | Q
+ * | Disabled   | -
+ */
 #if defined(MY_RX_MESSAGE_BUFFER_FEATURE)
 #define MY_CAP_RXBUF "Q"
 #else
@@ -101,13 +212,31 @@
 #endif

 // Radio encryption
-#if defined(MY_RF24_ENABLE_ENCRYPTION) || defined(MY_RFM69_ENABLE_ENCRYPTION)
+/**
+ * @def MY_CAP_ENCR
+ * @brief Indicate the encryption setting.
+ *
+ * @see MY_RF24_ENABLE_ENCRYPTION, MY_RFM69_ENABLE_ENCRYPTION, MY_NRF5_ESB_ENABLE_ENCRYPTION
+ *
+ * | Setting    | Indicator
+ * |------------|----------
+ * | Enabled    | X
+ * | Disabled   | -
+ */
+#if defined(MY_RF24_ENABLE_ENCRYPTION) || defined(MY_RFM69_ENABLE_ENCRYPTION) || defined (MY_NRF5_ESB_ENABLE_ENCRYPTION)
 #define MY_CAP_ENCR "X"
 #else
 #define MY_CAP_ENCR "-"
 #endif


+/**
+ * @def MY_CAPABILITIES
+ * @brief This is the resulting capabilities string.
+ *
+ * @see MY_CAP_RESET, MY_CAP_RADIO, MY_CAP_OTA_FW, MY_CAP_TYPE, MY_CAP_ARCH, MY_CAP_SIGN, MY_CAP_RXBUF, MY_CAP_ENCR
+ */
 #define MY_CAPABILITIES MY_CAP_RESET MY_CAP_RADIO MY_CAP_OTA_FW MY_CAP_TYPE MY_CAP_ARCH MY_CAP_SIGN MY_CAP_RXBUF MY_CAP_ENCR

+/** @}*/ // End of MyCapabilities group
 #endif /* MyCapabilities_h */
--- a/core/MySigning.h
+++ b/core/MySigning.h
@@ -394,7 +394,7 @@
 * That is enough to enable protection from both Eve and Mallory in your network
 * although if you do not also enable encryption, Eve can eavesdrop, but not do anything about,
 * your messages (except possibly preventing them from arriving). @ref MY_SIGNING_SIMPLE_PASSWD also
- * enable encryption autmatically.
+ * enable encryption automatically.
 *
 * How are the messages actually affected by the signing?<br>
 * The following illustration shows what part of the message is signed, and where the signature is