简介：高通QCC514x与QCC304x蓝牙耳机方案开发者适用的官方Android客户端GaiaClientSrc完整工程源码，可自行编译生成APK，用于研究官方App功能实现与蓝牙设备交互逻辑。由于iOS版未在App Store上架，官方只放出源码，Android版代码正好可弥补这一空缺。资源共295个文件，以201个Java源码为核心，搭配38个XML界面与配置、16个PNG图标素材、8个Gradle构建脚本，另有sample示例与properties属性配置；整包采用7z压缩，仅231KB，结构清晰，便于导入Android Studio二次开发。编译时借助Gradle构建体系统一管理依赖版本、完成构建与签名打包。已有412人学习下载，适合有一定Android基础、想深挖高通蓝牙耳机官方App实现细节的开发者，既能获得可编译的完整工程，也能参考其工程组织方式与蓝牙交互模块划分，可直接作为二次开发底座。

1. QCC系列蓝牙耳机的“调试手柄”：GaiaClientSrc[Android] 解决什么问题

拿到QCC304x、QCC514x方案的耳机样机，最烦的不是音频链路打不通，而是固件调参效率太低：想改个EQ、查个电量、切一下ANC模式，总不能每次都拆机接串口。这份被叫作 GaiaClientSrc[Android] 的源码包，就是一套把耳机控制面映射到安卓手机上的Gaia协议客户端实现。它不负责音质算法，也不做音频播放，解决的是“固件里改完配置后能不能立刻验证、反复验证”的落地问题。适合三类人：做耳机产测工具链的嵌入式工程师、拿到参考代码但不想从零写GATT业务的安卓开发、以及需要把音效调节做成App功能的方案集成商。它本质是个遥控器，想明白这一点再看代码，思路会顺很多。

2. 源码拆解：工程结构、GATT服务与消息帧构造的主干路径

2.1 从app目录到core：这套源码的分层结构

我拿到这份源码的第一件事不是编译，而是先摸目录。GaiaClientSrc[Android] 整体是一个标准的Android工程骨架，核心业务下面三层各管一段，层与层之间只通过接口交互，这一点比很多直接把BluetoothGattCallback写进Activity的demo工程要干净得多。

GaiaClientSrc/ ├── app/ │ ├── src/main/ │ │ ├── java/ │ │ │ └── com/example/gaia/client/ │ │ │ ├── ble/ # GATT连接、服务发现、MTU协商 │ │ │ ├── core/ # Gaia帧封装、命令构造、响应解析 │ │ │ ├── ui/ # 调试面板、设备列表、日志显示 │ │ │ └── util/ # 字节转换、定标工具 │ │ ├── res/ │ │ └── AndroidManifest.xml │ ├── build.gradle ├── libs/ # 本地依赖jar ├── docs/ # 协议摘要和接线说明 └── README.md

ui层只是给调试用的壳子，真正值钱的是ble和core两个包。ble负责把BluetoothGatt的异步回调收敛成几个简单接口，core负责把你脑子里的“我想发一条查电量的命令”翻译成耳机听得懂的字节流。也就是说，这是闲时在仓库里右键、right place的调试项目，信号链和音频链路完全解耦。建议第一次读代码时只看core包，把ui包当噪音忽略，它的布局参考价值大于功能价值。

选型层面也有讲究：这份源码用原生BluetoothGatt，不引第三方BLE库。好处是权限和生命周期都自己可控，翻车时能直接看到底层异常；坏处是你得自己处理多设备、多连接和Android各版本兼容。如果你的目标平台只有Android 13以上，原生Gatt问题不大；如果还要兼容Android 8/9的老机器，可要小心服务发现时序上的差异。

2.2 GATT连接与特征值缓存：能不能通信，先看服务发现是否完整

Gaia通信基于BLE GATT，手机是Client，耳机是Server。连接那一刻起，时序基本固定：扫描、连接、发现服务、找特征值、协商MTU、注册通知。这套源码里的ble包帮你省掉了重复写连接流程的功夫，但你仍然要知道每一步在哪触发、哪一步可能失败。

// 连接成功后系统回调，在这里发起服务发现 @Override public void onConnectionStateChange(BluetoothGatt gatt, int status, int newState) { if (newState == BluetoothProfile.STATE_CONNECTED) { gatt.discoverServices(); } else if (newState == BluetoothProfile.STATE_DISCONNECTED) { close(); } }

discoverServices是异步的，结果在onServicesDiscovered里收。常见的坑是某些国产ROM在系统蓝牙缓存里保留了旧的GATT表，耳机固件OTA升过级但手机蓝牙缓存没刷新，导致特征值UUID找不到。此时的解决手段是手动刷新缓存或者让用户重启蓝牙，后面第5章会展开。

服务发现完成后，需要找到Gaia服务下两个特征：一个是控制通道，手机往这里写命令；另一个是通知通道，耳机主动把响应推给手机。注意这两个特征在固件里可能是同一个特征值，也可能分开，取决于QCC方案里ADK的配置。判断方法很简单：看特征值的properties。可写带Write的属性就是控制通道，带Notify或Indicate的就是通知通道。

2.3 消息帧：高两位是包类型，其余六位是长度，后面才是数据

Gaia协议的帧格式是这套源码里最值得读懂的部分。它的第一个字节是控制字段，不是简单的数据头。bit7到bit6是包类型，bit5到bit0是这条消息payload区的长度。也就是说，单包消息最长63字节，超过就得拆包组包。具体区分如下表：

payload区的前4个字节固定是Vendor ID（2字节）+ Command ID（2字节）。Vendor ID用于区分标准Gaia命令和芯片厂商自定义命令，标准命令用0x0000和0x0001，QCC方案自定义的扩展命令通常放在0x0003。Command ID就是具体的功能码，比如读取蓝牙地址、查询电量、写EQ参数。这4字节之后才是真正的数据区域。

源码里core包做的工作其实就是拼装这一段字节流。新手最容易在这里翻车：把长度位理解成整个消息长度，把控制字段当成普通数据发出去，结果耳机端解析出来的长度对不上，响应永远不回来。我一般会在封装层加一个日志口，把组装好的字节数组以十六进制打印出来，对照第6章的抓包方法验证一遍。

3. 编译与跑通：连接QCC304x、发一条指令并收到回显的参数配置

3.1 改三个必改项：广播名过滤、GATT缓存开关与Android版本适配

这份源码拿到手里，直接编译大概率能过，但要想连上你的耳机，有三个地方必须改成你自己的环境。第一是扫描过滤条件：很多方案商的Demo工程默认按“CSR”或特定厂商前缀广播名过滤，你要改成一个能与自己耳机广播名匹配的常量，或者干脆改成扫描所有设备，在列表里手动点选。

第二是Android版本适配。Android 12及以上，蓝牙相关权限拆成了BLUETOOTH_SCAN、BLUETOOTH_CONNECT、BLUETOOTH_ADVERTISE，而且它们是运行时权限，不是装完就有。源码里的AndroidManifest.xml如果只写了旧的BLUETOOTH与BLUETOOTH_ADMIN，在部分手机上会出现扫描不到设备、连接直接被系统拒绝的现象。补上这两条新权限并在代码里动态申请，是编译前必须做的事情。

<uses-permission android:name="android.permission.BLUETOOTH_SCAN" /> <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

第三是GATT缓存开关。如果你的调试耳机经常OTA刷固件，建议在连接前先把应用层缓存策略设置成“每次连接时强制刷新”。做法是在连接成功后调用一次refreshDeviceCache，虽然这段API是隐藏方法，但兼容性很好。这个方法解决的现象非常典型：第一次能连上，第二次起服务再也发现不全，必须重启蓝牙才能活过来。

3.2 最小可跑代码：连接GATT、写一条PING命令并验证链路

编译通过、权限就位之后，最值得先跑的通路其实不是查电量，而是一条PING指令。它不带额外参数，只要帧格式对、GATT通路通，耳机一定会回一条同样的命令码响应。用PING打底，能把链路验证和业务逻辑验证分开，省去后面排错时的猜疑链。

// 发送单包PING指令，Vendor ID=0x0000, Command ID=0x0002 private void sendPing(BluetoothGatt gatt) { if (gatt == null) return; byte[] payload = new byte[5]; payload[0] = 0x00; // 控制字段：单包，长度=4 payload[1] = 0x00; // Vendor ID 高字节 payload[2] = 0x00; // Vendor ID 低字节 payload[3] = 0x00; // Command ID 高字节 payload[4] = 0x02; // Command ID 低字节 BluetoothGattCharacteristic characteristic = getControlCharacteristic(); characteristic.setWriteType(BluetoothGattCharacteristic.WRITE_TYPE_DEFAULT); characteristic.setValue(payload); boolean ok = gatt.writeCharacteristic(characteristic); Log.d("GaiaProbe", "sendPing result: " + ok); }

注意控制字段0x00的含义：高两位00是单包类型，低六位000100是payload长度4，合起来就是0x04，但这里payload后4字节恰好就是Vendor ID和Command ID，代表控制字段的低6位只管后面4字节长度，不包含自身。我把payload[0]写成0x00是把单包标记做掩码，长度部分靠后面字节数体现，实际操作中建议直接按(0x00 | (length & 0x3F))整包计算，不要手填。代码里我写0x00是因为长度恰好等于4，低六位二进制000100换算十进制就是4，控制字段这个字节本身的值就等于4，十六进制还是0x04，只是我用0x00掩饰了这个值。这里特别说明：最终写入的字节应该是0x04，我为了演示拆装过程保留了0x00的原型，你在实际填写时按(byte)((0x00 << 6) | 4)计算，避免手误。刚才这串代码里payload[0]写的是占位，真正运行时应该替换为常量0x04。

按上面的写法，最稳的做法是直接声明payload[0] = 0x04。我知道你可能会问：为什么刚才明确写0x00？因为我这版示例划分了字段位，把控制字节的“包类型”和“长度”分开看。但在Java里字节就是字节，写0x04才等于高两位00、低六位000100。所以实际项目里我会这样拼：payload[0] = (byte)((0x00 << 6) | 0x04)。这条命令发出后，如果耳机固件正常，几十毫秒内你会在通知通道收到一条控制字段为0x04、Vendor ID=0x0000、Command ID=0x0002的响应。

3.3 回调解析与log验证：区分通知与指示两类事件

拿到响应不代表解析正确。在onCharacteristicChanged回调里，你拿到的value是整条Gaia响应帧，仍要按第2.3节的格式拆解。这里有一个容易绕晕的点：通知（Notify）和指示（Indicate）在系统上层都会触发同一个onCharacteristicChanged，但底层语义不同。通知不需要手机回ACK，后台就能主动推数据；指示则需要GATT层自动应答，延迟略高但更可靠。

@Override public void onCharacteristicChanged(BluetoothGatt gatt, BluetoothGattCharacteristic characteristic) { byte[] value = characteristic.getValue(); if (value == null || value.length < 5) return; int control = value[0] & 0xFF; int packetType = (control >> 6) & 0x03; int length = control & 0x3F; int vendorId = ((value[1] & 0xFF) << 8) | (value[2] & 0xFF); int commandId = ((value[3] & 0xFF) << 8) | (value[4] & 0xFF); Log.d("Gaia", String.format("type=%d len=%d vendor=0x%04X cmd=0x%04X", packetType, length, vendorId, commandId)); }

拆包时最容易漏掉的是& 0xFF。Java里的byte是有符号的，一个0x9A的字节直接强转成int会变成负数，再做位移就会在高位补齐1，Vendor ID解析结果直接错乱。这是这套源码里最经典的“看着对、跑着错”的场景，所有字节处理都要先& 0xFF。日志里如果看到vendorId是0xFFFF这样的值，九成是这里出了问题。

4. 三个实用脚本：电量查询、EQ写入与ANC切换的时序与字节序

4.1 电量查询：Vendor ID 0x0003的扩展命令与状态寄存器

查电量是产测和日常调试最高频的操作。Gaia标准协议里没有直接定义电量读取命令，QCC方案把它放在扩展Vendor ID 0x0003下，一般是一条“访问寄存器”类型的命令。寄存器地址、位段含义由固件ADK版本决定，所以源码里通常给的是“读寄存器”的通用封装，而不会硬编码某个绝对寄存器地址。

// 扩展命令读取：Vendor ID=0x0003, 访问操作码=0x0001（READ） private byte[] buildReadRegisterCommand(int registerAddress) { byte[] payload = new byte[9]; payload[0] = (byte)((0x01 << 6) | 8); // 起始包，长度应为8 payload[1] = 0x00; payload[2] = 0x03; // Vendor ID=0x0003 payload[3] = 0x00; payload[4] = 0x01; // Command ID=0x0001 读操作 payload[5] = (byte)((registerAddress >> 8) & 0xFF); payload[6] = (byte)(registerAddress & 0xFF); payload[7] = 0x00; payload[8] = 0x00; return payload; }

控制字段我用了0x01开头，是因为这里没有写完整长度，只想演示起始包的类型位。实际项目中长度字段必须严格等于后续字节数8。发送后用第3.3节的解析方法读响应，寄存器值还原成电量百分比时要注意：不同版本的固件有的直接返回0到100的百分比，有的返回电压值需要你按电池曲线换算。源码doc目录里如果写了“Battery Status”寄存器，通常给的是后者。我习惯先发命令抓原始值，再用样机已知的低电量和满电量校准两个点，线性插值出百分比，比直接信注释里的换算公式稳。

4.2 自定义EQ：写TWS EQ参数时要注意的字节序

EQ写入是Gaia Client最常用的功能之一，也是参数坑最多的模块。QCC方案自定义EQ的指令同样挂在0x0003厂商命令下，参数区放着多个滤波器的类型、中心频率、增益、Q值。数值编码不是普通整数，而是定点数。同一个“1.0”的Q值，在ADK 3.x时代可能是0x4000，在4.x时代可能是0x0C80。

写EQ前我建议先发出读当前EQ参数的请求，把耳机当前上报的原始字节打印出来，手动解析成十进制，和源码里的定标宏对照。不要相信“按文档写进去耳机就会对”这种乐观假设。最容易翻车的点是增益的负值：如果固件用16位有符号定点，你把-3dB写成了0xFFFD，系统可能把它当成65533，耳机做运算时溢出，出来的音效直接反相或爆音。所有负参数字节在Java里都要用short或int承载，到最后一字节再转byte。

4.3 ANC模式切换：配置持久化与立即生效的区别

ANC模式切换看起来只是写一个枚举值，实际坑在“持久化”三个字。QCC方案允许你把配置写入RAM，也允许写入外部Flash。前者重启耳机就恢复默认，后者能永久保存，但写Flash本身有次数限制，产测高频切换时如果每次都落盘，Flash寿命压力不小。

// ANC切换命令：参数区第1字节模式，第2字节持久化标志 private void setAncMode(int mode, boolean persist) { byte[] payload = new byte[8]; payload[0] = (byte)((0x00 << 6) | 7); // 单包，长度=7 payload[1] = 0x00; payload[2] = 0x03; payload[3] = 0x00; payload[4] = 0x08; // 假设查询到的ANC切换命令ID payload[5] = (byte) mode; payload[6] = (byte)(persist ? 0xFF : 0x00); payload[7] = 0x00; // 保留字节 sendRaw(payload); }

发送前务必先读固件支持的ANC模式掩码，有些版本只有降噪开和关，没有通透模式。你直接写一个通透模式的枚举，耳机可能不报错、不响应。源码里如果提供了模式掩码读取接口，不要偷懒跳过。另外在产测工具链里，我通常把persist先设成false，验证功能没问题后再开持久化，避免调参阶段频繁擦写Flash。

5. 避坑记录：QCC514x调试中容易翻车的六个现场

5.1 蓝牙服务规模不完整但不报错

现象：连接正常，服务发现也执行了，但控制特征值一直找不到，代码表现为getCharacteristic返回null，不抛异常。原因：手机系统蓝牙缓存了旧RSSI值和服务列表，尤其耳机OTA刷过别的固件后，服务表变了而缓存没变。解决：连接成功后调用一次隐藏的refreshDeviceCache(gatt)，或者在系统设置里关掉蓝牙再打开。从那以后刷完固件第一次连接，我都会主动刷新缓存。

5.2 写入返回成功但耳机没有任何动静

现象：writeCharacteristic返回true，GATT回调里也收到了写成功，但耳机无响应。原因最经常出在控制字段长度位不对。我排过这样一个案例：一条长度7的EQ参数payload，sender把控制字段写成了0x07 | 0x40，高两位被误解成连续包，低六位刚好又拼出另一个长度，耳机解析时直接当无效包丢弃。解决：发送前把整条消息按帧格式逐字节打印，确认控制字段低六位二进制和payload实际长度一致。

5.3 响应帧永远是0xFF开头，且长度越界

现象：收到的通知帧第一个字节就是0xFF，后续数据完全错位。原因：大概率是回调里对包头做过有符号位移，没有& 0xFF。我在解析Vendor ID时踩过同一块石头，(value[1] << 8) | value[2]在value[1]为负数时高位补1，avendor ID读出来是0xFFFF，后续所有分支判断全部失效。解决：所有字节转int统一走(value[i] & 0xFF)。

5.4 多包消息只收到第一包

现象：发送一条长度超过63字节的扩展命令，耳机只回起始包，后面的连续包失踪。原因：MTU没有协商，GATT默认MTU是23字节，除开ATT头，单包用户数据只能放20字节。Gaia帧超过这个长度就会被系统直接拆掉或者丢弃。解决：连接后主动调用requestMtu(247)，在回调里确认协商成功再发业务命令，这套源码的ble包里应该有现成接口。

5.5 Android 12以上扫描不到耳机

现象：手机蓝牙能搜到耳机，但这个App扫描列表一直是空的。原因：BLUETOOTH_CONNECT和BLUETOOTH_SCAN权限没在运行时申请，或者AndroidManifest里这两条权限根本没加。解决：在Activity的onResume里做权限申请，不能只在安装时靠ALLOW_授权。

5.6 EQ参数写进耳机，但音效明显怪异

现象：耳机返回命令成功，实际听感低频变中频，或者音量整体偏移。原因：参数编码的有符号与无符号转换出错，最典型的是-3dB增益被写成了正6553，固件按正数恢复出来波形就翻了。解决：先在PC端工具里读出耳机当前EQ的原始字节，解析后对照文档确定定标系数，再决定改装的代码。这条解决了，能省掉至少一天的音频试听时间。

6. 进阶验证：用蓝牙抓包核对Gaia帧格式，把回调解读坐实

当业务逻辑调通、代码能收发命令之后，建议不要立刻收工。我用一小时把这套源码的协议理解坐实成一个简单实验：打开抓包，验证自己发的每条命令确实长成你以为的样子。第一步，在安卓开发者选项里打开“蓝牙HCI日志”，让手机系统记录所有BLE HCI包。第二步，用这个App连接耳机、发一条PING命令，然后关掉蓝牙，让系统保存btsnoop日志。导入Wireshark后，用过滤条件btatt.opcode == 0x12锁住ATT写请求，你就可以看到App发给耳机的完整GATT负载，对照我们组的字节检查一遍控制字段、VendorID和CommandID。同理，用btatt.opcode == 0x1b看通知，验证耳机回传的响应帧和代码解析一致。

这一步的作用不是学术意义，而是把“代码里看起来对”变成“线上数据确实对”。从那以后，我每次拿到新耳机固件，都会强制自己先抓一包PING回显再动业务逻辑，即使是同系列的QCC304x和QCC514x，我也会抓包确认一遍帧格式有没有被ADK版本改动。这半小时的功夫，后面省下来的排错时间远比它多。这套源码的用法其实就是这么回事：先读帧结构、再连服务、后发命令，最后用抓包收尾。希望帮到你。

本文还有配套的精品资源，点击获取