ufm::hw::GpioButton 類別 參考文件

GPIO 按鈕控制類別 更多...

#include <GpioButton.h>

類別ufm::hw::GpioButton的繼承圖:

複合項目
struct	Event
	按鈕事件處理介面 更多...

公開方法(Public Methods)
	GpioButton (hal::digital::GeneralInput &pin, uint32 debounceMillicroseconds=5000, bool inverted=false)
	建構 GPIO 按鈕物件
virtual	~GpioButton (void) override
	解構 GPIO 按鈕物件
virtual void	update (void) override
	更新按鈕狀態
GpioButton &	setEvent (Event *event)
	設定事件處理器
GpioButton &	setInverted (bool inverted)
	設定按鈕邏輯反相
公開方法(Public Methods) 繼承自 ufm::lang::Object
void *	operator new (size_t n)
	使用運算子 new 分配記憶體
void *	operator new (size_t n, void *p)
	在指定記憶體上調用運算子 new
virtual ufm::lang::Object &	getObject (void) override
	取得對應的 Object 物件
void	delay (int milliseconds) const
	延遲指定的毫秒數進行執行緒等待
bool	equals (Object *object) const
	判斷與另一物件是否為相同參照（指標型態比較）
bool	equals (Object &object) const
	判斷與另一物件是否為相同參照（參照型態比較）
void	wait (void) const
	使當前線程等待直到被通知
bool	wait (int timeout) const
	等待通知或超時
bool	yield (void) const
	讓執行緒讓渡控制權給同優先權的下一個執行緒
int	lock (void) const
	核心鎖定，鎖定期間禁止線程切換
int	unlock (void) const
	核心解鎖
ufm::sys::Thread *	currentThread (void) const
	取得當前執行緒指標
virtual int	hashcode (void) const
	返回對象的哈希碼值。支持這種方法是為了散列表，如HashMap提供的那樣。
公開方法(Public Methods) 繼承自 ufm::lang::Interface
virtual	~Interface (void)=default
	虛擬析構函式

詳細描述

GPIO 按鈕控制類別

此類別用於管理 GPIO 按鈕的狀態檢測，提供防彈跳功能以及按鈕按下/釋放事件處理。 支援正常邏輯（高電平為按下）和反相邏輯（低電平為按下）兩種模式。

主要特性：

• **防彈跳處理**：可設定防彈跳時間，避免按鈕機械抖動造成的誤觸發
• **事件驅動**：透過事件回調機制處理按鈕狀態變化
• **邏輯反相**：支援設定按鈕邏輯反相以適應不同硬體設計
• **週期性更新**：實現 Updatable 介面，支援系統週期性狀態檢查
• **單次觸發**：確保事件只在狀態轉換瞬間觸發一次，避免重複觸發

使用範例：

// 建立按鈕物件
hal::digital::GeneralInput& buttonPin = getButtonPin();
ufm::hw::GpioButton button(buttonPin, 10000, false); // 10ms 防彈跳，正常邏輯
 
// 設定事件處理器
class MyButtonHandler : public ufm::hw::GpioButton::Event {
public:
  void onPressed(void) override { 
    // 處理按鈕按下事件
  }
  void onReleased(void) override { 
    // 處理按鈕釋放事件
  }
};
 
MyButtonHandler handler;
button.setEvent(&handler);
 
// 在主迴圈中定期更新
while(true) {
  button.update();
  // 其他程式邏輯...
}

註

此類別需要配合系統的更新機制定期呼叫 update() 方法

警告

防彈跳時間設定過短可能導致誤觸發，設定過長可能影響回應速度

參閱

ufm::lang::Object

ufm::lang::Updatable

hal::digital::GeneralInput

建構子與解構子說明文件

GpioButton()

ufm::hw::GpioButton::GpioButton	(	hal::digital::GeneralInput &	pin,
		uint32	debounceMillicroseconds = 5000,
		bool	inverted = false )

建構 GPIO 按鈕物件

建立一個新的 GPIO 按鈕控制物件，並初始化相關參數。 建構時會讀取按鈕的初始狀態並啟動防彈跳計時器。

參數

pin	GPIO 輸入腳位的參考，必須是有效的 GeneralInput 物件
debounceMillicroseconds	防彈跳時間，單位為微秒，預設值為 5000 微秒（5 毫秒）
inverted	按鈕邏輯是否反相，預設值為 false（正常邏輯） false: 高電平表示按下，低電平表示釋放 true: 低電平表示按下，高電平表示釋放

註

防彈跳時間建議設定在 1000-50000 微秒（1-50 毫秒）之間，視按鈕特性而定

機械式按鈕建議使用較長的防彈跳時間（10-50ms），觸控式按鈕可使用較短時間（1-10ms）

警告

防彈跳時間設定為 0 將會導致不可預期的行為

~GpioButton()

virtual ufm::hw::GpioButton::~GpioButton ( void )

overridevirtual

解構 GPIO 按鈕物件

清理物件資源，確保物件安全銷毀。 解構時不會觸發任何事件，也不會改變 GPIO 腳位的狀態。

註

解構後，相關的事件處理器指標會失效，請確保不再呼叫相關方法

函式成員說明文件

setEvent()

GpioButton & ufm::hw::GpioButton::setEvent

(

Event *

event

)

設定事件處理器

設定或變更按鈕狀態變化時的事件處理器。當按鈕狀態發生轉換時， 會呼叫事件處理器的對應方法。

參數

event

事件處理器指標，必須繼承自 Event 結構體 傳入有效指標：啟用事件處理，狀態轉換時會觸發回調 傳入 nullptr：停用事件處理，狀態轉換時不會觸發任何回調

傳回值

GpioButton& 返回當前物件的參考，支援鏈式呼叫（Method Chaining）

使用範例：

MyButtonHandler handler;
button.setEvent(&handler);           // 設定事件處理器
button.setEvent(nullptr);            // 停用事件處理
button.setEvent(&handler).setInverted(true); // 鏈式呼叫

註

事件處理器的生命週期必須長於 GpioButton 物件

可以在執行時動態變更事件處理器

警告

請確保事件處理器指標的有效性，無效指標會導致程式崩潰

參閱

Event

setInverted()

setInverted()

GpioButton & ufm::hw::GpioButton::setInverted

(

bool

inverted

)

設定按鈕邏輯反相

設定按鈕的邏輯極性，以適應不同的硬體設計需求。 這個設定會影響 GPIO 電平狀態到邏輯狀態的對應關係。

參數

inverted

邏輯反相旗標 false: 正常邏輯，高電平（1）表示按下，低電平（0）表示釋放 true: 反相邏輯，低電平（0）表示按下，高電平（1）表示釋放

傳回值

GpioButton& 返回當前物件的參考，支援鏈式呼叫（Method Chaining）

硬體應用場景：

• **正常邏輯（false）**：按鈕按下時連接到 VCC，釋放時透過下拉電阻接地
• **反相邏輯（true）**：按鈕按下時接地，釋放時透過上拉電阻連接到 VCC

使用範例：

// 一般上拉配置（按下時接地）
button.setInverted(true);
 
// 一般下拉配置（按下時接 VCC）
button.setInverted(false);
 
// 鏈式呼叫
button.setInverted(true).setEvent(&handler);

註

此設定可以在執行時動態變更，立即生效

變更此設定不會觸發狀態轉換事件

反相設定會影響所有後續的狀態讀取和事件觸發

參閱

setEvent()

update()

virtual void ufm::hw::GpioButton::update ( void )

overridevirtual

更新按鈕狀態

定期檢查按鈕狀態變化並處理防彈跳邏輯。此方法實現了完整的按鈕狀態管理流程：

1. 讀取當前 GPIO 狀態
2. 根據反相設定調整邏輯狀態
3. 檢測狀態變化並重新啟動防彈跳計時器
4. 等待防彈跳時間確保狀態穩定
5. 在狀態轉換瞬間觸發對應事件（單次觸發）

狀態轉換時序：

• 狀態變化檢測 → 重新啟動計時器 → 等待防彈跳時間 → 確認穩定狀態 → 觸發事件

防彈跳機制：

• 當檢測到狀態變化時，會重新啟動計時器
• 只有當狀態持續穩定超過設定的防彈跳時間才會被確認
• 確認後的狀態變化會觸發對應的事件回調

註

此方法必須定期被呼叫以確保按鈕狀態能即時更新和處理

呼叫頻率建議至少是防彈跳時間的 1/10，例如防彈跳 10ms 則至少每 1ms 呼叫一次

此方法實現了 ufm::lang::Updatable 介面的純虛函數

警告

如果長時間未呼叫此方法，按鈕狀態變化將無法被檢測

參閱

setEvent()

Event::onPressed()

Event::onReleased()

實作 ufm::lang::Updatable.

---

此類別(class) 文件是由下列檔案中產生:

• GpioButton.h