【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 Name

Bluetooth HCI Command - Read Local Name
    Command 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 Complete
    Event Code: Command Complete (0x0e)
    Parameter Total Length: 252
    Number of Allowed Command Packets: 1
    Command 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]

1. Status（1 字节）

   • 表示命令执行是否成功
   • 0x00 表示成功，其他值为错误码（如 0x01 Invalid HCI Command Parameters）

2. 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 获取的。

在底层协议栈中，手机或车机可能通过以下步骤实现这一过程：

1. Host 发送 HCI_Read_Local_Name 命令到 Controller
2. Controller 返回 HCI_Command_Complete 事件，其中包含 Local Name
3. 上层显示或广播这个名称

---

2. 相关章节

Section 6.23 – 该节通常会详细说明 Local Name 是如何被存储和更新的，比如：

• 可以通过 HCI_Write_Local_Name 改名

• 被远程设备读取时也会用这个值（如 Inquiry Response 时）

• 在 Extended Inquiry Response（EIR）数据中也可能包含这个名字

---

3. aosp 中的例子

  
// system/gd/hci/controller.cc

struct 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.cc

  void 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 \0
    local_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
应用场景	显示蓝牙设备名称、广播设备身份、配对时展示名称等