Software/Android-KTag-Apps
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Initial public release.

Browse source
This commit is contained in:
Joe Kearney 2026-03-01 17:03:10 -06:00
parent ed31acd60f
commit 58d87b11b7
249 changed files with 15831 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

86
subapp-sentry/README.md Normal file
View file

@ -0,0 +1,86 @@
# Sentry
An autonomous sentry gun subapp that uses the device camera and on-device machine learning to detect people and automatically send a tag from a KTag blaster connected via USB when a person is detected in the crosshair.
## How It Works
1. The back camera streams frames continuously through CameraX.
2. Each frame is analyzed by **MediaPipe Tasks Vision** running the **EfficientDet-Lite0** object detection model entirely on-device — no network connection required.
3. When a person is detected with ≥ 50 % confidence, a red bounding box is drawn over them and a continuous 880 Hz tone plays (if enabled).
4. If the bounding box overlaps the crosshair at the centre of the screen, the sentry fires: it sends a trigger-press command followed by a trigger-release command over USB serial to the connected KTag device.
5. A cooldown period prevents the sentry from firing again until the timer expires.
## Setup
### 1. Download the detection model
The EfficientDet-Lite0 model is not bundled with the APK and must be placed manually:
```
subapp-sentry/src/main/assets/efficientdet_lite0.tflite
```
Download the **TFLite (efficientdet/lite0/detection/metadata/1)** file from:
> https://tfhub.dev/tensorflow/lite-model/efficientdet/lite0/detection/metadata/1
### 2. Connect a KTag device via USB
Plug a KTag device into the Android device using a USB OTG cable. The app will detect it automatically and show it in the device selector.
### 3. Grant camera permission
The app requests `CAMERA` permission on first launch. Deny it and the camera preview will not start.
## UI
| Element | Description |
|----------------------|-----------------------------------------------------------------------------------------------------|
| Camera preview | Full-screen live view from the back camera |
| Red bounding box | Drawn around any detected person |
| White crosshair | Fixed plus symbol at the centre of the screen; firing only occurs when it overlaps the bounding box |
| **DETECTED** badge | Appears in the top-right corner whenever a person is visible |
| Device selector | Drop-down listing connected USB serial devices |
| Connect / Disconnect | Connects to the selected USB device or drops the connection |
| Status bar | Shows connection state, configured team, and time since last trigger |
## Settings
Open the settings screen via the gear icon in the top-right corner.
| Setting | Options | Default | Description |
|---------------------|----------------------|---------|----------------------------------------------------------|
| Tag Team | Blue, Red, Purple | Blue | Team argument sent in the trigger command |
| Trigger Cooldown | 3 s, 5 s, 10 s, 30 s | 5 s | Minimum time between consecutive trigger firings |
| Play Detection Tone | On / Off | On | Plays a continuous 880 Hz tone while a person is visible |
## USB Serial Protocol
When the sentry fires, it simulates a trigger press by sending two commands in sequence:
```
KEvent 7 0\n ← trigger press
KEvent 8 0\n ← trigger release
```
The device selector lists all recognised USB serial devices. The app requests USB permission automatically on first connect.
## Audio
| Sound | Condition | Details |
|------------------------|-------------------------|----------------------------------------------------------------------------------------------|
| Continuous 880 Hz tone | Person visible in frame | `AudioTrack` sine wave; plays until person leaves frame or "Play Detection Tone" is disabled |
| Short beep | Sentry fires | 200 ms `ToneGenerator` beep |
Both sounds play on the media audio stream and respect the device's media volume.
## Dependencies
| Library | Version | Purpose |
|------------------------|---------|----------------------------------------------------------|
| CameraX | 1.4.0 | Camera preview and frame capture |
| MediaPipe Tasks Vision | 0.10.32 | On-device object detection |
| EfficientDet-Lite0 | 1 | Person detection model (Apache-2.0, download separately) |
| usb-serial-for-android | 3.10.0 | USB serial communication with KTag hardware |
> **Note:** MediaPipe transitively includes Firebase. The `AndroidManifest.xml` explicitly removes `FirebaseInitProvider` via `tools:node="remove"` to prevent any Firebase initialisation.