Cam Mail Intercept Plugin

Attention: work in progress, software not yet uploaded

Plugin that can be used for integrating surveillance systems, webcams and home automation systems into hangoutsbot. These systems will typically generate email notifications. This plugin acts as a simple local smtp relay and intercepts messages in order to insert them (and their attached pictures) in the hangouts conversation.

#Functions: This plugin provides several functions, but its most important merit is that it separates your internal home network from the Internet. No incoming flows into your home network need to be allowed on your firewall. No messing with NAT translations, ...

• Notification: intercept notification emails (like motion detection mails with attached snapshot image) and insert the notification and snapshot image in the conversation. Configure your cams or surveillance system to send their mail notifications to the smtp listener address and port of this plugin.
• Grab snapshots from cameras: typing the name of the camera in the conversation will let the plugin grab a new snapshot and insert it into the conversation
• Trigger actions: when connected to a domotics system, the plugin can send http/https messages to trigger actions on the domotics system. Currently we only support the PUT method, we believe POST methods should also be supported in the future
• Mail relay: some devices like printers, cams, scanners and routers may want to send out mail messages. It is considered dangerous to enter your gmail or other provider's credentials in these 'untrusted' devices. The plugin acts as a mail relay on your local network. Your devices can deliver their mail to the plugin's smtp interface without requiring credentials. The mails are then forwarded over the internet using your bot's gmail credentials. We recommend to create an app-specific password (part of Google's 2-factor authentication scheme).

This plugin has been tested only with a Synology Surveillance station, together with Apexis J233 webcams. It should however work with any system that generates email notifications. You can run the bot on the Synology system itself.

Limitations

• If there is an image attachment in the mail, only the subject of an email is inserted in a conversation (besides the image attachment). The rationale for this is that the systems that send messages send these in an automatic way, so the body of the mail does not add much value in most cases. A picture says more than a thousand words.
• Only basic authentication is supported for Cams, Domotics/Alarm systems
• HTTP/HTTPS communication is currently limited to GET requests. POST is currently not supported
• The current version only supports notification mails with exactly one image attachment.

User Commands

Taking a snapshot image from a connected cam is not done through a /bot command, but is part of the normal conversation. Just type the name of a camera as defined in camurlsat the beginning of a message(case insensitive).

backcam

/bot interceptCamMail

• Let the current conversation <convid> receive alarms from the surveillance system. ATTENTION: does not work in this version, configure the conversation id in config.jsonfor now.

Admin Commands

/bot chatreset [<optional conv id>]

• Removes an API instance for a supplied <conv id> or the current conversation, if it exists
• Effectively restarts a cleverbot conversation from a blank slate

Settings in config.json

SMTP communication credentials for forwarding to external provider on Internet. For Google, please consider the use of application-specific passwords (part of 2 factor authentication mechanism)

"extsmtpuser"       : "name_of_mybot@gmail.com"
"extsmtppwd"        : "botsmtppassword" # recommend to use an app password
"extsmtpserver"     : "smtp.gmail.com" (optional default value gmail server) 
"extsmtpport"       : "587" (optional, default value 587)

Plugin's internal SMTP listener address and port. Use the real address or name of the system on which the bot is installed instead of the loopback address in case the service needs to be reached from another system on your lan. If these parameters are missing, the hostname of your bot system will be used and the smtp service will run on port 10025:

"intsmtpaddress"    : "127.0.0.1" # (optional) default is your hostname
"intsmtpport"       : "10025"     # (optional) default "10025"

Conversation to which the plugin listens and to which notifications are sent:

"cammailcid"        : "Umyconversationid45dsseAQ"

Alarm (Domotics) system parameters. Alarmsysurl is the url that will be fetched to determine whether the alarm system is active or not. If the alarm system is not activated, alarm messages will not be inserted in the conversation. "alarmsysoffregexp" is the pattern that must be found in the reply in order to conclude that the alarm system is disabled. The "alarmsysusr" and "alarmsyspwd" credentials will be used in the GET request. These parameters are optional:

"alarmsysurl"       : "http://10.10.10.32/AlarmLoadedFlag"
"alarmsysoffregexp" : "value=\"0\""

Format of the mail subject (regexp and index in the regexp where the camera/location name can be found). In the exaple regexp below, the second word represents the location/camera name. The location/camera name is used as an index in the camurls dictionary:

"alarmsubjectformat": { "regexp": "(.*) (.*)( (.*))*", "locationindex": 2 }  # (optional) 

Url and credentials for notifying the domotics or alarm system <location> will be substituted by the camera (location) name:

"alarmnoturl"       : "http://10.10.10.32/%(location)s/pulse"
"alarmsysusr"       : "camera",
"alarmsyspwd"       : "mypassword",

Camera credentials for grabbing camera sapshots (assuming basic authentication):

"campwd"            : "myCAMpassword"
"camusr"            : "CAMdmin"

List of camera url's (also conversation keywords for grabbing live snapshots):

"camurls"           : { 'backcam'   : 'http://10.10.10.31:27116/snapshot.cgi',
                        'frontcam'  : 'http://10.10.10.33:27118/snapshot.cgi'
                      }

Startup script for Synology

If you decide to install hangoutsbot on a Synology station, install the python3 (and git) Synology package, follow the hangoutsbot's installation instructions, create a user 'botty' (or whatever name you want) and create a /etc/init/hangoutsbot.conf startup file with following content:

# only start this service after the httpd user process has started
start on started httpd-user

# stop the service gracefully if the runlevel changes to 'reboot'
stop on runlevel [06]

# run the scripts as the 'botty' (or a name of your choice) user. Running as root (the default) is a bad idea.
# you need to create this user first !
setuid botty

# exec the process. Use fully formed path names so that there is no reliance on $PATH
# the 'www' file is a node.js script which starts the foobar application.
exec /usr/bin/python3 /volume1/homes/botty/hangoutsbot/hangupsbot/hangupsbot.py

For debugging, it may be required to give this user a /bin/sh shell at login (e.g by editing /etc/passwd)