Security Monitor ESP32

by Ben Jones

SKU: OXRS-AC-SECURITYMONITOR-ESP32-FW

Introduction

A security sensor monitor for DIY home automation projects.

This system uses UTP cable (typically Cat-5e because it's cheap) to connect sensors to a central controller. The sensors can be reed sensors attached to doors or windows, PIR sensors for motion detection, or anything else that reports a digital state.


How does it work?

When a sensor state change is detected an MQTT message is published to the configured MQTT broker for further processing by your home automation system.

Devices such as PIR sensors or door/window reed switches can be connected to provide a high level of security and ensure you are alerted if there is any tampering to the sensor or wiring (whether intentional or not), as well as reporting the sensor state.

The security monitor will report one of 5 states for each connected device. It achieves this by using two end-of-line (EOL) resistors connected to each security sensor.

State Monitor Security Sensor circuit diagram

Resistor 1 (10K) is connected in series with the security alarm wiring, and resistor 2 (4K7) is connected across the alarm contact.

The firmware will detect and report the following states for a security sensor wired up with EOL resistors;

StateLCD DisplayDescription
NormalGreenThe sensor is in a safe state, e.g. no movement detected or door/window is closed
AlarmRedThe sensor has been tripped, e.g. movement detected or door/window is opened
TamperMagenta (flashing)The sensor wiring has been compromised (open circuited), e.g. a sensor cover has been removed or a cable has been cut
ShortMagenta (flashing)The sensor wiring has been compromised (shorted), e.g. intentional attempt to bypass the sensor, or a nail/screw through the cable
FaultCyan (flashing)The sensor has been unplugged or a system fault has been detected

The firmware is designed to run on hardware using MCP23017 I/O buffer chips via I2C, e.g. the Security Moduleopen in new window.

Configuration

The firmware can be configured by publishing an MQTT message to this topic;

[PREFIX/]conf/CLIENTID[/SUFFIX]

where:

  • PREFIX: Optional topic prefix if required
  • CLIENTID: Client id of device, defaults to <MACADDRESS>
  • SUFFIX: Optional topic suffix if required

The message payload should be JSON and it's format is defined in a JSON schema document included in the adoption payload published here;

[PREFIX/]stat/CLIENTID[/SUFFIX]/adopt

See the config value in the /adopt payload.

TIP

This firmware works in a similar way to the State Monitor, but with all ports set to type "security".

Port Config

Each PORT can be configured via the following properties;

KeyMandatoryValue
portMandatoryIndex of the port to configure
invertOptionalEither true or false
disabledOptionalEither true or false

WARNING

Disabling a port will stop any events being emitted!

Examples

To configure port 4 to be inverted, and port 8 to be disabled;

{ 
  "ports": [
    { "port": 4, "invert": true },
    { "port": 8, "disabled": true }
  ]
}

TIP

A retained message will ensure the device auto-configures on startup.

Events

A port EVENT is reported to a topic of the form:

[PREFIX/]stat/CLIENTID[/SUFFIX]

where;

  • PREFIX: Optional topic prefix if required
  • CLIENTID: Client id of device, defaults to <MACADDRESS>
  • SUFFIX: Optional topic suffix if required

The message payload is JSON and contains:

KeyValue
portPort this event occured on (1-32)
typeEvent type (always security)
eventEvent (see below)
Event TypeEvent
securitynormal, alarm, tamper, short or fault

Examples

A contact sensor opening on port 2;

{ 
  "port": 2, 
  "type": "security", 
  "event": "alarm" 
}

A short detected on port 4;

{ 
  "port": 4, 
  "type": "security", 
  "event": "short" 
}

Supported Hardware

This firmware is compatible with the Security Moduleopen in new window and is designed to run on the RACK32 as part of the OXRSopen in new window eco-system.

The Security Module hardware provides 12V power down the cable, which can be used for powering sensors (e.g. PIRs).

The sensor needs to have EOL resistors installed, or alternatively you can use an EOL Senseopen in new window RJ45 breakout from Bedrock Media Designs, which has the EOL resistors built-in and provides easy-to-use screw terminals for connecting your sensor to.

The RJ45 pinout for each port is;

PINDESCRIPTION
1SENSOR
2SENSOR CMN
3SPARE
4VIN
5VIN
6SPARE CMN
7GND
8GND

Further Information

Downloads

Download the latest binaryopen in new window of the firmware from GitHub.

Download the source codeopen in new window of the firmware from GitHub.

Home Automation Integration

Below are some examples of how you could integrate with various home automation systems.

Home Assistantopen in new window integration examples.

Node-REDopen in new window integration examples.

Credits

License

Copyright 2020-present Austin's Creations https://www.austinscreations.caopen in new window

The software portion of this project is licensed under the Simplified BSD License. The "licence" folder within this project contains a copy of this license in plain text format.