运行环境与快速开始

本页介绍 Flutter-JL_Home（杰理之家 Demo，Flutter）的运行环境要求与快速开始步骤，帮助开发者从零开始搭建开发环境、获取源码、导入工程并运行示例应用，最终通过 RCSP 协议连接杰理音箱/耳机类产品进行蓝牙控制开发。

Purpose and Scope

本页覆盖以下内容：

运行环境要求：操作系统、硬件（杰理芯片）、开发平台与语言支持；
快速开始流程：克隆仓库 → 导入 Android Studio → 插件引用 → 运行示例应用；
工程结构：code/、doc/、libs/ 目录的职责划分；
配置说明：插件 jl_home 的 pubspec 环境约束与平台注册信息，示例应用的第三方依赖；
调试技巧：SDK 内置日志在 Android/iOS 上的查看方式。

以下主题不属于本页范围，请在对应页面查看：

工程内部的具体功能实现（音乐控制、音效调节、ANC、AI 翻译等）——见功能相关目录页；
收发接口（Send/Receive Interface）的详细 API 说明——见 doc/ 下的接口介绍文档；
原生平台 SDK（Android/iOS）的调试细节——见杰理官方文档中心的 SDK 接入文档。

Flutter-JL_Home 是珠海市杰理科技股份有限公司为杰理音箱、耳机类产品提供的蓝牙控制开发平台。该平台基于 RCSP 协议（远程控制系统协议），以 Flutter 插件形式封装蓝牙控制能力，并提供完整的示例应用，支持音箱类（智能音箱、蓝牙音箱、Auracast 音箱）、耳机类（TWS 耳机、头戴式耳机、挂脖耳机、彩屏仓、翻译耳机）以及音频设备（蓝牙音频接收器、声卡、录音笔等）的开发场景。

示例应用提供的主要功能包括：音乐控制、设备设置、文件浏览、闹钟管理、FM 控制、灯光控制（RGB/频率/模式）、音效调节（均衡器/混响/高低音）、按键设置、查找设备、ANC 设置（正常/主动降噪/通透）、彩屏仓控制（亮度/屏保更新）、AI 翻译（同声传译/面对面翻译）以及自定义命令扩展。

整个 SDK 采用 Dart 层插件（jl_home）＋原生层（Android com.jieli.bt.sdk / iOS JlHomePlugin）＋杰理硬件设备 的分层架构：Dart 层通过 MethodChannel 调用原生实现，原生层负责 BLE 扫描、连接与 RCSP 协议数据收发，最终与设备完成交互。

Architecture

下图展示了仓库整体布局与运行时的分层架构：

flowchart TD
    subgraph sg_Repo["Flutter-JL_Home 仓库"]
        subgraph sg_Code["code/JieLi_Home_Demo"]
            Plugin["jl_home 插件<br/>JlHomePlugin"]
            Example["example 示例应用"]
        end
        Doc["doc/ 文档"]
        Libs["libs/ 收发接口"]
    end

    subgraph sg_Native["原生平台层"]
        Android["Android<br/>com.jieli.bt.sdk"]
        IOS["iOS<br/>JlHomePlugin"]
    end

    subgraph sg_Device["硬件设备层"]
        Device["杰理音箱/耳机<br/>RCSP 协议"]
    end

    Example -->|"MethodChannel 调用"| Plugin
    Plugin --> Android
    Plugin --> IOS
    Android -->|"BLE + RCSP"| Device
    IOS -->|"BLE + RCSP"| Device
    Doc -.-> Example
    Libs -.-> Plugin

分层说明：

示例应用层（example/）：完整的音箱/耳机控制 App，依赖 jl_home 插件，集成了卡拉 OK、音效调节、多语言、HTTP 接口、OTA 升级等能力，是开发者快速验证 SDK 集成效果的最佳入口。
插件层（jl_home）：Flutter 插件工程，通过 plugin_platform_interface 与 equatable 提供 Dart 侧抽象，插件在 Android 与 iOS 上注册 JlHomePlugin 实现类。
原生平台层：Android 侧以 com.jieli.bt.sdk 为包名承载 BLE 通信与 RCSP 协议栈；iOS 侧由 JlHomePlugin 提供同等能力。
硬件设备层：支持 RCSP 功能的杰理芯片（AC701N、AC707N、AC697N、AC696N、AC695N 等）所构成的音箱/耳机产品。

运行环境要求

环境总览

类别	要求	说明
操作系统	Android 6.0+、iOS 13.0+	需支持 BLE（低功耗蓝牙）功能
硬件要求	支持 RCSP 功能的 SDK	AC701N、AC707N、AC697N、AC696N、AC695N 等杰理芯片
开发平台	Android Studio（支持 Flutter）	建议使用最新版
语言支持	Dart / Kotlin / Swift	提供完整的 API 支持

来源：README.md 运行环境

Dart / Flutter SDK 版本约束

插件工程 jl_home 的 pubspec 对 SDK 版本有明确约束：

name: jl_home
description: "A new Flutter plugin project."
version: 1.0.0+1
homepage:

environment:
  sdk: ^3.8.1
  flutter: '>=3.3.0'

来源：code/JieLi_Home_Demo/pubspec.yaml

设计意图说明：

Dart SDK ^3.8.1：要求较新的 Dart 3.8 及以上版本，保证空安全（Null Safety）与现代语言特性（如 records、patterns）可用，同时与 Flutter 3.3 之后的工具链保持兼容；
Flutter >=3.3.0：插件层仅使用 MethodChannel 与 plugin_platform_interface，对 Flutter 版本要求较为宽松，便于接入方在既有工程中低门槛集成；
示例应用（example/）同样声明 sdk: ^3.8.1，因此建议开发者统一使用 Flutter 3.3+ / Dart 3.8+ 的工具链进行开发。

插件平台注册

jl_home 在 pubspec 中声明了 Android 与 iOS 双平台的原生注册信息：

flutter:
  plugin:
    platforms:
      android:
        package: com.jieli.bt.sdk
        pluginClass: JlHomePlugin
      ios:
        pluginClass: JlHomePlugin

来源：code/JieLi_Home_Demo/pubspec.yaml

其中 Android 侧使用包名 com.jieli.bt.sdk 承载原生实现，插件类为 JlHomePlugin；iOS 侧同样注册 JlHomePlugin。插件注册后，Flutter 工具链会在构建时自动把原生代码绑定到宿主工程，开发者无需手工配置 MethodChannel。

快速开始

流程总览

sequenceDiagram
    participant Dev as 开发者
    participant AS as Android Studio
    participant FL as Flutter 工具链
    participant Dev2 as 真机 (Android 6.0+ / iOS 13.0+)
    participant JLD as 杰理设备 (RCSP)

    Dev->>Dev: git clone 仓库
    Dev->>AS: 导入 code/JieLi_Home_Demo
    AS->>FL: flutter pub get
    FL-->>AS: 依赖解析完成
    Dev->>AS: 连接真机并运行
    AS->>Dev2: 安装并启动示例 App
    Dev2->>JLD: BLE 扫描 / 连接
    JLD-->>Dev2: RCSP 数据交互
    Dev2-->>Dev: 验证 SDK 集成效果

3.1 克隆仓库

git clone https://github.com/Jieli-Tech/Flutter-JL_Home.git
cd Flutter-JL_Home

来源：README.md 快速开始

注意：仓库托管于 GitHub，示例中的远程地址以仓库实际为准；本 Wiki 文件引用基于 Gitee 镜像（https://gitee.com/Jieli-Tech/Flutter-JL_Home）。

3.2 导入项目到 Android Studio

打开 Android Studio；
选择 "Open an existing project"；
导航到解压后的 code/ 目录；
打开 JieLi_Home_Demo 中的项目文件。

来源：README.md 导入项目

项目根目录即 Flutter 工程，包含插件 jl_home 与示例应用 example 两个子工程。Android Studio 检测到 pubspec.yaml 后会自动触发 flutter pub get，拉取全部依赖。

3.3 插件引用

宿主工程如需直接使用 SDK，可在 pubspec.yaml 中按以下方式引用插件：

  plugin:
    platforms:
      android:
        package: com.jieli.bt.sdk
        pluginClass: JlHomePlugin
      ios:
        pluginClass: JlHomePlugin

来源：README.md 插件引用

3.4 运行示例应用

运行项目到 Android 或 iOS 设备，即可使用各项测试功能验证 SDK 集成效果。

来源：README.md 运行示例应用

运行前请确认：

真机系统版本满足要求（Android 6.0+ / iOS 13.0+），且已开启蓝牙与定位权限（BLE 扫描在 Android 上通常需要位置权限）；
手边有支持 RCSP 的杰理设备（如 AC69xN / AC70xN 系列方案的音箱或耳机）用于连接验证；
iOS 真机调试需要配置开发者证书与签名。

工程结构

Flutter-JL_Home/
├── code/                                    # 参考源码工程文件夹
│   └── JieLi_Home_Demo                      # 杰理之家Demo(Flutter)项目源码
├── doc/                                     # 文档文件夹
│   ├── Jieli Home Demo (Flutter) - Send/Receive Interface Introduction_en.md   # 英文文档
│   ├── Jieli Home Demo (Flutter) - Send/Receive Interface Introduction.md      # 中文文档
│   └── ReadMe.txt                           # 说明文件
└── libs/                                    # 核心收发接口文件夹
    ├── Receive Interface                    # 杰理之家Demo(Flutter)的接收接口
    └── Send Interface                       # 杰理之家Demo(Flutter)的发送接口

来源：README.md 工程结构

code/JieLi_Home_Demo/：工程源码，内部包含插件 jl_home 与示例应用 example；
doc/：收发接口（Send/Receive Interface）的中英文介绍文档，是二次开发时查阅 API 的主要入口；
libs/：核心收发接口的说明文件夹，分别对应发送与接收两条数据通路。

配置说明

5.1 示例应用（`code/JieLi_Home_Demo/example/`）

项目	说明
适用场景	完整的音箱/耳机控制 App，支持多媒体、音效、设备管理
关键特性	卡拉 OK、音效调节、多语言、HTTP 接口、OTA 升级
参考文档	SDK 接入文档

来源：README.md 配置说明

5.2 示例应用第三方依赖

示例应用在 example/pubspec.yaml 中声明了以下运行依赖（部分摘录）：

依赖	版本约束	用途
`flutter`	sdk: flutter	Flutter 框架
`flutter_localizations`	sdk: flutter	官方本地化支持
`intl`	^0.20.2	消息格式化与复数处理
`permission_handler`	^12.0.0+1	动态权限管理（BLE/相机等）
`webview_flutter`	^4.2.2	WebView 核心库
`camera`	^0.10.5	摄像头支持（AI 翻译场景）
`integration_test`	sdk: flutter	集成测试
`flutter_test`	sdk: flutter	单元测试

来源：code/JieLi_Home_Demo/example/pubspec.yaml

设计意图说明：

permission_handler 用于在 Android 6.0+（动态权限模型）与 iOS 上统一处理蓝牙、定位、相机等运行时权限，保证 RCSP 设备扫描与 AI 翻译等能力可正常使用；
webview_flutter 与 camera 服务于 OTA 升级页面、HTTP 接口及翻译等富媒体功能；
插件侧仅依赖 plugin_platform_interface（多平台实现分发标准）与 equatable（值对象比较），保持轻量，减少接入方依赖冲突。

5.3 插件依赖

dependencies:
  flutter:
    sdk: flutter
  plugin_platform_interface: ^2.0.2
  equatable: ^2.0.5

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^5.0.0

来源：code/JieLi_Home_Demo/pubspec.yaml

调试技巧

日志输出：SDK 内置详细日志，可实时监控蓝牙连接状态及数据交互全过程，便于快速定位问题；
日志查看方式：
- Android：使用 Android Studio 的 Logcat 工具查看实时日志；
- iOS：使用 Xcode 的 Console（控制台）查看实时日志；
问题排查：
- Android SDK：详见 Android SDK 调试说明
- iOS SDK：详见 iOS SDK 调试说明

来源：README.md 调试技巧

常见问题与边界情况

BLE 扫描失败：Android 6.0+ 上扫描 BLE 设备通常需要位置权限；请确认已授予 permission_handler 请求的权限，并确保系统蓝牙已开启。iOS 13.0+ 则需在 Info.plist 中配置蓝牙使用描述（NSBluetoothAlwaysUsageDescription）。
设备无法连接：请确认目标设备使用支持 RCSP 的杰理芯片（AC701N、AC707N、AC697N、AC696N、AC695N 等），且固件已开启 RCSP 功能。
版本不匹配：示例应用要求 Dart SDK ^3.8.1；若本机 Flutter 工具链过旧，flutter pub get 会因版本约束失败，请先升级 Flutter 至 3.3+（含 Dart 3.8+）。
iOS 签名问题：真机运行前必须在 Xcode 中配置开发者证书与 Team，否则无法安装到设备。

版本与许可证

版本	日期	修改记录
1.0.0	2026/07/02	初始版本

来源：README.md 版本历史

本项目采用 Apache License 2.0 开源协议。

来源：README.md 许可证

README（中文）：项目总览、功能清单与全部章节入口
README_EN.md：英文版项目说明
code/JieLi_Home_Demo/pubspec.yaml：插件 jl_home 环境约束与平台注册
code/JieLi_Home_Demo/example/pubspec.yaml：示例应用依赖清单
doc/ 文档中心：Send/Receive 收发接口中英文介绍
LICENSE：Apache 2.0 开源协议
杰理科技官网：https://www.zh-jieli.com/