ESP32 Telegram 回覆鍵盤 (Reply Keyboard)」

 ESP32 Telegram 回覆鍵盤 (Reply Keyboard)」

/*******************************************************************

     An example of how to use a custom reply keyboard markup.  

     written by Vadim Sinitski (modified by Brian Lough)

 *******************************************************************/

#include <WiFi.h>

#include <WiFiClientSecure.h>

#include <UniversalTelegramBot.h>

// Wifi network station credentials

#define WIFI_SSID "Wokwi-GUEST"

#define WIFI_PASSWORD ""

// Telegram BOT Token (Get from Botfather)

#define BOT_TOKEN "7738940254:AAHbrWu9ovb1BKPQyWsbNSjNxfCGCrEWU-o"

const unsigned long BOT_MTBS = 1000; // mean time between scan messages

const int ledPin = 2 ;

WiFiClientSecure secured_client;

UniversalTelegramBot bot(BOT_TOKEN, secured_client);

unsigned long bot_lasttime;          // last time messages' scan has been done

int ledStatus = 0;

void handleNewMessages(int numNewMessages)

{

  Serial.println("handleNewMessages");

  Serial.println(String(numNewMessages));

  for (int i = 0; i < numNewMessages; i++)

  {

    String chat_id = bot.messages[i].chat_id;

    String text = bot.messages[i].text;

    String from_name = bot.messages[i].from_name;

    if (from_name == "")

      from_name = "Guest";

    if (text == "/ledon")

    {

      digitalWrite(ledPin, HIGH); // turn the LED on (HIGH is the voltage level)

      ledStatus = 1;

      bot.sendMessage(chat_id, "Led is ON", "");

    }

    if (text == "/ledoff")

    {

      ledStatus = 0;

      digitalWrite(ledPin, LOW); // turn the LED off (LOW is the voltage level)

      bot.sendMessage(chat_id, "Led is OFF", "");

    }

    if (text == "/status")

    {

      if (ledStatus)

      {

        bot.sendMessage(chat_id, "Led is ON", "");

      }

      else

      {

        bot.sendMessage(chat_id, "Led is OFF", "");

      }

    }

    if (text == "/options")

    {

      String keyboardJson = "[[\"/ledon\", \"/ledoff\"],[\"/status\"]]";

      bot.sendMessageWithReplyKeyboard(chat_id, "Choose from one of the following options", "", keyboardJson, true);

    }

    if (text == "/start")

    {

      String welcome = "Welcome to Universal Arduino Telegram Bot library, " + from_name + ".\n";

      welcome += "This is Reply Keyboard Markup example.\n\n";

      welcome += "/ledon : to switch the Led ON\n";

      welcome += "/ledoff : to switch the Led OFF\n";

      welcome += "/status : Returns current status of LED\n";

      welcome += "/options : returns the reply keyboard\n";

      bot.sendMessage(chat_id, welcome, "Markdown");

    }

  }

}

void setup()

{

  Serial.begin(115200);

  Serial.println();

  // attempt to connect to Wifi network:

  Serial.print("Connecting to Wifi SSID ");

  Serial.print(WIFI_SSID);

  WiFi.begin(WIFI_SSID, WIFI_PASSWORD);

  secured_client.setCACert(TELEGRAM_CERTIFICATE_ROOT); // Add root certificate for api.telegram.org

  while (WiFi.status() != WL_CONNECTED)

  {

    Serial.print(".");

    delay(500);

  }

  Serial.print("\nWiFi connected. IP address: ");

  Serial.println(WiFi.localIP());

  Serial.print("Retrieving time: ");

  configTime(0, 0, "pool.ntp.org"); // get UTC time via NTP

  time_t now = time(nullptr);

  while (now < 24 * 3600)

  {

    Serial.print(".");

    delay(100);

    now = time(nullptr);

  }

  Serial.println(now);

  pinMode(ledPin, OUTPUT); // initialize digital ledPin as an output.

  delay(10);

  digitalWrite(ledPin, LOW); // initialize pin as off

}

void loop()

{

  if (millis() - bot_lasttime > BOT_MTBS)

  {

    int numNewMessages = bot.getUpdates(bot.last_message_received + 1);

    while (numNewMessages)

    {

      Serial.println("got response");

      handleNewMessages(numNewMessages);

      numNewMessages = bot.getUpdates(bot.last_message_received + 1);

    }

    bot_lasttime = millis();

  }

}

這段程式碼將 Telegram 機器人與 ESP32 的硬體控制（LED 燈） 結合，並使用了 「回覆鍵盤 (Reply Keyboard)」。

與前一個範例的「內嵌按鈕」不同，回覆鍵盤會直接取代使用者的手機輸入法鍵盤，讓使用者像點選選單一樣發送指令。以下是詳細說明：

---

1. 硬體定義與狀態變數

C++

const int ledPin = LED_BUILTIN; // 定義 LED 引腳（通常是開發板上的內建 LED，GPIO 2）
int ledStatus = 0;              // 儲存 LED 的狀態：0 為關，1 為開

2. 指令邏輯：handleNewMessages

這部分決定了收到不同文字指令時，硬體該如何反應：

• 開燈與關燈 (/ledon, /ledoff)

  C++

  if (text == "/ledon") {
    digitalWrite(ledPin, HIGH); // 輸出高電位，點亮 LED
    ledStatus = 1;              // 記錄狀態
    bot.sendMessage(chat_id, "Led is ON", ""); // 回報訊息
  }
  

• 查詢狀態 (/status)

  C++

  if (text == "/status") {
    // 根據 ledStatus 變數判斷目前狀態並回報
    if (ledStatus) bot.sendMessage(chat_id, "Led is ON", "");
    else bot.sendMessage(chat_id, "Led is OFF", "");
  }
  

3. 自定義回覆鍵盤 (/options)

這是本程式最實用的部分，它讓控制變得直覺：

C++

if (text == "/options") {
  // 定義鍵盤佈局：第一排兩個按鈕，第二排一個按鈕
  String keyboardJson = "[[\"/ledon\", \"/ledoff\"],[\"/status\"]]";
  
  // 傳送鍵盤，最後一個參數 true 代表點擊後會自動縮回鍵盤
  bot.sendMessageWithReplyKeyboard(chat_id, "Choose from one of the following options", "", keyboardJson, true);
}

---

4. 初始化與硬體設定 (setup)

除了 WiFi 和時間同步，這裡多了一個關鍵步驟：

C++

pinMode(ledPin, OUTPUT);    // 將 LED 引腳設定為輸出模式
digitalWrite(ledPin, HIGH); // 初始化狀態（注意：有些板子 HIGH 是關燈，視硬體配置而定）

---

5. 功能比較：Inline vs Reply Keyboard

特性	內嵌鍵盤 (Inline - 前一個範例)	回覆鍵盤 (Reply - 本範例)
位置	附著在特定訊息下方	取代手機原本的輸入法區域
操作	點擊後發送隱藏資料 (Callback)	點擊後等同於「幫使用者打字」發送
外觀	較精美，適合單次操作	較醒目，適合持續性的選單控制

---

程式運作流程總結

1. 啟動：ESP32 連接 WiFi，同步時間，並準備好 GPIO 2 控制權。

2. 等待：每秒檢查一次 Telegram 訊息。

3. 互動：

   • 使用者輸入 /start 看到說明。

   • 使用者輸入 /options 彈出「按鈕選單」。

   • 點選按鈕時，手機自動發出 /ledon 等指令。

   • ESP32 接收指令後，切換 LED 正負極電壓，並回傳結果。