docs: add TROUBLESHOOTING.md

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to the FPGA Event-Based Drone Collision Avoidance project.
 
+## [Unreleased]
+
+### Added
+- ARM MAVLink v2 `.bin` telemetry logger (`arm/mavlink_sd_logger.h`): buffered, crash-safe SD-card-over-SPI logging of the 100 Hz control loop as CRC-checked MAVLink v2 frames (`CA_TELEM` record per tick), with optional ground-station-decodable `NAMED_VALUE_*` output in `MAVLINK_AVAILABLE` builds
+- Telemetry logging integrated into `arm/drone_main.cpp` control loop (per-tick log, periodic `fsync`, flush-on-shutdown)
+- `arm/test_mavlink_logger.cpp`: 11 unit tests (CRC known-answer, framing, field round-trip, buffering, crash/write-failure handling) wired into `make test` and CI
+- Control-loop latency profiler (`arm/loop_profiler.h`) with per-stage instrumentation in `arm/drone_main.cpp`, enabled via `make profile` (`-DPROFILE_LOOP`); zero overhead in production builds
+- Link-time optimization (`-flto`) added to the ARM release build (`arm/Makefile` `RELEASE_FLAGS`)
+- `docs/loop-latency.md`: worst-case 100 Hz control-loop latency analysis (measured ~482 µs / 4.8 % of budget) and the SD `fsync` real-hardware caveat
+
 ## [1.0.0] — 2026-06-08
 
 ### Added

CONTRIBUTING.md

@@ -13,6 +13,10 @@ pip install pre-commit && pre-commit install   # flake8 + clang-format on commit
 No local toolchain? `make docker-test` builds the pinned environment
 (Python 3.11, g++-13, CPU torch) and runs the full suite inside it.
 
+Hit a snag? See [`TROUBLESHOOTING.md`](TROUBLESHOOTING.md) for common build,
+simulation, and deployment issues (Vitis HLS licensing, CUDA mismatches,
+MAVLink port conflicts, ARM cross-compilation, event-camera drivers, SD logging).
+
 ## Running Tests
 
 ```bash

Makefile

@@ -60,6 +60,7 @@ test-arm:
 	@echo "=== ARM C++ Unit Tests ==="
 	cd arm && $(MAKE) sim
 	cd test && g++ -std=c++17 -O2 -I.. -I../arm -o test_arm_cp test_arm_collision_predictor.cpp -lpthread && ./test_arm_cp
+	cd arm && $(MAKE) test-logger
 
 test-fpga:
 	@echo "=== FPGA C++ Testbench ==="