Update README.md

Author: GyverLibs

README.md

@@ -1,4 +1,4 @@
-[![Foo](https://img.shields.io/badge/Version-2.12-brightgreen.svg?style=flat-square)](#versions)
+[![Foo](https://img.shields.io/badge/Version-2.13-brightgreen.svg?style=flat-square)](#versions)
 [![Foo](https://img.shields.io/badge/Website-AlexGyver.ru-blue.svg?style=flat-square)](https://alexgyver.ru/)
 [![Foo](https://img.shields.io/badge/%E2%82%BD$%E2%82%AC%20%D0%9D%D0%B0%20%D0%BF%D0%B8%D0%B2%D0%BE-%D1%81%20%D1%80%D1%8B%D0%B1%D0%BA%D0%BE%D0%B9-orange.svg?style=flat-square)](https://alexgyver.ru/support_alex/)
 
@@ -19,6 +19,7 @@
 - Поддержка Unicode (другие языки + эмодзи) для входящих сообщений
 - Встроенный urlencode для исходящих сообщений
 - Встроенные часы реального времени с синхронизацией от сервера Telegram
+- Возможность OTA обновления прошивки файлом из чата Telegram
 
 ### Совместимость
 ESP8266 (SDK v2.6+), ESP32
@@ -48,7 +49,21 @@ ESP8266 (SDK v2.6+), ESP32
 - [Инициализация](#init)
 - [Документация](#docs)
 - [Использование](#usage)
-- [Пример](#example)
+    - [ID чата/чатов](#chatid)
+    - [Парсинг сообщений](#inbox)
+    - [Тикер](#tick)
+    - [Минимальный пример](#example)
+    - [Обращение к сообщениям](#msgid)
+    - [Отправка стикеров](#sticker)
+    - [Меню](#menu)
+    - [Обычное меню](#basic)
+    - [Инлайн меню](#inline)
+    - [Инлайн меню с коллбэком](#callb)
+    - [Ответ на коллбэк](#answer)
+    - [Модуль времени](#unix)
+    - [Время получения сообщения](#time)
+    - [Часы реального времени](#rtc)
+    - [OTA обновление прошивки](#ota)
 - [Версии](#versions)
 - [Баги и обратная связь](#feedback)
 
@@ -67,9 +82,11 @@ ESP8266 (SDK v2.6+), ESP32
 
 <a id="init"></a>
 ## Инициализация
+- [Инструкция как создать и настроить Telegram бота](https://kit.alexgyver.ru/tutorials/telegram-basic/)
+
 ```cpp
 FastBot bot;
-FastBot bot(токен); // токен - уникальный код бота, берётся у BotFather
+FastBot bot(токен); // с указанием токена
 ```
 
 <a id="docs"></a>
@@ -235,7 +252,7 @@ String dateString();    // получить строку даты формата
 // Многие функции возвращают статус:
 // 0 - ожидание
 // 1 - ОК
-// 2 - Переполнен по ovf
+// 2 - Переполнен
 // 3 - Ошибка телеграм
 // 4 - Ошибка подключения
 // 5 - не задан chat ID
@@ -251,12 +268,15 @@ String dateString();    // получить строку даты формата
 
 <a id="usage"></a>
 ## Использование
+
+<a id="chatid"></a>
 ### ID чата/чатов
 В библиотеке реализован необязательный "белый список" ID чатов, в которых работает бот. По умолчанию отключен.
 - Устанавливается через `setChatID()`, куда можно передать одиночный ID или сразу несколько через запятую: `setChatID("id1,id2,id3")`
 - Можно редактировать строку `chatIDs` напрямую как член класса
 - Все функции отправки будут отправлять данные в заданный чат/чаты, если не указать его вручную в функции
 
+<a id="inbox"></a>
 ### Парсинг сообщений
 Сообщения автоматически читаются в `tick()`, при поступлении нового сообщения вызывается указанная функция-обработчик. Но тут есть варианты:
 - Если задан ID чата/чатов (через `setChatID()`) - происходит автоматическое отсеивание сообщений НЕ из указанных чатов
@@ -272,11 +292,12 @@ String dateString();    // получить строку даты формата
     - `String username` - имя пользователя (в API Telegram это first_name)
     - `String chatID` - ID чата
     - `int32_t messageID` - ID сообщения в чате
-    - `String text` - текст сообщения
+    - `String text` - текст сообщения или попдпись к файлу
     - `String data` - callback дата сообщения (если есть)
     - `bool query` - запрос
     - `bool edited` - сообщение отредактировано
     - `bool isBot` - сообщение от бота
+    - `bool OTA` - запрос на OTA обновление (получен .bin файл)
     - `uint32_t unix` - время сообщения
 
 С версии 2.11 добавлен метод `toString()`, позволяющий вывести строкой всё содержимое структуры
@@ -286,12 +307,14 @@ String dateString();    // получить строку даты формата
 
 > Примечание: Телеграм разделяет текст на несколько сообщений, если длина текста превышает ~4000 символов! Эти сообщения будут иметь разный ID в чате.
 
+<a id="tick"></a>
 ### Тикер
 Для опроса входящих сообщений нужно подключить обработчик сообщений и вызывать `tick()` в главном цикле программы `loop()`, опрос происходит по встроенному таймеру. 
 По умолчанию период опроса установлен 3600 миллисекунд. Можно опрашивать чаще (сменить через `setPeriod()`), но Телеграм иногда тупит и 
 при частом опросе запрос может выполняться ~3 секунды вместо 60 миллисекунд! На это время программа "зависает" внутри `tick()`. 
 При периоде ~3600 мс этого не происходит, поэтому я сделал его по умолчанию.
 
+<a id="example"></a>
 ### Минимальный пример
 ```cpp
 void setup() {
@@ -314,6 +337,7 @@ void loop() {
 }
 ```
 
+<a id="msgid"></a>
 ### Обращение к сообщениям
 Для редактирования и удаления сообщений и меню, а также закрепления сообщений, нужно знать ID сообщения.
 - ID входящего сообщения приходит в обработчик входящих сообщений
@@ -322,10 +346,12 @@ void loop() {
 
 Будьте внимательны с ID чата, у всех чатов своя нумерация ID сообщений!
 
+<a id="sticker"></a>
 ### Отправка стикеров
 Для отправки стикера нужно знать ID стикера. Отправь нужный стикер боту *@idstickerbot*, он пришлёт ID стикера. 
 Этот ID нужно передать в функцию `sendSticker()`.
 
+<a id="menu"></a>
 ### Меню
 > Примечание: для всех вариантов меню *не производится* url encode. Избегайте символов `#` и `&` или используйте уже закодированный url!
 
@@ -347,20 +373,23 @@ void loop() {
 |_______________________|
 ```
 
+<a id="basic"></a>
 ### Обычное меню
 Большое меню в нижней части чата.
 ```cpp
 showMenu("Menu1 \t Menu2 \t Menu3 \n Menu4");
 ```
 Нажатие на кнопку отправляет текст с кнопки (поле сообщения `text`).
 
+<a id="inline"></a>
 ### Инлайн меню
 Меню в сообщении. Требует ввода имени меню.
 ```cpp
 inlineMenu("MyMenu", "Menu1 \t Menu2 \t Menu3 \n Menu4");
 ```
 Нажатие на кнопку отправляет имя меню (поле сообщения `text`) и текст с кнопки (поле сообщения `data`).
 
+<a id="callb"></a>
 ### Инлайн меню с коллбэком
 Меню в сообщении. Позволяет задать каждой кнопке уникальный текст, который будет отправляться ботом вместе с именем меню. 
 Список коллбэков перечисляется через запятую по порядку кнопок меню:
@@ -372,6 +401,7 @@ bot.inlineMenuCallback("Menu 1", menu1, cback1);
 Нажатие на кнопку отправляет имя меню (поле сообщения `text`) и указанные данные (поле сообщения `data`).
 - (С версии 2.11) если callback задан как http/https адрес, кнопка автоматически станет **кнопкой-ссылкой**
 
+<a id="answer"></a>
 ### Ответ на коллбэк
 При нажатии на кнопку инлайн-меню боту отправляется коллбэк, в обработчике сообщения будет поднят флаг `query`. Сервер Телеграм будет ждать ответа. 
 Ответить на коллбэк можно при помощи:
@@ -387,6 +417,7 @@ void newMsg(FB_msg& msg) {
 
 > Если ничего не отвечать, библиотека сама отправит пустой ответ и "таймер" на кнопке исчезнет.
 
+<a id="unix"></a>
 ### Модуль времени
 В библиотеке есть тип данных `FB_Time`, который является структурой с полями:
 ```cpp
@@ -424,6 +455,7 @@ Serial.print(' ');
 Serial.println(t.dateString()); // ДД.ММ.ГГГГ
 ```
 
+<a id="time"></a>
 ### Время получения сообщения
 В обработчике входящих сообщений у структуры `FB_msg` есть поле `unix`, оно хранит время сообщения в unix формате. 
 Для перевода в более читаемый формат действуем по описанной выше схеме:
@@ -436,6 +468,7 @@ void newMsg(FB_msg& msg) {
 }
 ```
 
+<a id="rtc"></a>
 ### Часы реального времени
 В ответ на любое сообщение от бота сервер сообщает время отправки в формате unix. С версии 2.6 это время парсится 
 библиотекой и **счёт продолжается дальше** при помощи стандартных функций времени. Таким образом достаточно один раз отправить 
@@ -453,7 +486,29 @@ FB_Time t = bot.getTime(3);
 FB_Time t(bot.getUnix(), 3);
 ```
 
-<a id="example"></a>
+<a id="ota"></a>
+### OTA обновление прошивки
+С версии библиотеки 2.13 появилось обновление прошивки "по воздуху" (OTA) через чат. Для обновления нужно:
+- Скомпилировать программу в файл: *Arduino IDE/Скетч/Экспорт бинарного файла* (файл **.bin** появится в папке со скетчем)
+- Отправить файл в чат с ботом, можно добавить подпись
+- Файл будет обработан как обычное входящее сообщение от пользователя
+    - Подпись к файлу можно получить из поля `text`
+    - Будет поднят флаг `OTA`
+- Для запуска процесса обновления нужно вызвать `update` внутри обработчика сообщений
+- В тот же чат чат будет отправлен статус обновления (*OK* или *error*)
+- После успешного обновления esp перезагрузится
+
+```cpp
+// обновить, если просто прислали bin файл
+if (msg.OTA) bot.update();
+
+// обновить, если файл имеет нужную подпись
+if (msg.OTA && msg.text == "update") bot.update();
+
+// обновить, если прислал известный человек (админ)
+if (msg.OTA && msg.chatID == "123456") bot.update();
+```
+
 
 <a id="versions"></a>
 ## Версии
@@ -513,7 +568,8 @@ FB_Time t(bot.getUnix(), 3);
     - Окончательно убран старый обработчик входящих сообщений
 
 - v2.12: поправлены примеры, исправлен парсинг isBot, переделан механизм защиты от длинных сообщений, переделана инициализация
-    
+- v2.13: Оптимизация памяти. Добавил OTA обновление
+
 <a id="feedback"></a>
 ## Баги и обратная связь
 При нахождении багов создавайте **Issue**, а лучше сразу пишите на почту [alex@alexgyver.ru](mailto:alex@alexgyver.ru)