# MAG160C Linux SDK Reverse Engineering Plan

## Goal

Create an original, Linux-usable source implementation for the USB thermal camera in this workspace, using the bundled Windows/Android apps and SDK as interoperability references.

## Constraints

- Prefer clean-room-style interoperability notes: derive public behavior, protocol, data formats, and API shapes; do not copy proprietary binary code.
- Do not install tools unless they are needed. If tools are installed, record what was installed and where.
- Current workspace is not a git repository, so progress is tracked in these markdown files instead of commits.
- Ask for approval before writing implementation code because the brainstorming skill requires an approved design first.

## Phases

1. [complete] Set up persistent planning files.
2. [complete] Inventory SDK documents, headers, examples, APK/AAR/native libraries, and USB identifiers.
3. [complete] Extract public API and data-flow evidence from Windows C# and Android Java/JNI/libuvc code.
4. [complete] Inspect binaries only as needed for symbols/strings/imports, using installed or portable open-source tools where available.
5. [complete] Present Linux implementation design with 2-3 approaches and get user approval.
6. [pending] Implement Linux source after approval, preferably as a small libusb/libuvc-based C/C++ project plus CLI sample.
7. [pending] Verify build/tests as far as possible without physical hardware, and document hardware test steps.

## Open Questions

- Whether the physical camera is currently attached to this Windows machine/WSL environment for live USB descriptor capture.
- Whether the desired Linux API should be C, C++, Python bindings, or a CLI-first tool. Answered: C++ core library with stable C ABI, CLI sample, and Python-callable wrapper/tooling.

## Errors Encountered

| Error | Attempt | Resolution |
|---|---|---|
| Not a git repository | Ran git status | Track with markdown files instead of commits. |
| Old using-superpowers path missing | Tried .system path | Read correct skill path under C:/Users/ZXC/.codex/skills/using-superpowers. |
| Get-PnpDevice access denied | Tried to enumerate attached USB devices from PowerShell | Need elevated device enumeration or user-provided lsusb/USB descriptor if live hardware testing is required. |
| ARM64 disassembly unsupported by MinGW objdump | Tried objdump on Android libcoresdk.so | Need LLVM objdump/capstone/ghidra/r2 or USB trace to recover low-level vendor protocol. |
| pip install capstone/pyelftools failed | Tried sandbox and escalated pip install into .tools/python-revlibs | Network/proxy unavailable; no new reverse-engineering package installed. |
| planning catchup script missing | Tried planning-with-files `.claude` catchup path from Codex session | Logged error; continued because task planning files were read directly. |
| PowerShell heredoc/Python quoting failed | Tried Bash heredoc and then malformed `python -c` for PDF extraction | Switched to PowerShell here-string piped into `python -`; PDF extraction succeeded. |

## Handoff Summary

- Reverse-engineering evidence is complete enough for a Linux-first source implementation skeleton.
- User chose approach 1: C++ core library + stable C ABI + CLI sample + Python-callable wrapper.
- Implemented so far:
  - public C ABI scaffolding
  - TCM frame encode/decode
  - TCM command builders
  - USB device model and endpoint discovery
  - IR API skeleton with explicit protocol-unknown errors and Linux endpoint/marker evidence in diagnostics
  - CLI diagnostics and dry-run commands
- Verification status:
  - CMake is not available in PATH in this environment.
  - Direct MinGW g++ compile/run checks were used instead and passed for the completed tasks.
- Current stop point:
  - Task 6 was implemented and locally verified in no-libusb mode after the user resumed work.
  - Next implementation task is Task 7: Python ctypes wrapper.
- If a new chat resumes work, start from the existing implementation plan and continue with the remaining Linux runtime pieces, keeping the same file-based notes.