CodexPad Arduino 库 4.0.0
载入中...
搜索中...
未找到
client.h
1#pragma once
2
3#include <functional>
4#include <mutex>
5#include <optional>
6#include <queue>
7#include <string>
8#include <vector>
9
10#include "NimBLEDevice.h"
11#include "gamepad_input_tracker.h"
12
13namespace codex_pad {
14
15/**
16 * @~English
17 * @class Client
18 * @brief Client main class
19 */
20/**
21 * @~Chinese
22 * @class Client
23 * @brief Client主类
24 */
25class Client : public NimBLEClientCallbacks {
26 public:
27 /**
28 * @~English
29 * @brief Constructor
30 */
31 /**
32 * @~Chinese
33 * @brief 构造函数
34 */
35 Client() noexcept;
36
37 /**
38 * @~English
39 * @brief Destructor
40 */
41 /**
42 * @~Chinese
43 * @brief 析构函数
44 */
45 ~Client() noexcept;
46
47 /**
48 * @~English
49 * @brief Initialize
50 */
51 /**
52 * @~Chinese
53 * @brief 初始化
54 */
55 void Init() noexcept;
56
57 /**
58 * @~English
59 * @brief Connect
60 * @param[in] bluetooth_device_address The Bluetooth device address(BD_ADDR) of the CodexPad, formatted as
61 * "XX:XX:XX:XX:XX:XX", X is a number or uppercase letter, colon separated
62 * @param[in] timeout_ms Timeout in milliseconds
63 * @retval true if connected successfully
64 * @retval false if connection failed
65 * */
66 /**
67 * @~Chinese
68 * @brief 连接
69 * @param[in] bluetooth_device_address CodexPad的蓝牙设备地址(BD_ADDR),格式为"XX:XX:XX:XX:XX:XX",X为数字或者大写字母,
70 * 半角冒号分隔
71 * @param[in] timeout_ms 超时时间,单位毫秒
72 * @retval true 连接成功
73 * @retval false 连接失败
74 */
75 bool Connect(const std::string& bluetooth_device_address, uint32_t timeout_ms = 5000) noexcept;
76
77 /**
78 * @~English
79 * @brief Scans for nearby CodexPad devices and automatically connects to a device whose button state matches the specified
80 * mask.
81 * @details This method actively scans for Bluetooth devices. When it discovers one or more CodexPad devices whose current
82 * button states exactly match the provided `button_mask`, it will attempt to establish a connection. If multiple nearby
83 * devices match the button mask, the device with the strongest signal (highest RSSI) will be selected for connection.
84 * @param[in] button_mask A 32-bit button mask used to match the target device's button states.
85 * Use the `ButtonMask()` function to combine multiple @ref Button values.
86 * @retval true Connection successful (a device matching the button mask was found and connected).
87 * @retval false Connection failed (no matching device found or connection attempt failed).
88 * @note This is a blocking call. It will continuously scan until a matching device is found, a connection is established, or
89 * the internal timeout is reached.
90 * @warning **DO NOT** include `Button::kHome` in the button mask. Holding the Home button triggers a device reboot, which
91 * will interrupt the connection process. Example:
92 * @code
93 * codex_pad::Client g_codex_pad_client;
94 * g_codex_pad_client.Init();
95 * // Continuously try to connect to a device where the Start and Cross/A buttons are pressed.
96 * while (!g_codex_pad_client.ScanAndConnect(gamepad::input::Button::kStart | gamepad::input::Button::kStart)) {
97 * // Optional: Add a small delay or other operations between attempts.
98 * delay(100);
99 * }
100 * // Once the loop exits, connection is successful.
101 * Serial.println("CodexPad connected!");
102 * @endcode
103 */
104 /**
105 * @~Chinese
106 * @brief 扫描附近的 CodexPad 设备,并自动连接到一个按键状态与指定掩码匹配的设备。
107 * @details 此方法会主动扫描蓝牙设备。当发现一个或多个 CodexPad 设备,其当前按键状态与提供的 `button_mask`
108 * 完全匹配时,它将尝试建立连接。 如果附近有多个设备都符合按键掩码,则会选择信号最强(RSSI 值最大)的设备进行连接。
109 * @param[in] button_mask 用于匹配目标设备按键状态的32位按钮掩码。
110 * 使用 `ButtonMask()` 函数来组合多个 @ref Button 枚举值。
111 * @retval true 连接成功(找到了符合按键掩码的设备并成功连接)。
112 * @retval false 连接失败(未找到匹配设备或连接尝试失败)。
113 * @note 这是一个阻塞式调用。它会持续扫描,直到找到匹配的设备、连接建立或达到内部超时时间。
114 * @warning **请勿**在按钮掩码中包含 `Button::kHome`。按住 Home 键会触发设备重启,这将中断连接过程。
115 * 示例:
116 * @code
117 * codex_pad::Client g_codex_pad_client;
118 * g_codex_pad_client.Init();
119 * // 持续尝试连接到 Start 和 Cross/A 按键被同时按下的设备。
120 * while (!g_codex_pad_client.ScanAndConnect(gamepad::input::Button::kStart | gamepad::input::Button::kStart)) {
121 * // 可选:在尝试之间添加短暂延时或其他操作。
122 * delay(100);
123 * }
124 * // 循环退出,意味着连接成功。
125 * Serial.println("CodexPad 连接成功!");
126 * @endcode
127 */
128 bool ScanAndConnect(gamepad::input::Button buttons) noexcept;
129
130 /**
131 * @~English
132 * @brief Disconnect
133 */
134 /**
135 * @~Chinese
136 * @brief 断开连接
137 */
138 void Disconnect() noexcept { Reset(); }
139
140 /**
141 * @~English
142 * @brief Update, need to be called in Loop
143 */
144 /**
145 * @~Chinese
146 * @brief 更新,需要在Loop中不断调用
147 */
148 const gamepad::input::Tracker& Update() noexcept;
149
150 /**
151 * @~English
152 * @brief Is connected
153 * @retval true if connected
154 * @retval false if not
155 */
156 /**
157 * @~Chinese
158 * @brief 是否连接
159 * @retval true 已连接
160 * @retval false 未连接
161 */
162 bool is_connected() const noexcept;
163
164 /**
165 * @~English
166 * @brief Get model number of the CodexPad
167 * @return Model number of the CodexPad
168 */
169 /**
170 * @~Chinese
171 * @brief 获取CodexPad的型号
172 * @return CodexPad的型号
173 */
174 const std::string& remote_device_name() const noexcept { return remote_device_name_; }
175
176 /**
177 * @~English
178 * @brief Get model number of the CodexPad
179 * @return Model number of the CodexPad
180 */
181 /**
182 * @~Chinese
183 * @brief 获取CodexPad的型号
184 * @return CodexPad的型号
185 */
186 const std::string& remote_model_number() const noexcept { return remote_model_number_; }
187
188 /**
189 * @~English
190 * @brief Get firmware version of the CodexPad
191 * @return Firmware version of the CodexPad
192 */
193 /**
194 * @~Chinese
195 * @brief 获取CodexPad的固件版本
196 * @return CodexPad的固件版本
197 */
198 const std::array<uint8_t, 3>& remote_firmware_version() const noexcept { return remote_firmware_version_; }
199
200 /**
201 * @~English
202 * @brief Get the input tracker object
203 * @details This function returns a reference to the internal input tracker object.
204 * @return Input tracker object
205 */
206 /**
207 * @~Chinese
208 * @brief 获取输入跟踪器对象
209 * @details 此函数返回内部输入跟踪器对象的引用。
210 * @return 输入跟踪器对象
211 */
212 const gamepad::input::Tracker& input_tracker() const noexcept { return input_tracker_; }
213
214 /**
215 * @~English
216 * @brief Get the RSSI of the CodexPad
217 * @return RSSI of the CodexPad
218 */
219 /**
220 * @~Chinese
221 * @brief 获取CodexPad的RSSI
222 * @return CodexPad的RSSI
223 */
224 int32_t rssi() const noexcept;
225
226 /**
227 * @~English
228 * @brief Get the BLE client object
229 * @details This function returns a pointer to the internal BLE client object. The caller should not try and release/delete
230 * it.
231 * @return BLE client object
232 */
233 /**
234 * @~Chinese
235 * @brief 获取 BLE 客户端对象
236 * @details 此函数返回内部 BLE 客户端对象的指针。调用者不应尝试释放/删除它。
237 * @return BLE 客户端对象
238 */
239 NimBLEClient* ble_client() const noexcept { return ble_client_; }
240
241 private:
242 static constexpr size_t kInputsQueueMax = 10;
243 bool onConnParamsUpdateRequest(NimBLEClient*, const ble_gap_upd_params*) override {
244 return false; // update our own connection parameters, so we reject the request
245 }
246
247 void onPhyUpdate(NimBLEClient*, uint8_t tx_phy, uint8_t rx_phy) override;
248 bool Connect(const NimBLEAddress& address, bool async_connect, const uint32_t timeout_ms);
249 void OnNotify(const NimBLERemoteCharacteristic* remote_characteristic, const uint8_t* data, const size_t length,
250 const bool is_notify);
251 void Reset();
252
253 mutable std::mutex mutex_;
254 NimBLEClient* ble_client_{nullptr};
255 std::string remote_device_name_;
256 std::string remote_model_number_;
257 std::array<uint8_t, 3> remote_firmware_version_{0, 0, 0};
258 std::queue<gamepad::input::State> inputs_queue_;
259 gamepad::input::Tracker input_tracker_;
260};
261} // namespace codex_pad
Client() noexcept
构造函数
const gamepad::input::Tracker & Update() noexcept
更新,需要在Loop中不断调用
const std::string & remote_device_name() const noexcept
获取CodexPad的型号
const std::array< uint8_t, 3 > & remote_firmware_version() const noexcept
获取CodexPad的固件版本
bool is_connected() const noexcept
是否连接
NimBLEClient * ble_client() const noexcept
获取 BLE 客户端对象
void Init() noexcept
初始化
void Disconnect() noexcept
断开连接
bool ScanAndConnect(gamepad::input::Button buttons) noexcept
扫描附近的 CodexPad 设备,并自动连接到一个按键状态与指定掩码匹配的设备。
bool Connect(const std::string &bluetooth_device_address, uint32_t timeout_ms=5000) noexcept
连接
const std::string & remote_model_number() const noexcept
获取CodexPad的型号
const gamepad::input::Tracker & input_tracker() const noexcept
获取输入跟踪器对象
int32_t rssi() const noexcept
获取CodexPad的RSSI
~Client() noexcept
析构函数