Bridge to convert motion detection email notifications from Hichip IPCams to MQTT messages.

Clone this repo:

Branches

  1. 7270556 Specify image size when uploading to Minio by avm99963 · 1 year, 2 months ago main
  2. 8355e00 Add functionality to upload images to S3 by avm99963 · 1 year, 4 months ago
  3. 308de8e Fix env.sample file syntax by avm99963 · 1 year, 4 months ago
  4. 6b0447c Change docker-compose version to 3.5 by avm99963 · 1 year, 4 months ago
  5. b33bc0c Remove overrideable Go-Guerrilla configuration by avm99963 · 1 year, 4 months ago

hichip2mqtt bridge

This program is a bridge to convert motion detection email notifications from the Hichip IP Cameras to MQTT messages. It runs continously as a daemon.

It is based in the Go-Guerilla SMTP server and a custom processor in order to process incoming emails, and in the Eclipse Paho MQTT client in order to interact with the MQTT broker to send the motion detected event details.

Overview

The bridge will receive email notifications from HiChip IP cameras directed to *@{HICHIPBRIDGE_SMTP_HOST}. Then, it will process each message received by checking whether the message's body contains a token, and after that it will publish the event as a MQTT message in the {HICHIPBRIDGE_MQTT_TOPIC}/{USERNAME}/motion topic, where {USERNAME} is the username part of the email address sending the message.

The message will be a JSON string containing only a timestamp field with the UNIX timestamp of the motion event. This is done like this because in the future additional fields will be added.

This is an example of the published MQTT messages:

{"timestamp":0}
The server also publishes the online message to {HICHIPBRIDGE_MQTT_TOPIC}/status when it is started, and sets the offline message as the last will message to the same topic, so it gets published when the daemon disconnects from the MQTT broker due to a manual stop/crash/etc.

Run the bridge

There are 2 ways to run the bridge: running the daemon binary directly, or running it as a Docker container.

Use daemon directly

First, install the daemon using the following command: go install gomodules.avm99963.com/hichip2mqtt/cmd/hichip2mqtt

Then you can run the daemon using hichipbridge serve (make sure to include Go's bin folder in your PATH).

Before running it, though, you'll have to create a configuration file and set several environment variables.

Use the Docker image

In order to use the Docker image, you'll have to build it first (a CD system to publish the image at the Docker public registry will be developed later on). To build it, go to the cmd/hichipbridge folder and run the following command: make docker-prod.

Then, set up the docker-compose.yml file to fit your needs, create a configuration file and set the environment variables.

After that, you can create and run the Docker container via docker-compose by running docker-compose up.

Configuration file

The configuration file is used for the Go-Guerilla module, in order to configure the STMP server.

By default, the daemon looks for a config.json file in the current directory, but a different location can be supplied via the -c flag.

To learn its syntax, take a look at the documentation for the Go-Guerrilla module. You can also use the config.sample.json file as a template.

Note: The allowed_hosts setting, and the save_process, validate_process and primary_mail_host subsettings in the backend_config setting are overriden by the environmental variables, and so don't need to be configured in the config.json file.

Environment variables

Some settings are set via environment variables.

  • If you're using the binary directly, you should set those up manually in your system. Take a look at the env.sample file to see the list of environment variables that you should set.
  • If you're using the Docker container via docker-compose, you should set those in the .env file (you can use the env.sample file as a template).

Set the IP cameras

In order for the daemon to receive email notifications, the cameras have to be set up to send the email messages to the daemon's STMP server.

For that, configure your HiChip IP camera with the following settings:

  • SMTP server name/port: according to your config.json file.
  • SMTP Authentication: Off
  • Recipient/Send to: {random_username}@{HICHIP_SMTP_HOST}, where {random_username} is ignored and can be set to anything, and {HICHIP_SMTP_HOST} has to be set as the corresponding enviromental variable's value.
  • Sender: {username}@{random_domain}, where {username} is what the daemon will understand as the camera's username, and will be used to form the MQTT topic name. {random_domain} is ignored and can be set to anything, such as cams.example.com.
  • Message: Y-Token: {HICHIP_EMAIL_TOKEN}, where {HICHIP_EMAIL_TOKEN} is the corresponding enviromental variable.