Serial Stream Refactor and Split-Channel Example

.gitignore

@@ -3,7 +3,35 @@
 *.exe
 *.out
 
-.DS_Store
 .idea
 build
 
+#
+# MacOS
+#
+.DS_Store
+.localized
+__MACOSX/
+.AppleDouble
+._*
+
+#
+# Visual Studio Code
+#
+.vscode/
+!.vscode/settings.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+!*.code-workspace
+# Built Visual Studio Code Extensions
+*.vsix
+
+#
+# PlatformIO
+#
+.pio
+.pioenvs
+.piolibdeps
+
+# Local working notes
+notes/

Arduino/Arduino.h

@@ -4,6 +4,7 @@
 #include <cstdlib>
 #include <cstring>
 #include <cstdio>
+#include <Stream.h>
 
 #define F(s) s
 
@@ -28,15 +29,4 @@ void pinMode(int, PinMode);
 void digitalWrite(int, PinState);
 byte digitalRead(int);
 
-struct Serial_T
-{
-  void begin(int baudrate);
-
-  bool available();
-  char read();
-  void flush();
-  unsigned char readBytesUntil(int termChar, char *string, int length);
-  void print(const char *);
-  void println(const char *);
-};
-extern struct Serial_T Serial;
+extern Stream Serial;

Arduino/Stream.h

@@ -0,0 +1,17 @@
+#pragma once
+
+struct ENDL_T;
+
+class Stream
+{
+public:
+  Stream() = default;
+  virtual ~Stream() = default;
+
+  virtual void begin(int);
+  virtual bool available();
+  virtual char read();
+  virtual void print(const char *);
+  virtual void println(const char *);
+  virtual void flush();
+};

Arduino/Streaming.h

@@ -1,15 +1,17 @@
 #pragma once
 
 #include <Arduino.h>
+#include <Stream.h>
 
 struct ENDL_T {};
 
-Serial_T & operator<<(Serial_T &, int);
-Serial_T & operator<<(Serial_T &, unsigned int);
-Serial_T & operator<<(Serial_T &, long);
-Serial_T & operator<<(Serial_T &, unsigned long);
-Serial_T & operator<<(Serial_T &, const char *);
-Serial_T & operator<<(Serial_T & s, const ENDL_T & e);
+Stream & operator<<(Stream &, int);
+Stream & operator<<(Stream &, unsigned int);
+Stream & operator<<(Stream &, long);
+Stream & operator<<(Stream &, unsigned long);
+Stream & operator<<(Stream &, const char *);
+Stream & operator<<(Stream & s, const ENDL_T & e);
+
 extern ENDL_T endl;
 template <typename T> T _HEX(T v) { return v;}
 template <typename T> T _WIDTH(T v, int width) { return v;}

CMakeLists.txt

@@ -112,6 +112,7 @@ add_executable(VLCB_Arduino
         examples/VLCB_SerialGC_4in4out/VLCB_SerialGC_4in4out.ino
         examples/VLCB_SerialGC_4in4out_slot/VLCB_SerialGC_4in4out_slot.ino
         examples/VLCB_SerialGC_empty/VLCB_SerialGC_empty.ino
+        examples/VLCB_SerialGC_SerialUI_empty/VLCB_SerialGC_SerialUI_empty.ino
 )
 
 add_executable(testAll

README.md

@@ -93,7 +93,7 @@ by email to vlcb@rosvall.ie or create an [issue in GitHub](https://github.com/Sv
 * John Fletcher - Contributor
 * Chris Andrews - Contributor
 * David Ellis - Contributor
-* brocci - Contributor to the CBUS library
+* Bruno Rocci - Contributor to the CBUS library
 
 ## License
 

docs/Examples.md

@@ -107,3 +107,11 @@ use for programming the Arduino.
 You can then start FCU (or any other configuration utility) and connect through
 this serial port.
 The FCU will then communicate with your Arduino module as a CBUS module.
+
+## [VLCB_SerialGC_SerialUI_empty](../examples/VLCB_SerialGC_SerialUI_empty/VLCB_SerialGC_SerialUI_empty.ino)
+This example demonstrates split serial usage on a single node.
+The hardware serial port is dedicated to [SerialGC](../docs/CanTransport.md) for VLCB/GridConnect traffic,
+while a separate SoftwareSerial port is used for [SerialUserInterface](SerialUserInterface.md) commands and status output.
+
+This layout is useful when you want to keep the transport channel and the user console separate.
+It also shows the intended use of the Stream-based serial refactor for either HardwareSerial or SoftwareSerial.

examples/VLCB_SerialGC_SerialUI_empty/VLCB_SerialGC_SerialUI_empty.ino

@@ -0,0 +1,143 @@
+//  Copyright (C) Bruno Rocci (bruno_rocci@hotmail.com)
+//  This file is part of VLCB-Arduino project on https://github.com/SvenRosvall/VLCB-Arduino
+//  Licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
+//  The full licence can be found at: http://creativecommons.org/licenses/by-nc-sa/4.0
+
+/*
+      3rd party libraries needed for compilation: (not for binary-only distributions)
+
+      Streaming      -- C++ stream style output, v5, (http://arduiniana.org/libraries/streaming/)
+      SoftwareSerial -- Arduino software serial library (not needed when USE_MEGA_SERIAL1 is set)
+*/
+
+// This example demonstrates split serial usage:
+//
+// - SerialGC uses the default hardware Serial port for GridConnect transport
+// - SerialUserInterface uses SoftwareSerial for user commands and status output
+// - Optionally, hardware Serial1 can be used for the SerialUserInterface on Mega2560 by setting the USE_MEGA_SERIAL1 build flag in platformio.ini
+//
+// This is useful on boards where the USB serial port is already committed to
+// the VLCB/GridConnect transport, but a separate command console is still wanted.
+//
+// Based on VLCB_SerialGC_empty example from Sven Rosvall (MERG 3777)
+
+// 3rd party libraries
+#include <Streaming.h>
+#ifndef USE_MEGA_SERIAL1
+#include <SoftwareSerial.h>
+#endif
+
+// VLCB library header files
+#include <VLCB.h>
+#include <SerialGC.h>
+#include <SerialUserInterface.h>
+
+// forward function declarations
+void printConfig();
+
+// constants
+const byte VER_MAJ = 1;             // code major version
+const char VER_MIN = 'a';           // code minor version
+const byte VER_BUILD = 0;           // code build number
+const byte MANUFACTURER = MANU_DEV; // for boards in development.
+const byte MODULE_ID = 98;          // VLCB module type
+
+// module name, must be at most 7 characters
+char mname[] = "SPLIT";
+
+const byte LED_GRN = 4;             // VLCB green Unitialised LED pin
+const byte LED_YLW = 7;             // VLCB yellow Normal LED pin
+const byte SWITCH0 = 8;             // VLCB push button switch pin
+
+#ifdef USE_MEGA_SERIAL1
+// Use hardware Serial1 on pins 18 (TX1) and 19 (RX1)
+#define serialUserPort Serial1
+#else
+// Use SoftwareSerial on pins 2 (RX) and 3 (TX)
+const byte UI_RX_PIN = 2;
+const byte UI_TX_PIN = 3;
+SoftwareSerial serialUserPort(UI_RX_PIN, UI_TX_PIN);
+#endif
+
+// module objects
+VLCB::SerialGC serialGC(Serial);                 // CAN transport object using hardware serial
+VLCB::SerialUserInterface serialUserInterface(serialUserPort);
+
+// Service objects
+VLCB::LEDUserInterface ledUserInterface(LED_GRN, LED_YLW, SWITCH0);
+VLCB::MinimumNodeServiceWithDiagnostics mnService;
+VLCB::CanService serialCanService(&serialGC);
+
+//
+/// setup VLCB - runs once at power on from setup()
+//
+void setupVLCB()
+{
+  VLCB::checkStartupAction(LED_GRN, LED_YLW, SWITCH0);
+
+  VLCB::setServices({
+    &mnService, &ledUserInterface, &serialUserInterface, &serialCanService});
+
+  // set module parameters
+  VLCB::setVersion(VER_MAJ, VER_MIN, VER_BUILD);
+  VLCB::setModuleId(MANUFACTURER, MODULE_ID);
+
+  // set module name
+  VLCB::setName(mname);
+
+  // initialise and load configuration
+  VLCB::begin();
+
+  // show code version and copyright notice on the UI console
+  serialUserPort << F("> mode = ") << VLCB::Configuration::modeString(VLCB::getCurrentMode());
+  serialUserPort << F(", CANID = ") << VLCB::getCANID();
+  serialUserPort << F(", NN = ") << VLCB::getNodeNum() << endl;
+
+  printConfig();
+}
+
+//
+/// setup - runs once at power on
+//
+void setup()
+{
+  Serial.begin(115200);
+  serialUserPort.begin(9600);
+  delay(2000);  // Give some time to PIO to open the serial monitor before printing anything
+
+#ifdef USE_MEGA_SERIAL1
+  serialUserPort << F("> ** VLCB split: SerialGC + Serial1 UI example ** ") << __FILE__ << endl;
+#else
+  serialUserPort << F("> ** VLCB split: SerialGC + SoftwareSerial UI example ** ") << __FILE__ << endl;
+#endif
+
+  setupVLCB();
+
+  serialUserPort << F("> ready") << endl << endl;
+}
+
+//
+/// loop - runs forever
+//
+void loop()
+{
+  //
+  /// do VLCB message, switch and LED processing
+  //
+  VLCB::process();
+
+  // bottom of loop()
+}
+
+//
+/// print code version config details and copyright notice
+//
+void printConfig()
+{
+  // code version
+  serialUserPort << F("> code version = ") << VER_MAJ << VER_MIN << F(" build ") << VER_BUILD << endl;
+  serialUserPort << F("> compiled on ") << __DATE__ << F(" at ") << __TIME__ << F(", compiler ver = ") << __cplusplus << endl;
+
+  // copyright
+  serialUserPort << F("> Copyright © 2026 Bruno Rocci (MERG 9690)") << endl;
+}

src/SerialGC.cpp

@@ -19,7 +19,6 @@ namespace VLCB
 
   bool SerialGC::begin()  
   {
-    Serial << F("> ** GridConnect over serial ** ") << endl;
     receivedCount = 0;
     transmitCount = 0;
     return true;

src/SerialGC.h

@@ -7,6 +7,7 @@
 
 // header files
 #include <Arduino.h>
+#include <Stream.h>
 #include <Controller.h>
 #include <CanTransport.h>
 #include <GridConnect.h>
@@ -24,7 +25,7 @@ namespace VLCB
   class SerialGC : public CanTransport
   {
   public:
-    SerialGC(typeof(Serial)& _serial = Serial) : serial(_serial) {}
+    SerialGC(Stream& _serial = Serial) : serial(_serial) {}
     /// @cond LIBRARY
     bool begin();
 
@@ -48,7 +49,7 @@ namespace VLCB
     /// @endcond
 
   private:
-    typeof(Serial)& serial;
+    Stream& serial;
 
     char rxBuffer[RXBUFFERSIZE]; // Define a byte array to store the incoming data
     char txBuffer[RXBUFFERSIZE]; // Define a byte array to store the outgoing data