MAG160C/task_plan.md

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.