vmruiz/bside-hx1-firmware
Watch
1
0
Fork
You've already forked bside-hx1-firmware
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
No description
21 commits 1 branch 0 tags 403 KiB
  • Python 69.8%
  • C 15.7%
  • Java 10%
  • Makefile 3.4%
  • Shell 1%
Find a file
Exact
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Víctor Manuel Ruiz sánchez 29fe2f84b0 fix(test): place mock file_size at actual Thumb PC-relative address 
The mock fat_stat stub used ldr r2, [pc, #4], which at A=0x08008ae4
loads from (A+4)&~2+4 = 0x08008aec. The extra 2-byte pad pushed
file_size to 0x08008aee, so the load picked up the function's own
bytes (0xE2400000) instead of the size. Remove the pad.
2026-08-30 23:36:26 +02:00
docs feat: add focused scaling and firmware analysis workflow 2026-08-30 00:54:09 +02:00
firmware feat: reconstruct scsi_sense_slot helper 2026-08-30 23:34:53 +02:00
fixtures feat: add focused scaling and firmware analysis workflow 2026-08-30 00:54:09 +02:00
patches feat: add focused scaling and firmware analysis workflow 2026-08-30 00:54:09 +02:00
reverse-engineering feat: reconstruct scsi_sense_slot helper 2026-08-30 23:34:53 +02:00
tests fix(test): place mock file_size at actual Thumb PC-relative address 2026-08-30 23:36:26 +02:00
tools feat: add focused scaling and firmware analysis workflow 2026-08-30 00:54:09 +02:00
.gitignore feat: add focused scaling and firmware analysis workflow 2026-08-30 00:54:09 +02:00
Makefile feat: add focused scaling and firmware analysis workflow 2026-08-30 00:54:09 +02:00
README.md docs: add incremental reconstruction roadmap 2026-08-30 18:30:36 +02:00
requirements-dev.txt feat: add offline fixed-scale patcher with Celor provenance 2026-08-29 23:07:29 +02:00

README.md

BSIDE HX1 Firmware

Reverse engineering, verification tooling, and an incremental source rewrite for the BSIDE/Mustool HX1 thermal camera.

The current patch implements a focused fixed 0–100 °C thermal palette mapping. It allocates about 70% of the 166-color palette to 20–60 °C, reverses palette indexing to match the camera's legend, and fixes the sidebar endpoints at 0 and 100. The project replaces one tested component at a time while retaining a path toward a full firmware rewrite.

Safety

No generated image is suitable for flashing unless all documented verification gates pass and the target camera has a tested flash backup and recovery path. The repository does not contain vendor firmware or extracted device secrets.

Hardware gate (still required)

  • The on-device code.bin SHA-256 must equal 4a82c71e…032e6a9 (1.3.9) before any patch is accepted.
  • An SWD/JTAG backup of the entire external flash must be captured and verified as a byte-for-byte read-back on a second probe.
  • The recovery flow (re-flash the backup via SWD and reboot) must be exercised on a sacrificial device or a fully simulated MCU environment before touching the real camera.
  • Until those gates pass, the candidate Update/code.bin is research-only and must not be placed in the camera's Update/ directory.

A read-only inspection of the camera's user volume found only the photo tree and no recoverable firmware backup. No device identifiers, user files, or local forensic-image paths are retained in the repository.

The user subsequently upgraded the camera to stock official 1.3.9 / C 1.0.5 using the existing fixtures. The verified staging path is /Update/code.bin and /Update/const.bin, matching the firmware strings 1:/Update/code.bin and 1:/Update/const.bin. An earlier conclusion that the updater read the FAT32 root was incorrect and was refuted by subsequent hardware tests. The camera's lock-screen-style version display (e.g. H:1.0.0 S:1.3.9 C:1.0.5) and the eight-byte in-firmware version field (1.3.9\0\0\0) match after the upgrade, confirming the device is on the same baseline that patches/hx1-1.3.9.json locks to. Staged update files should be removed after an upgrade to prevent re-flash.

Layout

  • firmware/: independently compilable replacement components and native tests.
  • tools/: firmware decryption, encryption, and structural validation.
  • patches/: version locks and expected binary evidence for offline patch construction.
  • tests/: regression checks against local immutable vendor fixtures.
  • docs/: reverse-engineering evidence and verification requirements.
  • fixtures/: local vendor binaries, ignored by Git.

Reverse-engineering roadmap

reverse-engineering/ROADMAP.md is the durable checkpoint for incremental firmware-to-C reconstruction. It distinguishes mapped/named functions from genuinely reconstructed C, records the current baseline tests and their expected results, defines a strict per-function state machine (candidate → evidence captured → behavioural harness → C implementation → native verification → Unicorn differential verification → ARM compile/assembly comparison → integration-ready), and lists the next concrete target (0x08002f44) along with its exact acceptance criteria and the agent handoff protocol. Read it before starting a new reconstruction increment.

Tests

make test
make verify

See docs/verification.md before producing or testing a modified update package. Generated candidates are research artifacts named DO-NOT-FLASH; the builder has no network or hardware operations and writes only to the explicitly selected output directory.