Switch Input - MCP23017

.

Plugin details

Type: Switch Input

Name: MCP23017

Status: NORMAL

GitHub: P009_MCP.ino

Maintainer: .

Used libraries: .

Introduction

The number of GPIO pins on the ESP module can be expanded with a IO Expander. This plugin supports the MCP23017 that provides 16 more pins that can be used as input or output. This way it becomes possible to control a 16 channel relay board. Multiple of these boards can be connected, as there are 8 I2C addresses available via jumper pins.

Each individual pin can be used as either input or output.

As this plugin shares many attributes with the regular Switch plugin, the description has many similarities.

Supported hardware

../_images/P009_MCP23017Module.png

The chip can be used on specifically designed hardware, or a generic module can be used. These are available from several sources.

.

Configuration

../_images/P009_DeviceConfiguration.png
  • Name A unique name should be entered here.

  • Enabled The device can be disabled or enabled. When not enabled the device should not use any resources.

Sensor

  • Inversed Logic When enabled, inverts the input signal, so if the pin is logic high (3.3V), the Value will be 0, and if it is logic low (gnd), the Value will be 1.

I2C Options

The available settings here depend on the build used. At least the Force Slow I2C speed option is available, but selections for the I2C Multiplexer can also be shown. For details see the Hardware page

  • I2C Address: The address the device is using. As there are 8 possible I2C addresses, when the jumpers are configured, the selected value should match with that.

Available options:

../_images/P009_I2CAddressOptions.png
  • Port As there are multiple Ports available on each board, the desired Port can be selected here.

Available options:

../_images/P009_PortOptions.png

Device Settings

  • Send boot state: If checked the unit will publish the switch state when booting. If not checked you may find yourself with a latching switch caught in limbo. This means that the unit is registering a low/high value but the physical state of the switch might be the opposite. If you use a mechanical switch that may be physically set to a state you should check this option.

Advanced event management

  • De-bounce (ms): How long should the pulse (the time you press the button) be, if set to high you need to have it published for a longer time before the unit will register it as an state change. You could experiment with this setting to find a good behavior of the button if you feel that it’s not responding according to your preferences.

  • Double click event: If enabled the unit will detect double clicks which are within the set interval (see below). The double click event is identified as MCP23017#State=3. There’s three options for the double click: * Active only on low: the double clicks will be counted by how many low signals that is triggered within the set time. * Active only on high: the double clicks will be counted by how many high signals that is triggered within the set time.

    • Active on high & low: the double clicks will be counted by how many high and low signals that is triggered within the set time. This means that a double click could be registered as a press and release of a button. So not actually double click.

  • Double click max. interval (ms): This is the interval that you need to perform the double click within.

  • Long press event: If enabled the unit will detect a long press of a button. There’s three different behaviors of the long press:

    • Active only on low: this means that the unit will only be triggering the long press event if the signal is low. Two different event values are used, 10 if the state goes from 0 to 1 (MCP23017#State=10), and 11 if the state goes from 1 to 0 (MCP23017#State=11).

    • Active only on high: same as above but only triggered on high signal.

    • Active on high & low: the long press will be triggered both on high and low signals.

  • Long press min interval (ms): This is the interval that you need to press the button before the long press event is triggered.

  • Use safe button (slower): This effectively adds an extra De-bounce delay and sends event value 4 when reached.

Data Acquisition

This group of settings, Single event with all values, Send to Controller and Interval settings are standard available configuration items. Send to Controller is only visible when one or more Controllers are configured.

  • Interval By default, Interval will be set to 60 sec. It is the frequency used to read sensor values and send these to any Controllers configured for this device.

Values

The name for the value is initially set to a default name, but can be changed if desired.

Commands available

Command (MCPGPIO/Value)

Extra information

MCPGPIO,<MCPGPIO>,<state>

MCPGPIO: 0 … 255

State:

2 (HIGH-Z, input)

1 (HIGH, output)

0 (LOW, output)

-1 (OFFLINE, disconnected)

Basic on/off.. We can control a pin with simple http URL commands. To change the pin to high or low steady output. Setting PCFGPIO to 2 means that it will be able to detect low level relays (with high impedance, Z).

MCPGPIOtoggle,<MCPGPIO>

MCPGPIO: 0 … 255

Toggle on/off.. Toggle the current (output) state of the given MCPGPIO pin. When executed, it changes the pin mode to output.

MCPLongPulse,<MCPGPIO>,<state>,<duration>

MCPGPIO: 0 … 255

State: 1/0

Duration: 1 … 999 S

To send a *long* pulse to a certain pin.. A long pulse is basically the same as the plain pulse. Duration is defined in seconds, which makes it more suitable for longer duration. This command is not blocking, but will send 2 events to start and stop the pulse. This may have some variation depending on the system load of the module. Variation is typically up-to 10 msec, but may be up-to a second, depending on active plugins and controllers performing blocking operations.

MCPLongPulse_mS,<MCPGPIO>,<state>,<duration>

MCPGPIO: 0 … 255

State: 1/0

Duration: 10 … 15000 msec

To send a *long* pulse to a certain pin. A LongPulse_mS is the same as the regular LongPulse. The only difference is the time base in milliseconds rather than in seconds.

MCPPulse,<MCPGPIO>,<state>,<duration>

MCPGPIO: 0 … 255

State: 1/0

Duration: 0 … 1000 msec

To send a *short* pulse to a certain pin. Example to send an active high (1) pulse on MCPGPIO 14 for 500 mSeconds. Pulse duration is in milliseconds. State is 1 or 0. N.B. this is a blocking call, meaning no other actions will be performed during the pulse.

Status,MCP,<MCPGPIO>

MCPGPIO: 0 … 255

Returns the status of a pin. By the use of the command you will receive the status of the relevant pin.

Monitor,MCP,<MCPGPIO>

MCPGPIO: 0 … 255

To monitor a MCPGPIO state. By the use of the command you will receive events when the state of that pin is changed from 1 to 0 and from 0 to 1.

UnMonitor,MCP,<MCPGPIO>

MCPGPIO: 0 … 255

To cancel the monitor of a MCPGPIO state. By the use of the command you will stop receiving events when the state of that pin is changed from 1 to 0 and from 0 to 1.

MonitorRange,MCP,<MCPGPIO>

MCPGPIO: 0 … 255

To monitor a MCPGPIO state. By the use of the command you will receive events when the state of that pin is changed from 1 to 0 and from 0 to 1.

UnMonitorRange,MCP,<MCPGPIO>

MCPGPIO: 0 … 255

To cancel the monitor of a MCPGPIO state. By the use of the command you will stop receiving events when the state of that pin is changed from 1 to 0 and from 0 to 1.

MCPGPIOrange,<MCPGPIO start pin>,<MCPGPIO end pin>,<value> [,optional bitmask]

MCPGPIO start pin: 0 … 255

MCPGPIO end pin: 0 … 255

value: 0 or 1

bitmask:
- if not present assume to operate in all pins
- if present is used as a mask (1=update, 0=do not update)
- pins are numbered from right to left (i.e. 87654321)
- if number of bit lower than number of pins, then padded with 0
- if number of bit higher than number of pins, then it’s truncated
Change the status of a pin for a given range applying the given mask

examples:
- mcpgpioRange,1,8,1 -> set pins 1 to 8 to 1
- mcpgpioRange,3,12,1 -> set pins 3 to 12 to 1
- mcpgpioRange,5,17,0 -> set pins 5 to 17 to 0

- mcpgpioRange,3,12,1,525 or mcpgpioRange,3,12,1,0b0100001101
mask = ‘0100001101’
write pattern after mask = ‘x1xxxx11x1’ where x indicates that the pin will not be changed
(only pin 1,3,4,9 will be changed)

- mcpgpioRange,3,12,1,973 or mcpgpioRange,3,12,1,0b1111001101
mask = 973 = ‘1111001101’
write pattern after mask = ‘1111xx11x1’ where x indicates that the pin will not be changed

MCPGPIOpattern,<MCPGPIO start pin>,<MCPGPIO end pin>,<write pattern> [,optional bitmask]

MCPGPIO start pin: 0 … 255

MCPGPIO end pin: 0 … 255

write pattern: it’s a write pattern. Write 0 or 1.
- Example: use decimal number 15 (in binary is 00001111) to set to 1 pin 1,2,3 and 4 and to set to 0 pins 5,6,7,8
- if number of bit lower than number of pins, then padded with 0;
- if number of bit higher than number of pins, then it’s truncated.

bitmask:
- if not present assume to operate in all pins
- if present is used as a mask (1=update, 0=do not update)
- if number of bit lower than number of pins, then padded with 0
- if number of bit higher than number of pins, then it’s truncated
Change the status of a pin for a given range applying the given mask

examples:
- mcpgpioPattern,1,8,13
write pattern = ‘1101’ that will be padded as: ‘0000001101’
mask not present, assume mask = ‘1111111111’

- mcpgpioPattern,3,12,13
write pattern = ‘1101’ that will be padded as: ‘0000001101’
mask not present, assume mask = ‘1111111111’

- mcpgpioPattern,3,12,525
write pattern = 525 = ‘100001101’
mask not present, assume mask = ‘1111111111’

- mcpgpioPattern, 3, 12, 525, 973
write pattern = 525 = ‘100001101’
mask = 973 = ‘1111001101’
write pattern after mask = ‘1000xx11x1’ where x indicates that the pin will not be changed

MCPmode,<MCPGPIO>,<mode>

MCPGPIO: 0 … 255

mode:
0 = OUTPUT
1 = INPUT PULLUP
2 = INPUT

To change the mode of an MCPGPIO pin.

example: mcpMode,1,0 (set pin 1 as output)

MCPmodeRange,<MCPGPIO start pin>,<MCPGPIO end pin>, <mode>

MCPGPIO start pin: 0 … 255

MCPGPIO end pin: 0 … 255

mode:
0 = OUTPUT
1 = INPUT PULLUP
2 = INPUT

To change the mode of an MCPGPIO range of pin.

example: mcpModeRange,1,8,0 (set pin 1 to 8 as output)

Change log

Changed in version 2.0:

changed 2021-08-04 Replaced single Port inputfield with separate I2CAddress and Port selections.

added Major overhaul for 2.0 release.

New in version 1.0:

added Initial release version.