From f079c86c1561debd550709cbdbd98f9ff0a213fc Mon Sep 17 00:00:00 2001
From: Tianda Huang <37414124+tiandahuang@users.noreply.github.com>
Date: Tue, 11 Jun 2024 17:46:21 -0500
Subject: [PATCH] docs & cleanup

---
 Apps/Inc/PrintCANHelper.h | 19 +++++++++++++++++++
 Apps/Src/PrintCANHelper.c | 34 +++++++++++++++++++++++++++++++++-
 Tasks/Src/Task_Amperes.c  |  2 --
 3 files changed, 52 insertions(+), 3 deletions(-)

diff --git a/Apps/Inc/PrintCANHelper.h b/Apps/Inc/PrintCANHelper.h
index 1273bcc1..a6b20cab 100644
--- a/Apps/Inc/PrintCANHelper.h
+++ b/Apps/Inc/PrintCANHelper.h
@@ -10,7 +10,26 @@
 #include "common.h"
 #include "CANMetaData.h"
 
+/**
+ * @brief Convert CANBus message into a human-readable space-separated string with a newline at the end
+ * 
+ * @param msg CANBus message to convert
+ * @param buf buffer to store result in. Must be at least 28 bytes long.
+ * @param validonly only print valid data in the CAN payload (otherwise print all 8 bytes)
+ * @param crc print out crc at the end of the message
+ * @return int length of message
+ */
 int CAN_ToHexString_HumanReadable(CANMSG_t *msg, void *buf, bool validonly, bool crc);
+
+/**
+ * @brief Convert CANBus message into a raw byte array. Array will start with 0xBE 0xEF as framing bytes.
+ * 
+ * @param msg CANBus message to convert
+ * @param buf buffer to store result in. Must be at least 14 bytes long.
+ * @param validonly only convert valid data in the CAN payload (otherwise convert all 8 bytes)
+ * @param crc append 8-bit crc as last byte of message
+ * @return int length of message
+ */
 int CAN_ToBytes(CANMSG_t *msg, void *buf, bool validonly, bool crc);
 
 #endif // PRINT_CAN_HELPER_H
diff --git a/Apps/Src/PrintCANHelper.c b/Apps/Src/PrintCANHelper.c
index 1829ca21..c0e9552a 100644
--- a/Apps/Src/PrintCANHelper.c
+++ b/Apps/Src/PrintCANHelper.c
@@ -6,15 +6,30 @@
 
 #include "PrintCANHelper.h"
 
+// lookup table for byte-to-string conversion
 static const char hex_lut[] = "0123456789ABCDEF";
 
+/**
+ * @brief convert a single byte to a 2-character hex string. not null terminated.
+ * 
+ * @param byte byte to convert
+ * @param buf  buffer to store the hex string. must be at least 2 bytes long.
+ */
 static inline void byte_to_hexstr(uint8_t byte, char *buf) {
     buf[0] = hex_lut[(byte >> 4) & 0x0F];   // high nibble
     buf[1] = hex_lut[byte & 0x0F];          // low nibble
 }
 
+// lookup table of precalculated crc values for each possible byte
 static const uint8_t crc8_SAE_J1850[256];
 
+/**
+ * @brief calculate 8-bit crc of data using SAE J1850 polynomial (0x1d).
+ * 
+ * @param data pointer to buffer
+ * @param len  length of data in buffer (in bytes)
+ * @return uint8_t crc result
+ */
 static uint8_t crc8(void *data, uint32_t len) {
     char *data_p = (char *)data;
     uint8_t crc = 0xFF;
@@ -24,6 +39,15 @@ static uint8_t crc8(void *data, uint32_t len) {
     return ~crc;
 }
 
+/**
+ * @brief Convert CANBus message into a human-readable space-separated string with a newline at the end
+ * 
+ * @param msg CANBus message to convert
+ * @param buf buffer to store result in. Must be at least 28 bytes long.
+ * @param validonly only print valid data in the CAN payload (otherwise print all 8 bytes)
+ * @param crc print out crc at the end of the message
+ * @return int length of message
+ */
 int CAN_ToHexString_HumanReadable(CANMSG_t *msg, void *buf, 
                                   bool validonly, bool crc) {
     char *buf_p = (char *)buf;
@@ -61,7 +85,15 @@ int CAN_ToHexString_HumanReadable(CANMSG_t *msg, void *buf,
     return end + 1; // excludes null term
 }
 
-
+/**
+ * @brief Convert CANBus message into a raw byte array. Array will start with 0xBE 0xEF as framing bytes.
+ * 
+ * @param msg CANBus message to convert
+ * @param buf buffer to store result in. Must be at least 14 bytes long.
+ * @param validonly only convert valid data in the CAN payload (otherwise convert all 8 bytes)
+ * @param crc append 8-bit crc as last byte of message
+ * @return int length of message
+ */
 int CAN_ToBytes(CANMSG_t *msg, void *buf, 
                 bool validonly, bool crc) {
     char *buf_p = (char *)buf;
diff --git a/Tasks/Src/Task_Amperes.c b/Tasks/Src/Task_Amperes.c
index e77df84b..21e4c6f2 100644
--- a/Tasks/Src/Task_Amperes.c
+++ b/Tasks/Src/Task_Amperes.c
@@ -63,8 +63,6 @@ void Task_AmperesMonitor(void *p_arg) {
             soc_data_send_prev_tick = (uint32_t)OSTimeGet(&err);
         }
 
-        // TODO: add averaging for AMPS and reduce rate for SoC
-
         //signal watchdog
         RTOS_BPS_MutexPend(&WDog_Mutex, OS_OPT_PEND_BLOCKING);