Support Serial output to STDERR (replaces #92)

Author: bxparks

CHANGELOG.md

@@ -1,6 +1,8 @@
 # Changelog
 
 * Unreleased
+    * Support sending output of `Serial` port to `STDERR`
+      (replaces [PR#92](https://github.com/bxparks/EpoxyDuino/pull/92).
 * 1.6.0 (2024-07-25)
     * Add `strncat_P()` to `pgmspace.h`.
     * Add `ESP.restart()` and `ESP.getChipId()`. See

README.md

@@ -106,6 +106,8 @@ The disadvantages are:
     * [Serial Port Emulation](#SerialPortEmulation)
         * [Unix Line Mode](#UnixLineMode)
         * [Enable Terminal Echo](#EnableTerminalEcho)
+        * [Output to STDERR](#OutputToStderr)
+        * [Multiple Serial Ports](#MultipleSerialPorts)
 * [Libraries and Mocks](#LibrariesAndMocks)
     * [Inherently Compatible Libraries](#InherentlyCompatibleLibraries)
     * [Emulation Libraries](#EmulationLibraries)
@@ -1062,7 +1064,7 @@ test(myTest) {
 ```
 
 <a name="EnableTerminalEcho"></a>
-#### Enable Terminal Echno
+#### Enable Terminal Echo
 
 By default, the `stdin` of the terminal is set to `NOECHO` mode for consistency
 with the actual serial port of an Arduino microcontroller. However when running
@@ -1084,6 +1086,45 @@ void setup() {
 }
 ```
 
+<a name="OutputToStderr"></a>
+#### Output to STDERR
+
+By default, the `Serial` instance sends its output to the STDOUT (file
+descriptor `STDOUT_FILENO`, i.e. 1). We can override that to send the output to
+STDERR (file descriptor `STDERR_FILENO`) using the
+`StdioSerial::setOutputFileDescriptor(int fd)` method:
+
+```C++
+Serial.println("This goes to STDOUT");
+Serial.setOutputFileDescriptor(STDERR_FILENO);
+Serial.println("This goes to STDERR");
+```
+
+<a name="MultipleSerialPorts"></a>
+#### Multiple Serial Ports
+
+By default, a default instance of `StdioSerial` class is created named `Serial`,
+which matches the behavior of the Arduino programming framework on actual
+microcontrollers which a single serial port is provided by default.
+
+Some microcontrollers provide multiple serial ports, often called `Serial1` or
+`Serial2`. We can emulate that in EpoxyDuino by creating additional instances of
+`StdioSerial`. The following creates a `Serial1` instances bound to STDOUT, and
+another `Serial2` bound to STDERR:
+
+```C++
+#ifdef EPOXY_DUINO
+StdioSerial Serial1(STDOUT_FILENO);
+StdioSerial Serial2(STDERR_FILENO);
+...
+void someFunction() {
+    Serial1.println("Print to STDOUT");
+    Serial2.println("Print to STDERR");
+    ...
+}
+#endif
+```
+
 <a name="LibrariesAndMocks"></a>
 ## Libraries and Mocks
 

cores/epoxy/StdioSerial.cpp

@@ -4,11 +4,11 @@
  */
 
 #include <stdio.h>
-#include <unistd.h>
+#include <unistd.h> // STDIN_FILENO
 #include "StdioSerial.h"
 
 size_t StdioSerial::write(uint8_t c) {
-  ssize_t status = ::write(STDOUT_FILENO, &c, 1);
+  ssize_t status = ::write(outputFd, &c, 1);
   return (status <= 0) ? 0 : 1;
 }
 

cores/epoxy/StdioSerial.h

@@ -6,6 +6,7 @@
 #ifndef EPOXY_DUINO_STDIO_SERIAL_H
 #define EPOXY_DUINO_STDIO_SERIAL_H
 
+#include <unistd.h> // STDOUT_FILENO
 #include "Print.h"
 #include "Stream.h"
 
@@ -15,6 +16,20 @@
  */
 class StdioSerial: public Stream {
   public:
+    /**
+     * Construct an instance. The default output file descriptor is
+     * STDOUT_FILENO, but STDERR_FILENO is another option. POSIX.1-2017 defines
+     * these values in <unistd.h> (see
+     * https://unix.stackexchange.com/questions/437602).
+     */
+    StdioSerial(int fd = STDOUT_FILENO) : outputFd(fd) { }
+
+    /**
+     * Override the output file descriptor. Two common values are expected to be
+     * STDOUT_FILENO and STDERR_FILENO.
+     */
+    void setOutputFileDescriptor(int fd) { outputFd = fd; }
+
     void begin(unsigned long /*baud*/) { bufch = -1; }
 
     size_t write(uint8_t c) override;
@@ -37,6 +52,7 @@ class StdioSerial: public Stream {
     int peek() override;
 
   private:
+    int outputFd;
     int bufch;
 };
 

examples/StdioSerialMultiple/Makefile

@@ -0,0 +1,6 @@
+# See https://github.com/bxparks/EpoxyDuino for documentation about this
+# Makefile to compile and run Arduino programs natively on Linux or MacOS.
+
+APP_NAME := StdioSerialMultiple
+ARDUINO_LIBS :=
+include ../../../EpoxyDuino/EpoxyDuino.mk

examples/StdioSerialMultiple/StdioSerialMultiple.ino

@@ -0,0 +1,41 @@
+/*
+ * Test emulation of multiple Serial ports.
+ *
+ * $ ./StdioSerialMultiple.out
+ * Printing to STDOUT
+ * Printing to STDERR
+ *
+ * $ ./StdioSerialMultiple.out > /dev/null
+ * Printing to STDERR
+ */
+
+#include <Arduino.h>
+
+//-----------------------------------------------------------------------------
+
+#if defined(EPOXY_DUINO)
+StdioSerial Serial1(STDOUT_FILENO);
+StdioSerial Serial2(STDERR_FILENO);
+#endif
+
+
+void setup(void) {
+#if ! defined(EPOXY_DUINO)
+  delay(1000);
+#endif
+
+  Serial1.begin(115200);
+  Serial2.begin(115200);
+  while (!Serial1);
+  while (!Serial2);
+
+#if defined(EPOXY_DUINO)
+  Serial1.setLineModeUnix();
+  Serial2.setLineModeUnix();
+#endif
+
+  Serial1.println(F("Printing to STDOUT"));
+  Serial2.println(F("Printing to STDERR"));
+}
+
+void loop(void) {}