Rename MessageType::Req to MessageType::Cmd (emit 'C'), accept legacy 'R'

Co-authored-by: petesramek <2333452+petesramek@users.noreply.github.com>
Agent-Logs-Url: https://github.com/petesramek/tiny-link/sessions/47ca4beb-1f07-4daf-9f99-6f7d3b0de914

Author: Copilot

CHANGELOG.md

@@ -23,9 +23,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- `src/protocol/MessageType.h`: focused header with `MessageType` enum, `message_type_from_wire()`, `message_type_to_wire()`, and `message_type_to_string()` helpers.
+- Compatibility unit tests: `test_message_type_legacy_req_maps_to_cmd` and `test_message_type_cmd_wire_byte_is_C`.
+- Migration guide in README for `MessageType::Req` → `MessageType::Cmd`.
 - `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, `CHANGELOG.md`, issue/PR templates, and `CITATION.cff` for OSS best practices.
 
 ### Changed
+- `MessageType::Req` (wire byte `'R'`) renamed to `MessageType::Cmd` (wire byte `'C'`). Parsers accept both `'R'` (legacy) and `'C'` (new) via `message_type_from_wire()`.
+- `src/TinyProtocol.h` now includes `src/protocol/MessageType.h` instead of defining the enum inline.
+- Examples updated to use `message_type_to_wire(MessageType::Cmd)`.
 - Payload size limit reduced from 240 bytes to 64 bytes to enforce micro-message design intent and eliminate a latent `_rawIdx` overflow bug on large payloads.
 
 ---

README.md

@@ -163,12 +163,33 @@ Serial.print("Timeouts: "); Serial.println(stats.timeouts);
 
 `src/`: Core protocol logic (`TinyLink.h`, `TinyProtocol.h`).
 
+`src/protocol/`: Focused protocol headers (`MessageType.h`, etc.).
+
 `src/adapters/`: Hardware-specific drivers (Arduino, Posix, Windows, etc.).
 
 `examples/`: Ready-to-run duplex, callback, and health-monitoring demos.
 
 `test/`: Native C++ unit tests using `TinyTestAdapter`.
 
+## 🔄 Migration: `MessageType::Req` → `MessageType::Cmd`
+
+`MessageType::Req` (wire byte `'R'`) has been renamed to `MessageType::Cmd` (wire byte `'C'`).
+New code should use `MessageType::Cmd` or the helper `message_type_to_wire(MessageType::Cmd)`.
+
+Parsers automatically accept both `'R'` and `'C'` via `message_type_from_wire()` for backward
+compatibility with older firmware.
+
+```cpp
+// New outgoing frames (prefer this):
+link.send(message_type_to_wire(MessageType::Cmd), msg);   // emits 'C'
+
+// Parsing accepts both legacy 'R' and new 'C':
+MessageType mt;
+if (message_type_from_wire(link.type(), mt) && mt == MessageType::Cmd) {
+    // handles frames from old ('R') and new ('C') senders
+}
+```
+
 ## 📜 License
 This project is licensed under the MIT License.
 

examples/Gateway_Handshake_Calback/ESPM3_Bridge.ino

@@ -23,7 +23,7 @@ void setup() {
 
     // 2. Signal to the Tiny88 that we are ready to receive
     GatewayStatus msg = { 1, (uint32_t)millis() };
-    statusLink.send(TYPE_REQ, msg);
+    statusLink.send(message_type_to_wire(MessageType::Cmd), msg);
 }
 
 void loop() {

examples/Gateway_Handshake_Polling/ESPM3_Bridge.ino

@@ -19,7 +19,7 @@ void setup() {
     // 3. Signal to Tiny88 that we are stable and ready for data
     TinyLink<GatewayStatus, TinyArduinoAdapter> statusLink(adapter);
     GatewayStatus msg = { 1, 0 };
-    statusLink.send(TYPE_REQ, msg);
+    statusLink.send(message_type_to_wire(MessageType::Cmd), msg);
 }
 
 void loop() {

keywords.txt

@@ -34,5 +34,5 @@ seq	KEYWORD2
 #######################################
 TYPE_DATA	LITERAL1
 TYPE_DEBUG	LITERAL1
-TYPE_REQ	LITERAL1
+TYPE_CMD	LITERAL1
 TYPE_DONE	LITERAL1

src/TinyProtocol.h

@@ -8,24 +8,9 @@
 
 #include <stdint.h>
 
-namespace tinylink {
+#include "protocol/MessageType.h"
 
-    // ------------------------------------------------------------
-    // Message Types (Wire Format)
-    // ------------------------------------------------------------
-
-    /**
-     * @brief Message type identifiers used in TinyLink frames.
-     *
-     * These are 1‑byte ASCII codes placed in pBuf[0].
-     * Using enum class ensures type safety while allowing easy casting.
-     */
-    enum class MessageType : uint8_t {
-        Data = 'D',   /**< Standard data payload */
-        Debug = 'g',   /**< Debugging / Logging information */
-        Req = 'R',   /**< Request for data / action */
-        Done = 'K'    /**< Acknowledgment of completion */
-    };
+namespace tinylink {
 
     // ------------------------------------------------------------
     // High-Level Status Codes

test/test_protocol.cpp

@@ -925,6 +925,40 @@ void test_crc_endian_sensitivity(void) {
     TEST_ASSERT_EQUAL_UINT16(1, link.getStats().crcErrs);
 }
 
+/**
+ * @brief TEST: MessageType wire parsing — legacy 'R' backward compatibility.
+ *
+ * Verifies that message_type_from_wire() maps both the legacy wire byte 'R'
+ * and the new wire byte 'C' to MessageType::Cmd, ensuring parsers accept
+ * frames generated by older firmware.
+ */
+void test_message_type_legacy_req_maps_to_cmd(void) {
+    tinylink::MessageType mt;
+
+    // Legacy 'R' (Req) must decode to Cmd
+    bool ok_r = tinylink::message_type_from_wire('R', mt);
+    TEST_ASSERT_TRUE_MESSAGE(ok_r, "message_type_from_wire should accept legacy 'R'");
+    TEST_ASSERT_EQUAL_UINT8(static_cast<uint8_t>(tinylink::MessageType::Cmd),
+                            static_cast<uint8_t>(mt));
+
+    // New 'C' (Cmd) must also decode to Cmd
+    bool ok_c = tinylink::message_type_from_wire('C', mt);
+    TEST_ASSERT_TRUE_MESSAGE(ok_c, "message_type_from_wire should accept 'C'");
+    TEST_ASSERT_EQUAL_UINT8(static_cast<uint8_t>(tinylink::MessageType::Cmd),
+                            static_cast<uint8_t>(mt));
+}
+
+/**
+ * @brief TEST: MessageType wire encoding — Cmd emits 'C', not 'R'.
+ *
+ * Verifies that message_type_to_wire(MessageType::Cmd) returns 'C' so
+ * new code always sends the updated wire byte.
+ */
+void test_message_type_cmd_wire_byte_is_C(void) {
+    uint8_t wire = tinylink::message_type_to_wire(tinylink::MessageType::Cmd);
+    TEST_ASSERT_EQUAL_UINT8('C', wire);
+}
+
 void register_protocol_tests(void) {
     // --- Core Protocol & Asynchronous Events ---
     RUN_TEST(test_cobs_loopback);                /**< Basic encode/decode/verify pipeline */
@@ -997,5 +1031,6 @@ void register_protocol_tests(void) {
     RUN_TEST(test_primitive_type_support);
     RUN_TEST(test_truncated_cobs_rejection);
     RUN_TEST(test_fletcher_overflow_stability);
-    RUN_TEST(test_crc_endian_sensitivity);
+    RUN_TEST(test_message_type_legacy_req_maps_to_cmd); /**< Legacy 'R' maps to MessageType::Cmd */
+    RUN_TEST(test_message_type_cmd_wire_byte_is_C);     /**< MessageType::Cmd emits 'C' on the wire */
 }