MAG160C/.superpowers/sdd/task-3-brief.md

Task 3 Brief: TCM command builders

Context

Tasks 1 and 2 are complete. Existing TCM frame codec is in src/core/tcm_frame.* and C ABI frame utilities are in src/c_api.cpp.

CMake is unavailable on PATH in this environment. Keep CMakeLists.txt correct, but use direct MinGW g++ verification if CMake cannot run.

Global constraints

• Use only original source code; do not link proprietary SDK binaries.
• Current workspace is not a git repository; replace commit steps with verification plus updates to progress.md.
• Keep public C ABI free of C++ types.
• Use C++17.
• libusb-1.0 is the only native runtime dependency for the core library.
• Firmware update commands are not exposed as an easy accidental CLI action.
• IR protocol gaps return MAG160C_ERR_PROTOCOL_UNKNOWN or MAG160C_ERR_UNSUPPORTED.

Files

• Create: src/core/transport.hpp
• Create: src/core/tcm_device.hpp
• Create: src/core/tcm_device.cpp
• Create: tests/cpp/test_tcm_device.cpp
• Modify: CMakeLists.txt
• Modify: include/mag160c/mag160c.h
• Modify: src/c_api.cpp
• Update: progress.md with the checkpoint.

Interfaces to produce

• mag160c::core::Transport
• mag160c::core::TcmCommandBuilder
• mag160c_tcm_build_rotate_frame
• mag160c_tcm_build_light_frame

Required transport interface

class Transport {
public:
    virtual ~Transport() = default;
    virtual mag160c_error_t write(const std::vector<uint8_t>& bytes) = 0;
    virtual mag160c_error_t read(std::vector<uint8_t>* out, int timeout_ms) = 0;
};

Required TCM command behavior

• Frame id starts at 1.
• Frame id increments after each encoded frame.
• Frame id wraps to 1 before reaching 0x8000.
• rotate clamps input to [-128, 128].
• rotate payload is [direction, magnitude], direction 0 for positive and 1 for negative.
• light payload is [on, red, green, blue].
• red/green/blue/yellow channel value is 0xff.
• off payload is [0, 0, 0, 0].
• light steady sub is 0x31, blink is 0x32, breath is 0x33.
• all observed TCM main commands here use main 0x02.

Required exact test vectors

• rotate +5 with initial frame id 1:

7e 00 07 85 02 77 00 01 00 05 7f

• after one prior command, rotate -3 with frame id 2:

7e 00 07 85 02 77 00 02 01 03 7f

• green blink with initial frame id 1:

7e 00 09 87 02 32 00 01 01 00 ff 00 35

Required C ABI declarations

Add to include/mag160c/mag160c.h:

typedef enum mag160c_tcm_light_color_t {
    MAG160C_TCM_LIGHT_OFF = 0,
    MAG160C_TCM_LIGHT_RED = 1,
    MAG160C_TCM_LIGHT_GREEN = 2,
    MAG160C_TCM_LIGHT_BLUE = 3,
    MAG160C_TCM_LIGHT_YELLOW = 4
} mag160c_tcm_light_color_t;

typedef enum mag160c_tcm_light_mode_t {
    MAG160C_TCM_LIGHT_STEADY = 0,
    MAG160C_TCM_LIGHT_BLINK = 1,
    MAG160C_TCM_LIGHT_BREATH = 2
} mag160c_tcm_light_mode_t;

MAG160C_API mag160c_error_t mag160c_tcm_build_rotate_frame(
    int angle,
    uint8_t* out_bytes,
    size_t out_capacity,
    size_t* out_size
);

MAG160C_API mag160c_error_t mag160c_tcm_build_light_frame(
    mag160c_tcm_light_color_t color,
    mag160c_tcm_light_mode_t mode,
    uint8_t* out_bytes,
    size_t out_capacity,
    size_t* out_size
);

Required C ABI behavior

• Build helpers are dry-run byte builders only; they do not talk to USB.
• If out_size is null, return MAG160C_ERR_INVALID_ARGUMENT.
• If output buffer is null or too small, set out_size to the required frame size and return MAG160C_ERR_INVALID_ARGUMENT.
• On success, copy bytes, set out_size, clear last_error, return MAG160C_OK.
• Invalid light color or mode returns MAG160C_ERR_INVALID_ARGUMENT and sets a useful last_error.

Required tests

Create tests/cpp/test_tcm_device.cpp with:

• test_rotate_positive_payload exact vector.
• test_rotate_negative_payload_and_frame_increment exact vector.
• test_green_blink_payload exact vector.

Also extend tests/cpp/test_c_api.cpp if convenient to check the new dry-run C ABI for rotate +5.

CMake update

• Add src/core/tcm_device.cpp to mag160c_core sources.
• Add test_tcm_device executable linked to mag160c_core.
• Give test_tcm_device access to src private headers.
• Register test_tcm_device with CTest.

Verification

First try:

cmake --build build
ctest --test-dir build --output-on-failure

If CMake is unavailable, run:

g++ -std=c++17 -DMAG160C_STATIC -DMAG160C_HAS_LIBUSB=0 -Iinclude -Isrc src\core\error.cpp src\core\context.cpp src\core\tcm_frame.cpp src\core\tcm_device.cpp src\c_api.cpp tests\cpp\test_c_api.cpp -o build_task3_c_api_test.exe
.\build_task3_c_api_test.exe
g++ -std=c++17 -DMAG160C_STATIC -DMAG160C_HAS_LIBUSB=0 -Iinclude -Isrc src\core\error.cpp src\core\context.cpp src\core\tcm_frame.cpp src\core\tcm_device.cpp src\c_api.cpp tests\cpp\test_tcm_frame.cpp -o build_task3_tcm_frame_test.exe
.\build_task3_tcm_frame_test.exe
g++ -std=c++17 -DMAG160C_STATIC -DMAG160C_HAS_LIBUSB=0 -Iinclude -Isrc src\core\error.cpp src\core\context.cpp src\core\tcm_frame.cpp src\core\tcm_device.cpp src\c_api.cpp tests\cpp\test_tcm_device.cpp -o build_task3_tcm_device_test.exe
.\build_task3_tcm_device_test.exe

Expected: all executables exit 0.

Progress checkpoint

Append this line to progress.md after verification:

- Implemented Task 3 TCM command builder, dry-run C ABI helpers, and command payload tests.

Report contract

Write a report to .superpowers/sdd/task-3-report.md with:

• status: DONE, DONE_WITH_CONCERNS, NEEDS_CONTEXT, or BLOCKED
• files created/modified
• exact commands run
• test results
• concerns, if any
• self-review notes