CodexPad Arduino Lib 5.0.0
Loading...
Searching...
No Matches
codex_pad::Client Class Reference

Client main class. More...

#include <client.h>

Inheritance diagram for codex_pad::Client:

Public Member Functions

 Client () noexcept
 Constructor.
 
 ~Client () noexcept
 Destructor.
 
void Init () noexcept
 Initialize.
 
bool Connect (const std::string &address, uint32_t timeout_ms=5000) noexcept
 Connect.
 
bool Connect (gamepad::input::Button buttons) noexcept
 Scans for nearby CodexPad devices and automatically connects to a device whose button state matches the specified mask.
 
void Disconnect () noexcept
 Disconnect.
 
const gamepad::input::Tracker & Update () noexcept
 Update, need to be called in Loop.
 
bool is_connected () const noexcept
 Is connected.
 
const std::string & remote_device_name () const noexcept
 Get model number of the CodexPad.
 
const std::string & remote_model_number () const noexcept
 Get model number of the CodexPad.
 
const std::array< uint8_t, 3 > & remote_firmware_version () const noexcept
 Get firmware version of the CodexPad.
 
const gamepad::input::Tracker & input_tracker () const noexcept
 Get the input tracker object.
 
int32_t rssi () const noexcept
 Get the RSSI of the connected CodexPad.
 
void set_local_tx_power (int32_t tx_power) noexcept
 Set the local BLE TX power (manual mode).
 
int32_t local_tx_power () const noexcept
 Get the manually configured local BLE TX power value.
 
void set_dynamic_tx_power_enabled (bool enabled) noexcept
 Enable or disable dynamic TX power adjustment based on RSSI.
 
NimBLEClient * ble_client () const noexcept
 Get the BLE client object.
 

Detailed Description

Client main class.

Examples
basic_polling.ino, button_mask_connection.ino, and inputs_detection.ino.

Definition at line 27 of file client.h.

Constructor & Destructor Documentation

◆ Client()

codex_pad::Client::Client ( )
noexcept

Constructor.

Definition at line 46 of file client.cpp.

◆ ~Client()

codex_pad::Client::~Client ( )
noexcept

Destructor.

Definition at line 49 of file client.cpp.

Member Function Documentation

◆ ble_client()

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

Get the BLE client object.

This function returns a pointer to the internal BLE client object. The caller should not try and release/delete it.

Returns
BLE client object
Examples
basic_polling.ino, button_mask_connection.ino, and inputs_detection.ino.

Definition at line 328 of file client.h.

◆ Connect() [1/2]

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

Connect.

Parameters
[in]addressThe Bluetooth device address(BD_ADDR) of the CodexPad, formatted as "XX:XX:XX:XX:XX:XX", X is a number or uppercase letter, colon separated
[in]timeout_msTimeout in milliseconds
Return values
trueif connected successfully
falseif connection failed
Examples
basic_polling.ino, button_mask_connection.ino, and inputs_detection.ino.

Definition at line 57 of file client.cpp.

◆ Connect() [2/2]

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

Scans for nearby CodexPad devices and automatically connects to a device whose button state matches the specified mask.

This method actively scans for Bluetooth devices. When it discovers one or more CodexPad devices whose current button states exactly match the provided button_mask, it will attempt to establish a connection. If multiple nearby devices match the button mask, the device with the strongest signal (highest RSSI) will be selected for connection.

Parameters
[in]button_maskA 32-bit button mask used to match the target device's button states. Use the ButtonMask() function to combine multiple Button values.
Return values
trueConnection successful (a device matching the button mask was found and connected).
falseConnection failed (no matching device found or connection attempt failed).
Note
This is a blocking call. It will continuously scan until a matching device is found, a connection is established, or the internal timeout is reached.
Warning
DO NOT include Button::kHome in the button mask. Holding the Home button triggers a device reboot, which will interrupt the connection process. Example:
codex_pad::Client g_codex_pad_client;
g_codex_pad_client.Init();
// Continuously try to connect to a device where the Start and Cross/A buttons are pressed.
while (!g_codex_pad_client.ScanAndConnect(gamepad::input::Button::kStart | gamepad::input::Button::kStart)) {
// Optional: Add a small delay or other operations between attempts.
delay(100);
}
// Once the loop exits, connection is successful.
Serial.println("CodexPad connected!");
Client main class.
Definition client.h:27
void Init() noexcept
Initialize.
Definition client.cpp:51

Definition at line 68 of file client.cpp.

◆ Disconnect()

void codex_pad::Client::Disconnect ( )
inlinenoexcept

Disconnect.

Definition at line 140 of file client.h.

◆ Init()

void codex_pad::Client::Init ( )
noexcept

Initialize.

Definition at line 51 of file client.cpp.

◆ input_tracker()

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

Get the input tracker object.

This function returns a reference to the internal input tracker object.

Returns
Input tracker object

Definition at line 214 of file client.h.

◆ is_connected()

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

Is connected.

Return values
trueif connected
falseif not

Definition at line 158 of file client.cpp.

◆ local_tx_power()

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

Get the manually configured local BLE TX power value.

This function returns the value previously stored by set_local_tx_power() (or its default). Note: When dynamic TX power adjustment is enabled (which is the default, see set_dynamic_tx_power_enabled), the actual TX power is controlled automatically by the RSSI-based hysteresis quantizer. In that case, the value returned by this function does not reflect the real-time TX power being used; it only reflects the stored manual setting.

Returns
The stored local BLE TX power setting in dBm.

Definition at line 279 of file client.h.

◆ remote_device_name()

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

Get model number of the CodexPad.

Returns
Model number of the CodexPad
Examples
basic_polling.ino, button_mask_connection.ino, and inputs_detection.ino.

Definition at line 176 of file client.h.

◆ remote_firmware_version()

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

Get firmware version of the CodexPad.

Returns
Firmware version of the CodexPad
Examples
basic_polling.ino, button_mask_connection.ino, and inputs_detection.ino.

Definition at line 200 of file client.h.

◆ remote_model_number()

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

Get model number of the CodexPad.

Returns
Model number of the CodexPad
Examples
basic_polling.ino, button_mask_connection.ino, and inputs_detection.ino.

Definition at line 188 of file client.h.

◆ rssi()

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

Get the RSSI of the connected CodexPad.

This function retrieves the current Received Signal Strength Indication (RSSI) from the underlying NimBLE client. Note: On ESP32 Arduino Core versions older than 3.1.0, RSSI readings suffer from severe fluctuation (drift) and are highly unreliable. Relying on this return value for logic or display purposes in those older versions is not recommended. For accurate RSSI measurements, please upgrade to ESP32 Arduino Core 3.1.0 or later.

Returns
The current RSSI value in dBm. Returns 0 if the BLE client is not initialized or not connected.
Examples
button_mask_connection.ino, and inputs_detection.ino.

Definition at line 275 of file client.cpp.

◆ set_dynamic_tx_power_enabled()

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

Enable or disable dynamic TX power adjustment based on RSSI.

This feature is enabled by default and highly recommended to keep enabled. When enabled, the client periodically reads the peer's RSSI during Update() and adjusts the local BLE transmit power using a hysteresis quantizer:

  • Strong signal (high RSSI) → Lower TX power to save energy and reduce interference.
  • Weak signal (low RSSI) → Higher TX power to maintain connection stability. Conflict with manual power: When dynamic adjustment is enabled, any value set via set_local_tx_power() will be overwritten and not take effect. To use a fixed manual TX power, you must first disable this feature by calling set_dynamic_tx_power_enabled(false).
    Note
    On ESP32, this feature relies on NimBLEClient::getRssi(). Due to severe RSSI fluctuation (drift) in ESP32 Arduino Core versions older than 3.1.0, the actual adjustment is only compiled and executed when ESP_ARDUINO_VERSION >= ESP_ARDUINO_VERSION_VAL(3, 1, 0). In earlier versions, the logic is disabled via preprocessor macros, allowing set_local_tx_power() to work as a fallback.
    Parameters
    enabledtrue to enable (recommended), false to disable and switch to manual control.

Definition at line 314 of file client.h.

◆ set_local_tx_power()

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

Set the local BLE TX power (manual mode).

This function stores the desired TX power level. However, if dynamic TX power adjustment is enabled (which is the default, see set_dynamic_tx_power_enabled), this value will be ignored and overwritten by the dynamic adjustment logic during Update(). To ensure this manual setting takes effect persistently, you must first call set_dynamic_tx_power_enabled(false). On ESP32 Arduino Core versions older than 3.1.0, where dynamic adjustment is internally disabled due to RSSI drift, this setting will apply normally.

Parameters
tx_powerLocal BLE TX power in dBm.

Definition at line 258 of file client.h.

◆ Update()

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

Update, need to be called in Loop.

Definition at line 127 of file client.cpp.


The documentation for this class was generated from the following files: