search

asmaklad / TeleView

A telegram photo sending bot using the ESP32 CAM on Arduino IDE.
GNU Lesser General Public License v2.1
21 stars 8 forks source link

readme

TeleView:

A telegram-bot project to control an ESP32-Camera enabled board with many features.

Generic Features:

Specific Features per Type of Board:

Tested Boards:

Required Installation:

Required Libraries:

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

A note about the ESP32 core Libraries:

Online, there are two URL's to be added to the Arduino Prefrences -> "Additional Board Managers URL"

  1. this one is the normal and mentioned everywhere : https://dl.espressif.com/dl/package_esp32_index.json this allows the installtion of ESP32 core up to 1.0.6 Teleview project uses The ESP32-CAM API 1.0.6 .
  2. this one which is mentioned by Espressif: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json . This one allows for more version, up to 2.0.3 (till the time of writing this). Also Allows ESP32-S2, S3 and C3 boards. Teleview project is not compatible The ESP32-CAM API beyond 1.0.6. Some how there are breaking changes introduced in 2.0.0 !

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

User Guide:

Compile and Upload

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"

Enabling Disabeling Features at compile time

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.

Setting up the WiFi:

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:

Setting up the Telegrambot:

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

OTA (it is there but doesnt work with all boards)

Having more than one user to use the bot:

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.

Having multiple boards to use the same bot token:

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.

The Telegram Keyboard

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)

A note about PIR motion Detection and Buzzer alerts:

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

A note about Deep Sleep:

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.

The Configuration Web interface

http://TeleView.local/

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.

http://TeleView.local/_ac

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.

Intput Text

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.

ComboBoxes:

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:

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.

Sending Emails

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

The computer Vision Motion Detection

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)

capture and streaming

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.

streaming : /streaming

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.

Capture as an image : /capture

will send a jpeg with the header: ( the picture will be displayed directly in the brwoser )

Content-Disposition:inline; filename=capture.jpg

Capture as an atatchment jpg file: /capture.jpg

will send a jpeg with the header: (as an attachement or downloadable file)

Content-Disposition:attachment; filename=capture.jpg