ESP32 I/O handler library
by SuperHouse Automation
SKU: OXRS-IO-IOHandler-ESP32-LIB
Introduction
This library serves two functions, for input monitoring and output control. It can monitor buttons, switches, contacts, or any binary sensor, and report events back to the caller. It can also listen for binary commands and passes control events back to the caller.
Typically used with MCP23017 I2C I/O buffers to detect digital signals being pulled to GND (inputs) and to control relays (outputs).
How does it work?
The library contains two classes which can be used independently or together, depending on what your firmware is trying to do.
USM_Input.h
Monitors and maintains state for up to 16 inputs. Takes 16 bits of binary data and checks each value against an internal state machine to determine if any input events have occurred.
USM_Output.h
Waits for commands and generates control events for up to 16 outputs. Keeps track of output state and handles interlocking and timers.
Configuration
USM_Input.h
Each of the 16 inputs can be configured as either BUTTON
, CONTACT
, PRESS
, ROTARY
, SECURITY
, SWITCH
or TOGGLE
. Different events will be generated depending on the configured type, and the sequence of state changes.
Each of the 16 inputs can also be inverted, so events are generated on LOW
-> HIGH
transitions instead of HIGH
-> LOW
.
Rotary Encoders
A pair of inputs can be set as ROTARY
inputs, and connected to an incremental rotary encoder. The library will decode the signals from the encoder and generate LOW_EVENT
(clockwise) or HIGH_EVENT
(counter clockwise) events, depending which way the encoder is turned.
Encoder Direction | I/O Event |
---|---|
Clockwise | LOW_EVENT |
Counter Clockwise | HIGH_EVENT |
Security Sensors
A set of 4 inputs can be set as SECURITY
inputs, and connected to a security monitor module (Monimod). This module is capable of reading the end-of-line (EOL) resistance of your security sensor and detecting one of 5 possible states; normal
, alarm
, tamper
, short
or fault
. The library will decode the 4 inputs from the Monimod and generate the appropriate event, ready for your firmware to act upon.
The table below shows the state of the 4 inputs from the Monimod for each sensor state, and what I/O event is generated as a result;
Sensor State | CH1 | CH2 | CH3 | CH4 | I/O Event |
---|---|---|---|---|---|
Normal | OFF | ON | OFF | ON | HIGH_EVENT |
Alarm | OFF | ON | ON | ON | LOW_EVENT |
Tamper | ON | OFF | ON | ON | TAMPER_EVENT |
Short | OFF | ON | OFF | OFF | SHORT_EVENT |
Fault | ? | ? | ? | ? | FAULT_EVENT |
Functions
setType(input, type)
: Set the input typesetInvert(input, invert)
: Invert input handlingsetDisabled(input, disabled)
: Disable an input (stop processing events)
Code Example
#include <Adafruit_MCP23X17.h> // For MCP23017 I/O buffers
#include <OXRS_Input.h> // For input handling
// I/O buffers
Adafruit_MCP23X17 mcp23017;
// Input handlers
OXRS_Input oxrsInput;
void setup() {
// Initialise the MCP chip (assume at address 0x20)
mcp23017.begin_I2C(0x20);
// Set every pin to be INPUT with internal PULLUPs enabled
for (uint8_t pin = 0; pin < 16; pin++) {
mcp23017.pinMode(pin, INPUT_PULLUP);
}
// Initialise the input handler
oxrsInput.begin(inputEvent);
// Configurate types and invert state here
//oxrsInput.setType(0, BUTTON);
//oxrsInput.setInvert(0, 1);
}
void loop() {
// Read the values for all 16 inputs on this MCP in one hit
uint16_t io_value = mcp23017.readGPIOAB();
// Check for any input events
oxrsInput.process(0, io_value);
}
void inputEvent(uint8_t id, uint8_t input, uint8_t type, uint8_t state) {
// Code to handle the event goes in here!
}
USM_Output.h
Each of the 16 outputs can be configured as either MOTOR
, RELAY
, or TIMER
. Different control signals will be generated depending on the configured type.
Interlocking
Interlocking two outputs allows them to control equipment such as roller blinds, garage doors, louvre roofing etc.
If two outputs are interlocked it means they can't be on
at the same time. E.g. if output A and B are interlocked, and an on
command is sent to output B while output A is on
, output A will automatically turn off
and after a short delay output B will then turn on
.
Timers
Timers allow an output to automatically turn off
a set number of seconds after being turned on
(configurable but defaults to 60 seconds).
If another on
command is sent while the timer is running, it will reset to zero and begin counting down again. If an off
command is sent the timer will be cancelled and the output turned off
immediately.
Functions
setType(output, type)
: Set the output typesetInterlock(output, interlock)
: Interlock an output with anothersetTimer(output, seconds)
: Set the timer duration (in seconds)setDisabled(output, disabled)
: Disable an output (stop processing events)
TIP
The only difference between MOTOR
and RELAY
outputs is the interlock delay. For MOTOR
outputs the delay is 2000ms, for RELAY
outputs it is only 500ms.
Code Example
#include <Adafruit_MCP23X17.h> // For MCP23017 I/O buffers
#include <OXRS_Output.h> // For output handling
// I/O buffers
Adafruit_MCP23X17 mcp23017;
// Input handlers
OXRS_Output oxrsOutput;
void setup() {
// Initialise the MCP chip (assume at address 0x20)
mcp23017.begin_I2C(0x20);
// Set every pin to OUTPUT
for (uint8_t pin = 0; pin < 16; pin++) {
mcp23017.pinMode(pin, OUTPUT);
}
// Initialise the output handler
oxrsOutput.begin(outputEvent);
// Configurate types, interlocks and timers here
//oxrsOutput.setInterlock(0, 1);
//oxrsOutput.setInterlock(1, 0);
}
void loop() {
// Check for any output events
oxrsOutput.process();
// Need a way to receive commands - e.g. serial input or MQTT messages
//oxrsOutput.handleCommand(0, output, RELAY_ON);
}
void outputEvent(uint8_t id, uint8_t output, uint8_t type, uint8_t state) {
// Code to handle the event goes in here!
}
Downloads
Download the latest version of the firmware on Github.
Supported Hardware
Designed to run on ESP32 based devices.
Credits
- OXRS Core Team
License
Found here.