【android bluetooth 协议分析 01】【HCI 层介绍 7】【ReadLocalName命令介绍】
1. HCI_Read_Local_Name
Read Local Name 是 HCI（Host Controller Interface）命令之一，属于 BR/EDR 控制器的 HCI Command 类别，其主要功能是 读取本地设备（Controller）的人类可读名称（Local Name）。这通常用于让其它蓝牙设备知道该设备的“蓝牙名称”。
1. 命令功能（Description）
HCI_Read_Local_Name 命令允许 Host 读取 BR/EDR Controller 存储的人类友好名称（即 Bluetooth 名称）。
这类似于你打开手机蓝牙设置看到的“设备名称”，例如“John’s iPhone”或“Car Audio”。这个名称就是 Controller 的 Local Name。
2. 命令参数（Command Parameters）
9 2025-04-24 15:55:53.352134 host controller HCI_CMD 4 Sent Read Local NameBluetooth HCI Command - Read Local NameCommand Opcode: Read Local Name (0x0c14)0000 11.. .... .... = Opcode Group Field: Host Controller & Baseband Commands (0x03).... ..00 0001 0100 = Opcode Command Field: Read Local Name (0x014)Parameter Total Length: 0[Response in frame: 10][Command-Response Delta: 1.381ms]None
该命令不需要 Host 提供任何参数，直接发出即可。
3. 返回参数（Return Parameters）
10 2025-04-24 15:55:53.353515 controller host HCI_EVT 255 Rcvd Command Complete (Read Local Name)Bluetooth HCI Event - Command CompleteEvent Code: Command Complete (0x0e)Parameter Total Length: 252Number of Allowed Command Packets: 1Command Opcode: Read Local Name (0x0c14)0000 11.. .... .... = Opcode Group Field: Host Controller & Baseband Commands (0x03).... ..00 0001 0100 = Opcode Command Field: Read Local Name (0x014)Status: Success (0x00)Device Name: [Command in frame: 9][Command-Response Delta: 1.381ms]-
Status（1 字节）
- 表示命令执行是否成功
- 0x00 表示成功，其他值为错误码（如 0x01 Invalid HCI Command Parameters）
-
Local_Name（248 字节）
- 即设备的本地名称（最多 248 字节，UTF-8 编码时最多 248 个字节，但不一定是 248 个字符）
- 如果名称不足 248 字节，其余部分将被填充为 0x00。
4. 事件（Event(s) Generated）
当该命令完成时，Controller 会回送一个
HCI_Command_Complete事件。
这个事件中会包含上述的 Status 和 Local_Name 字段。
2. 实际应用场景说明
1. 例子：手机蓝牙配对显示名称
当手机或车机进行蓝牙配对时，通常会显示对方设备的名称，比如：
发现设备：
Car Audio
这是通过读取对方设备的 Local Name 获取的。
在底层协议栈中，手机或车机可能通过以下步骤实现这一过程：
- Host 发送
HCI_Read_Local_Name命令到 Controller - Controller 返回
HCI_Command_Complete事件，其中包含 Local Name - 上层显示或广播这个名称
2. 相关章节
Section 6.23 – 该节通常会详细说明 Local Name 是如何被存储和更新的，比如：
-
可以通过
HCI_Write_Local_Name改名 -
被远程设备读取时也会用这个值（如 Inquiry Response 时）
-
在 Extended Inquiry Response（EIR）数据中也可能包含这个名字
3. aosp 中的例子
// system/gd/hci/controller.ccstruct Controller::impl {void Start(hci::HciLayer* hci) {
...hci_->EnqueueCommand(ReadLocalNameBuilder::Create(),handler->BindOnceOn(this, &Controller::impl::read_local_name_complete_handler));...
}
在 Controller::impl::Start 函数中，我们会获取 本地蓝牙设备的名字。
当我们获取到内容后，回调 read_local_name_complete_handler
1. read_local_name_complete_handler
// system/gd/hci/controller.ccvoid read_local_name_complete_handler(CommandCompleteView view) {auto complete_view = ReadLocalNameCompleteView::Create(view);ASSERT(complete_view.IsValid());ErrorCode status = complete_view.GetStatus();ASSERT_LOG(status == ErrorCode::SUCCESS, "Status 0x%02hhx, %s", status, ErrorCodeText(status).c_str());std::array<uint8_t, 248> local_name_array = complete_view.GetLocalName();local_name_ = std::string(local_name_array.begin(), local_name_array.end());// erase \0local_name_.erase(std::find(local_name_.begin(), local_name_.end(), '\0'), local_name_.end());}
最终我们将 读到的蓝牙名字保存在 local_name_ 中。
std::string Controller::GetLocalName() const {return impl_->local_name_;
}如果其他模块需要本地蓝牙的名字，可以通过调用 Controller::GetLocalName 函数获得
4.总结
| 项目 | 内容 |
|---|---|
| 命令名称 | HCI_Read_Local_Name |
| 功能 | 读取 Controller 存储的人类可读设备名称 |
| 命令参数 | 无 |
| 返回值 | Status（1B）+ Local_Name（248B） |
| 触发事件 | HCI_Command_Complete |
| 应用场景 | 显示蓝牙设备名称、广播设备身份、配对时展示名称等 |