OpenLogi

0x0007 · deviceFriendlyName

通过 15-byte 名称分块读取或修改设备专属友好名称。

deviceFriendlyName 保存用户指定的标签。它与 0x0005 deviceTypeAndName 中固定的市场名称不同。该功能以 15-byte 分块读取当前名称和默认名称,并可写入或重置当前名称。

**规格:**没有公开的 Logitech 规格。布局由 Logi Options+ 2.8 静态分析逆向得出。**用于:**OpenLogi 未使用。

函数参考

已注册的 DeviceFriendlyNameFeature 封装实现功能版本 0。

方法

函数HID++ fn签名返回值
get_friendly_name_length0()DeviceFriendlyNameLength
get_friendly_name1(index: u8)[u8; 15]
get_whole_friendly_name便捷方法()String
get_default_friendly_name2(index: u8)[u8; 15]
get_whole_default_friendly_name便捷方法()String
set_friendly_name3(index: u8, chunk: [u8; 15])u8
set_whole_device_name便捷方法(name: String)u8
reset_friendly_name4()u8

所有方法都是异步方法,并返回 Result<…, Hidpp20Error>。便捷方法会执行多个 HID++ 调用,因此没有单一函数索引。

set_friendly_name 返回响应中的回显 charIndex。它不返回名称长度。set_whole_device_name 返回截断后实际发送的输入名称字节数。

类型

DeviceFriendlyNameLength

字段类型说明
name_lengthu8设备报告的当前名称长度。
name_max_lengthu8设备报告的最大可写名称长度。
default_name_lengthu8设备报告的默认名称长度。

事件

可用证据没有记录事件布局。OpenLogi 没有为此功能注册事件处理程序。

线格式

函数 0、1、2 和 4 使用 3-byte short request。函数 3 使用 16-byte long request。下列字节偏移从 HID++ 功能 header 后开始计算。

get_friendly_name_length(fn 0)

请求:[0x00, 0x00, 0x00]

字节字段说明
0name_length当前友好名称长度。
1name_max_length最大可写友好名称长度。
2default_name_length默认友好名称长度。
3–15尾部 payload在 extend_payload() 后,OpenLogi 忽略这些字节。

get_friendly_name(fn 1)

请求:[char_index, 0x00, 0x00]

字节字段说明
0char_index请求分块开始处的名称偏移。
1–2保留OpenLogi 写入 0x00。
字节字段说明
0回显的 char_index与请求不同时,OpenLogi 会记录 warning。它会保留分块,与 Options+ 2.8 一致。
1–15名称分块15 个名称字节。OpenLogi 将这些字节复制到 [u8; 15]。

get_default_friendly_name(fn 2)

请求:[char_index, 0x00, 0x00]

字节字段说明
0char_index请求分块开始处的默认名称偏移。
1–2保留OpenLogi 写入 0x00。
字节字段说明
0回显的 char_index与请求不同时,OpenLogi 会记录 warning。它会保留分块。Options+ 2.8。
1–15默认名称分块15 个默认名称字节。OpenLogi 将这些字节复制到 [u8; 15]。

OpenLogi 对两个读取函数都使用 extend_payload()。short 响应会在封装复制字节 1–15 前补零。封装不会拒绝 short 响应。

set_friendly_name(fn 3)

请求:[char_index, chunk[0], …, chunk[14]]

字节字段说明
0char_index写入该分块的名称偏移。
1–15chunk恰好 15 个名称字节。整名帮助方法会为最后一个不完整分块补 0x00。
字节字段说明
0回显的 char_indexset_friendly_name 返回这个原始字节。它不是长度。Options+ 2.8。
1–15尾部 payloadOpenLogi 忽略这些字节。

reset_friendly_name(fn 4)

请求:[0x00, 0x00, 0x00]

字节字段说明
0报告的长度reset_friendly_name 返回此字节。
1–15尾部 payload在 extend_payload() 后,OpenLogi 忽略这些字节。

OpenLogi 的用法

设备功能表公布 0x0007 时,此功能会注册。OpenLogi v0.8.15 没有设备层、agent、IPC、CLI 或 UI 调用此封装。它不在库存或缓存身份中使用友好名称。

公开的整名读取方法先获得长度,再按自己的偏移读取分块,并删除尾部 NUL 字符。读取回显不匹配时会产生 warning,但读取不会失败。

公开的整名写入方法读取 name_max_length,按 UTF-8 字符边界截断输入,并在偏移 0、15、30 等位置发送补零分块。它使用本地偏移,而不使用响应字节。写入回显不匹配会产生 warning,但不会停止后续分块。写入方法不会读回存储的名称。

未确认的细节

没有公开的 Logitech 规格涵盖此功能。已知函数号和回显字段来自 Options+ 2.8 的静态分析。硬件抓包尚未验证所有布局。

可用证据没有确定功能版本门控或改名通知事件。它也没有确定空名称或恰好 15-byte 名称的设备行为。空输入时,OpenLogi 不写入分块,并建议用 reset_friendly_name 恢复默认值。

Rust 用法

use hidpp::{
    device::Device,
    feature::device_friendly_name::DeviceFriendlyNameFeature,
    protocol::v20::Hidpp20Error,
};

async fn inspect_or_rename(device: &mut Device) -> Result<(), Hidpp20Error> {
    device.enumerate_features().await?;
    let Some(feature) = device.get_feature::<DeviceFriendlyNameFeature>() else {
        return Ok(());
    };

    println!("current name: {}", feature.get_whole_friendly_name().await?);
    let bytes_written = feature.set_whole_device_name("Desk mouse".to_owned()).await?;
    println!("sent {bytes_written} name bytes");
    Ok(())
}

本页目录