Extract shared docs and slim variant READMEs by dougborg · Pull Request #7 · f1yaw4y/FlockSquawk

dougborg · 2026-02-02T08:06:53Z

Stack order: 5/8 — merge after #6 (PR4: Docker and deps)

Summary

Extract shared documentation into docs/ directory covering architecture, build system, configuration, extending, getting started, telemetry format, testing, and troubleshooting
Slim variant READMEs to focus on variant-specific information and link to shared docs
Update CLAUDE.md to reference new doc locations

Test plan

Verify all internal doc links resolve correctly
Verify variant READMEs link to appropriate shared docs
Check that CLAUDE.md task-to-file mappings are accurate

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Provides per-variant build/upload/flash/monitor targets for all 6 hardware variants, plus LittleFS data upload for variants with audio assets. Uses GNU Make define/eval/call to generate targets from a single template. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Tests compile natively with clang++/g++ — no ESP32 hardware needed. Covers detectors, device tracker state machine, and threat analyzer scoring pipeline (37 cases, 126 assertions) targeting the M5Stick variant's pure-logic headers. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Move DetectorTypes.h, Detectors.h, DeviceSignatures.h, EventBus.h, ThreatAnalyzer.h, and TelemetryReporter.h from the M5Stick variant's src/ into a new top-level common/ directory. Update Makefile to pass -I common via build.extra_flags for all variants, update test includes, and fix the M5Stick FQBN (m5stick_c_plus2 -> m5stack_stickc_plus2). Merge AudioEvent (from M5Fire's EventBus.h) into the shared header so other variants can adopt it when migrated. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Delete local copies of EventBus.h, DeviceSignatures.h, ThreatAnalyzer.h, and TelemetryReporter.h from m5fire/src/. Replace legacy ThreatAnalyzer (simple boolean matching) and TelemetryReporter (DynamicJsonDocument with nested objects) implementations with the shared detector-based system. Add ISR-safe deferred event processing with portMUX spinlocks for WiFi, BLE, and threat events. Add ThreatAnalyzer::tick() heartbeat in loop() and shouldAlert gate on triggerAlert(). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Delete local copies of EventBus.h, DeviceSignatures.h, ThreatAnalyzer.h, and TelemetryReporter.h from mini12864/src/. Replace legacy ThreatAnalyzer and TelemetryReporter implementations with shared detector-based system. Add ISR-safe deferred event processing with portMUX spinlocks. Move display notifications (Mini12864DisplayNotifyWifiFrame, ShowAlert) and audio playback to the main loop's deferred handlers. Add tick() heartbeat and shouldAlert gate. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Also fix Makefile build.extra_flags override that was clobbering ESP32 core defines (-DESP32=ESP32 etc). Use build.defines instead, which is included within build.extra_flags and starts empty. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Move variant-specific src/ files into sketch directory to follow Arduino convention. Keep Flipper's own TelemetryReporter (line-based protocol for Flipper app). Fix radioType null-check for char array. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Dockerfile builds a debian:bookworm-slim image containing arduino-cli, ESP32 core v3.0.7, all Arduino libraries (version-pinned), doctest.h, and pre-warmed core caches for all 4 FQBNs. Source is bind-mounted at runtime so the image is reusable across branches. Also adds docker-compose.yml (build-all, test, shell, build-variant services), entrypoint.sh (seeds doctest.h into bind-mount), .dockerignore, and Makefile docker-* targets. Fixes a portability bug in test/mocks/Arduino.h: adds <cstdio> for snprintf, which macOS clang resolves transitively but Debian clang-14 does not. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Audit all dependency versions against latest available in the Arduino library index, update where possible, and centralize pins in a single versions.env file consumed by both Makefile (include) and Dockerfile (--build-arg). Version changes: - Base image: debian:bookworm-slim → debian:trixie-slim (Debian 13) - arduino-cli: unpinned → 1.4.1 - ArduinoJson: 7.3.0 → 7.4.2 - NimBLE-Arduino: 2.2.1 → 2.3.7 - M5Unified: 0.2.2 → 0.2.11 - Adafruit SSD1306: 2.5.13 → 2.5.16 - doctest: 2.4.11 → 2.4.12 - ESP32 core: 3.0.7 (unchanged — newer causes IRAM overflow) - U8g2: 2.35.30 (unchanged — already latest in Arduino index) - Adafruit GFX: 1.12.4 (unchanged — already latest) Makefile install-deps now pins library versions from versions.env, matching what the Dockerfile installs. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Move duplicated content (setup, architecture, telemetry, configuration, troubleshooting, extending) from 6 variant READMEs into 8 shared docs/ files. Add new docs for build system and testing (previously undocumented). Restructure CLAUDE.md as a scannable agent gateway with dispatch table. Fix incorrect .ino filename reference in portable variant README. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Copilot

Pull request overview

This PR refactors the FlockSquawk project to centralize documentation and extract shared code into a common directory. It introduces comprehensive documentation in docs/, slims variant READMEs to focus on variant-specific information, and consolidates shared headers into common/. The PR also adds a complete build system with Makefile, Docker support, and host-side unit tests.

Changes:

Extract 8 comprehensive documentation files into docs/ covering architecture, build system, configuration, extending, getting started, telemetry format, testing, and troubleshooting
Slim all variant READMEs to reference shared docs and focus on variant-specific setup
Consolidate shared headers (EventBus, ThreatAnalyzer, Detectors, DeviceSignatures, TelemetryReporter) into common/ directory
Add complete build infrastructure: Makefile with per-variant targets, Dockerfile with pre-baked dependencies, docker-compose.yml
Introduce versions.env as single source of truth for all dependency versions
Add host-side unit tests using doctest framework with comprehensive test coverage
Update CLAUDE.md with quick reference and task-to-file mappings

Reviewed changes

Copilot reviewed 63 out of 67 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
docs/*.md	8 new documentation files providing comprehensive project-wide guidance
common/*.h	Shared headers extracted from variant src/ directories (EventBus, ThreatAnalyzer, Detectors, etc.)
*/README.md	Slimmed variant READMEs now reference shared docs
Makefile	Complete build automation with variant targets, Docker integration, test runner
Dockerfile, docker-compose.yml	Reproducible build environment with all dependencies pre-baked
versions.env	Centralized dependency version management
test/*	Host-side unit tests with doctest framework, mocks, and comprehensive coverage
entrypoint.sh	Docker entrypoint for seeding doctest.h into bind-mounted workspace
.gitignore, .dockerignore	Build artifacts and Docker exclusions
CLAUDE.md	AI assistant quick reference with file mappings

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

Copilot · 2026-02-02T08:14:57Z

 public:
    static const uint8_t MAX_WIFI_CHANNEL = 13;
-    static const uint16_t CHANNEL_SWITCH_MS = 500;
+    static const uint16_t CHANNEL_SWITCH_MS = 1000;


Changed CHANNEL_SWITCH_MS from 500 to 1000ms. This doubles the time spent on each WiFi channel, which may cause the system to miss brief transmissions on other channels. This appears to be an unintended change as it's not mentioned in the PR description and differs from other variants (which remain at 500ms). Consider reverting to 500ms to maintain consistency across variants.

Copilot · 2026-02-02T08:14:58Z

+
 private:
-    static uint8_t currentWifiChannel;
+    static volatile uint8_t currentWifiChannel;


Changed from static to volatile static. While this is correct for thread safety (the variable is accessed from ISR context), it's inconsistent with the pattern used in other variants where this variable isn't declared volatile. Verify that this change is intentional and doesn't introduce synchronization issues. The Flipper variant also doesn't use volatile for this field.

Copilot · 2026-02-02T08:14:58Z


    Serial.printf("ALERT,RSSI=%d,MAC=%s", threat.rssi, macStr);
-    if (threat.radioType) {
+    if (threat.radioType[0] != '\0') {


Checking if radioType is not an empty string by comparing the first character is insufficient. The field is now a fixed-size char array (char radioType[16]) instead of a const char pointer, so this check should use strlen(threat.radioType) > 0 or simply remove the check entirely since radioType should always be populated. The original code checked if the pointer was non-null, which made sense for pointer types but not for arrays.

Copilot · 2026-02-02T08:14:59Z

+if [ -d "test" ] && [ ! -f "${DOCTEST_DST}" ] && [ -f "${DOCTEST_SRC}" ]; then
+    cp "${DOCTEST_SRC}" "${DOCTEST_DST}"
+fi


The entrypoint script copies doctest.h from a pre-baked location into the bind-mounted source tree if missing. However, this approach has a subtle issue: if test/doctest.h already exists in the host filesystem (e.g., from a previous make test run), it won't be updated even if the Docker image contains a newer version. Consider adding a version check or timestamp comparison, or always copy to ensure consistency with the Docker image's pinned version.

dougborg and others added 13 commits February 2, 2026 00:48

Add pluggable detector system with scoring pipeline and device tracking

d9825be

Add CLAUDE.md with project architecture and build guidance

cfa53a3

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Migrate 128x32 Portable variant to common/ shared headers

d693bb7

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings February 2, 2026 08:06

dougborg mentioned this pull request Feb 2, 2026

Improve detection scoring and expand surveillance OUI coverage #8

Merged

4 tasks

Copilot started reviewing on behalf of dougborg February 2, 2026 08:07 View session

Copilot AI reviewed Feb 2, 2026

View reviewed changes

dougborg mentioned this pull request Feb 2, 2026

Add pluggable detector system with scoring pipeline and device tracking #3

Open

4 tasks

f1yaw4y merged commit beac852 into f1yaw4y:main Mar 8, 2026
5 of 6 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Extract shared docs and slim variant READMEs#7

Extract shared docs and slim variant READMEs#7
f1yaw4y merged 13 commits into
f1yaw4y:mainfrom
dougborg:pr/05-docs

dougborg commented Feb 2, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

dougborg commented Feb 2, 2026

Summary

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants