官方文档与集成指南

Flutter-JL_Home 是珠海市杰理科技股份有限公司为杰理音箱、耳机及音频设备提供的蓝牙控制开发平台（Flutter Demo）。本页汇总该仓库内的官方文档体系（README、doc/、libs/）并给出完整的 SDK 集成指南，帮助开发者从零开始接入基于 RCSP 协议（远程控制系统协议） 的蓝牙控制能力。

Purpose and Scope

本页覆盖以下内容：

• 仓库中官方文档的组织方式（README.md / README_EN.md / doc/ / libs/ 各自的定位与用途）；
• SDK 集成的完整流程：环境要求、克隆仓库、导入工程、插件引用、运行示例；
• 工程结构说明与关键目录导航；
• 调试技巧与问题排查入口（Android Logcat / iOS Console、官方调试文档链接）。

以下主题属于兄弟页面或仓库内独立文档，不在本页展开：

• 收发接口的具体 API 签名与数据结构：参见 doc/ 目录下的《Jieli Home Demo (Flutter) - Send/Receive Interface Introduction》（中英文版）以及 libs/ 目录中的收发接口源码；
• SDK 版本历史与许可证细节：见 README.md 的版本历史与 Apache License 2.0 章节；
• 示例 App 的完整功能实现：属于 code/JieLi_Home_Demo/ 下的独立工程文档。

Overview

Flutter-JL_Home 是杰理科技官方发布的蓝牙控制开发平台，专为杰理音箱耳机类产品提供服务。SDK 以 RCSP（Remote Control System Protocol，远程控制系统协议） 为基础，通过 BLE 连接手机与设备，提供完整的蓝牙控制功能与丰富的应用示例。

适用产品

核心能力

平台对外提供以下功能接口（由收发接口层支撑）：

来源：README.md

文档体系架构

仓库内文档与代码以"主 README → 接口文档 → 收发接口源码 → 示例工程"的层次组织。集成者按此路径逐层深入即可完成从"了解"到"接入"再到"二次开发"的全过程。

flowchart TD
    subgraph sg_Repo["Flutter-JL_Home 仓库"]
        README["README.md<br/>（中文主文档）"]
        README_EN["README_EN.md<br/>（英文主文档）"]
        DOC["doc/ 文档目录<br/>收发接口介绍（中/英）"]
        LIBS["libs/ 收发接口<br/>Receive / Send Interface"]
        CODE["code/JieLi_Home_Demo<br/>示例工程源码"]
    end

    subgraph sg_Integrator["集成者路径"]
        START["克隆仓库"] --> IMPORT["导入 Android Studio"]
        IMPORT --> PLUGIN["pubspec 插件引用<br/>JlHomePlugin"]
        PLUGIN --> RUN["运行示例 App"]
        RUN --> CUSTOM["基于 libs/ 二次开发"]
    end

    README --> DOC
    README --> LIBS
    README --> CODE
    DOC --> LIBS
    LIBS --> CUSTOM
    CODE --> RUN

    style sg_Repo fill:#f5f7fa,stroke:#4a6fa5
    style sg_Integrator fill:#eef7ee,stroke:#4a8f5a

各组成部分的职责：

• README.md / README_EN.md：总入口文档。涵盖概述、运行环境、快速开始、工程结构、配置说明、调试技巧、社区支持、版本历史与许可证，中英文一一对应；
• doc/：官方接口文档目录，含《Jieli Home Demo (Flutter) - Send/Receive Interface Introduction》的中英文版本及说明文件，是理解收发接口协议的核心资料；
• libs/：核心收发接口代码，分为 "Receive Interface"（接收接口）与 "Send Interface"（发送接口）两个子目录；
• code/JieLi_Home_Demo/：完整的参考实现工程，集成者可将其作为模板直接修改扩展。

运行环境要求

来源：README.md

环境要求的两个关键约束：一是系统版本门槛由 BLE（低功耗蓝牙）能力决定（Android 6.0+ / iOS 13.0+）；二是设备端固件必须内置支持 RCSP 功能的 SDK（AC 系列芯片），二者缺一不可，否则无法建立控制链路。

集成流程（快速开始）

集成者按"克隆 → 导入 → 插件引用 → 运行 → 二次开发"五步即可完成 SDK 接入。下图展示了完整的集成时序：

sequenceDiagram
    participant Dev as 开发者
    participant Git as GitHub/Gitee 仓库
    participant IDE as Android Studio
    participant App as 示例 App (JieLi_Home_Demo)
    participant Device as 杰理设备 (AC 系列)

    Dev->>Git: git clone Flutter-JL_Home
    Git-->>Dev: 本地代码（code/ doc/ libs/）
    Dev->>IDE: Open 项目 code/JieLi_Home_Demo
    IDE->>IDE: 解析 pubspec 插件配置（JlHomePlugin）
    Dev->>App: 运行到 Android / iOS 设备
    App->>Device: BLE 连接（RCSP 协议）
    Device-->>App: 设备状态/能力上报
    App-->>Dev: 验证音乐/音效/ANC 等控制功能
    Dev->>libs: 基于 Send/Receive Interface 扩展自定义命令

3.1 克隆仓库

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

来源：README.md

3.2 导入项目到 Android Studio

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

来源：README.md

3.3 插件引用

插件声明是整个集成的核心环节：Android 平台通过 package: com.jieli.bt.sdk + pluginClass: JlHomePlugin 绑定原生 SDK，iOS 平台通过同名 JlHomePlugin 类绑定，双端共用同一插件名以屏蔽平台差异：

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

来源：README.md

3.4 运行示例应用

运行项目到 Android 或 iOS 设备，即可使用各项测试功能验证 SDK 集成效果。示例工程覆盖音乐控制、音效调节、设备管理、卡拉 OK、多语言、HTTP 接口与 OTA 升级等能力，可作为功能验证与二次开发的起点。

来源：README.md、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/：可编译运行的参考工程，集成者优先从这里复制项目骨架；
• doc/：协议层面的权威资料。收发接口介绍文档定义了消息的发送格式与接收回调，是理解 libs/ 源码的前提，也是本页所述"接口参考"类兄弟页面的内容来源；
• libs/：将收发接口与业务 UI 解耦：Send Interface 负责将上层指令编码为 RCSP 消息下发，Receive Interface 负责解析设备上报并回调给上层。二次开发时只需复用这两组接口即可接入任意自定义功能。

配置说明

code/JieLi_Home_Demo/ 作为完整的音箱/耳机控制 App，其配置要点如下：

来源：README.md

调试与问题排查

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

日志查看方式

• Android：使用 Android Studio 的 Logcat 工具查看实时日志；
• iOS：使用 Xcode 的 Console（控制台）查看实时日志。

官方调试文档

• Android SDK：Android SDK 调试说明
• iOS SDK：iOS SDK 调试说明

来源：README.md

调试链路中应重点观察三类日志：BLE 连接状态变化（确认链路建立）、RCSP 消息收发记录（确认指令编码/解码正确）、业务回调触发（确认设备响应到达上层）。日志由 SDK 内置输出，无需额外引入日志库。

故障模式与边界情况

依据官方文档中的环境要求与调试指引，集成过程中常见的故障场景及处理建议如下：

上述排查思路来源于 README.md 运行环境、插件引用 与 调试技巧 章节。

社区与支持

常用资源：

来源：README.md

版本历史

来源：README.md

许可证

本项目采用 Apache License 2.0 开源协议，版权归珠海市杰理科技股份有限公司所有（Copyright 2024）。完整许可证文本见仓库 LICENSE 文件，允许商用、修改与再分发，但需保留版权声明并注明修改。

来源：README.md

Related Links

• README.md（中文主文档）
• README_EN.md（英文主文档）
• doc/Jieli Home Demo (Flutter) - Send/Receive Interface Introduction.md（收发接口中文文档）
• doc/Jieli Home Demo (Flutter) - Send/Receive Interface Introduction_en.md（收发接口英文文档）
• code/JieLi_Home_Demo/README.md（示例工程说明）
• 杰理科技 Android SDK 调试说明
• 杰理科技 iOS SDK 调试说明