From 5f38e79b8f02e993c4da5b4eb4c2fc7558eb8e44 Mon Sep 17 00:00:00 2001 From: Jm Casler Date: Wed, 26 Jul 2023 16:34:36 -0700 Subject: [PATCH] Add documentation to a few areas --- .vscode/extensions.json | 7 ++- src/FSCommon.cpp | 40 ++++++++++++ src/gps/RTC.cpp | 32 +++++++++- src/modules/ExternalNotificationModule.cpp | 19 ++++++ src/modules/RangeTestModule.cpp | 21 +++++-- src/modules/SerialModule.cpp | 30 ++++++++- src/modules/esp32/StoreForwardModule.cpp | 73 +++++++++++++++++++++- 7 files changed, 209 insertions(+), 13 deletions(-) diff --git a/.vscode/extensions.json b/.vscode/extensions.json index 4fc84fa78..080e70d08 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -2,8 +2,9 @@ // See http://go.microsoft.com/fwlink/?LinkId=827846 // for the documentation about the extensions.json format "recommendations": [ - "ms-vscode.cpptools", - "platformio.platformio-ide", - "trunk.io" + "platformio.platformio-ide" ], + "unwantedRecommendations": [ + "ms-vscode.cpptools-extension-pack" + ] } diff --git a/src/FSCommon.cpp b/src/FSCommon.cpp index a458a9fcf..9b59bdadf 100644 --- a/src/FSCommon.cpp +++ b/src/FSCommon.cpp @@ -1,3 +1,11 @@ +/** + * @file FSCommon.cpp + * @brief This file contains functions for common filesystem operations such as copying, renaming, listing and deleting files and directories. + * + * The functions in this file are used to perform common filesystem operations such as copying, renaming, listing and deleting files and directories. + * These functions are used in the Meshtastic-device project to manage files and directories on the device's filesystem. + * + */ #include "FSCommon.h" #include "configuration.h" @@ -14,6 +22,13 @@ SPIClass SPI1(HSPI); #endif // HAS_SDCARD +/** + * @brief Copies a file from one location to another. + * + * @param from The path of the source file. + * @param to The path of the destination file. + * @return true if the file was successfully copied, false otherwise. + */ bool copyFile(const char *from, const char *to) { #ifdef FSCom @@ -43,6 +58,14 @@ bool copyFile(const char *from, const char *to) #endif } +/** + * Renames a file from pathFrom to pathTo. + * + * @param pathFrom The original path of the file. + * @param pathTo The new path of the file. + * + * @return True if the file was successfully renamed, false otherwise. + */ bool renameFile(const char *pathFrom, const char *pathTo) { #ifdef FSCom @@ -59,6 +82,13 @@ bool renameFile(const char *pathFrom, const char *pathTo) #endif } +/** + * Lists the contents of a directory. + * + * @param dirname The name of the directory to list. + * @param levels The number of levels of subdirectories to list. + * @param del Whether or not to delete the contents of the directory after listing. + */ void listDir(const char *dirname, uint8_t levels, bool del = false) { #ifdef FSCom @@ -154,6 +184,13 @@ void listDir(const char *dirname, uint8_t levels, bool del = false) #endif } +/** + * @brief Removes a directory and all its contents. + * + * This function recursively removes a directory and all its contents, including subdirectories and files. + * + * @param dirname The name of the directory to remove. + */ void rmDir(const char *dirname) { #ifdef FSCom @@ -182,6 +219,9 @@ void fsInit() #endif } +/** + * Initializes the SD card and mounts the file system. + */ void setupSDCard() { #ifdef HAS_SDCARD diff --git a/src/gps/RTC.cpp b/src/gps/RTC.cpp index b80fd04aa..b2d397ed8 100644 --- a/src/gps/RTC.cpp +++ b/src/gps/RTC.cpp @@ -17,6 +17,10 @@ static uint32_t timeStartMsec; // Once we have a GPS lock, this is where we hold the initial msec clock that corresponds to that time static uint64_t zeroOffsetSecs; // GPS based time in secs since 1970 - only updated once on initial lock +/** + * Reads the current date and time from the RTC module and updates the system time. + * @return True if the RTC was successfully read and the system time was updated, false otherwise. + */ void readFromRTC() { struct timeval tv; /* btw settimeofday() is helpful here too*/ @@ -83,7 +87,15 @@ void readFromRTC() #endif } -/// If we haven't yet set our RTC this boot, set it from a GPS derived time +/** + * Sets the RTC (Real-Time Clock) if the provided time is of higher quality than the current RTC time. + * + * @param q The quality of the provided time. + * @param tv A pointer to a timeval struct containing the time to potentially set the RTC to. + * @return True if the RTC was set, false otherwise. + * + * If we haven't yet set our RTC this boot, set it from a GPS derived time + */ bool perhapsSetRTC(RTCQuality q, const struct timeval *tv) { static uint32_t lastSetMsec = 0; @@ -151,6 +163,13 @@ bool perhapsSetRTC(RTCQuality q, const struct timeval *tv) } } +/** + * Sets the RTC time if the provided time is of higher quality than the current RTC time. + * + * @param q The quality of the provided time. + * @param t The time to potentially set the RTC to. + * @return True if the RTC was set to the provided time, false otherwise. + */ bool perhapsSetRTC(RTCQuality q, struct tm &t) { /* Convert to unix time @@ -171,11 +190,22 @@ bool perhapsSetRTC(RTCQuality q, struct tm &t) } } +/** + * Returns the current time in seconds since the Unix epoch (January 1, 1970). + * + * @return The current time in seconds since the Unix epoch. + */ uint32_t getTime() { return (((uint32_t)millis() - timeStartMsec) / 1000) + zeroOffsetSecs; } +/** + * Returns the current time from the RTC if the quality of the time is at least minQuality. + * + * @param minQuality The minimum quality of the RTC time required for it to be considered valid. + * @return The current time from the RTC if it meets the minimum quality requirement, or 0 if the time is not valid. + */ uint32_t getValidTime(RTCQuality minQuality) { return (currentQuality >= minQuality) ? getTime() : 0; diff --git a/src/modules/ExternalNotificationModule.cpp b/src/modules/ExternalNotificationModule.cpp index 7dd6dd1ce..a939ee3f1 100644 --- a/src/modules/ExternalNotificationModule.cpp +++ b/src/modules/ExternalNotificationModule.cpp @@ -1,3 +1,17 @@ +/** + * @file ExternalNotificationModule.cpp + * @brief Implementation of the ExternalNotificationModule class. + * + * This file contains the implementation of the ExternalNotificationModule class, which is responsible for handling external notifications such as vibration, buzzer, and LED lights. + * The class provides methods to turn on and off the external notification outputs and to play ringtones using PWM buzzer. + * It also includes default configurations and a runOnce() method to handle the module's behavior. + * + * Documentation: + * https://meshtastic.org/docs/settings/moduleconfig/external-notification + * + * @author Jm Casler & Meshtastic Team + * @date [Insert Date] + */ #include "ExternalNotificationModule.h" #include "MeshService.h" #include "NodeDB.h" @@ -113,6 +127,11 @@ int32_t ExternalNotificationModule::runOnce() } } +/** + * Sets the external notification on for the specified index. + * + * @param index The index of the external notification to turn on. + */ void ExternalNotificationModule::setExternalOn(uint8_t index) { externalCurrentState[index] = 1; diff --git a/src/modules/RangeTestModule.cpp b/src/modules/RangeTestModule.cpp index 28835406d..705c72c68 100644 --- a/src/modules/RangeTestModule.cpp +++ b/src/modules/RangeTestModule.cpp @@ -1,3 +1,13 @@ +/** + * @file RangeTestModule.cpp + * @brief Implementation of the RangeTestModule class and RangeTestModuleRadio class. + * + * As a sender, this module sends packets every n seconds with an incremented PacketID. + * As a receiver, this module receives packets from multiple senders and saves them to the Filesystem. + * + * The RangeTestModule class is an OSThread that runs the module. + * The RangeTestModuleRadio class handles sending and receiving packets. + */ #include "RangeTestModule.h" #include "FSCommon.h" #include "MeshService.h" @@ -10,11 +20,6 @@ #include "gps/GeoCoord.h" #include -/* - As a sender, I can send packets every n seconds. These packets include an incremented PacketID. - As a receiver, I can receive packets from multiple senders. These packets can be saved to the Filesystem. -*/ - RangeTestModule *rangeTestModule; RangeTestModuleRadio *rangeTestModuleRadio; @@ -97,6 +102,12 @@ int32_t RangeTestModule::runOnce() return disable(); } +/** + * Sends a payload to a specified destination node. + * + * @param dest The destination node number. + * @param wantReplies Whether or not to request replies from the destination node. + */ void RangeTestModuleRadio::sendPayload(NodeNum dest, bool wantReplies) { meshtastic_MeshPacket *p = allocDataPacket(); diff --git a/src/modules/SerialModule.cpp b/src/modules/SerialModule.cpp index 1caae69a3..47ca1eef6 100644 --- a/src/modules/SerialModule.cpp +++ b/src/modules/SerialModule.cpp @@ -86,7 +86,13 @@ SerialModuleRadio::SerialModuleRadio() : MeshModule("SerialModuleRadio") } } -// For the serial2 port we can't really detect if any client is on the other side, so instead just look for recent messages +/** + * @brief Checks if the serial connection is established. + * + * @return true if the serial connection is established, false otherwise. + * + * For the serial2 port we can't really detect if any client is on the other side, so instead just look for recent messages + */ bool SerialModule::checkIsConnected() { uint32_t now = millis(); @@ -191,6 +197,11 @@ int32_t SerialModule::runOnce() } } +/** + * Allocates a new mesh packet for use as a reply to a received packet. + * + * @return A pointer to the newly allocated mesh packet. + */ meshtastic_MeshPacket *SerialModuleRadio::allocReply() { auto reply = allocDataPacket(); // Allocate a packet for sending @@ -198,6 +209,12 @@ meshtastic_MeshPacket *SerialModuleRadio::allocReply() return reply; } +/** + * Sends a payload to a specified destination node. + * + * @param dest The destination node number. + * @param wantReplies Whether or not to request replies from the destination node. + */ void SerialModuleRadio::sendPayload(NodeNum dest, bool wantReplies) { meshtastic_Channel *ch = (boundChannel != NULL) ? &channels.getByName(boundChannel) : NULL; @@ -216,6 +233,12 @@ void SerialModuleRadio::sendPayload(NodeNum dest, bool wantReplies) service.sendToMesh(p); } +/** + * Handle a received mesh packet. + * + * @param mp The received mesh packet. + * @return The processed message. + */ ProcessMessage SerialModuleRadio::handleReceived(const meshtastic_MeshPacket &mp) { if (moduleConfig.serial.enabled) { @@ -277,6 +300,11 @@ ProcessMessage SerialModuleRadio::handleReceived(const meshtastic_MeshPacket &mp return ProcessMessage::CONTINUE; // Let others look at this message also if they want } +/** + * @brief Returns the baud rate of the serial module from the module configuration. + * + * @return uint32_t The baud rate of the serial module. + */ uint32_t SerialModule::getBaudRate() { if (moduleConfig.serial.baud == meshtastic_ModuleConfig_SerialConfig_Serial_Baud_BAUD_110) { diff --git a/src/modules/esp32/StoreForwardModule.cpp b/src/modules/esp32/StoreForwardModule.cpp index fccbd7199..bce228224 100644 --- a/src/modules/esp32/StoreForwardModule.cpp +++ b/src/modules/esp32/StoreForwardModule.cpp @@ -1,3 +1,16 @@ +/** + * @file StoreForwardModule.cpp + * @brief Implementation of the StoreForwardModule class. + * + * This file contains the implementation of the StoreForwardModule class, which is responsible for managing the store and forward functionality of the Meshtastic device. + * The class provides methods for sending and receiving messages, as well as managing the message history queue. + * It also initializes and manages the data structures used for storing the message history. + * + * The StoreForwardModule class is used by the MeshService class to provide store and forward functionality to the Meshtastic device. + * + * @author Jm Casler + * @date [Insert Date] + */ #include "StoreForwardModule.h" #include "MeshService.h" #include "NodeDB.h" @@ -52,9 +65,9 @@ int32_t StoreForwardModule::runOnce() return disable(); } -/* - Create our data structure in the PSRAM. -*/ +/** + * Populates the PSRAM with data to be sent later when a device is out of range. + */ void StoreForwardModule::populatePSRAM() { /* @@ -82,6 +95,12 @@ void StoreForwardModule::populatePSRAM() LOG_DEBUG("*** numberOfPackets for packetHistory - %u\n", numberOfPackets); } +/** + * Sends messages from the message history to the specified recipient. + * + * @param msAgo The number of milliseconds ago from which to start sending messages. + * @param to The recipient ID to send the messages to. + */ void StoreForwardModule::historySend(uint32_t msAgo, uint32_t to) { uint32_t queueSize = storeForwardModule->historyQueueCreate(msAgo, to); @@ -101,6 +120,13 @@ void StoreForwardModule::historySend(uint32_t msAgo, uint32_t to) storeForwardModule->sendMessage(to, sf); } +/** + * Creates a new history queue with messages that were received within the specified time frame. + * + * @param msAgo The number of milliseconds ago to start the history queue. + * @param to The maximum number of messages to include in the history queue. + * @return The ID of the newly created history queue. + */ uint32_t StoreForwardModule::historyQueueCreate(uint32_t msAgo, uint32_t to) { @@ -141,6 +167,11 @@ uint32_t StoreForwardModule::historyQueueCreate(uint32_t msAgo, uint32_t to) return this->packetHistoryTXQueue_size; } +/** + * Adds a mesh packet to the history buffer for store-and-forward functionality. + * + * @param mp The mesh packet to add to the history buffer. + */ void StoreForwardModule::historyAdd(const meshtastic_MeshPacket &mp) { const auto &p = mp.decoded; @@ -162,6 +193,12 @@ meshtastic_MeshPacket *StoreForwardModule::allocReply() return reply; } +/** + * Sends a payload to a specified destination node using the store and forward mechanism. + * + * @param dest The destination node number. + * @param packetHistory_index The index of the packet in the packet history buffer. + */ void StoreForwardModule::sendPayload(NodeNum dest, uint32_t packetHistory_index) { LOG_INFO("*** Sending S&F Payload\n"); @@ -183,6 +220,12 @@ void StoreForwardModule::sendPayload(NodeNum dest, uint32_t packetHistory_index) service.sendToMesh(p); } +/** + * Sends a message to a specified destination node using the store and forward protocol. + * + * @param dest The destination node number. + * @param payload The message payload to be sent. + */ void StoreForwardModule::sendMessage(NodeNum dest, meshtastic_StoreAndForward &payload) { meshtastic_MeshPacket *p = allocDataProtobuf(payload); @@ -203,6 +246,12 @@ void StoreForwardModule::sendMessage(NodeNum dest, meshtastic_StoreAndForward &p service.sendToMesh(p); } +/** + * Sends a store-and-forward message to the specified destination node. + * + * @param dest The destination node number. + * @param rr The store-and-forward request/response message to send. + */ void StoreForwardModule::sendMessage(NodeNum dest, meshtastic_StoreAndForward_RequestResponse rr) { // Craft an empty response, save some bytes in flash @@ -211,6 +260,11 @@ void StoreForwardModule::sendMessage(NodeNum dest, meshtastic_StoreAndForward_Re storeForwardModule->sendMessage(dest, sf); } +/** + * Sends statistics about the store and forward module to the specified node. + * + * @param to The node ID to send the statistics to. + */ void StoreForwardModule::statsSend(uint32_t to) { meshtastic_StoreAndForward sf = meshtastic_StoreAndForward_init_zero; @@ -231,6 +285,12 @@ void StoreForwardModule::statsSend(uint32_t to) storeForwardModule->sendMessage(to, sf); } +/** + * Handles a received mesh packet, potentially storing it for later forwarding. + * + * @param mp The received mesh packet. + * @return A `ProcessMessage` indicating whether the packet was successfully handled. + */ ProcessMessage StoreForwardModule::handleReceived(const meshtastic_MeshPacket &mp) { #ifdef ARCH_ESP32 @@ -287,6 +347,13 @@ ProcessMessage StoreForwardModule::handleReceived(const meshtastic_MeshPacket &m return ProcessMessage::CONTINUE; // Let others look at this message also if they want } +/** + * Handles a received protobuf message for the Store and Forward module. + * + * @param mp The received MeshPacket to handle. + * @param p A pointer to the StoreAndForward object. + * @return True if the message was successfully handled, false otherwise. + */ bool StoreForwardModule::handleReceivedProtobuf(const meshtastic_MeshPacket &mp, meshtastic_StoreAndForward *p) { if (!moduleConfig.store_forward.enabled) {