项目简介与功能总览

Flutter-JL_Home 是珠海市杰理科技股份有限公司面向杰理音箱、耳机类产品推出的 Flutter 蓝牙控制开发平台（杰理之家 Demo）。本页面从项目整体视角介绍该 SDK 的定位、功能矩阵、工程结构、核心架构与快速接入方式，为后续各功能模块的专项文档提供全局上下文。

Purpose and Scope

本页面（1-overview.project-intro）是杰理之家（Flutter）SDK 文档的入口页，覆盖以下内容：

• 项目定位、适用产品与典型应用场景
• 功能总览（音乐控制、设备设置、闹钟、FM、灯光、ANC、AI 翻译等）
• 运行环境与工程目录结构
• 以 RCSP 协议为核心的整体架构（Flutter → MethodChannel → 原生插件 → BLE SDK → 设备）
• 收发接口设计理念、插件引用方式与调试入口
• 版本历史与许可证

本页不深入展开的专题，将在各自的目录页中说明，例如：

• 具体发送/接收接口的逐方法说明 → 参见「收发接口介绍」相关页面
• 闹钟、FM、灯光、ANC 等各功能模块的详细实现 → 参见各自的功能页面
• OTA 升级、Auracast、AI 翻译等扩展能力 → 参见对应专项页面

Overview

杰理科技为音箱、耳机等蓝牙产品提供了一套完整的蓝牙控制 SDK。Flutter-JL_Home 是该 SDK 的 Flutter 参考实现（Demo），基于 RCSP 协议（远程控制系统协议 Remote Control System Protocol） 与设备通信，屏蔽了底层 BLE 的复杂细节，让开发者能够快速构建跨平台（Android / iOS）的音箱耳机控制 App。

该平台主要面向以下应用场景：

设计意图：通过统一的 Flutter 插件封装（JlHomePlugin），把原生平台（Android/iOS）的 BLE 连接、协议解析、数据收发能力以 MethodChannel 形式暴露给 Dart 层，业务开发者只需调用 Dart 层的 Manager 接口即可控制设备，无需关心蓝牙底层实现与平台差异。

Architecture

整体架构采用「Flutter 业务层 → Dart 收发接口层 → MethodChannel → 原生插件 → BLE SDK → 蓝牙设备」的分层设计：

flowchart TD
    subgraph sg_App["应用层 (Flutter)"]
        UI["杰理之家 Demo UI<br/>(音乐/闹钟/FM/灯光/ANC等页面)"]
    end

    subgraph sg_Dart["Dart SDK 层"]
        Send["发送接口 Send Interface<br/>(BleAlarmManager 等 Manager)"]
        Recv["接收接口 Receive Interface<br/>(回调分发)"]
        Base["BleBaseManager<br/>MethodChannel 封装"]
        Models["数据模型层<br/>(AlarmModel 等)"]
    end

    subgraph sg_Native["原生插件层 (JlHomePlugin)"]
        Channel["MethodChannel<br/>com.jieli.home_plugin/methods"]
        Android["Android 实现<br/>package: com.jieli.bt.sdk"]
        IOS["iOS 实现"]
    end

    subgraph sg_BLE["蓝牙协议层"]
        RCSP["RCSP 协议引擎"]
        BLEStack["BLE 协议栈<br/>(GATT/连接管理)"]
    end

    subgraph sg_Device["设备端"]
        Device["杰理音箱/耳机设备<br/>(AC701N/AC697N等芯片)"]
    end

    UI --> Send
    UI --> Recv
    Send --> Base
    Base --> Channel
    Recv --> Base
    Send --> Models
    Recv --> Models
    Channel --> Android
    Channel --> IOS
    Android --> RCSP
    IOS --> RCSP
    RCSP --> BLEStack
    BLEStack <--> Device

各层职责说明：

• 应用层（Flutter）：code/JieLi_Home_Demo 下的示例 App，提供音乐控制、设备设置、文件浏览、闹钟管理、FM、灯光、音效、按键设置、查找设备、ANC、彩屏仓、AI 翻译等测试页面，用于验证 SDK 集成效果。
• Dart SDK 层：即仓库根目录 libs/ 下的「Send Interface」与「Receive Interface」，按功能域拆分为多个 BleXxxManager 静态类，统一通过 BleBaseManager.invokeMethod() 走 MethodChannel 调用原生层。
• 原生插件层：Flutter 插件 JlHomePlugin，Android 端包名为 com.jieli.bt.sdk，负责把 Dart 调用翻译成杰理蓝牙 SDK 的调用，并把设备回调翻译回 Dart。
• 蓝牙协议层：RCSP 协议引擎基于 BLE 协议栈（GATT）与设备交互，处理指令封装、应答解析、事件上报。
• 设备端：支持 RCSP 功能的杰理芯片（AC701N、AC707N、AC697N、AC696N、AC695N 等）驱动的音箱/耳机产品。

分层的好处是：协议细节与平台差异被完全封装在原生层与协议层，Dart 开发者面对的是与业务一一对应的 Manager 接口（如 BleAlarmManager.getAllAlarmList()），从而显著降低开发门槛、加快产品落地速度。

功能总览

杰理之家 Demo(Flutter) 提供了丰富的功能接口，覆盖影音娱乐、设备控制与扩展支持三大类：

功能清单出处：README.md

官方接口文档还进一步将这些能力归纳为三大主题：

• 影音娱乐：设备音乐播放、FM 接收、第三方播放器、外部音源输入、卡拉 OK、音效与音量调节
• 设备控制：灯光效果设置、闹钟设定、设备查找、设备双连、PC 从机/SPDIF 输出、OTA 在线升级、设备设置管理、彩屏充电仓相关功能、Auracast Broadcast、AI 翻译
• 扩展支持：自定义指令配置

出处：收发接口介绍文档

运行环境

出处：README.md

工程结构

仓库采用「参考源码 + 文档 + 核心接口」的布局：

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/：一个 Flutter 插件型工程（plugin project），既包含可运行的示例 App（example/），也承载平台相关实现代码（Android/iOS），是接入 SDK 的起点。
• libs/Send Interface：Dart 层发送接口，按功能域组织为 BleXxxManager 类，开发者主动调用以向设备下发指令。
• libs/Receive Interface：Dart 层接收接口，用于接收设备上报的数据与事件，通常以回调形式返回给 UI。
• doc/：收发接口的详细介绍文档（中英文双语），是查阅具体方法签名与使用方式的一手资料。

核心机制：收发接口与 MethodChannel

5.1 RCSP 协议

RCSP（远程控制系统协议）是杰理设备与 App 之间的通信协议，定义了一套完整的指令集，覆盖音乐控制、设备状态查询、闹钟、FM、灯光、音效、ANC、OTA 等能力。协议运行在 BLE 连接之上：

• 下发指令：App 将业务操作封装为 RCSP 指令包，经 BLE GATT 通道发送给设备；
• 设备应答：设备执行后回传应答包，App 解析后更新 UI；
• 事件上报：设备主动推送状态变化（如播放状态、来电、按键事件），由接收接口分发到上层。

这一协议层完全封装在原生 SDK 中，Dart 层无需接触指令字节流。

5.2 Dart 层发送接口

发送接口采用「静态 Manager + 统一通道」的设计。每个功能域一个 Manager 类（如闹钟对应 BleAlarmManager），方法内部统一调用 BleBaseManager.invokeMethod() 完成跨端调用。以闹钟列表获取为例：

static const MethodChannel _methodChannel = MethodChannel(
  'com.jieli.home_plugin/methods',
);

Source: BleBaseManager.dart（收发接口介绍文档摘录）

BleBaseManager 持有全局唯一的 MethodChannel（通道名 com.jieli.home_plugin/methods），是所有发送接口的底层出口。方法名统一收口在 BleMethodConstants 常量类中，避免魔法字符串散落各处。

static Future<List<AlarmModel>> getAllAlarmList() async {
  try {
    final List<dynamic> result = await BleBaseManager.invokeMethod(
      BleMethodConstants.methodGetAllAlarmList,
    );
    return _convertToAlarmModels(result);
  } catch (e) {
    rethrow;
  }
}

static List<AlarmModel> _convertToAlarmModels(List<dynamic> rawData) {
  List<AlarmModel> alarmList = [];

  for (var item in rawData) {
    if (item is Map) {
      final alarm = AlarmModel.fromMap(item);
      alarmList.add(alarm);
    }
  }

  return alarmList;
}

使用示例：await BleAlarmManager.getAllAlarmList();

Source: BleAlarmManager.dart（收发接口介绍文档摘录）

这段代码体现了三个设计要点：

1. 异步化：所有接口返回 Future，与 Flutter 的异步 UI 模型天然契合；
2. 类型安全转换：原生层返回 List<dynamic>（本质是 Map 列表），Dart 层通过 fromMap 工厂构造强类型模型 AlarmModel，上层业务无需接触原始 Map；
3. 错误透传：catch (e) { rethrow; } 保留原始异常栈，便于调用方按需处理。

5.3 发送链路完整时序

sequenceDiagram
    participant UI as Flutter UI
    participant Mgr as BleXxxManager
    participant Base as BleBaseManager
    participant Ch as MethodChannel
    participant Native as JlHomePlugin (Android/iOS)
    participant SDK as 杰理蓝牙 SDK (RCSP)
    participant Dev as 蓝牙设备

    UI->>Mgr: await getAllAlarmList()
    Mgr->>Base: invokeMethod(methodGetAllAlarmList)
    Base->>Ch: invokeMethod(method, arguments)
    Ch->>Native: 平台通道调用
    Native->>SDK: 封装 RCSP 指令并发送
    SDK->>Dev: BLE GATT 写入指令包
    Dev-->>SDK: 设备应答/事件上报
    SDK-->>Native: 回调结果
    Native-->>Ch: 返回 List<dynamic>
    Ch-->>Base: Future 完成
    Base-->>Mgr: rawData
    Mgr->>Mgr: _convertToAlarmModels 转换
    Mgr-->>UI: List<AlarmModel>

5.4 接收接口

接收接口与发送接口对称：发送接口是「App → 设备」的主动指令，接收接口是「设备 → App」的数据与事件回调。其典型内容包括：

• 设备连接/断开状态变化
• 播放状态、音量、ID3 信息等状态上报
• 闹钟、FM、灯光等模块的设备端变更通知
• OTA 升级进度、AI 翻译结果等异步数据

接收接口同样通过 MethodChannel 由原生层回调到 Dart 层，再分发到注册的监听者，从而保证 UI 能实时反映设备状态。

插件引用方式

无论是使用现成 Demo 还是集成到自有工程，都需要在 pubspec.yaml 中声明插件平台映射，让 Flutter 引擎能够找到原生插件类：

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

Source: README.md

关键点：

• Android：声明包名 com.jieli.bt.sdk 与插件类 JlHomePlugin，对应 Android 原生实现；
• iOS：声明插件类 JlHomePlugin，对应 iOS 原生实现；
• 两端使用同一插件类名，Dart 层无需区分平台，这也是 Flutter 插件「一次编写、双端运行」的体现。

快速开始

克隆仓库

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

Source: README.md

导入项目

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

运行示例应用

运行项目到 Android 或 iOS 设备，即可使用各项测试功能验证 SDK 集成效果。示例 App 覆盖了前文功能总览中的全部模块，是理解各功能收发接口的最佳参考实现。

配置说明

code/JieLi_Home_Demo/ 是完整的音箱/耳机控制 App 参考工程，其关键配置如下：

出处：README.md

若要在自有 Flutter 工程中接入，核心配置即前文「插件引用方式」中的 pubspec.yaml 插件声明；具体业务功能（闹钟、FM、灯光等）的调用方式可对照 doc/ 下的收发接口介绍文档逐一接入。

调试技巧

SDK 内置详细日志，可实时监控蓝牙连接状态及数据交互全过程，便于快速定位问题。

• 日志查看方式：
  • Android：使用 Android Studio 的 Logcat 工具查看实时日志；
  • iOS：使用 Xcode 的 Console（控制台）查看实时日志。
• 问题排查：
  • Android SDK 调试说明：Android SDK 调试说明
  • iOS SDK 调试说明：iOS SDK 调试说明

调试时建议先确认设备已进入可连接状态、BLE 权限已授予，再结合日志中的连接状态与数据交互记录定位问题。

版本历史

出处：README.md

许可证

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

Copyright 2024 珠海市杰理科技股份有限公司

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Source: README.md

社区与支持

Related Links

• README.md（项目主文档）
• README_EN.md（英文项目文档）
• 收发接口介绍（中文）
• 收发接口介绍（英文）
• 杰理之家 Demo 工程
• LICENSE（Apache 2.0）