# espressifapp/espblufiforandroid architecture

> Architecture diagram of the GitHub repository espressifapp/espblufiforandroid, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/espressifapp/espblufiforandroid
- Repository: https://github.com/espressifapp/espblufiforandroid

## Overview

EspBlufiForAndroid is an Android demo for provisioning and inspecting ESP devices that run BluFi, alongside a reusable BluFi client library. The main workflow is to find a BLE device, open its control screen, establish a GATT connection, then issue security, configuration, status, version, Wi-Fi-scan, or custom-data operations and display callback results. Configuration forms and settings are additional app capabilities. The library implements the protocol over BLE, with parameter/response models and security helpers. Relationships for unsampled screens and protocol internals are included only where the README or source index supports them.

Main entry points: [`lib-blufi/src/main/java/blufi/espressif/BlufiClientImpl.java`](https://github.com/espressifapp/espblufiforandroid/blob/master/lib-blufi/src/main/java/blufi/espressif/BlufiClientImpl.java) (BLE protocol engine), [`app/src/main/java/com/espressif/espblufi/ui/BlufiActivity.java`](https://github.com/espressifapp/espblufiforandroid/blob/master/app/src/main/java/com/espressif/espblufi/ui/BlufiActivity.java) (Device controls), [`app/src/main/java/com/espressif/espblufi/ui/SettingsActivity.java`](https://github.com/espressifapp/espblufiforandroid/blob/master/app/src/main/java/com/espressif/espblufi/ui/SettingsActivity.java) (App settings), [`app/src/main/java/com/espressif/espblufi/ui/MainActivity.java`](https://github.com/espressifapp/espblufiforandroid/blob/master/app/src/main/java/com/espressif/espblufi/ui/MainActivity.java) (Device discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Android demo app"]
  node_main["Device discovery<br/>[MainActivity.java]"]
  node_control["Device controls<br/>[BlufiActivity.java]"]
  node_configui["Configuration forms"]
  node_settings["App settings"]
  node_appstate["App preferences<br/>[BlufiApp.java]"]
  node_appbase["Activity base<br/>[BaseActivity.java]"]
  node_appconstants["App constants"]
  node_release["Release lookup"]
end

subgraph group_client["BluFi client API"]
  node_api["Client facade<br/>[BlufiClient.java]"]
  node_callback["Callback contract<br/>[BlufiCallback.java]"]
end

subgraph group_protocol["Protocol implementation"]
  node_impl["BLE protocol engine"]
  node_params["Configuration parameters"]
  node_parameter["Protocol definitions"]
  node_responses["Status and scan models"]
  node_scanresult["Scan result model"]
  node_version["Version model"]
  node_notify["Notification assembly"]
  node_frame["Frame control<br/>[FrameCtrlData.java]"]
  node_security["Security primitives"]
end

node_user(("User"))
node_esp(("ESP BluFi device"))

node_user -.->|"selects device"| node_main
node_main -->|"opens controls"| node_control
node_user -.->|"changes settings"| node_settings
node_settings -->|"reads preferences"| node_appstate
node_settings -->|"checks release"| node_release
node_control -->|"opens forms"| node_configui
node_control -->|"issues commands"| node_api
node_configui -->|"builds settings"| node_params
node_api -->|"delegates calls"| node_impl
node_impl -.->|"exchanges BLE data"| node_esp
node_impl -->|"dispatches events"| node_callback
node_control -->|"handles events"| node_callback
node_impl -->|"encodes configuration"| node_params
node_impl -->|"uses protocol values"| node_parameter
node_impl -->|"builds status"| node_responses
node_impl -->|"builds scan results"| node_scanresult
node_impl -->|"builds version"| node_version
node_impl -->|"uses cryptography"| node_security
node_impl -->|"assembles notifications"| node_notify
node_impl -->|"reads frame flags"| node_frame
node_settings -->|"inherits navigation"| node_appbase
node_control -->|"inherits navigation"| node_appbase
node_control -->|"uses app settings"| node_appconstants

click node_main "https://github.com/espressifapp/espblufiforandroid/blob/master/app/src/main/java/com/espressif/espblufi/ui/MainActivity.java"
click node_control "https://github.com/espressifapp/espblufiforandroid/blob/master/app/src/main/java/com/espressif/espblufi/ui/BlufiActivity.java"
click node_configui "https://github.com/espressifapp/espblufiforandroid/blob/master/app/src/main/java/com/espressif/espblufi/ui/ConfigureOptionsActivity.java"
click node_settings "https://github.com/espressifapp/espblufiforandroid/blob/master/app/src/main/java/com/espressif/espblufi/ui/SettingsActivity.java"
click node_appstate "https://github.com/espressifapp/espblufiforandroid/blob/master/app/src/main/java/com/espressif/espblufi/app/BlufiApp.java"
click node_appbase "https://github.com/espressifapp/espblufiforandroid/blob/master/app/src/main/java/com/espressif/espblufi/app/BaseActivity.java"
click node_appconstants "https://github.com/espressifapp/espblufiforandroid/blob/master/app/src/main/java/com/espressif/espblufi/constants/BlufiConstants.java"
click node_release "https://github.com/espressifapp/espblufiforandroid/blob/master/app/src/main/java/com/espressif/espblufi/task/BlufiAppReleaseTask.java"
click node_api "https://github.com/espressifapp/espblufiforandroid/blob/master/lib-blufi/src/main/java/blufi/espressif/BlufiClient.java"
click node_callback "https://github.com/espressifapp/espblufiforandroid/blob/master/lib-blufi/src/main/java/blufi/espressif/BlufiCallback.java"
click node_impl "https://github.com/espressifapp/espblufiforandroid/blob/master/lib-blufi/src/main/java/blufi/espressif/BlufiClientImpl.java"
click node_params "https://github.com/espressifapp/espblufiforandroid/blob/master/lib-blufi/src/main/java/blufi/espressif/params/BlufiConfigureParams.java"
click node_parameter "https://github.com/espressifapp/espblufiforandroid/blob/master/lib-blufi/src/main/java/blufi/espressif/params/BlufiParameter.java"
click node_responses "https://github.com/espressifapp/espblufiforandroid/blob/master/lib-blufi/src/main/java/blufi/espressif/response/BlufiStatusResponse.java"
click node_scanresult "https://github.com/espressifapp/espblufiforandroid/blob/master/lib-blufi/src/main/java/blufi/espressif/response/BlufiScanResult.java"
click node_version "https://github.com/espressifapp/espblufiforandroid/blob/master/lib-blufi/src/main/java/blufi/espressif/response/BlufiVersionResponse.java"
click node_notify "https://github.com/espressifapp/espblufiforandroid/blob/master/lib-blufi/src/main/java/blufi/espressif/BlufiNotifyData.java"
click node_frame "https://github.com/espressifapp/espblufiforandroid/blob/master/lib-blufi/src/main/java/blufi/espressif/FrameCtrlData.java"
click node_security "https://github.com/espressifapp/espblufiforandroid/tree/master/lib-blufi/src/main/java/blufi/espressif/security"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_control,node_configui,node_settings,node_appstate,node_appbase,node_appconstants,node_release,node_user toneBlue
class node_api,node_callback toneAmber
class node_impl,node_params,node_parameter,node_responses,node_scanresult,node_version,node_notify,node_frame,node_security toneMint
class node_esp toneIndigo
```

## Components

### Android demo app

- [Device discovery](https://github.com/espressifapp/espblufiforandroid/blob/master/app/src/main/java/com/espressif/espblufi/ui/MainActivity.java): `app/src/main/java/com/espressif/espblufi/ui/MainActivity.java`
- [Device controls](https://github.com/espressifapp/espblufiforandroid/blob/master/app/src/main/java/com/espressif/espblufi/ui/BlufiActivity.java): `app/src/main/java/com/espressif/espblufi/ui/BlufiActivity.java`
- [Configuration forms](https://github.com/espressifapp/espblufiforandroid/blob/master/app/src/main/java/com/espressif/espblufi/ui/ConfigureOptionsActivity.java): `app/src/main/java/com/espressif/espblufi/ui/ConfigureOptionsActivity.java`
- [App settings](https://github.com/espressifapp/espblufiforandroid/blob/master/app/src/main/java/com/espressif/espblufi/ui/SettingsActivity.java): `app/src/main/java/com/espressif/espblufi/ui/SettingsActivity.java`
- [App preferences](https://github.com/espressifapp/espblufiforandroid/blob/master/app/src/main/java/com/espressif/espblufi/app/BlufiApp.java): `app/src/main/java/com/espressif/espblufi/app/BlufiApp.java`
- [Activity base](https://github.com/espressifapp/espblufiforandroid/blob/master/app/src/main/java/com/espressif/espblufi/app/BaseActivity.java): `app/src/main/java/com/espressif/espblufi/app/BaseActivity.java`
- [App constants](https://github.com/espressifapp/espblufiforandroid/blob/master/app/src/main/java/com/espressif/espblufi/constants/BlufiConstants.java): `app/src/main/java/com/espressif/espblufi/constants/BlufiConstants.java`
- [Release lookup](https://github.com/espressifapp/espblufiforandroid/blob/master/app/src/main/java/com/espressif/espblufi/task/BlufiAppReleaseTask.java): `app/src/main/java/com/espressif/espblufi/task/BlufiAppReleaseTask.java`

### BluFi client API

- [Client facade](https://github.com/espressifapp/espblufiforandroid/blob/master/lib-blufi/src/main/java/blufi/espressif/BlufiClient.java): `lib-blufi/src/main/java/blufi/espressif/BlufiClient.java`
- [Callback contract](https://github.com/espressifapp/espblufiforandroid/blob/master/lib-blufi/src/main/java/blufi/espressif/BlufiCallback.java): `lib-blufi/src/main/java/blufi/espressif/BlufiCallback.java`

### Protocol implementation

- [BLE protocol engine](https://github.com/espressifapp/espblufiforandroid/blob/master/lib-blufi/src/main/java/blufi/espressif/BlufiClientImpl.java): `lib-blufi/src/main/java/blufi/espressif/BlufiClientImpl.java`
- [Configuration parameters](https://github.com/espressifapp/espblufiforandroid/blob/master/lib-blufi/src/main/java/blufi/espressif/params/BlufiConfigureParams.java): `lib-blufi/src/main/java/blufi/espressif/params/BlufiConfigureParams.java`
- [Protocol definitions](https://github.com/espressifapp/espblufiforandroid/blob/master/lib-blufi/src/main/java/blufi/espressif/params/BlufiParameter.java): `lib-blufi/src/main/java/blufi/espressif/params/BlufiParameter.java`
- [Status and scan models](https://github.com/espressifapp/espblufiforandroid/blob/master/lib-blufi/src/main/java/blufi/espressif/response/BlufiStatusResponse.java): `lib-blufi/src/main/java/blufi/espressif/response/BlufiStatusResponse.java`
- [Scan result model](https://github.com/espressifapp/espblufiforandroid/blob/master/lib-blufi/src/main/java/blufi/espressif/response/BlufiScanResult.java): `lib-blufi/src/main/java/blufi/espressif/response/BlufiScanResult.java`
- [Version model](https://github.com/espressifapp/espblufiforandroid/blob/master/lib-blufi/src/main/java/blufi/espressif/response/BlufiVersionResponse.java): `lib-blufi/src/main/java/blufi/espressif/response/BlufiVersionResponse.java`
- [Notification assembly](https://github.com/espressifapp/espblufiforandroid/blob/master/lib-blufi/src/main/java/blufi/espressif/BlufiNotifyData.java): `lib-blufi/src/main/java/blufi/espressif/BlufiNotifyData.java`
- [Frame control](https://github.com/espressifapp/espblufiforandroid/blob/master/lib-blufi/src/main/java/blufi/espressif/FrameCtrlData.java): `lib-blufi/src/main/java/blufi/espressif/FrameCtrlData.java`
- [Security primitives](https://github.com/espressifapp/espblufiforandroid/tree/master/lib-blufi/src/main/java/blufi/espressif/security): `lib-blufi/src/main/java/blufi/espressif/security`

### Other components

- **User**
- **ESP BluFi device**

## Connections

- User → Device discovery: selects device
- Device discovery → Device controls: opens controls (evidence: `app/src/main/java/com/espressif/espblufi/ui/MainActivity.java`)
- User → App settings: changes settings
- App settings → App preferences: reads preferences (evidence: `app/src/main/java/com/espressif/espblufi/ui/SettingsActivity.java`)
- App settings → Release lookup: checks release (evidence: `app/src/main/java/com/espressif/espblufi/ui/SettingsActivity.java`)
- Device controls → Configuration forms: opens forms (evidence: `app/src/main/java/com/espressif/espblufi/ui/BlufiActivity.java`)
- Device controls → Client facade: issues commands (evidence: `app/src/main/java/com/espressif/espblufi/ui/BlufiActivity.java`)
- Configuration forms → Configuration parameters: builds settings (evidence: `app/src/main/java/com/espressif/espblufi/ui/ConfigureOptionsActivity.java`)
- Client facade → BLE protocol engine: delegates calls (evidence: `lib-blufi/src/main/java/blufi/espressif/BlufiClient.java`)
- BLE protocol engine → ESP BluFi device: exchanges BLE data
- BLE protocol engine → Callback contract: dispatches events (evidence: `lib-blufi/src/main/java/blufi/espressif/BlufiClientImpl.java`)
- Device controls → Callback contract: handles events (evidence: `app/src/main/java/com/espressif/espblufi/ui/BlufiActivity.java`)
- BLE protocol engine → Configuration parameters: encodes configuration (evidence: `lib-blufi/src/main/java/blufi/espressif/BlufiClientImpl.java`)
- BLE protocol engine → Protocol definitions: uses protocol values (evidence: `lib-blufi/src/main/java/blufi/espressif/BlufiClientImpl.java`)
- BLE protocol engine → Status and scan models: builds status (evidence: `lib-blufi/src/main/java/blufi/espressif/BlufiClientImpl.java`)
- BLE protocol engine → Scan result model: builds scan results (evidence: `lib-blufi/src/main/java/blufi/espressif/BlufiClientImpl.java`)
- BLE protocol engine → Version model: builds version (evidence: `lib-blufi/src/main/java/blufi/espressif/BlufiClientImpl.java`)
- BLE protocol engine → Security primitives: uses cryptography (evidence: `lib-blufi/src/main/java/blufi/espressif/BlufiClientImpl.java`)
- BLE protocol engine → Notification assembly: assembles notifications (evidence: `lib-blufi/src/main/java/blufi/espressif/BlufiClientImpl.java`)
- BLE protocol engine → Frame control: reads frame flags (evidence: `lib-blufi/src/main/java/blufi/espressif/BlufiClientImpl.java`)
- App settings → Activity base: inherits navigation (evidence: `app/src/main/java/com/espressif/espblufi/ui/SettingsActivity.java`)
- Device controls → Activity base: inherits navigation (evidence: `app/src/main/java/com/espressif/espblufi/ui/BlufiActivity.java`)
- Device controls → App constants: uses app settings (evidence: `app/src/main/java/com/espressif/espblufi/ui/BlufiActivity.java`)
