Enable the injection of a prefined message before after a message. (#19)

Author: aentinger

examples/ts_serial_prefix_suffix/ts_serial_prefix_suffix.ino

@@ -0,0 +1,83 @@
+/**************************************************************************************
+ * INCLUDE
+ **************************************************************************************/
+
+#include <Arduino_ThreadsafeIO.h>
+
+/**************************************************************************************
+ * CONSTANTS
+ **************************************************************************************/
+
+static size_t constexpr NUM_THREADS = 5;
+
+/**************************************************************************************
+ * FUNCTION DECLARATION
+ **************************************************************************************/
+
+void serial_thread_func();
+
+/**************************************************************************************
+ * GLOBAL VARIABLES
+ **************************************************************************************/
+
+static char thread_name[NUM_THREADS][32];
+#undef Serial
+#ifdef ARDUINO_PORTENTA_H7_M4
+  SerialDispatcher Serial(Serial1); /* No SerialUSB for Portenta H7 / M4 Core */
+#else
+  SerialDispatcher Serial(SerialUSB);
+#endif
+
+/**************************************************************************************
+ * SETUP/LOOP
+ **************************************************************************************/
+
+void setup()
+{
+  /* Fire up some threads all accessing the LSM6DSOX */
+  for(size_t i = 0; i < NUM_THREADS; i++)
+  {
+    snprintf(thread_name[i], sizeof(thread_name[i]), "Thread #%02d", i);
+    rtos::Thread * t = new rtos::Thread(osPriorityNormal, OS_STACK_SIZE, nullptr, thread_name[i]);
+    t->start(serial_thread_func);
+  }
+}
+
+void loop()
+{
+
+}
+
+/**************************************************************************************
+ * FUNCTION DEFINITION
+ **************************************************************************************/
+
+void serial_thread_func()
+{
+  Serial.begin(9600);
+
+  char const * thread_name = rtos::ThisThread::get_name();
+  Serial.prefix([thread_name]() -> String
+                {
+                  char msg[64] = {0};
+                  snprintf(msg, sizeof(msg), "[%05lu] %s ", millis(), thread_name);
+                  return String(msg);
+                });
+  Serial.suffix([]() -> String
+                {
+                  return String("\r\n");
+                });
+
+  for(;;)
+  {
+    /* Sleep between 5 and 500 ms */
+    rtos::ThisThread::sleep_for(rtos::Kernel::Clock::duration_u32(random(5,500)));
+    /* Print a unbroken log message including thread name and timestamp as a prefix. */
+    Serial.block();
+    Serial.print("My ");
+    Serial.print("unbroken ");
+    Serial.print("thread-safe ");
+    Serial.print("message!");
+    Serial.unblock();
+  }
+}

keywords.txt

@@ -22,6 +22,8 @@ transfer	KEYWORD2
 create	KEYWORD2
 block	KEYWORD2
 unblock	KEYWORD2
+prefix	KEYWORD2
+suffix	KEYWORD2
 
 #######################################
 # Constants (LITERAL1)

src/serial/SerialDispatcher.cpp

@@ -69,6 +69,8 @@ void SerialDispatcher::begin(unsigned long baudrate, uint16_t config)
     ThreadCustomerData data;
     data.thread_id = current_thread_id;
     data.block_tx_buffer = false;
+    data.prefix_func = nullptr;
+    data.suffix_func = nullptr;
     _thread_customer_list.push_back(data);
   }
 }
@@ -184,6 +186,22 @@ void SerialDispatcher::unblock()
   _cond.notify_one();
 }
 
+void SerialDispatcher::prefix(PrefixInjectorCallbackFunc func)
+{
+  mbed::ScopedLock<rtos::Mutex> lock(_mutex);
+  auto iter = findThreadCustomerDataById(rtos::ThisThread::get_id());
+  if (iter == std::end(_thread_customer_list)) return;
+  iter->prefix_func = func;
+}
+
+void SerialDispatcher::suffix(SuffixInjectorCallbackFunc func)
+{
+  mbed::ScopedLock<rtos::Mutex> lock(_mutex);
+  auto iter = findThreadCustomerDataById(rtos::ThisThread::get_id());
+  if (iter == std::end(_thread_customer_list)) return;
+  iter->suffix_func = func;
+}
+
 /**************************************************************************************
  * PRIVATE MEMBER FUNCTIONS
  **************************************************************************************/
@@ -208,10 +226,46 @@ void SerialDispatcher::threadFunc()
                       if (d.block_tx_buffer)
                         return;
 
+                      /* Return if there's no data to be written to the
+                       * serial interface. This statement is necessary
+                       * because otherwise the prefix/suffix functions
+                       * will be invoked and will be printing something,
+                       * even though no data is actually to be printed for
+                       * most threads.
+                       */
+                      if (!d.tx_buffer.available())
+                        return;
+
+                      /* The prefix callback function allows the
+                       * user to insert a custom message before
+                       * a new message is written to the serial
+                       * driver. This is useful e.g. for wrapping
+                       * protocol (e.g. the 'AT' protocol) or providing
+                       * a timestamp, a log level, ...
+                       */
+                      if (d.prefix_func)
+                      {
+                        String const prefix_str = d.prefix_func();
+                        _serial.write(prefix_str.c_str());
+                      }
+
+                      /* Now it's time to actually write the message
+                       * conveyed by the user via Serial.print/println.
+                       */
                       while(d.tx_buffer.available())
                       {
                         _serial.write(d.tx_buffer.read_char());
                       }
+
+                      /* Similar to the prefix function this callback
+                       * allows the user to specify a specific message
+                       * to be appended to each message, e.g. '\r\n'.
+                       */
+                      if (d.suffix_func)
+                      {
+                        String const suffix_str = d.suffix_func();
+                        _serial.write(suffix_str.c_str());
+                      }
                     });
   }
 }

src/serial/SerialDispatcher.h

@@ -28,6 +28,7 @@
 #include <mbed.h>
 
 #include <list>
+#include <functional>
 
 #include <SharedPtr.h>
 
@@ -58,6 +59,12 @@ class SerialDispatcher : public arduino::HardwareSerial
   void block();
   void unblock();
 
+  typedef std::function<String(void)> PrefixInjectorCallbackFunc;
+  typedef PrefixInjectorCallbackFunc  SuffixInjectorCallbackFunc;
+  void prefix(PrefixInjectorCallbackFunc func);
+  void suffix(SuffixInjectorCallbackFunc func);
+
+
 private:
 
   bool _is_initialized;
@@ -75,6 +82,8 @@ class SerialDispatcher : public arduino::HardwareSerial
     arduino::RingBuffer tx_buffer;
     bool block_tx_buffer;
     mbed::SharedPtr<arduino::RingBuffer> rx_buffer; /* Only when a thread has expressed interested to read from serial a receive ringbuffer is allocated. */
+    PrefixInjectorCallbackFunc prefix_func;
+    SuffixInjectorCallbackFunc suffix_func;
   } ThreadCustomerData;
 
   std::list<ThreadCustomerData> _thread_customer_list;