Skip to content

Latest commit

 

History

History
339 lines (268 loc) · 9.04 KB

README.md

File metadata and controls

339 lines (268 loc) · 9.04 KB

G1 SDK

Python SDK for interacting with G1 Smart Glasses via Bluetooth LE. Provides a high-level interface for device communication, state management, and feature control.

Installation

Requirements:

  • Python 3.7+
  • Bluetooth LE support
pip install -r requirements.txt

Required packages:

  • bleak>=0.21.1: Bluetooth LE communication
  • rich>=13.7.0: Enhanced console output
  • asyncio>=3.4.3: Asynchronous I/O support

Quick Start

Simple connection example:

from connector import G1Connector
import asyncio

async def main():
    # Initialize connector
    glasses = G1Connector()
    
    # Connect to glasses (includes automatic retry logic)
    if await glasses.connect():
        print("Successfully connected to G1 glasses")
        # Your code here
    else:
        print("Failed to connect to glasses")

if __name__ == "__main__":
    asyncio.run(main())

Features

Bluetooth Management

  • Robust BLE connection handling with configurable retry logic
  • Automatic reconnection on disconnect
  • Dual glass (left/right) connection support
  • Connection state tracking and event notifications

State Management

  • Physical state monitoring (wearing, charging, cradle)
  • Battery level tracking
  • Device state updates
  • Interaction event processing
  • Dashboard mode support

Event Handling

Supports various interaction types:

  • Single/Double tap detection
  • Long press actions
  • Dashboard open/close events
  • Silent mode toggles

Display Control

Text display features:

  • Multi-line text support
  • Configurable font sizes
  • Page-based text display
  • Screen status tracking
  • Brightness level adjustment
  • Auto brightness on/off

Image display capabilities: (TODO)

  • 1-bit, 576x136 pixel BMP format
  • Packet-based transmission
  • CRC verification
  • Left/right glass synchronization

Audio Features

Microphone control: (TODO)

  • Right-side microphone activation
  • LC3 format audio streaming
  • 30-second maximum recording duration
  • Real-time audio data access

Even AI Integration

AI feature support: (TODO)

  • Start/stop AI recording
  • Manual/automatic modes
  • Result display handling
  • Network status monitoring

Core Components

Connector Module

Core connection and communication handling:

  • base.py: Base class for all connectors
  • bluetooth.py: BLE device management and connection handling
  • commands.py: Command protocol implementation
  • pairing.py: Device pairing and authentication

Services Module

Individual feature implementations:

  • audio.py: Microphone control and audio processing (TODO)
  • device.py: Device interactions (TODO)
  • display.py: Text and image display management (TODO)
  • events.py: Listening and responding to G1 events
  • state.py: State tracking and event management
  • status.py:
  • uart.py: Low-level UART communication

Utils Module

Supporting utilities:

  • config.py: Configuration management
  • constants.py: Protocol constants and enums
  • logger.py: Logging configuration

Flow

First Time Setup

  1. Config Initialization

    • utils/config.py: Creates default configuration if none exists
    • Default settings loaded from g1_config.json: 
      {
  "reconnect_attempts": 3,
  "reconnect_delay": 1.0,
  "connection_timeout": 20.0
}

  2. Logging Setup

    • utils/logger.py: Configures logging handlers
    • Creates log directory if not exists
    • Initializes both file and console logging
    • Log files stored in ./g1_connector.log

  3. Bluetooth Discovery

    • connector/bluetooth.py: BLEManager.scan_for_glasses()
    • Searches for devices matching G1 identifier
    • Returns list of discovered G1 glasses with addresses

  4. Pairing Process

    • connector/pairing.py: Handles initial device pairing
    • Establishes secure connection with both left and right glasses
    • Validates device authenticity
    • Stores pairing information

  5. Connection Confirmation

    • connector/bluetooth.py: _connect_glass()
    • Verifies successful connection to both glasses
    • Initializes UART service
    • Sets up notification handlers

  6. Device ID Storage

    • Stores validated glass IDs in config file
    • Left glass address: left_address
    • Right glass address: right_address

Subsequent Connections

  1. Direct Connection

    • Reads stored glass IDs from config
    • connector/bluetooth.py: Attempts direct connection
    • Uses configured retry logic: 
      for attempt in range(self.connector.config.reconnect_attempts):
    # Connection attempt logic

  2. Connection Maintenance

    • connector/commands.py: Sends periodic heartbeat
    • Default heartbeat command: HEARTBEAT_CMD = bytes([0x25, 0x06, 0x00, 0x01, 0x04, 0x01])
    • Monitors connection status
    • Automatic reconnection on disconnect

  3. Event Monitoring

    • services/state.py: Manages state tracking
    • services/uart.py: Handles UART notifications
    • Event types defined in utils/constants.py:
      • Physical states (wearing, charging)
      • Device states (connected, operational)
      • Interactions (taps, gestures)
      • Battery status

Examples

Basic Usage

Simple Connect

simple_connect.py Basic connection demonstration

python -m examples.simple_connect

Monitor State Changes

interactions.py Monitor and log device interactions

python -m examples.interactions

Dashboard

dashboard.py Monitor statuses and logs

python -m examples.dashboard

Display Features

Text Display

send_text.py Text display with multi-line support

python -m examples.send_text

PowerPoint Display (In progress)

ppt_teleprompter.py Send speaker notes from an active PowerPoint presentation to the glasses

python -m examples.ppt_teleprompter

Image Display

send_image.py (TODO) Image transmission (1-bit, 576x136 BMP)

python -m examples.send_image

Advanced Features

Microphone

microphone.py (TODO) Audio recording demonstration

python -m examples.microphone

Even AI

even_ai.py (TODO) Even AI integration example

python -m examples.even_ai

Protocol Details

Display Protocol

  • Text display supports configurable font sizes and line counts
  • Images must be 1-bit, 576x136 pixel BMP format
  • Packet-based transmission with CRC verification

Audio Protocol

  • LC3 format audio streaming
  • Right-side microphone activation
  • 30-second maximum recording duration

State Management

  • Physical state tracking (wearing, charging, etc.)
  • Battery level monitoring
  • Interaction event processing

Configuration

Default settings can be modified in g1_config.json:

  • device_name: Customize the device name for pairing
  • device_address: Manually set the device address
  • auto_reconnect: Enable or disable automatic reconnection
  • log_level: Set the logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
  • log_file: Specify a custom log file path
  • log_to_console: Enable or disable logging to the console
  • log_to_file: Enable or disable logging to a file

Roadmap & Planned Improvements

Immediate Priority

  • clean up the console logs for a new connection, many duplicates and logs with markup
  • Implement text sending functionality
  • Add comprehensive examples for text display and interaction
  • Document text positioning and formatting options

High Priority (Developer Experience)

  1. Connection Management

    • Implement Windows BLE connection recovery
      • Detect and reuse existing connections
      • Add configurable retry timing for connection attempts
      • Implement force-disconnect on SDK exit
      • Add connection state detection and logging

  2. Pairing Improvements

    • Add robust pairing state detection and management
      • Detect proper pairing state vs. just connected state
      • Add automatic re-pairing when connection is incomplete avoiding the need to delete the config file
      • Add user guidance for connection troubleshooting

  3. Documentation Improvements (add more detail to this readme doc)

    • Add inline examples in docstrings
    • add more detail/quickstarts/examples to this readme doc
    • Document error scenarios and solutions

  4. Developer Tools

    • Create higher-level abstractions for common patterns
    • Add more example applications
    • Implement helper utilities for content formatting

  5. Reliability Enhancements

    • Improve connection state recovery
    • Add automated reconnection strategies
    • Enhance error handling with specific solutions
    • Implement better battery and health monitoring (if supported by the device, events are a bit vague)

  6. Code Structure

    • Split G1Connector into focused components
    • Add more type hints and dataclasses
    • Implement async context managers
    • Add configuration validation

Medium Priority

  • Structured telemetry collection
  • Performance benchmarks
  • Circuit breakers for problematic operations
  • Formal dependency injection
  • Structured logging
  • Performance optimization