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