External Triggers in ZoneMinder: Initial Development

ESP-01 Pictured

The ESP-01 is smaller than my thumb and can be purchased for just over $2 on E-Bay. Yes, $2. Shipped. From China. How do they do it?

If you plan to follow along but have not read how to setup your build environment, please do so now. That describes how to properly set up an environment which can compile and then flash the ESP-01.

In this article, I'll describe how to take a device with a discrete output (button, relay, motion sensor, sound detector, etc) and use that as a trigger to put a camera, attached to a ZoneMinder server, into alarm. Putting a camera into alarm is like hitting the record button.

Required and Suggested Hardware

Naturally you will need an ESP-01. You also need a way to power it and connect it to your computer for programming. However, there are some other pieces of hardware you may want to consider buying to make things easier. What it comes down to is what is more important to you, your time or your money? There is no wrong answer.

ESP8266 ESP-01
ESP-01 Development Board with built-in 3.3v voltage regulator
3.3v compatible USB-to-TTL adapter
A small enclosure to mount the circuitry in
Device to act as a trigger. In my case, a sound detection sensor with digital output
Small USB wall charger from any mobile device.
Small solder-less breadboard
Breadboard compatible buttons
Variety of breadboard jumpers (male-male, male-female, and female-female)

The first six items are required. Note that the ESP-01 draws more current than a typical USB-to-TTL adapter provides so you need a different source of dedicated 3.3v power, such as a LM1117T-3.3 voltage regulator chip. Note that I switched from using the LM1117T to the ESP-01 development board after finding it on E-Bay.

Also a word caution. The ESP-01 is not tolerant of voltages higher than 3.3v. If you attach a device that uses 5v to signal HIGH, then you must use a logic level converter. Failure to do so can fry the ESP8266's GPIO pin.

The last three items are optional. Generally you will want to assemble and test your circuit on a solderless breadboard before soldering it all together.

Testing and Development

First, use the following schematic to wire everything to a solderless breadboard.

Click to Enlarge

For initial testing, wire GPIO2 to a button. Once the circuit is verified to work, then wire GPIO2 to the intended trigger device, motion detector, door contact, etc. Don't forget that the ESP8266 chip is not tolerant of 5 volt signals! Do not wire any device to GPIO2 that outputs a 5 volt signal.

Programming

With the circuit assembled, open the Arduino software and paste the code shown below into an empty sketch. Before you save it, there are several parameters you must modify:

zmserver - set this to the ip address of your ZoneMinder server
zmtriggerStartCmd - Set the ZoneMinder Monitor ID of the camera and modify the alarm text to your liking
zmtriggerStopCmd - Use the same Monitor ID and set the alarm restored text
WiFiMulti.addAP - Enter at least one ssid and one password for your WiFi network(s).

To program the ESP-01, attach the USB-to-TTL adapter to your pc via usb cable. Then hold the button wired to GPIO0 down, while simultaneously applying power to the circuit. While continuing to hold the GPIO0 button down, press the Upload button in the Arduino IDE. It will compile the sketch and then upload it to the ESP8266. The status is displayed in the black window at the bottom. It will state whether the upload was successful or not.

If the upload fails, first check that Tools -> Port is set to the port representing the USB-to-TTL adapter. For many of us, that will be /dev/ttyUSB0.

Testing

Let's do it! Following a successful upload, leave the circuit attached to the usb cable. From the Arduino menu, open the serial port monitor by selecting tools -> Serial Monitor. After setting the baud rate to 115200, you should see status text scrolling through every 10 seconds.

[SETUP] WAIT 4...
[SETUP] WAIT 3...
[SETUP] WAIT 2...
[SETUP] WAIT 1...
Waiting for WiFi to Connect........Connected!

HTTP server started

WiFi Status
IP address: 192.168.1.196
MAC address: 5C:CF:7F:0B:2F:18
SSID: bauerhaus
Signal Strength (%): 93
GPIO0 state: 1
GPIO2 state: 1

Using the ip address shown in the serial monitor, point your web browser to the device. You can poll the status of each of the GPIO pin through the web browser if needed.

Now for the moment we have been waiting for, press and hold the button wired to GPIO2. You should see output on your serial monitor similar to the following:

Event Trigger Sent to ZoneMinder
2|on|200|Alarm Sensor Active|An alarm has occured. Investigate the cause.|Alarm

Now release the button and you should see additional output similar to:

Event Trigger Sent to ZoneMinder
2|off+10|0|Alarm Sensor Normal|The Alarm has been restored|Normal

Now inspect the logfile on the ZoneMinder server. From the web console, click "Log" (top right). You will see events indicating receipt of the "on" command to put the camera into alarm, followed by an "off" command to turn the alarm off 10 seconds after the alarm has cleared.


ZoneMinder Log Showing Results of a Trigger

If the ESP8266 was not able to send these commands to ZoneMinder, the serial monitor will alert you with an error message. If that happens, try pinging the ESP8266 from the ZoneMinder server to verify network connectivity. Verify the zmtrigger service is running on the ZoneMinder server, and it is not being blocked by a firewall.

Assembly

Inexpensive USB Charger Case

The chosen trigger device is a microphone circuit with a digital output. This circuit can be purchased on E-Bay for just a few dollars. The goal will be to put a camera into alarm when the dogs bark.

After spending too much time evaluating small enclosures for sale on E-Bay, I settled on a small usb charger case, which one can get for less than $1. The inside of the case had a female micro-usb mounted to a small pcb, which we will reuse.

PCB with leads soldered

After removing the circuit board from the case, all the components on the bottom were de-soldered, except for the micro-usb port. Next positive and negative leads were soldered for power.

PCB reinserted and Mic circuit

Next up, I used Epoxy to secure the digital microphone and usb pcb back into the case.

All circuitry added

Here you can see the usb pcb, the digital microphone, the esp8266, and a capacitor mounted in the case.

Let's plug this thing in!

Here is the final product. Let's test this thing!

What we Accomplished and How to Improve

This article described how to attach any device with a discrete on/off output to an ESP-01, which in turn can notify a ZoneMinder server, running the zmtrigger service, when the device goes into alarm.

All parameters were hard coded into the script. This kept things simple, but is not user friendly. If any of the parameters change, a new sketch must be uploaded to the device. Stayed tuned for a future article, which will show how the WiFiManager library can solve the problem of user friendliness.

By design, this is intended to be attached to an unlimited power source, such as a USB power brick. Putting the device to sleep to conserve power, will be a topic in a future article. This is a necessary step when powering the device from a battery.