Serial Stream Refactor and Split-Channel Example by brocci · Pull Request #220 · SvenRosvall/VLCB-Arduino

brocci · 2026-06-17T21:47:22Z

This PR refactors serial bindings to use Arduino Stream instead of hard-wiring to global Serial, while preserving default behavior.

It also adds a new example showing split serial channels:

SerialGC on hardware Serial (GridConnect transport)
SerialUserInterface on SoftwareSerial or Serial1 on Mega2560 (user console)

Changes

Refactor SerialGC constructor/member type to Stream&
Keep transport stream protocol-clean in SerialGC::begin() (Removed startup banner print from begin)
Refactor SerialUserInterface to injected Stream& with default Serial
Add new split-channel example: examples/VLCB_SerialGC_SerialUI_SoftwareSerial/VLCB_SerialGC_SerialUI_SoftwareSerial.ino
Document new example in docs/Examples.md

Why

Allow SerialGC and SerialUserInterface to work with either HardwareSerial or SoftwareSerial (or other Stream-compatible ports).
Enable practical split-channel use where protocol traffic and UI commands are isolated.
Avoid accidental non-GridConnect text on the transport stream.

Compatibility

Existing sketches remain compatible via default constructors using Serial.
Behavior is unchanged unless an alternate stream is explicitly passed.

Closes #216

…xample

SvenRosvall · 2026-06-18T09:29:45Z

Quick early comment (before reviewing thoroughly) is that the name of the sketch is long. Also I'd like to include "empty" in the name to show what functionality it provides.

Suggest "VLCB_SerialGC_empty_withSerialUI.ino"
OK, that is not much shorter. :( The "SerialGC" must be there. Or can we shorten this marker? (applies to all serial example sketches) "VLCB" must be there to avoid confusion with the examples in the "CBUS" library if you work with both libraries.

Does this make sense?

brocci · 2026-06-18T09:54:05Z

Yes, it makes sense. The longest example filename is VLCB_long_message_example, 25 characters.
Would VLCB_SerialGC_SerialUI_empty be better?

…_SerialUI_empty

SvenRosvall · 2026-06-19T20:24:05Z

Would VLCB_SerialGC_SerialUI_empty be better?

Yes. it does. Just thinking that the "empty" bit should be earlier in the file name. But that would affect existing VLCB_SerialGC sketches. Need to think about a naming convention and if needed change all sketches.

SvenRosvall · 2026-06-19T20:29:44Z

@@ -0,0 +1,144 @@
+//  Copyright (C) Sven Rosvall (sven@rosvall.ie)


Please claim copyright for yourself.

Ahah. I didn't think about this ;-)

SvenRosvall · 2026-06-19T20:42:33Z

+  serialUserPort << F("> compiled on ") << __DATE__ << F(" at ") << __TIME__ << F(", compiler ver = ") << __cplusplus << endl;
+
+  // copyright
+  serialUserPort << F("> © Sven Rosvall (MERG 3777) 2026") << endl;


Claim copyright for yourself. ;)

Well, 90% of the code is yours. But OK ;-)

SvenRosvall · 2026-06-19T20:43:29Z

+//
+/// print code version config details and copyright notice
+//
+void printConfig()


Can you put this function at the bottom of this file. Then it is easier to compare the different "*_empty" sketches.

I thought I had put it back in my last commit. Need to check.

SvenRosvall · 2026-06-19T20:45:48Z

-{
-}
-
-Serial_T & operator<<(Serial_T & s, int i)


I implemented these operators this way so that any debug info would be printed in the text outputs for the unit tests. This is handy when troubleshooting.

Can you keep these operators but change to use your Stream class?

I will have a look.

SvenRosvall · 2026-06-19T20:51:57Z


-struct Serial_T
-{
-  void begin(int baudrate);


This begin() function is used by the example sketches.

No, these headers are not used by the Arduino IDE or your new workflows when compiling the example sketches. However I also use the headers in the Arduino directory for my IDE (CLion) so that the example sketch codes come up nicely in the IDE without any red markers. So please keep the begin() function in the Stream.h .

SvenRosvall · 2026-06-19T20:54:30Z

+  virtual void flush() {}
+};
+
+// Operator overloads for Stream to work with Streaming library


These operators don't need definitions in the Arduino directory. This directory is only used to make my IDE work well with Arduino code.
For executing test code the definitions should reside in ArduinoMock.cpp in the test directory. See also comments there.

SvenRosvall · 2026-06-19T20:56:46Z

  {
  public:
-    SerialGC(typeof(Serial)& _serial = Serial) : serial(_serial) {}
+    SerialGC(Stream& _serial = Serial) : serial(_serial) {}


Yes! That looks much nicer. Should have done that from the beginning. :)

SvenRosvall · 2026-06-19T21:00:59Z

 {
 public:
  /// @cond LIBRARY
+  SerialUserInterface(Stream& _serial = Serial) : serial(_serial) {}


The constructor should be declared above the @cond line.
The @cond tells Doxygen to ignore a block (until @endcond) of declarations. This is useful to reduce the amount of documentation a sketch developer needs to see. (The library developer needs to see everything.)
This constructor is something a sketch developer will use and thus it should be include in the sketch developer documentation.

SvenRosvall · 2026-06-19T21:05:05Z

Thanks for this pull request. It looks good. Will be a good feature. I know John Fletcher will be happy about this.

The comments I have added are mostly about my style and how I work with this project. Sorry that this is not documented properly. So the comments are there to share this until I get that bit done.

brocci · 2026-06-19T21:50:32Z

Thanks for this pull request. It looks good. Will be a good feature. I know John Fletcher will be happy about this.

Thank you. I will fix the remaining "glitches" and commit on this PR. Happy to make John happy :-)

The comments I have added are mostly about my style and how I work with this project. Sorry that this is not documented properly. So the comments are there to share this until I get that bit done.

No problem.

brocci added 3 commits June 17, 2026 23:27

Use Stream abstraction for serial services

59ca9f5

Fix CMake desktop build: add Stream.h mock, remove Serial_T indirection

ad582f6

Add Serial1 option for the SerialUserInterface to split SerialGC/UI e…

7ab0208

…xample

brocci marked this pull request as ready for review June 17, 2026 21:49

SvenRosvall requested review from SvenRosvall and david284 June 17, 2026 22:20

Rename VLCB_SerialGC_SerialUI_SoftwareSerial example to VLCB_SerialGC…

5309770

…_SerialUI_empty

SvenRosvall reviewed Jun 19, 2026

View reviewed changes

Fix Mockup for Stream. Update copyrights in example.

fff3c9b

		@@ -0,0 +1,144 @@
		// Copyright (C) Sven Rosvall (sven@rosvall.ie)

Conversation

brocci commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Why

Compatibility

Uh oh!

SvenRosvall commented Jun 18, 2026

Uh oh!

brocci commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SvenRosvall commented Jun 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SvenRosvall commented Jun 19, 2026

Uh oh!

brocci commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

brocci commented Jun 17, 2026 •

edited

Loading

brocci commented Jun 18, 2026 •

edited

Loading

brocci commented Jun 19, 2026 •

edited

Loading