CodexPad Arduino 库 5.0.0
载入中...
搜索中...
未找到
codex_pad::Client类 参考

Client主类 更多...

#include <client.h>

类 codex_pad::Client 继承关系图:

Public 成员函数

 Client () noexcept
 构造函数
 
 ~Client () noexcept
 析构函数
 
void Init () noexcept
 初始化
 
bool Connect (const std::string &address, uint32_t timeout_ms=5000) noexcept
 连接
 
bool Connect (gamepad::input::Button buttons) noexcept
 扫描附近的 CodexPad 设备,并自动连接到一个按键状态与指定掩码匹配的设备。
 
void Disconnect () noexcept
 断开连接
 
const gamepad::input::Tracker & Update () noexcept
 更新,需要在Loop中不断调用
 
bool is_connected () const noexcept
 是否连接
 
const std::string & remote_device_name () const noexcept
 获取CodexPad的型号
 
const std::string & remote_model_number () const noexcept
 获取CodexPad的型号
 
const std::array< uint8_t, 3 > & remote_firmware_version () const noexcept
 获取CodexPad的固件版本
 
const gamepad::input::Tracker & input_tracker () const noexcept
 获取输入跟踪器对象
 
int32_t rssi () const noexcept
 获取已连接 CodexPad 的 RSSI(接收信号强度指示)。
 
void set_local_tx_power (int32_t tx_power) noexcept
 设置本地 BLE 发射功率(手动模式)。
 
int32_t local_tx_power () const noexcept
 获取用户设定的本地 BLE 发射功率值。
 
void set_dynamic_tx_power_enabled (bool enabled) noexcept
 使能或禁用以 RSSI 为基础的动态发射功率调节。
 
NimBLEClient * ble_client () const noexcept
 获取 BLE 客户端对象
 

详细描述

Client主类

示例
basic_polling.ino, button_mask_connection.ino , 以及 inputs_detection.ino.

在文件 client.h 第 27 行定义.

构造及析构函数说明

◆ Client()

codex_pad::Client::Client ( )
noexcept

构造函数

在文件 client.cpp 第 46 行定义.

◆ ~Client()

codex_pad::Client::~Client ( )
noexcept

析构函数

在文件 client.cpp 第 49 行定义.

成员函数说明

◆ ble_client()

NimBLEClient * codex_pad::Client::ble_client ( ) const
inlinenoexcept

获取 BLE 客户端对象

此函数返回内部 BLE 客户端对象的指针。调用者不应尝试释放/删除它。

返回
BLE 客户端对象
示例
basic_polling.ino, button_mask_connection.ino , 以及 inputs_detection.ino.

在文件 client.h 第 328 行定义.

◆ Connect() [1/2]

bool codex_pad::Client::Connect ( const std::string & address,
uint32_t timeout_ms = 5000 )
noexcept

连接

参数
[in]addressCodexPad的蓝牙设备地址,格式为"XX:XX:XX:XX:XX:XX",X为数字或者大写字母, 半角冒号分隔
[in]timeout_ms超时时间,单位毫秒
返回值
true连接成功
false连接失败
示例
basic_polling.ino, button_mask_connection.ino , 以及 inputs_detection.ino.

在文件 client.cpp 第 57 行定义.

◆ Connect() [2/2]

bool codex_pad::Client::Connect ( gamepad::input::Button buttons)
noexcept

扫描附近的 CodexPad 设备,并自动连接到一个按键状态与指定掩码匹配的设备。

此方法会主动扫描蓝牙设备。当发现一个或多个 CodexPad 设备,其当前按键状态与提供的 button_mask 完全匹配时,它将尝试建立连接。 如果附近有多个设备都符合按键掩码,则会选择信号最强(RSSI 值最大)的设备进行连接。

参数
[in]button_mask用于匹配目标设备按键状态的32位按钮掩码。 使用 ButtonMask() 函数来组合多个 Button 枚举值。
返回值
true连接成功(找到了符合按键掩码的设备并成功连接)。
false连接失败(未找到匹配设备或连接尝试失败)。
注解
这是一个阻塞式调用。它会持续扫描,直到找到匹配的设备、连接建立或达到内部超时时间。
警告
**请勿**在按钮掩码中包含 Button::kHome。按住 Home 键会触发设备重启,这将中断连接过程。 示例:
codex_pad::Client g_codex_pad_client;
g_codex_pad_client.Init();
// 持续尝试连接到 Start 和 Cross/A 按键被同时按下的设备。
while (!g_codex_pad_client.ScanAndConnect(gamepad::input::Button::kStart | gamepad::input::Button::kStart)) {
// 可选:在尝试之间添加短暂延时或其他操作。
delay(100);
}
// 循环退出,意味着连接成功。
Serial.println("CodexPad 连接成功!");
Client主类
void Init() noexcept
初始化

在文件 client.cpp 第 68 行定义.

◆ Disconnect()

void codex_pad::Client::Disconnect ( )
inlinenoexcept

断开连接

在文件 client.h 第 140 行定义.

◆ Init()

void codex_pad::Client::Init ( )
noexcept

初始化

在文件 client.cpp 第 51 行定义.

◆ input_tracker()

const gamepad::input::Tracker & codex_pad::Client::input_tracker ( ) const
inlinenoexcept

获取输入跟踪器对象

此函数返回内部输入跟踪器对象的引用。

返回
输入跟踪器对象

在文件 client.h 第 214 行定义.

◆ is_connected()

bool codex_pad::Client::is_connected ( ) const
noexcept

是否连接

返回值
true已连接
false未连接

在文件 client.cpp 第 158 行定义.

◆ local_tx_power()

int32_t codex_pad::Client::local_tx_power ( ) const
inlinenoexcept

获取用户设定的本地 BLE 发射功率值。

该函数返回之前通过 set_local_tx_power() 保存的值(或其默认值)。 注意: 当动态发射功率调节处于开启状态(默认开启,参见 set_dynamic_tx_power_enabled) 时,实际发射功率由基于 RSSI 的滞环量化器自动控制。此时,该函数返回的值**不能代表当前实时 使用的发射功率**,它仅代表内部存储的手动设定值。

返回
存储的本地 BLE 发射功率设定值,单位 dBm。

在文件 client.h 第 279 行定义.

◆ remote_device_name()

const std::string & codex_pad::Client::remote_device_name ( ) const
inlinenoexcept

获取CodexPad的型号

返回
CodexPad的型号
示例
basic_polling.ino, button_mask_connection.ino , 以及 inputs_detection.ino.

在文件 client.h 第 176 行定义.

◆ remote_firmware_version()

const std::array< uint8_t, 3 > & codex_pad::Client::remote_firmware_version ( ) const
inlinenoexcept

获取CodexPad的固件版本

返回
CodexPad的固件版本
示例
basic_polling.ino, button_mask_connection.ino , 以及 inputs_detection.ino.

在文件 client.h 第 200 行定义.

◆ remote_model_number()

const std::string & codex_pad::Client::remote_model_number ( ) const
inlinenoexcept

获取CodexPad的型号

返回
CodexPad的型号
示例
basic_polling.ino, button_mask_connection.ino , 以及 inputs_detection.ino.

在文件 client.h 第 188 行定义.

◆ rssi()

int32_t codex_pad::Client::rssi ( ) const
noexcept

获取已连接 CodexPad 的 RSSI(接收信号强度指示)。

该函数从底层 NimBLE 客户端获取当前的接收信号强度指示(RSSI)值。 注意: 在低于 3.1.0 的 ESP32 Arduino Core 版本中,RSSI 读数存在严重漂移(不准确)。 不推荐在旧版本中依赖此返回值进行逻辑判断或界面显示。如需准确的 RSSI 测量, 请将 ESP32 Arduino Core 升级至 3.1.0 或更高版本。

返回
当前 RSSI 值,单位为 dBm。如果 BLE 客户端未初始化或未连接,则返回 0。
示例
button_mask_connection.ino , 以及 inputs_detection.ino.

在文件 client.cpp 第 275 行定义.

◆ set_dynamic_tx_power_enabled()

void codex_pad::Client::set_dynamic_tx_power_enabled ( bool enabled)
inlinenoexcept

使能或禁用以 RSSI 为基础的动态发射功率调节。

该功能**默认开启**,且**强烈建议保持开启**。启用后,客户端会在 Update() 中周期性读取对端设备的 RSSI,并通过滞环量化器(Hysteresis Quantizer)动态调整本地 BLE 发射功率:

  • 信号较好(RSSI 较高)时,降低发射功率以节省能耗并减少无线干扰;
  • 信号较差(RSSI 较低)时,提高发射功率以维持连接稳定性。 与手动功率的冲突: 当动态调节开启时,通过 set_local_tx_power() 设置的任何功率值都会被 **覆盖**,无法生效。如果需要使用固定的手动发射功率,必须先调用 set_dynamic_tx_power_enabled(false) 关闭此功能。
    注解
    在 ESP32 平台上,该功能依赖 。由于在 **3.1.0 之前**的 ESP32 Arduino Core 版本中 RSSI 读数存在严重漂移(不准确),实际调节逻辑仅在 ESP_ARDUINO_VERSION >= ESP_ARDUINO_VERSION_VAL(3, 1, 0) 时才会编译和执行。在更早的版本中,内部已通过预处理器宏禁用动态调节,此时 set_local_tx_power() 可以正常生效作为回退方案。
    参数
    enabledtrue 表示开启(推荐),false 表示关闭并切换为手动控制模式。

在文件 client.h 第 314 行定义.

◆ set_local_tx_power()

void codex_pad::Client::set_local_tx_power ( int32_t tx_power)
inlinenoexcept

设置本地 BLE 发射功率(手动模式)。

该函数用于保存期望的发射功率值。但是,**如果动态发射功率调节处于开启状态**(默认开启, 参见 set_dynamic_tx_power_enabled),该值将被忽略,并在 Update() 中被动态调节逻辑覆盖。 如需使该手动设置持续生效,必须先调用 set_dynamic_tx_power_enabled(false) 关闭动态调节功能。 在低于 3.1.0 的 ESP32 Arduino Core 版本中,由于内部因 RSSI 漂移已禁用动态调节,此设置可正常生效。

参数
tx_power本地 BLE 发射功率,单位 dBm。

在文件 client.h 第 258 行定义.

◆ Update()

const gamepad::input::Tracker & codex_pad::Client::Update ( )
noexcept

更新,需要在Loop中不断调用

在文件 client.cpp 第 127 行定义.


该类的文档由以下文件生成: