Product Requirements Document

August 21, 2025 · View on GitHub

Flipper Zero Bluetooth Govee Smart LED Controller

Executive Summary

A Flipper Zero application enabling comprehensive control of multiple Govee Bluetooth-enabled LED devices simultaneously, providing advanced lighting automation, scene management, and device orchestration capabilities.

Product Overview

Vision Statement

Transform the Flipper Zero into the ultimate portable smart lighting controller for Govee ecosystems, enabling power users to manage complex lighting setups through a single, intuitive interface.

Target Users

  • Smart home enthusiasts with multiple Govee LED devices
  • Security researchers studying BLE protocols
  • Event organizers requiring portable lighting control
  • Technical users seeking advanced LED automation

Problem Statement

Current Limitations

  1. Fragmented Control: Users must switch between multiple apps to control different Govee devices
  2. Limited Portability: Smartphone dependency for LED control
  3. No Bulk Operations: Cannot synchronize actions across multiple devices efficiently
  4. Lack of Advanced Features: Missing scene sequencing, timing controls, and custom effects
  5. Protocol Understanding: Limited visibility into BLE communication patterns

Opportunity

Leverage Flipper Zero's hardware capabilities and portability to create a unified control solution that surpasses existing mobile applications in functionality and convenience.

Solution Requirements

Functional Requirements

Core Features

  1. Device Discovery & Management

    • Automatic BLE scanning for Govee devices (range: 10-30m)
    • Device identification by model (H6160, H6163, H6104, etc.)
    • Persistent device registry with custom naming
    • Signal strength monitoring (RSSI)
    • Battery level detection (where supported)

  2. Multi-Device Control

    • Simultaneous connection to 5+ devices
    • Group management (bedroom, living room, etc.)
    • Synchronized commands across groups
    • Individual device override within groups
    • Connection state management with auto-reconnect

  3. Color & Brightness Control

    • RGB color picker with hex input
    • HSV color space support
    • Brightness control (0-100%)
    • Color temperature adjustment (2700K-6500K)
    • Preset color palettes
    • Custom color saving

  4. Effects & Animations

    • Built-in Govee effects library
    • Custom effect creation
    • Effect speed control
    • Transition timing
    • Music sync mode activation
    • DIY mode support

  5. Scene Management

    • Pre-configured scenes (Movie, Reading, Party, etc.)
    • Custom scene creation
    • Scene scheduling
    • Scene sequencing
    • Ambient light response

  6. Automation Features

    • Time-based schedules
    • Sunrise/sunset simulation
    • Presence detection integration
    • Temperature-based triggers
    • Button macro recording
Advanced Features

  1. Protocol Analysis

    • BLE packet capture
    • Command logging
    • Protocol reverse engineering tools
    • Custom command injection
    • Response monitoring

  2. Backup & Restore

    • Device configuration export
    • Scene library backup
    • Settings migration
    • Cloud sync capability

  3. Integration Capabilities

    • BadUSB script generation
    • Sub-GHz trigger support
    • NFC tag programming
    • GPIO expansion support

Non-Functional Requirements

Performance
  • Device discovery: <3 seconds
  • Command execution: <100ms latency
  • Multi-device sync: <50ms deviation
  • Battery impact: <10% per hour active use
  • Memory usage: <256KB RAM
  • Storage: <1MB for app and data
Reliability
  • 99.9% command success rate
  • Automatic reconnection within 5 seconds
  • Graceful degradation with connection issues
  • Data persistence across restarts
  • Error recovery mechanisms
Usability
  • Zero configuration for basic operations
  • Intuitive navigation with Flipper controls
  • Visual feedback for all actions
  • Contextual help system
  • Accessibility considerations
Security
  • Encrypted device credentials storage
  • Secure BLE pairing process
  • Command authentication
  • No cloud dependency for core features
  • Privacy-focused design

User Interface Design

Screen Layouts

┌─────────────────┐
│ Govee Control   │
├─────────────────┤
│ > Quick Control │
│   Devices       │
│   Scenes        │
│   Schedule      │
│   Settings      │
└─────────────────┘
Device List
┌─────────────────┐
│ Devices (3)     │
├─────────────────┤
│ ◉ Bedroom LED   │
│   -45dBm  ON    │
│ ○ Desk Strip    │
│   -62dBm  OFF   │
│ ◉ TV Backlight  │
│   -51dBm  ON    │
└─────────────────┘
Color Control
┌─────────────────┐
│ Bedroom LED     │
├─────────────────┤
│ Color: [######] │
│ Bright: ████░░  │
│ Temp:   ███░░░  │
│                 │
│ [OK] Apply All  │
└─────────────────┘
  1. Quick Access: Single button to last used device
  2. Group Control: Long press for group selection
  3. Gesture Support: Directional pad for color/brightness
  4. Shortcut Keys: Programmable quick actions

Technical Architecture

System Components

BLE Manager
  • Device discovery service
  • Connection pool management
  • Command queue processor
  • Response handler
  • Keep-alive mechanism
Device Abstraction Layer
  • Model-specific drivers
  • Protocol translators
  • Capability detection
  • State synchronization
Scene Engine
  • Scene definition parser
  • Timeline executor
  • Effect renderer
  • Transition calculator
Storage System
  • Device database
  • Scene library
  • Configuration store
  • Log manager

Communication Protocols

Govee BLE Protocol
  • Service UUID: 0000180a-0000-1000-8000-00805f9b34fb
  • Characteristic UUIDs:
    • Control: 00010203-0405-0607-0809-0a0b0c0d1910
    • Status: 00010203-0405-0607-0809-0a0b0c0d1911
  • Command Structure:
    • Header: 0x33
    • Command type byte
    • Payload (varies)
    • Checksum
Command Examples
Power On:  0x33 0x01 0x01 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x33
Power Off: 0x33 0x01 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x32
Color RGB: 0x33 0x05 0x02 [R] [G] [B] 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 [XOR]
Brightness: 0x33 0x04 [VALUE] 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 [XOR]

Implementation Roadmap

Phase 1: Foundation (Weeks 1-3)

  • BLE scanner implementation
  • Basic device connection
  • Simple on/off control
  • Device listing UI
  • Configuration storage

Phase 2: Core Features (Weeks 4-6)

  • Color control implementation
  • Brightness adjustment
  • Multi-device support
  • Group management
  • Basic scenes

Phase 3: Advanced Control (Weeks 7-9)

  • Effects library
  • Custom animations
  • Scene sequencing
  • Scheduling system
  • Automation rules

Phase 4: Polish & Optimization (Weeks 10-12)

  • Performance optimization
  • Battery usage reduction
  • Error handling improvement
  • Documentation
  • User testing

Risk Analysis

Technical Risks

  1. BLE Stack Limitations

    • Mitigation: Implement connection pooling and queuing

  2. Protocol Changes

    • Mitigation: Modular driver architecture

  3. Memory Constraints

    • Mitigation: Efficient data structures, lazy loading

  4. Battery Drain

    • Mitigation: Optimized scanning intervals, sleep modes

Market Risks

  1. Govee API Changes

    • Mitigation: Multiple protocol version support

  2. Legal Concerns

    • Mitigation: Reverse engineering for interoperability

Success Metrics

Quantitative Metrics

  • Device connection success rate: >95%
  • Command execution time: <100ms
  • User session length: >10 minutes
  • Daily active users: 1000+
  • App store rating: >4.5/5

Qualitative Metrics

  • User satisfaction with multi-device control
  • Ease of use compared to official app
  • Community engagement and contributions
  • Feature request implementation rate

Testing Strategy

Unit Testing

  • Protocol encoder/decoder
  • Color space conversions
  • Scene engine logic
  • Storage operations

Integration Testing

  • Multi-device scenarios
  • Group synchronization
  • Effect transitions
  • Error recovery

User Testing

  • Beta program with 50+ users
  • A/B testing for UI variants
  • Performance benchmarking
  • Battery life analysis

Documentation Requirements

User Documentation

  • Quick start guide
  • Device compatibility list
  • Troubleshooting guide
  • Video tutorials

Developer Documentation

  • API reference
  • Protocol specification
  • Plugin development guide
  • Contributing guidelines

Compliance & Standards

Bluetooth Compliance

  • Bluetooth 4.2+ compliance
  • BLE security standards
  • FCC Part 15 compliance

Privacy & Security

  • GDPR compliance for EU users
  • No unnecessary data collection
  • Local-first architecture
  • Encrypted credential storage

Future Enhancements

Version 2.0 Considerations

  • Wi-Fi device support
  • Cloud scene sharing
  • Voice control integration
  • Machine learning for automation
  • Energy monitoring
  • Circadian rhythm support

Ecosystem Integration

  • Home Assistant plugin
  • IFTTT support
  • Google Home bridge
  • Alexa skill
  • Apple HomeKit compatibility

Appendices

A. Supported Device Models

  • H6160 - LED Strip Lights
  • H6163 - LED Strip Lights Pro
  • H6104 - LED TV Backlight
  • H6110 - Smart Bulb
  • H6135 - Smart Light Bar
  • H6159 - Gaming Light Panels
  • H6195 - Immersion Light Strip

B. Color Space Conversions

// RGB to HSV
void rgb_to_hsv(uint8_t r, uint8_t g, uint8_t b, 
                uint16_t *h, uint8_t *s, uint8_t *v);

// HSV to RGB
void hsv_to_rgb(uint16_t h, uint8_t s, uint8_t v,
                uint8_t *r, uint8_t *g, uint8_t *b);

// Color temperature to RGB
void kelvin_to_rgb(uint16_t kelvin, 
                   uint8_t *r, uint8_t *g, uint8_t *b);

C. Protocol State Machine

IDLE -> SCANNING -> CONNECTING -> AUTHENTICATING -> READY
                 \-> FAILED -> IDLE
READY -> COMMANDING -> READY
      \-> DISCONNECTED -> RECONNECTING -> READY

Revision History

  • v1.0 - Initial PRD creation
  • v1.1 - Added multi-device requirements
  • v1.2 - Enhanced protocol specifications
  • v1.3 - Updated UI/UX requirements