A telegram-bot project to control an ESP32-Camera enabled board with many features.
Send Photo through telegram upon request.
Control camera options through Telegram Keyboard
Control camera resolution Inline keyboard:
View options through Telegram
Web interface
toggle flash when taking a photo : For the AI_Thinker board, there is a very strong led on the same side as camera, which could be used as a flash. This feature Will only be compiled in the sketch if the "#define CAMERA_MODEL_AI_THINKER" is chosen upon compile.
PIR motion detection : For the TTGO_TI board, there is a motion sensor , which could trigger a "sendPhoto". This will only be available when the sketch is compiled with "#define CAMERA_MODEL_TTGO_T1_CAMERA".
toggle Display : For the TTGO_TI board, there is a SSD1306 OLED display, which could display AutoConnect - AP , IP when connected and used as a weak-flash when taking a photo. This will only be available when the sketch is compiled with "#define CAMERA_MODEL_TTGO_T1_CAMERA". also you could flip the screen upside-down.
Save photos to SD as a configurable feature. file name by date-time.
Library | Version |
---|---|
ESP32 board libs (in the board manager) | 1.0.6 |
UniversalTelegramBot | 1.3.0 |
ArduinoJson | 6.19.4 |
Adafruit GFX Library | 1.11.3 |
Adafruit BusIO | 1.14.1 |
Adafruit SSD1306 | 2.5.7 |
AutoConnect | 1.4.0 |
ESP Mail Client(Mobizt) | 2.7.0 |
Online, there are two URL's to be added to the Arduino Prefrences -> "Additional Board Managers URL"
Version 1.0.6 works fine from both sources. However, from version 2 upward (availbale only on the 2nd link), a lot of exceptions and stack traces appears.
I recommend using ESP32 Core Libs version 1.0.6 from this link: https://dl.espressif.com/dl/package_esp32_index.json
This project is Compiled and uploaded through ArduinoIDE, use the normal procedure for installing ESP32 in ArduinoIDE and install the following Libs:
Before uploading, chose the target ESP32-CAM Board :
in Teleview.ino:
// Select camera model
//#define CAMERA_MODEL_WROVER_KIT
//#define CAMERA_MODEL_ESP_EYE
//#define CAMERA_MODEL_M5STACK_PSRAM
//#define CAMERA_MODEL_M5STACK_WIDE
//#define CAMERA_MODEL_AI_THINKER // Board definition "AI Thinker ESP32-CAM"
#define CAMERA_MODEL_TTGO_T1_CAMERA // Board definition "TTGO T1"
The "camera_pins.h" has the speces of each board pins and also supported features such as OLED , Flash ..etc This code has been tested on CAMERA_MODEL_AI_THINKER and CAMERA_MODEL_TTGO_T1_CAMERA modules. please update the camera_pins.h for other boards and more features. For the CAMERA_MODEL_TTGO_T1_CAMERA borad, please chose the "TTGO T1" and and set Tools-> Partiton Scheme --> Huge App (3MB No OTA/1MB SPIFF)
For example: in "camera_pins.h" inside the section "#elif defined(CAMERA_MODEL_TTGO_T1_CAMERA)", you will find these precompilers:
Also a section exists if an Active Buzzer is connected which is triggered with the motion detection.
These precompiler defines, are used upon compilation to utilize or ommit parts of the code depending on the features of the board.
This sektch uses the Autoconnect Arduino library (https://github.com/Hieromon/AutoConnect) to let the user configure WiFi SSID and Password at runtime. When the sketch starts, it looks for a familiar WiFi. If it can't find one, it will start its own Access Point where the owner can connect and configure the WIFI.
First Time installtion: SSID will be "TeleView" with the password "tv-ei-694"
The AutoConnect library will start a portal with the page /config to configure the Wifi and other configuration parameters.
After a scucessfull Wifi connection, the same portal interface will be exposed to the local Wifi. The borad couled be reached on the LAN through the address "{{The Device Name}}.local"
The default Device Name is Teleview and the address would be:
A Telegram-bot-token is required to use the Telegrambot feature. You may follow these instructions to get a Telegram Bot Token through the @botFather. https://docs.microsoft.com/en-us/azure/bot-service/bot-service-channel-connect-telegram?view=azure-bot-service-4.0
Q) If you are a family and would like to have two or more people access and manage the Telegram bot. how can this be preformed? Q) if I have multiple Bots and want to controll all of them from one chat group ?
Answer-A) Use the Admin_id and User_id for the second user. However, remember that following events are sent only to the chat with the Admin_id:
Answer-B)
this is cool, you shoul really try it ! Using Telegram Groups: 1) Create a Telegram group. Let us call it MyCameraBotGroup. 2) The MyCameraBotGroup has now only you as an administrator. 3) Add the bot(s) you want in that group and make them admins. 4) Add your other family members in that group as well and make them admins (if you want them to also send commands). 5) Edit the rights of the Bots and Members as you please. 6) type /start in the MyCameraBotGroup group. 7) the bot(s) will respond with the chat ID of the MyCameraBotGroup (notice the chat_id of the group has a negative number) for example ('' from -1234567890..) 8) Now go to the WebUI and put the chat_id of the group (don't forget the negative sign) in the "Admin Chat ID" textbox. 9) Now anyone in that group can request a photo with /sendPhoto and other options as the same when using a single user. 10) All "I am Alive!" events, Motion Detection and time lapse activities will be sent to that group as well.
As far as I tested, this also works as a way to manage multiple boards at the same time. However you will not be able to figuire out which board is sending the "photo" , "I am Alive!" ,options or "motion detected" events.
Most of the buttons in the telegram Keyboard are on/off options.
Feature | Description |
---|---|
/start | Press this on the first time you use the bot , it will show some helpful info. |
/options | Will show the current status of the differnt options and flags. |
/sendPhoto | Sends a photo to the requester. |
/vFlip | Flips the camera-image upside down. |
/hmirror | Mirror the camera-image . (unfortunately; there is no 90 degrees rotate ) |
/setLapse | It will ask to insert the lapse time in minutes. insert 0 to disbale, 60 for every 1 Hour, 1440 for once a day ...etc |
/webCaptureOn | This will disbale/enable the ./capture and ./capture.jpg urls. |
Will only be shown in TTGO_T1 : (or when an old display is enabled in camera_pins.h) Feature | Description |
---|---|
/screenOn | Use the screen to display useful information or switch it off. |
/screenFlip | Flips the screen upside down. |
/motDetectOn | Will enable/disable PIR motion detection feature. |
Will only be shown when an OLED or Flash led available: (or when enabled in camera_pins.h) Feature | Description |
---|---|
/useFlash | will enable/disbale using the flash upon a camera snapshot. |
Other Custome Fatures: Feature | Description |
---|---|
/saveToSD | Save Every photo taken to an SD as well as send it to telegram |
/useBuzzer | Trigger Buzzer whne motion is detected. |
Other Generic Fatures: Feature | Description |
---|---|
/useDeepSleep | Goto Deep sleep between timelapse ticks and PIR motion detection |
/motionDetectVC | Use Computer Vision (CV) for motion dection |
/alertALL | Alert both Admin Id and Chat ID |
/sendEmail | sends emails to up to 2 emails (with Photo) |
1) IN ESP32-CAM AI Thinker the Buzzer and PIR are usually connected to PIN 12 and 13 which are also used for the SD card communication. so please pay attention in case you have issues afterwards. 2) PIR PIN could be connected to other sensors. Example: a reed switch ( door opening) , a button , a laser tripwire ..etc 3) Buzzer PIN could be connected to any other External Alert. Example: a siren , a water pistol , a nerf gun ..etc
Deep sleep will be only utilized if one of those options is enabled: 1) PIR motion detection 2) time-lapse
Deep Sleep puts the ESP into sleep mode. so don't expect it to respond to any of your Telegram commands during its sleep. Deep Sleep will not play well with those features: 1) CV motion detection , since it uses the Camera and the microcontroller to make constant checks of the frame changes. 2) WebCapture for the obvious reasons.
if it happens you put the ESP into Deep sleep and somehow you chnaged your mind, then follow these steps: 1) issue the command "/setLapse" by typing it or clicking the button. 2) restart your ESP from the physical button on the board or by disconnecting and then connecting it again.
This root home page displays a preview of the camera and some basis info. The cog-wheel icon is a link to the AutoConnect portal.
The Autoconnect portal configures the WiFi access and has a link to the bot's configuration page "./teleView". It has the following elements:
Please note the below list is not exahustive.
UI Control | Description |
---|---|
Device Name | The name of the device , this will be used as a DNS entry in the local LAN and identifying the device. |
Lapse Time-min | Every X min , the board will send a photo to the admin. set this to 0 to disbale time-lapsing feature. |
Telegram Bot Token | This is the token you get from the BotFather. |
Admin Chat ID | Telegram commands will only be processed if the Chat_id of the incomming Message is the same as this Admin_id or User_id ( a Security feature ). This could be chat_id of a Person or a Group where the bot is registered as admin. |
User Chat ID | a second chat_id for controlling Teleview .Motion detection , time lapse and "I am Alive!" message will only be addressed to the AdminID. This could be chat_id of a Person or a Group where the bot is registered as admin. |
Checkbox | Description |
---|---|
Use Falsh when snapping a photo | Enable/Disable using the flash when capturing a photo. |
Horizontal Mirror | Horizontal Mirror effect on the captured image (left-right). |
Vertical Flip | Upside down effect on the Captured image. |
Screen Flip | Upside down of the OLED display. |
OLED Display is On | Enable/Disable The OLED display. |
Motion Detection Enabled | Enable/Disable the Motion Detection Feature. |
...
ComboBoxes | Description |
---|---|
Select TZ name | Select the Time Zone region (currently used for naming files stored on SD card) |
Select Resolution | Select the Camera Resolution. (never use the QXGA) |
Buttons | Description |
---|---|
OK | Submit and Save the configuration. |
Delete Everything | Deletes all configuration data. except Wifi credentials. |
Cancel | Go back to AutoConnect Portal without saving. |
In The configuration Page, you can set up the email sending feature through SMTP server. I do not recommend to sed emails from your mail email account, rather create a new email account dedicated for sending photos only. the password is stored plain text in the flash.
Example: Gmail SMTP Server Settings If you’re using a Gmail account, these are the SMTP Server details:
SMTP Server: smtp.gmail.com SMTP username: Complete Gmail address SMTP password: Your Gmail password SMTP port (TLS): 587 SMTP port (SSL): 465 SMTP TLS/SSL required: yes
Outlook SMTP Server Settings For Outlook accounts, these are the SMTP Server settings:
SMTP Server: smtp.office365.com SMTP Username: Complete Outlook email address SMTP Password: Your Outlook password SMTP Port: 587 SMTP TLS/SSL Required: Yes Live or Hotmail SMTP Server Settings For Live or Hotmail accounts, these are the SMTP Server settings:
SMTP Server: smtp.live.com SMTP Username: Complete Live/Hotmail email address SMTP Password: Your Windows Live Hotmail password SMTP Port: 587 SMTP TLS/SSL Required: Yes
this is an experimental feature, and I could use some help testing and refining it. I have been looking around for a mature library online for the ESP32 that is flexible and expandable in the CAM boards that it supports. But unfortunately, I couldn't find anything I could use. so I hade to build a simple-toy-algorithm in motionDetect.h by my self.
- It works by:
- taking two consequetive GRAYSCAL 320x240 frame captures.
- counts the number of BLACK, WHITE , GRAY pixels in each frame.
- Black Pixels have teh value of 0 to 85
- White Pixels have the value of 255-85 to 255
- the Gray Pixels have the value of 85 to 255-85
- Compare the number of BLACK, WHITE, GRAY Pixesl, and if there is difference of more than XX % percent to the total count of pixels between the frames, then an alert is triggered.
- So far, there are two control parameters that are configurable through the WebUI:
- The Interval between the two consequetive frame captures in ms (i.e. 500 = half a second)
- The percentage of change in previous frame pixels and current frame pixels.
- One important use I could have; is to identify day and night and decide whether asnapshot should be taken or not during using the timelapse features. (not yet implemented)
There are three enpoints for jpeg capture and streaming.
It is highly recommended NOT to contact the ESP with more than one client at the same time.
This will stream in MJPEG as fast as it can. However, it will check for the telegram events every 25 frames which will make it a bit choppy. The code will auotmatically stop of the client is closed (once you close the browser tab or move to a another endpoint)
Content-Type: multipart/x-mixed-replace;boundary=...
The CV motion detection will produce alot of false events during the streaming. I recomend to deactivate CVMotionDetect feature during streaming.
will send a jpeg with the header: ( the picture will be displayed directly in the brwoser )
Content-Disposition:inline; filename=capture.jpg
will send a jpeg with the header: (as an attachement or downloadable file)
Content-Disposition:attachment; filename=capture.jpg