refactor: make cel_serial_read non-blocking

Drop timeout_ms; read now returns immediately with whatever
data is available (0 if none), so callers don't block the rest
of their loop waiting on serial I/O.

telemetry's poll loop now sleeps interval_ms itself between
empty reads via a small sleep_ms helper.

celrs/CMakeLists.txt

@@ -2,10 +2,23 @@ add_library(celrs_crsf STATIC crsf.c)
 target_include_directories(celrs_crsf PUBLIC "${CMAKE_SOURCE_DIR}")
 target_compile_features(celrs_crsf PRIVATE c_std_23)
 
+# Platform-agnostic serial logic — calls cel_serial_platform_*();
+# symbol resolved by celrs_serial_platform (or a mock in tests)
 add_library(celrs_serial STATIC serial.c)
 target_include_directories(celrs_serial PUBLIC "${CMAKE_SOURCE_DIR}")
 target_compile_features(celrs_serial PRIVATE c_std_23)
 
+# Real platform backend — linked into production binaries only
+add_library(celrs_serial_platform STATIC)
+target_include_directories(celrs_serial_platform PUBLIC "${CMAKE_SOURCE_DIR}")
+target_compile_features(celrs_serial_platform PRIVATE c_std_23)
+if (IS_WINDOWS)
+    target_sources(celrs_serial_platform PRIVATE platform/serial_win.c)
+    target_link_libraries(celrs_serial_platform PRIVATE advapi32)
+elseif(IS_LINUX OR IS_MACOS)
+    target_sources(celrs_serial_platform PRIVATE platform/serial_posix.c)
+endif()
+
 # Level-filtering logger — calls log_write(); symbol resolved by the final binary
 add_library(celrs_logger STATIC logger.c)
 target_include_directories(celrs_logger PUBLIC "${CMAKE_SOURCE_DIR}")

celrs/platform/serial_internal.h

@@ -0,0 +1,7 @@
+#pragma once
+#include <stddef.h>
+
+/* Platform-specific port enumeration.
+ * Returns the number of ports found, or -1 on error.
+ * out_ports must be freed with cel_serial_free_ports(). */
+int cel_serial_platform_list_ports(char*** out_ports, int max_ports);

celrs/platform/serial_posix.c

@@ -0,0 +1,36 @@
+#include "celrs/platform/serial_internal.h"
+
+#include <dirent.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+
+int cel_serial_platform_list_ports(char*** out_ports, int max_ports) {
+    char** ports = (char**)calloc(max_ports, sizeof(char*));
+    if (ports == NULL) return -1;
+
+    int count = 0;
+    DIR* dir = opendir("/dev");
+    if (dir != NULL) {
+        struct dirent* entry;
+        while ((entry = readdir(dir)) != NULL && count < max_ports) {
+            if (strncmp(entry->d_name, "tty", 3) == 0) {
+                char* rest = entry->d_name + 3;
+                if (strncmp(rest, "USB", 3) == 0 ||
+                    strncmp(rest, "ACM", 3) == 0) {
+                    char path[256];
+                    snprintf(path, sizeof(path), "/dev/%s", entry->d_name);
+
+                    if (access(path, R_OK | W_OK) == 0) {
+                        ports[count] = strdup(path);
+                        if (ports[count] != NULL) count++;
+                    }
+                }
+            }
+        }
+        closedir(dir);
+    }
+
+    *out_ports = ports;
+    return count;
+}

celrs/platform/serial_win.c

@@ -0,0 +1,41 @@
+#include "celrs/platform/serial_internal.h"
+
+#include <windows.h>
+#include <stdlib.h>
+#include <string.h>
+
+/* Enumerate active COM ports via HKLM\HARDWARE\DEVICEMAP\SERIALCOMM.
+ * Windows keeps one value per active port in this key, so this is a
+ * single registry read instead of probing COM1..COM255 with CreateFile. */
+int cel_serial_platform_list_ports(char*** out_ports, int max_ports) {
+    char** ports = (char**)calloc(max_ports, sizeof(char*));
+    if (ports == NULL) return -1;
+
+    int count = 0;
+
+    HKEY key;
+    if (RegOpenKeyExA(HKEY_LOCAL_MACHINE, "HARDWARE\\DEVICEMAP\\SERIALCOMM",
+                      0, KEY_READ, &key) == ERROR_SUCCESS) {
+        for (DWORD index = 0; count < max_ports; index++) {
+            char value_name[256];
+            char port_name[256];
+            DWORD value_name_len = sizeof(value_name);
+            DWORD port_name_len  = sizeof(port_name);
+            DWORD type;
+
+            LONG result = RegEnumValueA(key, index, value_name, &value_name_len,
+                                         NULL, &type, (BYTE*)port_name, &port_name_len);
+            if (result != ERROR_SUCCESS) break;
+
+            if (type == REG_SZ) {
+                ports[count] = _strdup(port_name);
+                if (ports[count] != NULL) count++;
+            }
+        }
+
+        RegCloseKey(key);
+    }
+
+    *out_ports = ports;
+    return count;
+}

celrs/serial.c

@@ -3,16 +3,7 @@
 #endif
 
 #include "celrs/serial.h"
-
-/*
- * Platform-agnostic serial port implementation.
- *
- * Windows uses Win32 CreateFile/ReadFile/WriteFile.
- * POSIX uses open/read/write with termios.
- *
- * This is a stub implementation that compiles but does nothing.
- * Real platform-specific code will be added when TDD tests drive it.
- */
+#include "celrs/platform/serial_internal.h"
 
 #include <stdlib.h>
 #include <string.h>
@@ -46,16 +37,15 @@ void cel_serial_close(cel_serial_port* port) {
     free(port);
 }
 
-size_t cel_serial_read(cel_serial_port* port, unsigned char* buf, size_t len, int timeout_ms) {
+size_t cel_serial_read(cel_serial_port* port, uint8_t* buf, size_t len) {
     (void)port;
     (void)buf;
     (void)len;
-    (void)timeout_ms;
-    /* TODO: platform-specific read */
+    /* TODO: platform-specific non-blocking read */
     return 0;
 }
 
-size_t cel_serial_write(cel_serial_port* port, unsigned char const* buf, size_t len) {
+size_t cel_serial_write(cel_serial_port* port, uint8_t const* buf, size_t len) {
     (void)port;
     (void)buf;
     (void)len;
@@ -67,3 +57,17 @@ void cel_serial_flush(cel_serial_port* port) {
     (void)port;
     /* TODO: platform-specific flush */
 }
+
+int cel_serial_list_ports(char*** out_ports, int max_ports) {
+    if (out_ports == NULL) return -1;
+    if (max_ports <= 0) max_ports = 64;
+    return cel_serial_platform_list_ports(out_ports, max_ports);
+}
+
+void cel_serial_free_ports(char** ports, int count) {
+    if (ports == NULL) return;
+    for (int i = 0; i < count; i++) {
+        free(ports[i]);
+    }
+    free(ports);
+}

celrs/serial.h

@@ -1,5 +1,6 @@
 #pragma once
 #include <stddef.h>
+#include <stdint.h>
 
 /* Opaque serial port handle */
 typedef struct cel_serial_port cel_serial_port;
@@ -14,11 +15,20 @@ cel_serial_port* cel_serial_open(char const* path, int baud_rate);
 /* Close and free the serial port */
 void cel_serial_close(cel_serial_port* port);
 
-/* Read up to len bytes. Returns bytes read, 0 on timeout/error. */
-size_t cel_serial_read(cel_serial_port* port, unsigned char* buf, size_t len, int timeout_ms);
+/* Read up to len bytes without blocking.
+ * Returns bytes read immediately available, or 0 if none/error. */
+size_t cel_serial_read(cel_serial_port* port, uint8_t* buf, size_t len);
 
 /* Write data. Returns bytes written, 0 on error. */
-size_t cel_serial_write(cel_serial_port* port, unsigned char const* buf, size_t len);
+size_t cel_serial_write(cel_serial_port* port, uint8_t const* buf, size_t len);
 
 /* Flush output buffer */
 void cel_serial_flush(cel_serial_port* port);
+
+/* List available serial ports.
+ * Returns the number of ports found, or -1 on error.
+ * Caller must free the returned array with cel_serial_free_ports(). */
+int cel_serial_list_ports(char*** out_ports, int max_ports);
+
+/* Free the port list returned by cel_serial_list_ports */
+void cel_serial_free_ports(char** ports, int count);

tests/CMakeLists.txt

@@ -38,12 +38,12 @@ target_compile_features(test_crsf PRIVATE c_std_23)
 add_test(NAME test_crsf COMMAND test_crsf)
 list(APPEND TEST_TARGETS test_crsf)
 
-# Serial tests — mocks log_write.h for any logging calls
+# Serial tests — mocks the platform backend (serial_internal.h)
 add_executable(test_serial test_serial.c)
 target_include_directories(test_serial PRIVATE "${CMAKE_SOURCE_DIR}")
 target_link_libraries(test_serial PRIVATE celrs_serial Unity::Unity CMock::CMock)
 target_compile_features(test_serial PRIVATE c_std_23)
-cmock_generate_mock(test_serial "${CMAKE_SOURCE_DIR}/celrs/log_write.h")
+cmock_generate_mock(test_serial "${CMAKE_SOURCE_DIR}/celrs/platform/serial_internal.h")
 add_test(NAME test_serial COMMAND test_serial)
 list(APPEND TEST_TARGETS test_serial)
 

tests/test_serial.c

@@ -1,9 +1,11 @@
+#include <stdlib.h>
+
 #include "unity.h"
 #include "celrs/serial.h"
-#include "Mocklog_write.h"
+#include "Mockserial_internal.h"
 
-void setUp(void)    { Mocklog_write_Init(); }
-void tearDown(void) { Mocklog_write_Verify(); Mocklog_write_Destroy(); }
+void setUp(void)    { Mockserial_internal_Init(); }
+void tearDown(void) { Mockserial_internal_Verify(); Mockserial_internal_Destroy(); }
 
 void test_open_valid_path(void) {
     cel_serial_port* port = cel_serial_open("COM3", 400000);
@@ -32,7 +34,7 @@ void test_read_returns_zero_stub(void) {
     TEST_ASSERT_NOT_NULL(port);
     uint8_t buf[16];
     /* Stub implementation returns 0 */
-    size_t n = cel_serial_read(port, buf, sizeof(buf), 100);
+    size_t n = cel_serial_read(port, buf, sizeof(buf));
     TEST_ASSERT_EQUAL_UINT(0, n);
     cel_serial_close(port);
 }
@@ -58,6 +60,33 @@ void test_flush_null(void) {
     cel_serial_flush(NULL); /* should not crash */
 }
 
+void test_list_ports_null_out(void) {
+    TEST_ASSERT_EQUAL_INT(-1, cel_serial_list_ports(NULL, 16));
+}
+
+void test_list_ports_passes_max_ports_through(void) {
+    char** ports = NULL;
+    cel_serial_platform_list_ports_ExpectAndReturn(&ports, 16, 2);
+    int count = cel_serial_list_ports(&ports, 16);
+    TEST_ASSERT_EQUAL_INT(2, count);
+}
+
+void test_list_ports_zero_max_uses_default(void) {
+    char** ports = NULL;
+    cel_serial_platform_list_ports_ExpectAndReturn(&ports, 64, 0);
+    int count = cel_serial_list_ports(&ports, 0);
+    TEST_ASSERT_EQUAL_INT(0, count);
+}
+
+void test_free_ports_null(void) {
+    cel_serial_free_ports(NULL, 0); /* should not crash */
+}
+
+void test_free_ports_zero_count(void) {
+    char** empty = (char**)calloc(1, sizeof(char*));
+    cel_serial_free_ports(empty, 0); /* should not crash */
+}
+
 int main(void) {
     UNITY_BEGIN();
     RUN_TEST(test_open_valid_path);
@@ -68,5 +97,10 @@ int main(void) {
     RUN_TEST(test_write_returns_zero_stub);
     RUN_TEST(test_flush_no_crash);
     RUN_TEST(test_flush_null);
+    RUN_TEST(test_list_ports_null_out);
+    RUN_TEST(test_list_ports_passes_max_ports_through);
+    RUN_TEST(test_list_ports_zero_max_uses_default);
+    RUN_TEST(test_free_ports_null);
+    RUN_TEST(test_free_ports_zero_count);
     return UNITY_END();
 }

tools/CMakeLists.txt

@@ -1,4 +1,4 @@
-add_executable(tool_telemetry telemetry.c)
-target_include_directories(tool_telemetry PRIVATE "${CMAKE_SOURCE_DIR}")
-target_compile_features(tool_telemetry PRIVATE c_std_23)
-target_link_libraries(tool_telemetry PRIVATE celrs_crsf celrs_serial celrs_logger celrs_log_write)
+add_executable(telemetry telemetry.c)
+target_include_directories(telemetry PRIVATE "${CMAKE_SOURCE_DIR}")
+target_compile_features(telemetry PRIVATE c_std_23)
+target_link_libraries(telemetry PRIVATE celrs_crsf celrs_serial celrs_serial_platform celrs_logger celrs_log_write)

tools/telemetry.c

@@ -5,6 +5,12 @@
 #include <stdlib.h>
 #include <string.h>
 
+#ifdef _WIN32
+#include <windows.h>
+#else
+#include <time.h>
+#endif
+
 /* TX power index to dBm mapping (ELRS standard) */
 static int const s_tx_power_dbm[] = {
     0, 20, 26, 30, 32, 34, 36, 38,
@@ -31,34 +37,73 @@ static int telemetry_parse_link(int16_t* rssi, uint8_t* link_quality,
     return 0;
 }
 
+static void sleep_ms(int ms) {
+#ifdef _WIN32
+    Sleep((DWORD)ms);
+#else
+    struct timespec ts = {.tv_sec = ms / 1000, .tv_nsec = (ms % 1000) * 1000000L};
+    nanosleep(&ts, NULL);
+#endif
+}
+
 static void print_usage(char const* prog) {
-    printf("Usage: %s <serial_port> [interval_ms]\n", prog);
-    printf("  serial_port  : COM3 (Windows) or /dev/ttyUSB0 (Linux)\n");
-    printf("  interval_ms  : poll interval in ms (default 200)\n");
+    printf("Usage: %s --port <serial_port> [--baudrate <rate>] [interval_ms]\n", prog);
+    printf("       %s --list\n", prog);
+    printf("  --port <serial_port> : COM3 (Windows) or /dev/ttyUSB0 (Linux)\n");
+    printf("  --baudrate <rate>    : baud rate (default 400000)\n");
+    printf("  interval_ms          : poll interval in ms (default 200)\n");
+    printf("  --list               : list available serial ports and exit\n");
+}
+
+static int list_ports(void) {
+    char** ports = NULL;
+    int count = cel_serial_list_ports(&ports, 0);
+    if (count < 0) {
+        cel_log_err("Failed to list serial ports");
+        return 1;
+    }
+
+    for (int i = 0; i < count; i++) {
+        printf("%s\n", ports[i]);
+    }
+
+    cel_serial_free_ports(ports, count);
+    return 0;
 }
 
 int main(int argc, char const* argv[]) {
-    if (argc < 2) {
+    char const* port_path = NULL;
+    int baud_rate = 400000;
+    int interval_ms = 200;
+
+    for (int i = 1; i < argc; i++) {
+        if (strcmp(argv[i], "--list") == 0) {
+            return list_ports();
+        } else if (strcmp(argv[i], "--port") == 0 && i + 1 < argc) {
+            port_path = argv[++i];
+        } else if (strcmp(argv[i], "--baudrate") == 0 && i + 1 < argc) {
+            baud_rate = atoi(argv[++i]);
+            if (baud_rate <= 0) baud_rate = 400000;
+        } else {
+            interval_ms = atoi(argv[i]);
+            if (interval_ms <= 0) interval_ms = 200;
+        }
+    }
+
+    if (port_path == NULL) {
         print_usage(argv[0]);
         return 1;
     }
 
-    char const* port_path = argv[1];
-    int interval_ms = 200;
-    if (argc >= 3) {
-        interval_ms = atoi(argv[2]);
-        if (interval_ms <= 0) interval_ms = 200;
-    }
-
     /* Open serial port */
-    cel_serial_port* port = cel_serial_open(port_path, 400000);
+    cel_serial_port* port = cel_serial_open(port_path, baud_rate);
     if (port == NULL) {
         cel_log_err("Failed to open serial port");
         return 1;
     }
 
     char msg[256];
-    snprintf(msg, sizeof(msg), "Connected to %s (400000 baud)", port_path);
+    snprintf(msg, sizeof(msg), "Connected to %s (%d baud)", port_path, baud_rate);
     cel_log_info(msg);
 
     /* Send heartbeat to establish CRSF link */
@@ -76,8 +121,11 @@ int main(int argc, char const* argv[]) {
     int frames = 0, errors = 0;
 
     for (int i = 0; i < 20; i++) { /* read up to 20 telemetry frames */
-        size_t n = cel_serial_read(port, buf, sizeof(buf), interval_ms);
-        if (n == 0) continue;
+        size_t n = cel_serial_read(port, buf, sizeof(buf));
+        if (n == 0) {
+            sleep_ms(interval_ms);
+            continue;
+        }
 
         cel_crsf_frame frame;
         if (cel_crsf_frame_parse(&frame, buf, n) != 0) {