BirdShot Public Release

BirdShot is an offline-first CLI and local web UI for lab-owned Flock hardware research workflows.

Why BirdShot Exists

BirdShot exists because the Bird Hunting Season, formally known as Examining the Security Posture of an Anti-Crime Ecosystem, research outgrew scattered scripts, ad hoc notes, and one-off validation steps.

The project started as independent hardware, firmware, Android, wireless, BLE, local-service, media, and deployment research. Over time, the hard part became repeatability: keeping device state, work orders, logs, service checks, media validation, and evidence collection organized across multiple device families and research phases.

BirdShot is the operational synthesis of that work. It turns the public research into a repeatable framework for authorized lab/dev hardware, fixtures, and defensive validation.

Disclaimer

BirdShot is provided for educational, defensive, authorized research, and controlled lab use only. Use it only on hardware, networks, services, and data that you own or have explicit permission to test.

This public release does not include private keys, private tokens, live secrets, or BirdEye .tflite model binaries.

Quick Start

CLI:

python3 -m pip install -r Birdshot/requirements.txt
python3 -m Birdshot --config Birdshot/samples/lab_falcon.json

API:

uvicorn Birdshot.server:app --reload

UI:

cd Birdshot/birdshot-ui
npm install
npm run dev

BirdEye model files go under:

birdeye/assets/models/objects/

Related Research and References

The following GainSec publications are the public research context behind BirdShot. They are useful for understanding which device family or surface a BirdShot module maps to and what evidence or workflow it was built around. All vulnerabilities, issues, research, and related findings followed responsible coordinated disclosure. Flock has made multiple public statements and responses related to the research and surrounding claims:

Link	Date	Context
Gunshot Detection and License Plate Reader Security Alert	May 5, 2025	Flock customer/security alert covering gunshot detection and LPR device vulnerabilities.
Response to Compiled Security Research on Flock Safety Devices	November 6, 2025	Flock response to the published whitepaper and compiled device/software research.
Security is never "done." It's a commitment	December 8, 2025	Flock CEO Garrett Langley public LinkedIn statement on security posture.
Update on Limited Condor Device Configuration Issue	December 23, 2025	Flock statement about the Condor device configuration issue.
Has Flock Been Hacked?	January 6, 2026	Flock response to public claims about hacking, cloud compromise, and security research.

Link	Applicable to	Covers
Bird Hunting Season - Security Research on Flock Safety's Anti-Crime Systems	Entire Flock/Bird Hunting Season research series	Project overview, background on the ecosystem, device families, disclosure timeline, and links to the full disclosure series.
Plucked and Rooted - Device 1: Debug Shell on Flock Safety's Raven Gunshot Detection System	Raven	Raven hardware access, debug shell path, ESP32/security configuration findings, BLE/telemetry context, and Raven-specific vulnerability detail.
Grounded Flight - Device 2: Root Shell on Flock Safety's Falcon/Sparrow Automated License Plate Reader	Falcon / Sparrow LPR	Falcon/Sparrow hardware teardown, Android/bootloader/EDL path, root shell workflow, and physical/device security issues.
Trap Shooter - Flock Safety Sniffer & Alarm	Trap Shooter / Wi-Fi awareness	Companion sniffer/alarm project for detecting Flock-related wireless activity.
Root from the Coop - Device 3: Root Shell on Flock Safety's Picard/Bravo Compute Box	Picard / Bravo compute box	Compute-box hardware/software security, EDL/QDL, bootloader, secure boot, root shell path, and Bravo/Picard issue set.
Fly-By - Device 2: The Falcon/Sparrow - Gated Wireless RCE, Camera Feed, DoS, Information Disclosure and More	Falcon / Sparrow, Collins, Android apps, wireless/local network	Expanded Falcon/Sparrow wireless/local-service research, Collins API exposure, camera feed behavior, app secrets, hardcoded credentials, and related CVEs.
Button Presses to Wireless RCE: Shell on Flock Safety's License Plate Cameras Over Wi-Fi	Falcon / Sparrow wireless chain	Focused walkthrough of the button/hotspot/wireless path to shell, including hotspot association, Collins ADB enablement, and ADB shell access.
Formalizing my Flock Safety Security Research	Whitepaper / formal research record	Whitepaper announcement, formal statement, defenders checklist, and the indexed public write-up list.
BirdEye	BirdEye / visual ML replay	TensorFlow Lite visual recognition replay harness for webcam, recorded footage, and extracted session directories. BirdShot includes this as the birdeye/ harness.
Finding 67 Flock Safety Live PTZ Camera/LPR Feeds and Debug Web Interfaces accidentally exposed without authentication to the internet	Condor/PTZ camera feeds, LPR feeds, exposed debug web interfaces, Collins/local services, SpeedPourer/FRP context	Internet-exposed live camera/debug interface research, methodology for expanding from initial leads, exposed PTZ/LPR surface types, and follow-on network/service risk context.

Whitepaper and formal artifacts:

Link	Applicable to	Covers
GainSec whitepaper PDF on GitHub	Entire research set	Formal whitepaper: Examining the Security Posture of an Anti-Crime Ecosystem.
GainSec Defender's Checklist on GitHub	Defenders / operators / assessors	Spreadsheet checklist referenced by the whitepaper for reviewing findings, CVEs, affected areas, and defensive validation items.
Latest Zenodo record for v1.2 public release	Entire research set / citation	Archived v1.2 public release with the formal whitepaper, statement, and defenders checklist.
Anti-crime ecosystem research repository	Entire research set / source bundle	Repository containing the whitepaper release materials and related formal artifacts.
Bird Hunting Season Final Flight Presentation Slides	Def Con 34 Main Stage Presentation Slides	V1 of the presentations slide deck.
Bird Hunting Season Final Flight Presentation Companion	Def Con 34 Main Stage Presentation Companion Paper.	Includes all fully disclosed findings from whitepaper, extras, more information from the research project and more.

Device shell walkthroughs:

Goal	Article
Get a debug shell on the Raven Gunshot & Scream Audio Detection System	Follow Plucked and Rooted - Device 1: Debug Shell on Flock Safety's Raven Gunshot Detection System.
Get a root shell on the Falcon/Sparrow LPR	Follow Grounded Flight - Device 2: Root Shell on Flock Safety's Falcon/Sparrow Automated License Plate Reader.
Get a root shell on the Picard/Bravo Compute Box	Follow Root from the Coop - Device 3: Root Shell on Flock Safety's Picard/Bravo Compute Box.

What It Is For

BirdShot is for:

• Running repeatable checks against hardware you own or are explicitly authorized to test.
• Preserving evidence and reducing mistakes during multi-step device workflows.
• Working offline or in field/lab conditions without depending on cloud access.
• Using one interface across CLI, FastAPI, and Web UI workflows.
• Mirroring the workflows used during the research: wireless, BLE, local APIs, live view, crashpacks, ADB/JDWP, telemetry, reporting, and media validation.
• Turning Bird Hunting Season from a collection of disclosures and writeups into reusable research infrastructure.

What It Is Not For

BirdShot is not:

• A tool for attacking live third-party deployments.
• A repository of private keys, private tokens, or live secrets.
• A guarantee that every deployment or device is in the same state as the research hardware.
• A replacement for authorization, vendor remediation, coordinated disclosure, or operator approval.

Layout

• Birdshot/ - Python CLI, FastAPI service, shared toolkit, JDWP helpers, and React/Vite UI source.
• Birdshot/birdshot-ui/public/ - UI media assets used by the Vite app.
• Birdshot/birdshot-ui/dist/ - prebuilt UI assets.
• birdeye/ - BirdEye visual model replay harness and documentation.

Capability Inventory

BirdShot exposes the same core workflows through three interfaces:

• Interactive CLI: python3 -m Birdshot --config Birdshot/samples/lab_falcon.json
• Local API: uvicorn Birdshot.server:app --reload
• Browser UI: cd Birdshot/birdshot-ui && npm run dev

The CLI main menu exposes:

• Shared Toolkit Workflow
• Falcon / Falcon LR Utilities
• Picard / Avicore Conversions
• Raven Health Snapshot
• Penguin Packs
• Condor Utilities
• Trap Shooter
• Collins API
• JDWP Shell
• Auto - Wireless RCE
• Auto - Wireless RCE (System Shell)
• BirdEye Visual Model Replay

Menu Reference

BirdShot is organized around device families and the workflow surfaces found during the research. The CLI is the canonical menu. The API and web UI expose most of the same operations as callable actions.

Main menu:

Menu	Device / surface	What it does
1. Shared Toolkit Workflow	Cross-device workflow model	Opens the offline workflow shell for devices, work orders, tasks, live view, crashpacks, BLE, and debug actions.
2. Falcon / Falcon LR Utilities	Falcon, Falcon LR, Sparrow	Runs Falcon local API workflows, installer task helpers, Sparrow battery pairing, camera health, and guidance.
3. Picard / Avicore Conversions	Picard, Bravo/Picard compute box, Avicore migration workflows	Tracks Avicore-to-Picard conversion state, config lookup, Picard registration, Avicore retirement, and PTZ validation guidance.
4. Raven Health Snapshot	Raven gunshot detection device	Scans Raven BLE, reads LTE/battery telemetry, and shows Raven install checklist state.
5. Penguin Packs	Penguin battery pack	Pushes auth over BLE, reads battery/firmware state, and runs Nordic DFU update helpers.
6. Condor Utilities	Condor PTZ camera	Shows PTZ-camera status fields, install steps, boot validation steps, and Condor work-order tasks.
7. Trap Shooter	Wireless surface used by Falcon/Sparrow/Picard-class devices	Scans Wi-Fi interfaces for Flock hotspots, joins selected hotspots, and applies DHCP or static lab addressing.
8. Collins API	Collins local admin/service API	Checks local Collins reachability and runs live view, system, camera, modem, crashpack, and ADB actions.
9. JDWP Shell	Android devices exposing JDWP through ADB	Wraps jdwpifer/jdwp_exec.py to execute commands through a selected package/breakpoint.
10. Auto - Wireless RCE	Wireless + Collins + ADB chain	Finds or reuses a Flock hotspot, connects, enables ADB through Collins, and attempts an ADB shell.
11. Auto - Wireless RCE (System Shell)	Wireless + Collins + ADB + JDWP chain	Continues the wireless chain into JDWP-backed command execution.
12. BirdEye Visual Model Replay	Falcon/Sparrow/Picard/Bravo visual ML/media assets	Replays extracted visual recognition model metadata against webcam, video, frames, or session directories.
Q. Exit	CLI	Leaves the interactive CLI.

Global CLI commands available from the main menu:

Command	Device / surface	What it does
device / d	Any active device ID	Switches the active device used by workflow menus.
devices	Offline shared toolkit cache	Lists cached devices loaded from config or added during the session.
add / adddevice / add-device	Offline shared toolkit cache	Creates an offline device record and switches the active device to it.
jobs	Offline shared toolkit cache	Lists cached jobs and tasks.
scan	BLE-capable host and nearby peripherals	Runs the shared BLE scanner.

Shared Toolkit workflow commands:

Command / screen	Device / surface	What it does
Device screen	Any seeded device	Shows the selected device record and branches into work-order or Bluetooth flows.
work	Any seeded device with jobs/tasks	Opens work orders for the active device.
bt	BLE-capable host	Runs Bluetooth/BLE scan from inside the workflow shell.
force / wipe / shutdown / forcewipe	Android device reachable by ADB	Runs the explicit Force Wipe & Shutdown debug action after operator selection.
Work Orders screen	Any seeded job	Lists jobs and opens a selected job's task list.
`select <#	job-id>`	Any seeded job
Tasks screen	Any seeded task list	Shows task status, supports completing tasks, and branches into live-view/crashpack helpers.
complete <n>	Any seeded task	Marks the selected task complete in the offline job cache.
live	Devices with a configured live-view endpoint	Prints live-view launch information, usually an external ffplay command.
crash	Devices with crashpack support	Requests or records a crashpack bundle through the offline or registered crashpack service.
back	Workflow shell	Moves back one workflow screen.
exit	Workflow shell	Leaves the Shared Toolkit workflow.

Falcon / Sparrow menu:

Menu	Device / surface	What it does
Web/API: Status Snapshot	Falcon / Falcon LR offline cache	Shows local Falcon status for a selected device ID.
1. LAPI camera-control unlock and optionally update task	Falcon / Falcon LR local API	Sends the PTZ-named local LAPI unlock command observed in the app/API surface and can mark an installer task complete. This is endpoint naming, not a claim that Falcon/Sparrow are physical PTZ cameras.
2. LAPI preset command and stop	Falcon / Falcon LR local API	Sends the PTZ-named preset command observed in the app/API surface, waits for the requested duration, then sends stop. This is only applicable where that endpoint exists/responds.
3. Register Falcon device	Falcon / Falcon LR installer workflow	Submits Falcon registration to the installer API using job ID, serial, and optional MAC.
4. Pair Sparrow external battery and submit task	Sparrow / Falcon battery pairing workflow	Records camera and external battery serials, verifies local pairing state, and submits a task update.
5. Fetch camera health snapshot	Falcon / Falcon LR	Reads local camera health from the Falcon LAPI status endpoint.
6. Installer instructions	Falcon / Falcon LR	Prints installer workflow guidance.
7. Wi-Fi hotspot guidance	Falcon / Falcon LR	Prints hotspot/local-network guidance for lab workflows.
8. Back to main menu	CLI	Returns to the main menu.

Picard / Avicore menu:

Menu	Device / surface	What it does
1. Fetch Avicore configuration	Avicore / Picard conversion	Looks up Avicore config by serial and stores it in conversion state.
2. Set/Update Picard external ID	Picard conversion	Stores the Picard external ID in the current conversion state.
3. Submit conversion task update	Avicore-to-Picard workflow	Submits the current conversion state to the workflow API.
4. Register Picard camera	Picard	Registers a Picard camera with job ID, serial, external ID, and optional location.
5. Retire Avicore device	Avicore	Deregisters or retires the selected Avicore external ID.
6. Show current conversion state	Picard / Avicore conversion	Prints the in-memory conversion state.
7. PTZ / installation guidance	Picard conversion workflow	Prints conversion checklist and PTZ validation steps.
8. Back to main menu	CLI	Returns to the main menu.

Raven menu:

Menu	Device / surface	What it does
1. Scan Raven BLE characteristics	Raven BLE	Discovers Raven peripherals and caches scan results.
2. View LTE & Battery Telemetry	Raven BLE	Reads Raven BLE characteristics, parses LTE/battery data, and records telemetry.
3. Raven install checklist	Raven workflow	Seeds and displays Raven install tasks.
4. Back to Main Menu	CLI	Returns to the main menu.

Penguin Packs menu:

Menu	Device / surface	What it does
1. Stage enable bundle	Penguin battery pack over BLE	Pushes auth key, reads battery state, and reads bootloader/firmware versions.
2. Stage firmware update	Penguin battery pack over BLE + Nordic DFU	Pushes auth, verifies state, and runs bootloader/app DFU ZIP updates through nrfutil.
3. Status guidance	Penguin workflow	Prints battery enablement and firmware readiness guidance.
4. Back to Main Menu	CLI	Returns to the main menu.

Condor menu:

Menu	Device / surface	What it does
1. View Condor status	Condor PTZ camera	Displays Condor status fields from the offline cache.
2. Installer steps	Condor PTZ camera workflow	Prints Condor install steps.
3. Boot & validation checklist	Condor PTZ camera workflow	Prints boot and validation checks.
4. Review Condor work order tasks	Condor PTZ camera workflow	Seeds and displays Condor job tasks.
5. Back to Main Menu	CLI	Returns to the main menu.

Trap Shooter flow:

Step / action	Device / surface	What it does
List Wi-Fi interfaces	Host laptop	Shows wireless adapters and connection state.
Scan for Flock SSIDs	Host laptop near lab hardware	Repeatedly scans for SSIDs containing Flock.
Select hotspot	Falcon/Sparrow/Picard-class hotspot	Lets the operator choose a discovered Flock hotspot.
Connect to hotspot	Host laptop and lab device	Joins the selected hotspot using the lab default credential.
Static IP option	Host laptop interface	Applies 192.168.43.137/24 via 192.168.43.1 when selected.
DHCP option	Host laptop interface	Restores DHCP for the connection.
Continuous scan	Host laptop	Keeps scanning and printing matching hotspots.

Collins API menu:

Menu	Device / surface	What it does
1. Enable Live View	Collins local API	Enables local live-view streaming.
2. Disable Live View	Collins local API	Disables local live-view streaming.
3. System Reboot	Collins local API	Requests a system reboot.
4. Switch Enable	Collins local API	Calls the switch-enable endpoint.
5. Modem Stats	Collins local API	Reads modem status.
6. Battery Info	Collins local API	Reads battery status.
7. OS Build Info	Collins local API	Reads OS build information.
8. Apps Report	Collins local API	Reads installed/running app report data.
9. Logs Dump	Collins local API	Requests local system logs.
10. Crashpack Bundle	Collins local API	Requests a crashpack bundle.
11. Disable Internal Battery	Collins local API	Calls the internal-battery disable endpoint.
12. Set Battery Shutdown Delay	Collins local API	Sets shutdown delay seconds.
13. Enable ADB over TCP	Collins local API + ADB	Enables TCP ADB and optionally connects to the device.
14. List Stored Crashpacks	Collins local API	Lists stored crashpack artifacts.
15. Camera Settings (GET)	Collins local API	Reads camera settings.
16. Camera Registration Status	Collins local API	Reads registration state.
17. Camera OTA Status	Collins local API	Reads camera OTA state.
18. Modem APN List	Collins local API	Reads modem APN entries.
19. Disable ADB over TCP	Collins local API	Disables TCP ADB.
Q. Back to main menu	CLI	Returns to the main menu.

JDWP Shell menu:

Prompt / setting	Device / surface	What it does
ADB serial	Android device reachable by USB or TCP ADB	Chooses the target device for JDWP work.
Target package	Android app exposing JDWP	Defaults to com.flocksafety.android.cameraconfig.
Breakpoint method	JDWP target method	Defaults to java.net.ServerSocket.accept.
Local port	Host laptop	Forwards JDWP locally for command execution.
Shell command	Android process context	Runs the requested command through the JDWP helper.

Auto Wireless menus:

Menu / stage	Device / surface	What it does
Auto - Wireless RCE	Host Wi-Fi + Collins + ADB	Connects to the hotspot, enables ADB over TCP, and attempts ADB shell access.
Auto - Wireless RCE (System Shell)	Host Wi-Fi + Collins + ADB + JDWP	Runs the wireless chain, connects ADB, and launches JDWP command execution.
/auto/wireless/prep	API/UI split-stage prep	Connects to the hotspot and records gateway/session state without firing a command.
/auto/wireless/shell	API/UI ADB shell stage	Reuses the prepared connection and runs an ADB shell command.
/auto/wireless/system	API/UI JDWP system stage	Reuses the prepared connection and runs a JDWP-backed command.

BirdEye menu:

Menu / mode	Device / surface	What it does
1. Live webcam preview	Host camera + supplied model assets	Runs selected model against a webcam feed.
2. Replay recorded video	Recorded video + supplied model assets	Runs selected model against a video file.
3. Process session directory	Mounted media/session tree	Replays a device-style media session stage and writes detection reports/markers.
4. View latest summary	BirdEye output ledger	Prints the generated BirdEye summary ledger.
B. Back	CLI	Returns to the main menu.

Web UI panels:

Panel	Device / surface	What it does
Status	Any tracked device/session	Lists known device sessions, records device/IP/serial notes, shows ADB/IP hints, and runs LAN discovery.
CLI Modules	CLI action metadata	Renders supported CLI actions as browser forms and captures output.
Wi-Fi Utilities	Host Wi-Fi	Lists interfaces, scans SSIDs, and connects to selected SSIDs.
Collins API	Collins local API	Checks API reachability, runs Collins actions, and manages ADB port forwarding.
JDWP Shell	Android device reachable by ADB	Runs JDWP command execution from the browser.
Force Wipe & Shutdown	Android device reachable by ADB	Broadcasts the debug wipe/shutdown action after confirmation.
Live View Helpers	Collins local API / ADB	Ensures live view is running and provides capture helper material.
Auto Wireless Shell	Wireless + Collins + ADB	Runs prep and ADB shell command stages.
Auto Wireless System	Wireless + Collins + ADB + JDWP	Runs prep and JDWP-backed system command stages.
BirdEye	Supplied visual model assets	Runs BirdEye webcam/video/session replay and displays summary data.

Shared Toolkit

The shared toolkit is the local workflow engine that BirdShot uses when there is no cloud service available or when the operator wants a repeatable lab-only workflow. It is not one device-specific exploit module. It is the common state, navigation, repository, and service layer that lets BirdShot model "I have this device, these jobs, these tasks, this live-view endpoint, this crashpack request, this BLE scan, and this debug action" in one place.

Practically, the shared toolkit is useful when you want to:

• Seed devices and work orders from JSON before starting a lab session.

• Track device/task state without relying on a vendor backend.

• Reuse one Device -> Work Orders -> Tasks -> Live View -> Crashpack flow across multiple Flock device families.

• Swap from offline-only mode to a lab/dev HTTP backend by registering Retrofit-style clients.

• Keep analytics/telemetry/debug actions attached to the same local context while moving between menus.

• Device, job, task, crashpack, firmware, Wi-Fi credential, BLE peripheral, telemetry, and Raven telemetry data models.

• Compose-style navigation across Device, Work Orders, Tasks, Live View, and Crashpack fragments.

• Offline repositories for devices and jobs, with optional Retrofit-style HTTP clients for lab/dev backends.

• Services for analytics, BLE scanning/pairing, crashpack requests, debug actions, OTA staging/install triggering, and Wi-Fi credential provisioning.

• Config-file seeding for offline devices, jobs, tasks, lab clients, and BirdEye settings.

• Runtime commands to list devices, add an offline device, list jobs, run BLE scan, switch active device, and request force-wipe/shutdown from the shared workflow shell.

Falcon / Sparrow

Falcon and Sparrow workflows live primarily in Birdshot/falcon_sparrow.py and the Option 2 CLI/API group.

• Falcon local LAPI client for LAPI/V1.0 requests.
• PTZ-named LAPI camera-control commands observed in the app/API surface, including unlock, directional command values, preset command values, and stop. These names come from the software endpoint and do not mean every Falcon/Sparrow has physical PTZ hardware.
• Falcon camera health reads from Channel/0/System/Status.
• RTSP live-view URL helper for rtsp://<host>:8554/live.
• Installer API wrapper for task updates, device registration, and device deregistration.
• Falcon registration flow with job ID, serial number, and optional MAC address.
• Sparrow external battery pairing state, verification, artifact payload generation, and task submission.
• Installer instructions and Wi-Fi hotspot guidance.

Picard / Avicore

Picard and Avicore conversion helpers live in Birdshot/avicore_picard.py and the Option 3 CLI/API group.

• Avicore configuration lookup by serial.
• Mutable conversion state for Avicore serial/config, Picard external ID, and notes.
• Picard external ID capture.
• Conversion task submission through the workflow API.
• Picard camera registration with job ID, serial, external ID, and optional location hint.
• Avicore device retirement/deregistration.
• Batch conversion helper for submitting multiple task IDs from one conversion state.
• Conversion checklist and PTZ validation guidance.

Raven

Raven workflows use BLE helpers in Birdshot/raven_ble.py plus the Option 4 CLI/API group.

• Raven BLE peripheral discovery.
• Raven BLE characteristic snapshot reads.
• LTE metric parsing for RSSI, RSRP, RSRQ, and SINR.
• Battery percentage and voltage parsing.
• Raven telemetry recording into the shared analytics service.
• Raven install checklist seeding and display.

Penguin Packs

Penguin Pack workflows live in Birdshot/penguin_pack.py and the Option 5 CLI/API group.

• BLE client for Penguin Pack auth, battery, bootloader version, and firmware version characteristics.
• Auth-key push over BLE.
• Battery state reads: fully disabled, fully enabled, or charging disabled.
• Bootloader and firmware version reads.
• Enablement workflow that pushes auth and verifies battery state.
• Nordic nrfutil DFU handoff for bootloader and application ZIP packages.
• Combined enable-and-update flow.
• Status guidance for battery enablement, firmware revision, and MAC/serial tracking.

Condor

Condor workflows are exposed through the Option 6 CLI/API group. In this project, Condor refers to the PTZ camera device family, not Falcon/Sparrow LPR hardware.

• Condor status snapshot with PoE draw, backhaul throughput, and camera uptime fields.
• Installer step checklist.
• Boot and validation checklist.
• Condor work-order task seeding and review.

Trap Shooter / Wi-Fi

Trap Shooter and Wi-Fi helpers are implemented in Birdshot/main.py, Birdshot/server.py, and Birdshot/tools/.

• Wi-Fi interface listing.
• SSID scanning through NetworkManager nmcli on Linux.
• SSID scanning and association through networksetup on macOS.
• CoreWLAN fallback scanner through tools/corewlan_scan.swift and tools/corewlan_scan.py.
• Continuous scan mode for SSIDs containing Flock.
• Interactive Flock hotspot selection.
• Hotspot association using the lab default password.
• Optional static IP application or DHCP restoration.
• Gateway and interface CIDR detection.
• Cleanup flow to disable or reset the active Wi-Fi connection after automated work.

Collins API

Collins helpers are exposed through Option 8, /collins/*, and the web UI.

• API reachability check.
• Enable and disable live view.
• System reboot.
• Switch enable.
• Modem stats.
• Battery info.
• OS build info.
• Apps report.
• Logs dump.
• Crashpack bundle request.
• Disable internal battery.
• Set battery shutdown delay.
• Enable ADB over TCP and optionally connect with adb.
• List stored crashpacks.
• Read camera settings.
• Read camera registration status.
• Read camera OTA status.
• Read modem APN list.
• Disable ADB over TCP.
• Live-view ensure helper that tries Collins first and can fall back to starting com.flocksafety.android.collins/.InstallService over ADB.
• MJPEG and WebSocket live-view helper notes for external capture tools.

ADB, JDWP, and Debug Helpers

ADB/JDWP support is exposed through Option 9, /jdwp/run, /adb/forward, /debug/force-wipe, and the web UI.

• ADB device listing and manual serial entry.
• ADB TCP connect helper after Collins enables ADB.
• ADB port-forward creation and removal for local access to device services.
• JDWP command execution wrapper around Birdshot/jdwpifer/jdwp_exec.py.
• Configurable JDWP package, breakpoint method, local port, and shell command.
• Interactive JDWP shell loop.
• Force Wipe & Shutdown wrapper around the debug broadcast exposed by the device software.

Auto Wireless Chains

The automated wireless chains are exposed through CLI Options 10 and 11 plus /auto/wireless*.

• Auto-select or accept a Wi-Fi interface.
• Reuse an existing Flock hotspot connection when already associated.
• Scan for Flock SSIDs when not connected.
• Associate to the selected hotspot.
• Apply DHCP or static addressing depending on mode.
• Detect interface CIDR and gateway.
• Check Collins API reachability.
• Enable ADB over TCP through Collins.
• Attempt ADB connection to <gateway>:5555.
• Run an ADB shell command through /auto/wireless/shell.
• Run a JDWP-backed system command through /auto/wireless/system.
• Split-stage prep flow through /auto/wireless/prep so the UI can associate first, then fire commands.

Status, Discovery, and Web UI

The FastAPI server and React UI add browser-accessible workflow support.

• Local Swagger UI served with bundled static assets for offline docs.
• /menu endpoint mirroring the CLI main menu.
• /cli/actions metadata for web-rendered CLI modules.
• /cli/run captured execution for supported CLI actions.
• /wifi/interfaces, /wifi/scan, and /wifi/connect.
• /status/devices to list or manually record active device sessions.
• /status/hints to surface known ADB serials and known device IPs.
• /status/discovery/interfaces to list scan-capable interfaces with CIDR data.
• /status/discovery LAN host discovery using ARP/neighbor tables, nmap -sn when available, UDP nudging, and ping fallback.
• Browser panels for status tracking, CLI modules, Wi-Fi utilities, Collins, JDWP, force wipe, live view, Auto Wireless Shell, Auto Wireless System, and BirdEye.

BirdEye Visual Model Replay

BirdEye is the ML/media replay harness under birdeye/ and Birdshot/birdeye.py.

• Reads genuine model metadata from assets/models/objects/models.json.
• Supports SSD and YOLO-style TFLite metadata, labels, anchors, confidence thresholds, cluster thresholds, and input scaling.
• Lists available models from metadata.
• Runs against a live webcam.
• Replays recorded video files.
• Processes directories of still frames.
• Processes mounted session directories such as /mnt/expand/<UUID>/media/0/media.
• Watches a session stage continuously with --session-watch.
• Mirrors the Android-style media boundary by writing detection reports and detectionProcessed/ or discarded/ markers.
• Maintains a session index for idempotent session replay.
• Emits JSON detection reports.
• Appends run statistics to birdeye/detections/visualmodel-summary.md.
• Can disable display output for headless operation.
• Can cap runs with --max-frames.
• Exposes config, run, and latest-summary endpoints through /birdeye/config, /birdeye/run, and /birdeye/summary.

BirdEye Model Files

BirdEye ML model binaries are not included in this public release.

If you have model files from hardware or a licensed build, place them here:

birdeye/assets/models/objects/

Expected filenames are referenced by:

birdeye/assets/models/objects/models.json

The current metadata expects files such as:

• flock_small_tf.tflite
• MLM-2854-pico3-best-fp16.tflite
• MLM-2324-nano2-fp16.tflite
• MLM-2857-large-fp16.tflite

Keep the original filenames so models.json resolves correctly.

BirdEye includes:

• birdeye/SCRIPTS/run_tflite_detector.py - replay harness for live webcams, recorded video, still frames, or mounted session directories.
• birdeye/SCRIPTS/requirements-ml.txt and birdeye/SCRIPTS/requirements-ml-osx.txt - dependency pin sets for Linux and macOS/Apple Silicon.
• birdeye/docker/Dockerfile.ml - container recipe for reproducible BirdEye runs.
• birdeye/setup.sh - helper that creates a .venv, installs platform-specific dependencies, and prepares the CLI.
• birdeye/birdeye.md - replay workflow, CLI flags, model defaults, and runbook notes.

BirdEye Quick Start

cd birdeye
./setup.sh
source .venv/bin/activate

Python 3.11 or newer is recommended. On macOS, Homebrew Python works:

brew install python@3.11

BirdEye:

cd birdeye
python SCRIPTS/run_tflite_detector.py \
  --models-json assets/models/objects/models.json \
  --assets-root assets/models/objects \
  --model-name yolo_large_float16 \
  --camera 0

BirdEye will not run inference until the required .tflite model files are placed under birdeye/assets/models/objects/.

BirdEye session replay:

cd birdeye
python SCRIPTS/run_tflite_detector.py \
  --models-json assets/models/objects/models.json \
  --assets-root assets/models/objects \
  --model-name yolo_large_float16 \
  --session-root /mnt/expand/<UUID>/media/0/media \
  --session-stage motionProcessed

BirdEye writes detection JSON under detections/ for simple runs or detections_pipeline/detections/ for session mode. It also appends run stats to:

birdeye/detections/visualmodel-summary.md

In session mode, BirdEye mirrors the Android-style processing boundary by writing detection reports and creating detectionProcessed/ or discarded/ markers under the configured output tree.

The harness prints the BirdEye banner and, when display output is enabled, renders detections in a window titled:

Bird Hunting Season - BirdEye - By GainSec - Flock ML