english readme

Author: GyverLibs

README_EN.md

@@ -23,12 +23,12 @@ Use the [CharDisplay] library(https://github.com/GyverLibs/CharDisplay) to displ
 ESP8266 (SDK v2.6+), ESP32
 
 ## Documentation and projects
-Detailed tutorials on working with the Telegram bot using this library can be found on the [GyverKIT Arduino website] (https://kit.alexgyver.ru/tutorials-category/telegram/)
+Detailed tutorials on working with the Telegram bot using this library can be found on the [GyverKIT Arduino site] (https://kit.alexgyver.ru/tutorials-category/telegram/)
 
 ## Comparison with Universal-Arduino-Telegram-Bot
 [Universal-Arduino-Telegram-Bot](https://github.com/witnessmenow/Universal-Arduino-Telegram-Bot)
 
-For comparison, we used a minimal example with sending a message to the chat and outputting incoming messages to the series:
+For comparison, a minimal example was used with sending a message to the chat and outputting incoming messages to the series:
 - **send** - send a message to the chat
 - **update** - check incoming messages
 - **free heap** - amount of free RAM while the program is running
@@ -39,8 +39,12 @@ For comparison, we used a minimal example with sending a message to the chat and
 | fastbot | 393220 | 28036 | 70 | 70 | 37552 |
 | diff | 6784 | 1812 | 1930 | 1830 | 1040 |
 
-- FastBot is lighter by almost 7 kB of Flash and 2 kB of SRAM, but takes up 1 kB of SRAM more while the program is running. Total lighter by 2-1 = 1 kB of SRAM.
+- FastBot is almost 7kB lighter than Flash and 2kB SRAM, but takes up 1kB more SRAM while the program is running. Total lighter by 2-1 = 1 kB of SRAM.
 - FastBot processes chat and sends messages much faster (by 2 seconds) due to manual parsing of the server response and statically allocated HTTP clients
+- The test was carried out in the normal mode of operation of FastBot. When `FB_DYNAMIC` is activated, the library will take 10kb less memory, but it will work slower:
+  - Free heap: 48000 kB
+  - Sending a message: 1 second
+  - Update request: 1 second
 
 ## Content
 - [Install](#install)
@@ -68,17 +72,22 @@ For comparison, we used a minimal example with sending a message to the chat and
 - [Bugs and feedback](#feedback)
 
 <a id="install"></a>
-## Installation
+## Installedcranberry vka
 - The library can be found by the name **FastBot** and installed through the library manager in:
     - Arduino IDE
     - Arduino IDE v2
     - PlatformIO
 - [Download library](https://github.com/GyverLibs/FastBot/archive/refs/heads/main.zip) .zip archive for manual installation:
     - Unzip and put in *C:\Program Files (x86)\Arduino\libraries* (Windows x64)
-    - Unpack and putin *C:\Program Files\Arduino\libraries* (Windows x32)
+    - Unzip and put in *C:\Program Files\Arduino\libraries* (Windows x32)
     - Unpack and put in *Documents/Arduino/libraries/*
     - (Arduino IDE) automatic installation from .zip: *Sketch/Include library/Add .ZIP library…* and specify the downloaded archive
 - Read more detailed instructions for installing libraries [here] (https://alexgyver.ru/arduino-first/#%D0%A3%D1%81%D1%82%D0%B0%D0%BD%D0%BE% D0%B2%D0%BA%D0%B0_%D0%B1%D0%B8%D0%B1%D0%BB%D0%B8%D0%BE%D1%82%D0%B5%D0%BA)
+### Update
+- I recommend always updating the library: new versions fix errors and bugs, as well as optimize and add new features
+- Through the IDE library manager: find the library as during installation and click "Update"
+- Manually: **delete the folder with the old version**, and then put the new one in its place. "Replacement" cannot be done: sometimes new versions delete files that remain after replacement and can lead to errors!
+
 
 <a id="init"></a>
 ## Initialization
@@ -157,7 +166,7 @@ uint8_t closeMenu();
 uint8_t closeMenu(String id);
 
 
-// ======== REGULAR MENU WITH TEXTOM =========
+// ======== REGULAR MENU WITH TEXT =========
 // message (msg) + show menu (menu) in the chat/chats specified in setChatID OR pass the id of the chat/chats
 uint8_t showMenuText(String msg, String menu);
 uint8_t showMenuText(String msg, String menu, String id);
@@ -227,7 +236,7 @@ int32_t lastBotMsg(); // ID of the last message sent by the bot
 int32_t lastUsrMsg(); // ID of the last message sent by the user
 String chatIDs; // the string specified in setChatID, for debugging and editing the list
 
-uint8_t sendRequest(String&req); // send request (https://api.telegram.org/bot...)
+uint8_t sendRequest(String&req); // send request(https://api.telegram.org/bot...)
 void autoIncrement(boolean incr); // auto increment messages (enabled by default)
 void incrementID(uint8_tval); // manually increment ID by val
 
@@ -245,7 +254,8 @@ bool& edited; // message edited
 bool isBot; // message from bot
 bool OTA; // request for OTA update
 uint32_t unix; // message time
-String toString(); // all information in one line
+String&fileName; // File name
+String&replyText; // response text, if any
 
 
 // ================ TIME =================
@@ -290,6 +300,7 @@ String FB_64str(int64_t id); // transfer from int64_t to String
 #define FB_NO_UNICODE // disable Unicode conversion for incoming messages (slightly speed up the program)
 #define FB_NO_URLENCODE // disable urlencode conversion for outgoing messages (slightly speeds up the program)
 #define FB_NO_OTA // disable support for OTA updates from chat
+#define FB_DYNAMIC // enable dynamic mode: the library takes longer to execute the request, but takes up 10 kb less memory in SRAM
 ```
 
 <a id="usage"></a>
@@ -318,64 +329,67 @@ bot.sendMessage("Hello!", "112233"); // will go to "112233"
 Telegram sets the following limits on **sending** messages by the bot ([documentation](https://core.telegram.org/bots/faq#my-bot-is-hitting-limits-how-do-i-avoid-this ))
 - To chat: no more than once per second. *You can send more often, but the message may not reach*
 - To a group: no more than 20 messages per minute
-- Total limit: no more than 30 messages per second
+- Total limit: no more than 30 messages per secondКлюква ду
 
-The bot can also read messages that are less than 24 hours old.
+Также бот может читать сообщения, с момента отправки которых прошло меньше 24 часов.
 
 <a id="inbox"></a>
-## Message parsing
-Messages are automatically requested and read in `tick()`, when a new message arrives, the specified handler function is called:
-- Create our own function in the sketch like `void function(FB_msg& message)`
-- Call `attach(function)`
-- This function will be automatically called on an incoming message if the chat ID matches or is not configured
-- If the handler is not connected - messages will not be checked
-- Inside this function, you can use the passed variable `message`, which has the type `FB_msg` (structure) and contains:
-    - `String userID` - user ID
-    - `String username` - user or channel name
-    - `String chatID` - chat ID
-    - `int32_t messageID` - message ID in the chat
-    - `String text` - message text or file caption
-    - `String data` - callback data from the menu (if any)- `bool query` - query
-    - `bool edited` - message has been edited
-    - `bool isBot` - message from bot
-    - `bool OTA` - request for OTA update (received .bin file)
-    - `uint32_t unix` - message time
-    - `String fileName` - file name
-    - `String toString()` - all information from the message, convenient for debugging (since 2.11)
-
-**Notes:**
-- Telegram splits the text into several messages if the text length exceeds ~4000 characters! These messages will have a different messageID in the chat.
-- When replying to a message, the library parses the text of the original message, not the answer
-
-### White list
-The library implements a white list mechanism: you can specify in `setChatID()` the ID of a chat (or several, separated by commas), messages from which will be accepted.
-Messages from other chats will be ignored.
+## Парсинг сообщений
+Сообщения автоматически запрашиваются и читаются в `tick()`, при поступлении нового сообщения вызывается указанная функция-обработчик:
+- Создаём в скетче свою функцию вида `void функция(FB_msg& сообщение)`
+- Вызываем `attach(функция)`
+- Эта функция будет автоматически вызвана при входящем сообщении, если ID чата совпадает или не настроен
+- Если обработчик не подключен - сообщения не будут проверяться
+- Внутри этой функции можно пользоваться переданной переменной `сообщение`, которая имеет тип `FB_msg` (структура) и содержит в себе:
+    - `String userID` - ID пользователя
+    - `String username` - имя пользователя или канала
+    - `String chatID` - ID чата
+    - `int32_t messageID` - ID сообщения в чате
+    - `String text` - текст сообщения или попдпись к файлу
+    - `String replyText` - текст ответа, если он есть
+    - `String data` - callback данные из меню (если есть)
+    - `bool query` - запрос
+    - `bool edited` - сообщение отредактировано
+    - `bool isBot` - сообщение от бота
+    - `bool OTA` - запрос на OTA обновление (получен .bin файл)
+    - `uint32_t unix` - время сообщения
+    - `String fileName` - имя файла
+
+А также `String toString()` - вся информация из сообщения, удобно для отладки (с версии 2.11)
+
+**Примечания:**
+- Телеграм разделяет текст на несколько сообщений, если длина текста превышает ~4000 символов! Эти сообщения будут иметь разный messageID в чате.
+- При ответе на сообщение библиотека парсит текст исходного сообщения, а не ответа
+
+### Белый список
+В библиотеке реализован механизм белого списка: можно указать в `setChatID()` ID чата (или нескольких через запятую), сообщения из которого будут приниматься. 
+Сообщения из остальных чатов будут игнорироваться.
 
 <a id="tick"></a>
-## Ticker
-To poll incoming messages, you need to connect a message handler and call `tick()` in the main loop of the program `loop()`, polling occurs according to the built-in timer.
-By default, the polling period is set to 3600 milliseconds.
+## Тикер
+Для опроса входящих сообщений нужно подключить обработчик сообщений и вызывать `tick()` в главном цикле программы `loop()`, опрос происходит по встроенному таймеру. 
+По умолчанию период опроса установлен 3600 миллисекунд.
 
-You can poll more often (change the period via `setPeriod()`), but personally, since ~ 2021, the Telegram server has not responded
-sooner than ~3 seconds later. If you request updates more often than this period, the program hangs inside a `tick()` (inside a GET request)
-waiting for the server response for the remainder of 3 seconds. With a period of ~3600 ms this does not happen, so I made it the default.
-Maybe it depends on the provider or the country.
+Можно опрашивать чаще (сменить период через `setPeriod()`), но лично у меня с ~2021 года сервер Телеграм стал отвечать не 
+раньше, чем через ~3 секунды. Если запрашивать обновления чаще этого периода, программа зависает внутри `tick()` (внутри GET запроса) 
+в ожидании ответа сервера на остаток от 3 секунд. При периоде ~3600 мс этого не происходит, поэтому я сделал его по умолчанию. 
+Возможно это зависит от провайдера или страны.
 
 <a id="example"></a>
-## Minimal example
+## Минимальный пример
 ```cpp
 void setup() {
-  // connect to WiFi
-  bot.attach(newMsg); // connect the message handler
+  // подключаемся к WiFi
+  bot.attach(newMsg);   // подключаем обработчик сообщений
 }
 
 void newMsg(FB_msg& msg) {
-  // display the username and message text
+  // выводим имя юзера и текст сообщения
   //Serial.print(msg.username);
   //Serial.print(", ");
   //Serial.println(msg.text);
 
-  // output all information about the message
+  // выводим всю информацию о сообщении
   Serial.println(msg.toString());
 }
 
@@ -385,29 +399,29 @@ void loop() {
 ```
 
 <a id="msgid"></a>
-## Accessing messages
-To edit and delete messages and menus, as well as pin messages, you need to know the message ID (its number in the chat):
-- ID of the incoming message is sent to the incoming message handler
-- Last received message ID can be obtained from `lastUsrMsg()`
-- The ID of the last message sent by the bot can be obtained from `lastBotMsg()`
+## Обращение к сообщениям
+Для редактирования и удаления сообщений и меню, а также закрепления сообщений, нужно знать ID сообщения (его номер в чате):
+- ID входящего сообщения приходит в обработчик входящих сообщений
+- ID последнего принятого сообщения можно получить из `lastUsrMsg()`
+- ID последнего отправленного ботом сообщения можно получить из `lastBotMsg()`
 
-Be careful with the chat ID, all chats have their own message numbering!
+Будьте внимательны с ID чата, у всех чатов своя нумерация сообщений!
 
 <a id="sticker"></a>
-## Send stickers
-To send a sticker, you need to know the sticker ID. Send the desired sticker to the *@idstickerbot* bot, it will send the sticker ID.
-This ID must be passed to the `sendSticker()` function.
+## Отправка стикеров
+Для отправки стикера нужно знать ID стикера. Отправь нужный стикер боту *@idstickerbot*, он пришлёт ID стикера. 
+Этот ID нужно передать в функцию `sendSticker()`.
 
 <a id="menu"></a>
-## Menu
-> Note: for all menu options *not produced* url encode. Avoid the `#` and `&` characters, or use an already encoded url!
+## Меню
+> Примечание: для всех вариантов меню *не производится* url encode. Избегайте символов `#` и `&` или используйте уже закодированный url!
 
-To send the menu, a string with button names and special formatting is used:
-- `\t` - horizontal separation of buttons
-- `\n` - vertical separation of buttons
-- Extra spaces are cut automatically
+Для отправки меню используется строка с именами кнопок и специальным форматированием:
+- `\t` - горизонтальное разделение кнопок
+- `\n` - вертикальное разделение кнопок
+- Лишние пробелы вырезаются автоматически
 
-3x1 menu example: `"Menu1 \t Menu2 \t Menu3 \n Menu4"`
+Пример меню 3x1: `"Menu1 \t Menu2 \t Menu3 \n Menu4"`
 
 Result:
 ```cpp
@@ -442,7 +456,7 @@ Menu in the message. Allows you to set a unique text for each button, which will
 The list of callbacks is listed separated by commas in the order of the menu buttons:
 ```cpp
 String menu1 = F("Menu 1 \t Menu 2 \t Menu 3 \n Back");
-String cback1 = F("action1,acaction2,action3,back");
+String cback1 = F("action1,action2,action3,back");
 bot.inlineMenuCallback("Menu 1", menu1, cback1);
 ```
 Clicking the button sends the menu name (the `text` message field) and the specified data (the `data` message field).
@@ -522,8 +536,8 @@ library and **count continues on** using standard time functions. Thus, it is en
 message after the board is turned on, so that the library synchronizes the clock. The time will also be synchronized on further sendings.
 and to be specified, because the time calculated by means of esp will go away (~ 2 seconds per day). Tools:
 
-- `uint32_t getUnix()` - returns the current time in unix format, or `0` if the time is out of sync.
-- `bool timeSynced()` - will return `true` if the clock is synchronized.
+- `uint32_t getUnix()` - returns the current time in unix format or `0` if the time is out of sync.
+- `booltimeSynced()` - will return `true` if clocks are synchronized.
 - `FB_Time getTime(gmt)` - you need to pass your time zone, it will return `FB_Time`.
 
 Thus, there are two ways to get the time (see the timeTest example):
@@ -546,7 +560,7 @@ Since version 2.13 of the library, a firmware update has appeared "over the air"
 - After a successful update, the esp will reboot
 
 ```cpp
-// update if justsent bin file
+// update if just sent a bin file
 if (msg.OTA) bot.update();
 
 // update if the file has the desired signature
@@ -630,7 +644,7 @@ void loop() {
 - v2.1:
     - More optimization
     - Added text formatting (markdown, html)
-    - Added a reply to the message
+    -Added a reply to a post
 
 - v2.2:
     - Big memory and performance optimizations
@@ -650,7 +664,7 @@ void loop() {
     - Callback data is now parsed separately in data
     - Redesigned work with callback
     - Added toString() for FB_msg for debugging
-    - Processing added to callbackcranberry url addresses
+    - Added processing of url addresses in callback
     - Removed first_name and last_name (preserving legacy)
     - usrID and ID renamed to userID and messageID (preserving legacy)
     - Completely removed the old incoming message handler
@@ -660,8 +674,20 @@ void loop() {
 - v2.14: Improved ID string parsing, added OTA disable, added group/channel name parsing to username
 - v2.15: ESP32 library curve patch
 - v2.16: added fileName output, fixed unsent messages in Markdown mode
+- v2.17: displaying the text of the message to which the user replied + correct work with menu in groups
+- v2.17.1: minor fix https://github.com/GyverLibs/FastBot/issues/12
+- v2.18: added FB_DYNAMIC mode: the library takes longer to execute a request, but takes up 10 kb less memory in SRAM
 
 <a id="feedback"></a>
 ## Bugs and feedback
 When you find bugs, create an **Issue**, or better, immediately write to the mail [alex@alexgyver.ru](mailto:alex@alexgyver.ru)
-The library is open for revision and your **Pull Request**'s!
+The library is open for revision and your **Pull Request**'s!
+
+When reporting bugs or incorrect work of the library, it is necessary to indicate:
+- Library version
+- What MK is used
+- SDK version (for ESP)
+- Arduino IDE version
+- Whether built-in examples work correctly, which use functions and constructs that lead to a bug in your code
+- What code was loaded, what work was expected from it and how it works in reality
+- Ideally, attach the minimum code in which the bug is observed. Not a canvas of a thousand lines, but a minimal code