Skip to content

Commit 7a7740b

Browse files
witnessmenowwitnessmenow
committed
Updating documentation and adding 101 code
1 parent 5f7a3a6 commit 7a7740b

File tree

12 files changed

+611
-8
lines changed

12 files changed

+611
-8
lines changed

‎README.md

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,13 @@ Forked from [ESP8266-TelegramBot](https://github.com/Gianbacchio/ESP8266-Telegra
99

1010
This library provides an interface for [Telegram Bot API](https://core.telegram.org/bots/api).
1111

12-
It is possible to define your personal Bot, make it able to read and write messages, receive orders and report data collected from the field.
12+
Telegram is a instant messaging app that allows for the creation of bots. Bots can be configured to send and receive messages. This is useful for Arduino projects as you can receive updates from your project or issue it commands via your Telegram app.
13+
14+
As mentioned, this is a library forked from [one library](https://github.com/Gianbacchio/ESP8266-TelegramBot) and inspired by [another](https://github.com/CasaJasmina/TelegramBot-Library)
15+
16+
Each library only supported a single type of Arduino and had different features implemented. The only thing that needs to be different for each board is the actual sending of requests to Telegram so I thought a library that additional architectures or boards could be configured easily would be useful, although this springs to mind:
17+
18+
![alt text](https://imgs.xkcd.com/comics/standards.png "standards")
1319

1420

1521
## Installing
@@ -21,6 +27,15 @@ The downloaded code can be included as a new library into the IDE selecting the
2127
You also have to install the ArduinoJson library written by [Benoît Blanchon](https://github.com/bblanchon).
2228
Available [here](https://github.com/bblanchon/ArduinoJson).
2329

30+
If your board is ESP8266 (e.g. WeMos v2 Mini) based include the following:
31+
32+
#include <ESP8266TelegramBOT.h>
33+
34+
or if its 101 based include:
35+
36+
#include <101TelegramBOT.h>
37+
38+
*NOTE:* 101TelegramBOT has not been tested as I do not have a compatible board. If you can help please let me know!
2439

2540
## Getting started
2641

‎examples/101/CustomKeyboard/CustomKeyboard.ino

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
/*******************************************************************
2+
* An example of how to use a custom reply keyboard using *
3+
* 101TelegramBOT. *
4+
* *
5+
* written by Brian Lough *
6+
*******************************************************************/
7+
8+
#include <WiFi101.h>
9+
#include <101TelegramBOT.h>
10+
11+
12+
// Initialize Wifi connection to the router
13+
char ssid[] = "xxxxxxxxxxxxxxxxxxxxxx"; // your network SSID (name)
14+
char pass[] = "yyyyyyyy"; // your network key
15+
16+
17+
18+
const int ledPin = 13;
19+
20+
// Initialize Telegram BOT
21+
#define BOTtoken "XXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" // your Bot Token (Get off Botfather)
22+
23+
101TelegramBOT bot(BOTtoken);
24+
25+
int Bot_mtbs = 1000; //mean time between scan messages
26+
long Bot_lasttime; //last time messages' scan has been done
27+
int ledStatus = 0;
28+
29+
void handleNewMessages(int numNewMessages) {
30+
Serial.println("handleNewMessages");
31+
Serial.println(String(numNewMessages));
32+
for(int i=0; i<numNewMessages; i++) {
33+
String chat_id = String(bot.messages[i].chat_id);
34+
String text = bot.messages[i].text;
35+
if (text == "\/ledon") {
36+
digitalWrite(ledPin, HIGH); // turn the LED on (HIGH is the voltage level)
37+
ledStatus = 1;
38+
bot.sendMessage(chat_id, "Led is ON", "");
39+
}
40+
if (text == "\/ledoff") {
41+
ledStatus = 0;
42+
digitalWrite(ledPin, LOW); // turn the LED off (LOW is the voltage level)
43+
bot.sendMessage(chat_id, "Led is OFF", "");
44+
}
45+
if (text == "\/status") {
46+
if(ledStatus){
47+
bot.sendMessage(chat_id, "Led is ON", "");
48+
} else {
49+
bot.sendMessage(chat_id, "Led is OFF", "");
50+
}
51+
}
52+
if (text == "\/options") {
53+
StaticJsonBuffer<500> jsonBuffer;
54+
JsonObject& payload = jsonBuffer.createObject();
55+
payload["chat_id"] = chat_id;
56+
payload["text"] = "Choose from one of the following options";
57+
JsonObject& replyMarkup = payload.createNestedObject("reply_markup");
58+
59+
// Reply keyboard is an array of arrays.
60+
// Outer array represents rows
61+
// Inner arrays represents columns
62+
// This example "ledon" and "ledoff" are two buttons on the top row
63+
// and "status is a single button on the next row"
64+
StaticJsonBuffer<200> keyboardBuffer;
65+
char keyboardJson[] = "[[\"/ledon\", \"/ledoff\"],[\"/status\"]]";
66+
replyMarkup["keyboard"] = keyboardBuffer.parseArray(keyboardJson);
67+
replyMarkup["resize_keyboard"] = true;
68+
69+
bot.sendPostMessage(payload);
70+
}
71+
72+
if (text == "\/start") {
73+
String wellcome = "The custom keyboard example for ESP8266TelegramBot";
74+
String wellcome1 = "/ledon : to switch the Led ON";
75+
String wellcome2 = "/ledoff : to switch the Led OFF";
76+
String wellcome3 = "/status : Returns current status of LED";
77+
String wellcome4 = "/options : returns the custom keyboard";
78+
bot.sendMessage(chat_id, wellcome, "");
79+
bot.sendMessage(chat_id, wellcome1, "");
80+
bot.sendMessage(chat_id, wellcome2, "");
81+
bot.sendMessage(chat_id, wellcome3, "");
82+
bot.sendMessage(chat_id, wellcome4, "");
83+
}
84+
}
85+
}
86+
87+
88+
void setup() {
89+
Serial.begin(115200);
90+
delay(3000);
91+
92+
// attempt to connect to Wifi network:
93+
Serial.print("Connecting Wifi: ");
94+
Serial.println(ssid);
95+
while (WiFi.begin(ssid, pass) != WL_CONNECTED) {
96+
Serial.print(".");
97+
delay(500);
98+
}
99+
Serial.println("");
100+
Serial.println("WiFi connected");
101+
Serial.println("IP address: ");
102+
IPAddress ip = WiFi.localIP();
103+
Serial.println(ip);
104+
bot.begin(); // launch Bot functionalities
105+
pinMode(ledPin, OUTPUT); // initialize digital ledPin as an output.
106+
delay(10);
107+
digitalWrite(ledPin, HIGH); //initilase pin as off
108+
109+
}
110+
111+
112+
113+
void loop() {
114+
if (millis() > Bot_lasttime + Bot_mtbs) {
115+
116+
int numNewMessages = bot.getUpdates(bot.last_message_recived + 1);
117+
if(numNewMessages) {
118+
Serial.println("got response");
119+
handleNewMessages(numNewMessages);
120+
}
121+
Bot_lasttime = millis();
122+
}
123+
}

‎examples/101/CustomKeyboard/README.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
#101 - Custom Keyboard bot
2+
3+
This is an example of how to use custom reply keyboards using the 101TelegramBOT
4+
5+
The application will turn on and off an led based on commands received via telegram
6+
7+
NOTE: You will need to enter your SSID, password and bot Token for the example to work.
8+
9+
Application written by [Brian Lough](https://github.com/witnessmenow)
10+
11+
12+
13+
## License
14+
15+
You may copy, distribute and modify the software provided that modifications are described and licensed for free under [LGPL-3](http://www.gnu.org/licenses/lgpl-3.0.html). Derivatives works (including modifications or anything statically linked to the library) can only be redistributed under [LGPL-3](http://www.gnu.org/licenses/lgpl-3.0.html), but applications that use the library don't have to be.

‎examples/101/EchoBot/EchoBot.ino

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
/*******************************************************************
2+
* An example of bot that echos back any messages received *
3+
* using 101TelegramBOT. *
4+
* *
5+
* written by Giacarlo Bacchio (Gianbacchio on Github) *
6+
* adapted by Brian Lough *
7+
*******************************************************************/
8+
9+
10+
#include <WiFi101.h>
11+
#include <101TelegramBOT.h>
12+
13+
14+
// Initialize Wifi connection to the router
15+
char ssid[] = "xxxxxxxxxxxxxxxxxxxxxxxx"; // your network SSID (name)
16+
char password[] = "yyyyyyyyy"; // your network key
17+
18+
19+
20+
// Initialize Telegram BOT
21+
#define BOTtoken "XXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" // your Bot Token (Get off Botfather)
22+
101TelegramBOT bot(BOTtoken);
23+
24+
int Bot_mtbs = 1000; //mean time between scan messages
25+
long Bot_lasttime; //last time messages' scan has been done
26+
27+
28+
/********************************************
29+
* EchoMessages - function to Echo messages *
30+
********************************************/
31+
void Bot_EchoMessages(int numNewMessages) {
32+
for(int i=0; i<numNewMessages; i++) {
33+
bot.sendMessage(bot.messages[i].chat_id, bot.messages[i].text, "");
34+
}
35+
}
36+
37+
38+
void setup() {
39+
40+
Serial.begin(115200);
41+
delay(3000);
42+
43+
// attempt to connect to Wifi network:
44+
Serial.print("Connecting Wifi: ");
45+
Serial.println(ssid);
46+
while (WiFi.begin(ssid, pass) != WL_CONNECTED) {
47+
Serial.print(".");
48+
delay(500);
49+
}
50+
Serial.println("");
51+
Serial.println("WiFi connected");
52+
Serial.println("IP address: ");
53+
IPAddress ip = WiFi.localIP();
54+
Serial.println(ip);
55+
56+
bot.begin(); // launch Bot functionalities
57+
}
58+
59+
60+
61+
void loop() {
62+
63+
if (millis() > Bot_lasttime + Bot_mtbs) {
64+
int numNewMessages = bot.getUpdates(bot.last_message_recived + 1); // launch API GetUpdates up to xxx message
65+
if(numNewMessages) {
66+
Serial.println("got response");
67+
Bot_EchoMessages(numNewMessages); // reply to message with Echo
68+
}
69+
Bot_lasttime = millis();
70+
}
71+
}

‎examples/101/EchoBot/README.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
#101 - Echo Bot
2+
3+
This is a basic example of how to use 101TelegramBOT.
4+
5+
The application will echo an message it received back to the user.
6+
7+
NOTE: You will need to enter your SSID, password and bot Token for the example to work.
8+
9+
Application originally written by [Giancarlo Bacchio]([email protected]) for [ESP8266-TelegramBot library](https://github.com/Gianbacchio/ESP8266-TelegramBot)
10+
11+
Adapted by [Brian Lough](https://github.com/witnessmenow)
12+
13+
## License
14+
15+
You may copy, distribute and modify the software provided that modifications are described and licensed for free under [LGPL-3](http://www.gnu.org/licenses/lgpl-3.0.html). Derivatives works (including modifications or anything statically linked to the library) can only be redistributed under [LGPL-3](http://www.gnu.org/licenses/lgpl-3.0.html), but applications that use the library don't have to be.

‎examples/101/EchoBotWithPost/EchoBotWithPost.ino

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
/*******************************************************************
2+
* An example of bot that echos back any messages received *
3+
* using 101TelegramBOT. *
4+
* *
5+
* written by Brian Lough *
6+
*******************************************************************/
7+
8+
9+
#include <WiFi101.h>
10+
#include <101TelegramBOT.h>
11+
12+
13+
// Initialize Wifi connection to the router
14+
char ssid[] = "xxxxxxxxxxxxxxxxxxxxxxxx"; // your network SSID (name)
15+
char password[] = "yyyyyyyyy"; // your network key
16+
17+
18+
// Initialize Telegram BOT
19+
#define BOTtoken "XXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" // your Bot Token (Get off Botfather)
20+
101TelegramBOT bot(BOTtoken);
21+
22+
int Bot_mtbs = 1000; //mean time between scan messages
23+
long Bot_lasttime; //last time messages' scan has been done
24+
25+
26+
/********************************************
27+
* EchoMessages - function to Echo messages *
28+
********************************************/
29+
void Bot_EchoMessages(int numNewMessages) {
30+
for(int i=0; i<numNewMessages; i++) {
31+
StaticJsonBuffer<500> jsonBuffer;
32+
JsonObject& payload = jsonBuffer.createObject();
33+
payload["chat_id"] = bot.messages[i].chat_id;
34+
payload["text"] = bot.messages[i].text;
35+
bot.sendPostMessage(payload);
36+
}
37+
}
38+
39+
40+
void setup() {
41+
42+
Serial.begin(115200);
43+
delay(3000);
44+
45+
// attempt to connect to Wifi network:
46+
Serial.print("Connecting Wifi: ");
47+
Serial.println(ssid);
48+
while (WiFi.begin(ssid, pass) != WL_CONNECTED) {
49+
Serial.print(".");
50+
delay(500);
51+
}
52+
Serial.println("");
53+
Serial.println("WiFi connected");
54+
Serial.println("IP address: ");
55+
IPAddress ip = WiFi.localIP();
56+
Serial.println(ip);
57+
58+
bot.begin(); // launch Bot functionalities
59+
}
60+
61+
62+
63+
void loop() {
64+
65+
if (millis() > Bot_lasttime + Bot_mtbs) {
66+
int numNewMessages = bot.getUpdates(bot.last_message_recived + 1); // launch API GetUpdates up to xxx message
67+
if(numNewMessages) {
68+
Serial.println("got response");
69+
Bot_EchoMessages(numNewMessages); // reply to message with Echo
70+
}
71+
Bot_lasttime = millis();
72+
}
73+
}

‎examples/101/EchoBotWithPost/README.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
#101 - Echo Bot with post
2+
3+
This is a basic example of how to use sendPostMessage functionality of 101TelegramBOT.
4+
5+
sendPostMessage allows the more advanced options of the Telegram Api to be used (see CustomKeyboard example for how to use keyboards).
6+
7+
The application will echo an message it received back to the user.
8+
9+
NOTE: You will need to enter your SSID, password and bot Token for the example to work.
10+
11+
Adapted by [Brian Lough](https://github.com/witnessmenow)
12+
13+
## License
14+
15+
You may copy, distribute and modify the software provided that modifications are described and licensed for free under [LGPL-3](http://www.gnu.org/licenses/lgpl-3.0.html). Derivatives works (including modifications or anything statically linked to the library) can only be redistributed under [LGPL-3](http://www.gnu.org/licenses/lgpl-3.0.html), but applications that use the library don't have to be.

0 commit comments

Comments
 (0)