Detention Block AA-23

BLE proximity-triggered control system for Star Wars themed installations. Raspberry Pi detects MOKO W6 BLE wristband beacons and triggers LED effects, MQTT events, and Arduino cell panel commands when characters enter range.

Quick Start

# 1. Flash Raspberry Pi OS Lite 64-bit (Bookworm) — enable SSH + WiFi in Imager
# 2. SSH in and clone this repo
git clone <your-repo-url> ~/detention-block
cd ~/detention-block

# 3. Run install (one time)
bash scripts/install.sh

Done. Auto-starts on boot. Auto-updates from git on every restart.

Configuration

Edit config/config.json with your W6 beacon MAC addresses:

nano ~/detention-block/config/config.json
sudo systemctl restart detention-block

Commands

sudo systemctl status detention-block     # Check status
sudo journalctl -u detention-block -f     # Live logs
sudo systemctl restart detention-block    # Restart (pulls latest code)
mosquitto_sub -t 'detention-block/#' -v   # Watch MQTT messages

Web Dashboard

http://<pi-ip>:3000

Architecture

• Raspberry Pi 3B — BLE scanner, control center, MQTT broker, web server
• MOKO W6 beacons — BLE 5.0 wristband tags on characters
• Arduino + Ethernet — MQTT subscriber, drives cell panel LEDs
• DFRobot MCP23017 — I2C IO expander for additional GPIO

Stack

• Node.js 20 (version-locked via .nvmrc)
• @abandonware/noble — BLE scanning
• express — REST API + dashboard
• mqtt — MQTT client (Mosquitto broker)
• onoff — GPIO control
• i2c-bus — MCP23017 IO expander

Detection Engine (5 layers)

1. RSSI Smoothing — rolling average removes per-packet noise
2. Hysteresis — different thresholds for enter (-60) vs leave (-75)
3. Debouncing — state stable for N seconds before confirming
4. Cooldowns — no re-trigger within timeout (Vader: 120s)
5. Absence Timeout — no signal for 15s = gone

Project Structure

├── src/
│   ├── main.js            # Entry point
│   ├── config.js          # Config loader
│   ├── scanner.js         # BLE scanning (noble)
│   ├── detection.js       # 5-layer detection engine
│   ├── effects.js         # Priority queue + GPIO coordination
│   ├── gpio.js            # LED patterns (onoff)
│   ├── mqttPublisher.js   # MQTT events/status/commands
│   └── web.js             # Express API + dashboard
├── config/
│   └── config.example.json
├── static/
│   └── index.html         # Web dashboard
├── arduino/
│   └── cell-panel/
│       └── cell-panel.ino # Arduino MQTT subscriber
├── scripts/
│   └── install.sh         # One-time Pi setup
├── sounds/                # WAV files (add your own)
└── docs/                  # Setup guide + implementation plan

See docs/ for the full implementation plan and Pi setup guide.