Extract shared headers and migrate all variants to common/

[dougborg]

Stack order: 3/8 — merge after #4 (PR2: build and test)

Summary

• Extract shared headers (DetectorTypes, Detectors, DeviceSignatures, EventBus, TelemetryReporter, ThreatAnalyzer) into common/ directory
• Migrate all 5 remaining variants to use shared headers via -I common:
  • M5Stack FIRE, Mini12864, 128x32 OLED, 128x32 Portable, Flipper Zero
• Remove duplicate header copies from each variant's src/ directory

Test plan

• Run make test to verify host-side tests still pass
• Compile each variant to verify include paths resolve correctly
• Verify no duplicate headers remain in variant src/ directories

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR consolidates duplicate code by extracting shared headers (DetectorTypes, Detectors, DeviceSignatures, EventBus, TelemetryReporter, ThreatAnalyzer) into a common/ directory, migrating all 5 remaining variants to use them via -I common. It also introduces a Makefile-based build system, comprehensive unit tests with doctest, and CLAUDE.md project documentation.

Changes:

• Extracted 6 shared headers into common/ directory with unified detector system, device tracking, and telemetry reporting
• Added Makefile with arduino-cli integration supporting all 6 variants, LittleFS flashing, and host-side unit tests
• Created test infrastructure with 322 unit tests covering detectors, device tracking, and threat analysis logic
• Updated all variant .ino files to use shared headers and implement deferred event processing for thread safety
• Added CLAUDE.md documentation describing architecture, build system, and development patterns

Reviewed changes

Copilot reviewed 43 out of 47 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
common/DetectorTypes.h	Defines detector result structures, flags, device states, and tracking constants
common/Detectors.h	Implements WiFi and BLE detector functions with weighted scoring and RSSI modifiers
common/DeviceSignatures.h	Contains MAC OUI prefix list for known surveillance devices
common/EventBus.h	Header-only event bus with updated ThreatEvent structure (char arrays instead of const char*)
common/ThreatAnalyzer.h	Unified threat analyzer with device tracker, detector registry, and heartbeat logic
common/TelemetryReporter.h	Standardized JSON telemetry output with detector weight reporting
Makefile	Arduino-cli build system with variant support, LittleFS upload, and host test targets
CLAUDE.md	Project documentation covering architecture, build system, and thread safety patterns
test/*.cpp	322 unit tests covering detectors, device tracking, and threat analysis
test/mocks/Arduino.h	Mock Arduino.h for host-side testing with minimal dependencies
test/eventbus_impl.cpp	EventBus implementation for test linking with mock millis()
m5stack/flocksquawk_m5stick/*.ino	Migrated to common headers, added thread-safe deferred event processing
m5stack/flocksquawk_m5fire/*.ino	Migrated to common headers with deferred processing and heartbeat support
Mini12864/flocksquawk_mini12864/*.ino	Migrated to common headers with FreeRTOS critical sections
128x32_OLED/flocksquawk_128x32/*.ino	Migrated to common headers with shouldAlert flag handling
128x32_OLED/flocksquawk_128x32_portable/*.ino	Migrated to common headers with buzzer heartbeat beeps
flipper-zero/.../flocksquawk-flipper/*.ino	Migrated to common headers, fixed radioType null check
*/src/RadioScanner.h	Updated CHANNEL_SWITCH_MS to 1000ms and made currentWifiChannel volatile (m5stick)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The CLAUDE.md documentation is now inaccurate after this PR's changes. Line 11 states "This is a pure Arduino IDE project (no CMake, PlatformIO, or Makefile)" but this PR adds a comprehensive Makefile build system.

Line 49 states "Variants do not share source files — each has its own copy of the core headers in src/" but this PR introduces shared headers in the common/ directory that all variants now use via -I common.

Line 73 states "The M5Stick variant introduces a function-pointer-based detector registry" but this PR migrates ALL variants to use the common detector system from common/ThreatAnalyzer.h.

These sections should be updated to reflect that:

1. A Makefile is now available for building all variants
2. Shared headers now exist in common/ (EventBus, ThreatAnalyzer, TelemetryReporter, Detectors, DetectorTypes, DeviceSignatures)
3. All variants now use the pluggable detector system, not just M5Stick

[Copilot]

The line 88 mentions "taskENTER_CRITICAL / taskEXIT_CRITICAL" but the actual code uses "portENTER_CRITICAL / portEXIT_CRITICAL" macros. These are different FreeRTOS APIs - portENTER_CRITICAL/portEXIT_CRITICAL are for synchronizing between tasks and ISRs (which is correct for this use case), while taskENTER_CRITICAL/taskEXIT_CRITICAL are for task-only synchronization. The documentation should be corrected to match the actual implementation.

Suggested change

	- `taskENTER_CRITICAL` / `taskEXIT_CRITICAL` for atomic reads/writes
	- `portENTER_CRITICAL` / `portEXIT_CRITICAL` for atomic reads/writes

[Copilot]

Inconsistent handling of the tick() return value across variants. The ThreatAnalyzer::tick() method returns true when a heartbeat beep should be emitted, but this return value is only checked in the m5stick and m5fire variants (lines 623-625 and 1158-1160 respectively).

The 128x32 OLED variant at line 550, Mini12864 variant at line 421, and Flipper Zero variant at line 463 all ignore the return value. While this may be intentional (e.g., Flipper has no audio), the 128x32_portable variant does have buzzer capability and should probably check the return value to emit heartbeat beeps.

Consider either using the return value consistently across all variants that have audio capability, or documenting why certain variants intentionally ignore it.

Suggested change

	threatEngine.tick(now);
	bool heartbeat = threatEngine.tick(now);
	if (heartbeat) {
	AudioEvent audioEvent;
	audioEvent.soundFile = "/heartbeat.wav";
	EventBus::publishAudioRequest(audioEvent);
	}

[Copilot]

The fetch-doctest target downloads and executes a third-party header from $(DOCTEST_URL) at build/test time without any integrity verification and only pins it to a mutable Git tag. If an attacker compromises the upstream repository or the tag, they could inject arbitrary C++ code into your test binary and run it in CI or developer environments with access to secrets. To reduce this supply-chain risk, vendor a known-good copy of doctest.h into the repo or pin to an immutable identifier (e.g., a specific commit hash) and verify it via checksum or signature before use.