use device centric api

mdurrani808 · mdurrani808 · commit ee4fa7c87641 · 2026-04-19T23:29:55.000-04:00
diff --git a/README.md b/README.md
@@ -0,0 +1,52 @@
+# UMD Loop DBC-to-CAN Generator
+
+This tool takes DBC files and spits out a header file that lets you encode and decode messages easily.
+
+## Build Instructions
+
+### Prerequisites
+- CMake 3.14+
+- C++17
+
+### Building & Generating
+```bash
+mkdir build && cd build
+cmake ..
+make
+```
+The build process automatically runs the generator. You can find the resulting API at:
+`build/generated/UMDLoopCANProtocol.hpp`
+
+### Running the Example/Tests
+To ensure everything is working correctly:
+```bash
+make protocol-test
+./protocol-test
+```
+
+---
+
+## Adding New Devices
+
+To make the generation work, you must follow some conventions:
+
+### 1. Device Prefixes
+The generator uses prefixes to decide which namespace a signal belongs to. If you want a signal to appear in the `Servo` namespace, it must start with `servo_`.
+
+**Currently supported prefixes:**
+`dc_motor`, `servo`, `stepper`, `laser`, `led`, `rotary_encoder`, `limit_switch`, `diode`, `ccd`, `spectroscopy`, `fluorometry`, `power`, `swerve`, `arm`, `kill`, `pcb`.
+
+### 2. Adding a New Device Type
+If you are adding a completely new type of hardware (e.g., a `lidar`), follow these steps:
+1. Open `src/generator.cpp`.
+2. Locate the `devices` vector inside the `parseDeviceCommand` function.
+3. Add `"lidar"` to the list.
+4. Rebuild the project.
+
+### 3. Port Multiplexing (Suffixes)
+For PCBs that have multiple identical ports (like a Servo board with 8 slots), name your signals with a port suffix (e.g., `servo_position_target_0` through `_7`). 
+- The generator will collapse these into a single function.
+- In C++, you’ll call `Servo::encode_position_target(pcb, port, data)`, where `port` is just an integer.
+
+### 4. Grouping Signals
+For "flat" messages (no multiplexer), the generator groups every signal inside that CAN frame into a single C++ struct.
diff --git a/example/main.cpp b/example/main.cpp
@@ -1,6 +1,6 @@
 #include "UMDLoopCANProtocol.hpp"
 #include <cstdio>
-#include <cstdlib>
+#include <optional>
 
 using namespace Protocol;
 
@@ -14,203 +14,64 @@ static int g_failures = 0;
         } \
     } while (false)
 
-static void test_message_type_dispatch() {
-    CanFrame f;
-
-    f.id = POWER_PCB_C::ID;
-    CHECK(getMessageType(f) == MessageType::POWER_PCB_C);
-
-    f.id = SCIENCE_SERVO_PCB_C::ID;
-    CHECK(getMessageType(f) == MessageType::SCIENCE_SERVO_PCB_C);
-
-    f.id = SCIENCE_SERVO_PCB_R::ID;
-    CHECK(getMessageType(f) == MessageType::SCIENCE_SERVO_PCB_R);
-
-    f.id = SWERVE_PCB_C::ID;
-    CHECK(getMessageType(f) == MessageType::SWERVE_PCB_C);
-
-    f.id = 0xDEAD;
-    CHECK(getMessageType(f) == MessageType::Unknown);
-
-    std::puts("test_message_type_dispatch done");
-}
-
-static void test_power_pcb_flat_roundtrip() {
-    POWER_PCB_C out;
-    out.cmd = 0x11;
-
-    CanFrame frame = encode(out);
-    CHECK(frame.id  == POWER_PCB_C::ID);   // 0x10
-    CHECK(frame.dlc == POWER_PCB_C::DLC);  // 3
-    CHECK(frame.data[0] == 0x11);          // cmd in byte 0
-
-    POWER_PCB_C in = decode<POWER_PCB_C>(frame);
-    CHECK(in.cmd == 0x11);
-
-    std::puts("test_power_pcb_flat_roundtrip done");
-}
-
-static void test_science_servo_velocity_roundtrip() {
-    for (uint8_t port = 0; port < 8; ++port) {
-        int16_t vel = static_cast<int16_t>(-500 + port * 150);  // mix of negative and positive
-
-        SCIENCE_SERVO_PCB_C_servo_velocity_target_t payload;
-        payload.port_id = port;
-        payload.servo_velocity_target = vel;
-
-        CanFrame frame = encode(payload);
-
-        CHECK(frame.id  == SCIENCE_SERVO_PCB_C::ID);   // 0x80
-        CHECK(frame.dlc == 3);
-        CHECK(frame.data[0] == static_cast<uint8_t>(0x30 + port));  // cmd byte
-        // little-endian payload
-        CHECK(frame.data[1] == static_cast<uint8_t>(vel & 0xFF));
-        CHECK(frame.data[2] == static_cast<uint8_t>((vel >> 8) & 0xFF));
-
-        // decode payload
-        auto decoded = decode<SCIENCE_SERVO_PCB_C_servo_velocity_target_t>(frame);
-        CHECK(decoded.port_id == port);
-        CHECK(decoded.servo_velocity_target == vel);
-    }
-    std::puts("test_science_servo_velocity_roundtrip done");
+static void test_servo_position_roundtrip() {
+    Servo::PositionTarget target{180};
+    // ScienceServo, Port 3 -> CAN ID 0x80, Mux 0x20 + 3 = 0x23
+    CanFrame frame = Servo::encode_position_target(Subsystem::ScienceServo, 3, target);
+    
+    CHECK(frame.id == 0x80);
+    CHECK(frame.data[0] == 0x23);
+    
+    auto decoded = Servo::decode_position_target(frame);
+    CHECK(decoded.has_value());
+    CHECK(decoded->port == 3);
+    CHECK(decoded->data.value == 180);
+    
+    std::puts("test_servo_position_roundtrip done");
 }
 
-static void test_science_servo_position_roundtrip() {
-    for (uint8_t port = 0; port < 8; ++port) {
-        int16_t pos = static_cast<int16_t>(port * 1000 - 3500);
-
-        SCIENCE_SERVO_PCB_C_servo_position_target_t payload;
-        payload.port_id = port;
-        payload.servo_position_target = pos;
-
-        CanFrame frame = encode(payload);
-
-        CHECK(frame.id  == SCIENCE_SERVO_PCB_C::ID);
-        CHECK(frame.dlc == 3);
-        CHECK(frame.data[0] == static_cast<uint8_t>(0x20 + port));
-        CHECK(frame.data[1] == static_cast<uint8_t>(pos & 0xFF));
-        CHECK(frame.data[2] == static_cast<uint8_t>((pos >> 8) & 0xFF));
-
-        auto decoded = decode<SCIENCE_SERVO_PCB_C_servo_position_target_t>(frame);
-        CHECK(decoded.port_id == port);
-        CHECK(decoded.servo_position_target == pos);
-    }
-    std::puts("test_science_servo_position_roundtrip done");
+static void test_servo_position_multi_pcb() {
+    Servo::PositionTarget target{90};
+    
+    // Swerve, Port 0 -> CAN ID 0x140, Mux 0x20 + 0 = 0x20
+    CanFrame frame_swerve = Servo::encode_position_target(Subsystem::Swerve, 0, target);
+    CHECK(frame_swerve.id == 0x140);
+    CHECK(frame_swerve.data[0] == 0x20);
+    
+    auto decoded_swerve = Servo::decode_position_target(frame_swerve);
+    CHECK(decoded_swerve.has_value());
+    CHECK(decoded_swerve->port == 0);
+    CHECK(decoded_swerve->data.value == 90);
+
+    // BaseArm, Port 2 -> CAN ID 0x130, Mux 0x20 + 2 = 0x22
+    CanFrame frame_arm = Servo::encode_position_target(Subsystem::BaseArm, 2, target);
+    CHECK(frame_arm.id == 0x130);
+    CHECK(frame_arm.data[0] == 0x22);
+
+    auto decoded_arm = Servo::decode_position_target(frame_arm);
+    CHECK(decoded_arm.has_value());
+    CHECK(decoded_arm->port == 2);
+    
+    std::puts("test_servo_position_multi_pcb done");
 }
 
-static void test_science_servo_bool_commands() {
-    for (uint8_t port = 0; port < 8; ++port) {
-        SCIENCE_SERVO_PCB_C_servo_state_req_event_t state_payload;
-        state_payload.port_id = port;
-        state_payload.servo_state_req_event = true;
-        CanFrame state_frame  = encode(state_payload);
-
-        SCIENCE_SERVO_PCB_C_servo_status_req_event_t status_payload;
-        status_payload.port_id = port;
-        status_payload.servo_status_req_event = true;
-        CanFrame status_frame = encode(status_payload);
-
-        CHECK(state_frame.data[0]  == static_cast<uint8_t>(0x40 + port));
-        CHECK(status_frame.data[0] == static_cast<uint8_t>(0x50 + port));
-
-        auto state_decoded = decode<SCIENCE_SERVO_PCB_C_servo_state_req_event_t>(state_frame);
-        CHECK(state_decoded.port_id == port);
-        CHECK(state_decoded.servo_state_req_event == true);
-
-        auto status_decoded = decode<SCIENCE_SERVO_PCB_C_servo_status_req_event_t>(status_frame);
-        CHECK(status_decoded.port_id == port);
-        CHECK(status_decoded.servo_status_req_event == true);
-    }
-    std::puts("test_science_servo_bool_commands done");
-}
-
-static void test_science_servo_pos_response_roundtrip() {
-    for (uint8_t port = 0; port < 8; ++port) {
-        SCIENCE_SERVO_PCB_R_pos_resp_t payload;
-        payload.port_id = port;
-        payload.servo_position_pos_resp = static_cast<int16_t>(port * 200 - 700);
-        payload.servo_velocity_pos_resp = static_cast<int16_t>(port * 50  - 100);
-
-        CanFrame frame = encode(payload);
-
-        CHECK(frame.id  == SCIENCE_SERVO_PCB_R::ID);   // 0x81
-        CHECK(frame.dlc == 5);
-        CHECK(frame.data[0] == static_cast<uint8_t>(0x20 + port));
-        // position little-endian at bytes 1-2
-        CHECK(frame.data[1] == static_cast<uint8_t>(payload.servo_position_pos_resp & 0xFF));
-        CHECK(frame.data[2] == static_cast<uint8_t>((payload.servo_position_pos_resp >> 8) & 0xFF));
-        // velocity little-endian at bytes 3-4
-        CHECK(frame.data[3] == static_cast<uint8_t>(payload.servo_velocity_pos_resp & 0xFF));
-        CHECK(frame.data[4] == static_cast<uint8_t>((payload.servo_velocity_pos_resp >> 8) & 0xFF));
-
-        auto decoded = decode<SCIENCE_SERVO_PCB_R_pos_resp_t>(frame);
-        CHECK(decoded.port_id == port);
-        CHECK(decoded.servo_position_pos_resp == payload.servo_position_pos_resp);
-        CHECK(decoded.servo_velocity_pos_resp == payload.servo_velocity_pos_resp);
-    }
-    std::puts("test_science_servo_pos_response_roundtrip done");
-}
-
-static void test_swerve_pcb_mux_commands() {
-    for (uint8_t port = 0; port < 2; ++port) {
-        int16_t pos = static_cast<int16_t>(port * 4500 - 2000);
-        int16_t vel = static_cast<int16_t>(port * 300  -  100);
-
-        SWERVE_PCB_C_servo_position_target_t pos_payload{port, pos};
-        SWERVE_PCB_C_servo_velocity_target_t vel_payload{port, vel};
-
-        CanFrame pos_frame = encode(pos_payload);
-        CanFrame vel_frame = encode(vel_payload);
-
-        CHECK(pos_frame.id == SWERVE_PCB_C::ID);
-        CHECK(vel_frame.id == SWERVE_PCB_C::ID);
-
-        auto pos_decoded = decode<SWERVE_PCB_C_servo_position_target_t>(pos_frame);
-        CHECK(pos_decoded.port_id == port);
-        CHECK(pos_decoded.servo_position_target == pos);
-
-        auto vel_decoded = decode<SWERVE_PCB_C_servo_velocity_target_t>(vel_frame);
-        CHECK(vel_decoded.port_id == port);
-        CHECK(vel_decoded.servo_velocity_target == vel);
-    }
-    std::puts("test_swerve_pcb_mux_commands done");
-}
-
-static void test_boundary_values() {
-    {
-        SCIENCE_SERVO_PCB_C_servo_velocity_target_t payload{0, INT16_MIN};
-        CanFrame f = encode(payload);
-        auto decoded = decode<SCIENCE_SERVO_PCB_C_servo_velocity_target_t>(f);
-        CHECK(decoded.servo_velocity_target == INT16_MIN);
-    }
-    {
-        SCIENCE_SERVO_PCB_C_servo_velocity_target_t payload{7, INT16_MAX};
-        CanFrame f = encode(payload);
-        auto decoded = decode<SCIENCE_SERVO_PCB_C_servo_velocity_target_t>(f);
-        CHECK(decoded.servo_velocity_target == INT16_MAX);
-        CHECK(decoded.port_id == 7);
-    }
-    // zero
-    {
-        SCIENCE_SERVO_PCB_C_servo_position_target_t payload{3, 0};
-        CanFrame f = encode(payload);
-        auto decoded = decode<SCIENCE_SERVO_PCB_C_servo_position_target_t>(f);
-        CHECK(decoded.servo_position_target == 0);
-        CHECK(f.data[1] == 0);
-        CHECK(f.data[2] == 0);
-    }
-    std::puts("test_boundary_values done");
+static void test_dc_motor_status() {
+    DcMotor::Status stat{1}; 
+    
+    CanFrame frame = DcMotor::encode_status(Subsystem::ScienceDcMotor, 0, stat);
+    CHECK(frame.id == 0x71);
+    
+    auto decoded = DcMotor::decode_status(frame);
+    CHECK(decoded.has_value());
+    CHECK(decoded->data.value == 1);
+    
+    std::puts("test_dc_motor_status done");
 }
 
 int main() {
-    test_message_type_dispatch();
-    test_power_pcb_flat_roundtrip();
-    test_science_servo_velocity_roundtrip();
-    test_science_servo_position_roundtrip();
-    test_science_servo_bool_commands();
-    test_science_servo_pos_response_roundtrip();
-    test_swerve_pcb_mux_commands();
-    test_boundary_values();
+    test_servo_position_roundtrip();
+    test_servo_position_multi_pcb();
+    test_dc_motor_status();
 
     if (g_failures == 0) {
         std::puts("\nAll tests passed.");
diff --git a/src/generator.cpp b/src/generator.cpp
