serial.h

Go to the documentation of this file.

// src/fl/remote/transport/serial.h
// Cross-platform serial transport layer for JSON-RPC
// Provides factory functions for creating RequestSource and ResponseSink callbacks
 
#pragma once
 
#include "fl/stl/json.h"
#include "fl/log/log.h"  // IWYU pragma: keep -- FL_WARN
#include "fl/system/delay.h"
#include "fl/stl/int.h"
#include "fl/stl/cctype.h"
#include "fl/stl/chrono.h"
// fl/stl/cstdio.h is REQUIRED here: this header calls fl::available,
// fl::read, fl::readLine, and fl::println, all declared in cstdio.h. PR
// #2685 tried to drop this include and rely on a strstream.h -> ostream.h
// -> cstdio.h transitive chain to work around zackees/zccache#619
// (Windows PCH path-spelling drift), but strstream.h does NOT include
// ostream.h, so the chain is broken on every non-PCH build (teensy,
// every Arduino ARM/AVR target, etc.) — see issue #2647-style follow-up.
// The Windows PCH dedup issue is fixed by the meson.build path
// normalization that landed in the same PR.
#include "fl/stl/cstdio.h"
#include "fl/stl/cstring.h"
#include "fl/stl/function.h"
#include "fl/stl/optional.h"
#include "fl/stl/pair.h"
#include "fl/stl/string.h"
#include "fl/stl/strstream.h"
#include "fl/stl/string_view.h"
#include "fl/remote/rpc/response_stream.h"
#include "fl/stl/noexcept.h"
 
namespace fl {
 
// =============================================================================
// Core Serialization Functions (Pure, No I/O)
// =============================================================================
// These functions have no I/O dependencies and are easily unit-testable

fl::string formatJsonResponse(const fl::json& response, const char* prefix = "") FL_NO_EXCEPT;
 
// =============================================================================
// Generic I/O Functions (Templated for Testability)
// =============================================================================

template<typename SerialIn>
fl::optional<fl::string> readSerialLine(SerialIn& serial, char delimiter = '\n', fl::optional<u32> timeoutMs = fl::nullopt) FL_NO_EXCEPT;

template<typename SerialOut>
void writeSerialLine(SerialOut& serial, const fl::string& str) FL_NO_EXCEPT;
 
// =============================================================================
// Serial Adapters (Using fl:: Functions)
// =============================================================================

struct SerialReader {
    int available() const FL_NO_EXCEPT { return fl::available(); }
    int read() FL_NO_EXCEPT { return fl::read(); }
};

inline fl::optional<fl::string> readSerialLine(SerialReader& serial, char delimiter = '\n', fl::optional<u32> timeoutMs = fl::nullopt) FL_NO_EXCEPT {
    (void)serial;  // Unused, we call fl::readLine() directly
    return fl::readLine(delimiter, '\r', timeoutMs);
}

struct SerialWriter {
    void println(const char* str) FL_NO_EXCEPT { fl::println(str); }
    void write(const char* data, fl::size len) FL_NO_EXCEPT {
        fl::write_bytes(reinterpret_cast<const fl::u8*>(data), len);  // ok reinterpret cast
    }
};
 
// =============================================================================
// Remote Callback Factories (Creates RequestSource and ResponseSink)
// =============================================================================

constexpr fl::size kDroppedRequestWarnBytes = 64;
 
inline fl::function<fl::optional<fl::json>()>
createSerialRequestSource(const char* prefix = "") FL_NO_EXCEPT {
    return [prefix]() -> fl::optional<fl::json> {
        // Non-blocking check - any data available?
        int avail = fl::available();
        if (avail <= 0) {
            return fl::nullopt;
        }
 
        // Data available - read a complete line.
        // On Arduino platforms, fl::readLine() delegates to Serial.readStringUntil()
        // which uses yield() (immediate context switch) for fast USB CDC multi-packet
        // assembly. On other platforms, falls back to character-by-character reading.
        auto line = fl::readLine('\n', '\r', fl::optional<u32>(1000));
        if (!line.has_value() || line->empty()) {
            return fl::nullopt;
        }
 
        // Use string_view for zero-copy prefix stripping and trimming
        fl::string_view view = *line;
 
        // Strip prefix if present
        if (prefix && prefix[0] != '\0') {
            if (view.starts_with(prefix)) {
                view.remove_prefix(fl::strlen(prefix));
            }
        }
 
        // Trim leading whitespace
        while (!view.empty() && fl::isspace(view.front())) {
            view.remove_prefix(1);
        }
 
        // Trim trailing whitespace
        while (!view.empty() && fl::isspace(view.back())) {
            view.remove_suffix(1);
        }
 
        // Only parse if input starts with '{'
        if (view.empty() || view[0] != '{') {
            // A short line here is ordinary serial noise -- boot banners,
            // stray newlines -- and warning about it would drown the log.
            // A long one is almost certainly a request that arrived damaged,
            // and dropping that silently is expensive to debug: the caller
            // sees no reply and no error, indistinguishable from an idle
            // link, while the device keeps answering everything else. That
            // is exactly how a receive-buffer truncation presented in
            // FastLED#3956 -- 735 bytes transmitted, nothing returned, and
            // no layer saying anything.
            // Measure what arrived, not what survived normalisation: the
            // view above has had its prefix stripped and whitespace trimmed,
            // so a 64-byte line can fall under the threshold and stay silent,
            // and the reported count would understate what was received.
            if (line->size() >= kDroppedRequestWarnBytes) {
                FL_WARN("[RPC] discarded a " << (static_cast<unsigned>(line->size())) << " byte line that does not begin with '{'; a request that arrived truncated looks exactly like this");
            }
            return fl::nullopt;
        }
 
        // Single copy when parsing JSON (unavoidable - JSON needs owned string)
        fl::string input(view);
        return fl::json::parse(input);
    };
}

inline fl::function<void(const fl::json&)>
createSerialResponseSink(const char* prefix = "REMOTE: ") FL_NO_EXCEPT {
    return [prefix](const fl::json& response) {
        // Format and write to serial (no filtering needed - protocol uses flat structure)
        SerialWriter serial;
        fl::string formatted = formatJsonResponse(response, prefix);
        writeSerialLine(serial, formatted);
    };
}

inline fl::ResponseStreamSink
createSerialResponseStreamSink(const char* prefix = "REMOTE: ") FL_NO_EXCEPT {
    return [prefix](fl::JsonStreamCallback writeJson) {
        SerialWriter serial;
        if (prefix && prefix[0] != '\0') {
            serial.write(prefix, fl::strlen(prefix));
        }
 
        fl::JsonStreamWriter writer([&serial](const char* data, fl::size len) {
            serial.write(data, len);
        });
        if (writeJson) {
            writeJson(writer);
        }
        writer.flush();
        serial.write("\n", 1);
        fl::flush();
    };
}

inline fl::pair<fl::function<fl::optional<fl::json>()>, fl::function<void(const fl::json&)>>
createSerialTransport(const char* responsePrefix = "REMOTE: ", const char* requestPrefix = "") FL_NO_EXCEPT {
    return {createSerialRequestSource(requestPrefix), createSerialResponseSink(responsePrefix)};
}
 
// =============================================================================
// Template Implementations
// =============================================================================
 
template<typename SerialIn>
fl::optional<fl::string> readSerialLine(SerialIn& serial, char delimiter, fl::optional<u32> timeoutMs) FL_NO_EXCEPT {
    // Delegate to readSerialStringUntil with default skipChar='\r'
    return readSerialStringUntil(serial, delimiter, '\r', timeoutMs);
}
 
template<typename SerialIn>
fl::optional<fl::string> readSerialStringUntil(SerialIn& serial, char delimiter, char skipChar, fl::optional<u32> timeoutMs) FL_NO_EXCEPT {
    // Follows Arduino Serial.readStringUntil() API - blocks until delimiter found
    fl::sstream buffer;
 
    u32 startTime = fl::millis();
 
    // Read characters until we find delimiter or timeout
    while (true) {
        // Check timeout (only if timeout is set)
        if (timeoutMs.has_value()) {
            if (fl::millis() - startTime >= timeoutMs.value()) {
                // Timeout occurred - return nullopt
                return fl::nullopt;
            }
        }
 
        // Try to read next character
        int c = serial.read();
 
        // Handle -1 (no data available) like Arduino's timedRead():
        // Keep trying until timeout (or forever if no timeout set)
        if (c == -1) {
            // Brief 1us yield instead of 1ms delay for fast USB CDC polling.
            fl::delayMicroseconds(1);
            continue;
        }
 
        // Found delimiter - complete
        if (c == delimiter) {
            break;
        }
 
        // Skip specified character (e.g., '\r' for cross-platform line endings)
        if (c == skipChar) {
            continue;
        }
 
        // Valid character - add to buffer
        buffer << static_cast<char>(c);
    }
 
    // Convert to string and trim whitespace
    fl::string result = buffer.str();
    result.trim();
    return result;
}
 
template<typename SerialOut>
void writeSerialLine(SerialOut& serial, const fl::string& str) FL_NO_EXCEPT {
    serial.println(str.c_str());
}
 
} // namespace fl