BLE Communication & Protocols¶

Overview¶

OvApp uses Bluetooth Low Energy (BLE) to communicate with Omnivoltaic-enabled devices such as charging stations, battery systems, vehicles, and embedded keypads. BLE provides low-power, short-range, and reliable communication, enabling both online and offline operations.

This document describes the BLE architecture, connection flow, data structures, security model, and supported operations.

Supported Roles¶

BLE functionality is primarily accessed through the BLE Device Manager role, with limited access for other operational roles.

Role	BLE Access Level
BLE Device Manager	Full configuration, diagnostics, and control
Attendant	Operational read/write access
Rider	Read-only and limited commands
Keypad	Embedded BLE interactions

BLE Architecture¶

OvApp follows the Central–Peripheral BLE model:

Central: Mobile device running OvApp
Peripheral: Omnivoltaic hardware device

OvApp (Central)
   ↓ Scan
BLE Device (Peripheral)
   ↓ Advertise
Service Discovery
   ↓
Characteristic Read / Write / Notify

Device Discovery & Pairing¶

Device Discovery¶

OvApp scans for nearby devices advertising Omnivoltaic-specific UUIDs
Devices are filtered by:
Device type
Signal strength (RSSI)
Advertisement payload

Pairing & Bonding¶

Secure pairing is required on first connection
Supported methods:
Passkey or PIN-based pairing
Pre-shared keys (PSK)
Provisioning codes

!!! note Pairing information is securely stored to allow trusted reconnections.

GATT Services & Characteristics¶

OvApp communicates with devices using GATT (Generic Attribute Profile) services.

Core Services¶

Service	Description
Device Information Service	Manufacturer, firmware, model
Status Service	Battery, health, connectivity
Command Service	Device control and configuration
Data Service	Telemetry and measurements
Diagnostics Service	Errors, logs, fault codes

Data Payload Structure¶

BLE messages follow a structured payload format:

{
  "att": {},
  "cmd": {},
  "sts": {},
  "dta": {},
  "dia": {}
}

Section	Description
`att`	Device attributes
`cmd`	Commands issued by OvApp
`sts`	Current device state
`dta`	Telemetry and sensor data
`dia`	Diagnostics and fault reporting

Communication Operations¶

Read Operations¶

Retrieve device attributes
Fetch current status
Query configuration values

Write Operations¶

Send control commands
Update device settings

Notify / Indicate¶

Real-time telemetry updates
State changes
Fault and alert notifications

Connection Lifecycle¶

Scan for BLE devices
Connect to selected device
Discover GATT services and characteristics
Authenticate (if required)
Exchange data
Subscribe to notifications
Disconnect gracefully

Security & Authorization¶

BLE communication is secured using:

Encrypted BLE connections
Role-based command authorization
Device whitelisting
Session-based authentication tokens

!!! warning Sensitive commands are restricted to authorized roles only.

Error Handling & Recovery¶

OvApp implements robust error handling, including:

Automatic reconnection attempts
Timeout handling
Command retry logic
Offline fallback mechanisms

Common Errors¶

Error	Cause	Resolution
Device not visible	BLE disabled	Enable Bluetooth
Connection timeout	Device out of range	Move closer
Authentication failure	Invalid credentials	Re-pair device
Command rejected	Insufficient role	Verify permissions

Performance Considerations¶

Optimized BLE payload sizes
Controlled notification frequency
Power-efficient scanning strategies
Adaptive reconnect intervals