Telegram bot

[egueli]

Description

This PR adds preliminary support for sending captured videos to a Telegram channel via a bot.

Bot usage

First setup:

1. Create a new bot via the BotFather bot and the /newbot command. Then copy the HTTP API token.

2. Create a new private Telegram group. The bot will send all captured videos there.

3. Invite an ID bot like IDBot to the channel. It will join and leave immediately, then send you a message with the group ID.

4. Enter your MyNaturewatchCamera machine via SSH, and edit the configuration file:

   nano NaturewatchCameraServer/naturewatch_camera_server/static/data/config.json

   and add two more key-value pairs:

   "telegram_api_key": "<your HTTP API token>",
   "telegram_chat_id": <your group ID>

   Note that the first value is surrounded by quotes and the other is not.

5. Now restart the app with

   sudo systemctl restart python.naturewatch.service

   and check the logs

   journalctl -fu python.naturewatch.service

   If the line Telegram publisher started appears in the logs, the bot is running.

Remember to enable video capture in the webpage. Once a video is captured, after two minutes the bot will publish it on that Telegram group.

Implementation details

Once a video is captured, it is "shrunk" with ffmpeg and sent via Telegram API, i.e. decode the original video and re-encode with a lower bandwidth. Shrinking is needed because the original video files are a bit too large to be shared comfortably, and may cause timeouts with Telegram APIs.

The shrinking and sending take a couple minutes, so they're done on a separate thread to not starve the detection algorithm. If more videos are captured during shrinking, videos will be queued.

The code around ChangeDetector and FileSaver has been reworked a bit to use exceptions instead of returning None, and keep the detection running if something happens. This is needed to prevent publishing if e.g. there's no more free space.

Shrinking on Pi Zero

Video shrinking works differently if done on the Pi Zero. Because it has less CPU power, the encoding takes a bit too long (at least 15 minutes). So the hardware encoder is used instead, and the image size is smaller, bringing the shrink time to around 3 minutes (if also hardware decoding is enabled, see below). Alas the image quality is worse than with the software encoder, so the latter is used on a board with four CPU cores, like the Pi 3/4.

Using hardware video encoder

The shrinking process can make use of hardware decoding, to take less time. This is only available if the Pi is configured to reserve at least 192MB of RAM to the GPU. By default, only 128MB are reserved so the (slower) software decoding is used. See the Pi documentation to change the amount of RAM.

Unlike hardware encoding, hardware decoding doesn't seem to affect image quality.

TODO

Dear PR reviewers, please advice if you'd like to merge the PR as it is or you'd like any of the following to be present as well:

• [ ] Publish photos
• [ ] Telegram configuration in settings page

Type of change

• [ ] Bug fix (non-breaking change which fixes an issue)
• [x] New feature (non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
• [ ] This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration.

Tested on the following devices:

• [ ] Development environment (Linux, Windows, or MacOS)
• [x] Pi Zero W
• [x] Pi 3A+
• [ ] Pi 3B+
• [ ] Pi 4

Checklist:

• [x] I have performed a self-review of my own code
• [x] I have commented my code, particularly in hard-to-understand areas
• [ ] My changes generate no new warnings
• [ ] New and existing unit tests pass locally with my changes

[egueli]

I tested on a Pi Zero W and alas some videos aren't being sent. Will investigate, in the meantime I'll turn this into a draft.

[mikevanis]

Thanks @egueli for yet another contribution! I think people would love to see this on the forum - we can gauge if there's interest for others to use it. 🙌

[egueli]

I think I solved the issues on the Pi Zero, so I un-drafted this PR and updated the description.

[PhilipMcGaw]

Is there any movement on these being folded into the main repo?