Arduino Helpers master
Utility library for Arduino
Public Types | Public Member Functions | Protected Member Functions | Private Types | Private Attributes | Static Private Attributes | List of all members
MCP23017Encoders< WireType, EncoderPositionType, InterruptSafe > Class Template Reference

#include <AH/Hardware/MCP23017Encoders.hpp>

Detailed Description

template<class WireType, class EncoderPositionType = int32_t, bool InterruptSafe = false>
class MCP23017Encoders< WireType, EncoderPositionType, InterruptSafe >

Class for reading 8 rotary encoders using a MCP23017 I²C port expander.

Encoders are indexed by a number from 0 to 7. Encoder #0 is connected to pins GPA0 and GPA1, Encoder #1 is connected to pins GPA2 and GPA3, ..., Encoder #7 is connected to pins GPB6 and GPB7.

Template Parameters
WireTypeThe type of the Wire I²C driver to use.
EncoderPositionTypeThe type used for saving the encoder positions. int32_t is the default because this matches the Encoder library. You can use small unsigned types such as uint8_t or uint16_t if you're just interrested in the deltas.
InterruptSafeMake the update method safe to use inside of an interrupt. It makes the necessary variables volatile and disables interrupts while reading the positions from the main program.
Examples
MCP23017-Encoders-Interrupts.ino, and MCP23017-Encoders-No-Interrupts.ino.

Definition at line 33 of file MCP23017Encoders.hpp.

+ Collaboration diagram for MCP23017Encoders< WireType, EncoderPositionType, InterruptSafe >:

Public Types

using MCP23017Encoder = typename RegisterEncoderType::Encoder
 Proxy to access a single encoder of the 8 encoders managed by MCP23017Encoders. More...
 

Public Member Functions

 MCP23017Encoders (WireType &wire, uint8_t addr_offset=0, pin_t interrupt_pin=NO_PIN)
 Constructor. More...
 
void begin ()
 Initialize the MCP23017. More...
 
void update ()
 If the state of the MCP23017's GPIO changed, read the new state and update the encoder positions. More...
 
EncoderPositionType read (uint8_t idx) const
 Read the position of the given encoder. More...
 
EncoderPositionType readAndReset (uint8_t idx)
 Read the position of the given encoder and reset it to zero. More...
 
void write (uint8_t idx, EncoderPositionType pos)
 Set the position of the given encoder. More...
 
MCP23017Encoder operator[] (uint8_t index)
 Get a proxy to one of the encoders managed by this MCP23017. More...
 

Protected Member Functions

template<size_t N>
void writeI2C (const uint8_t(&values)[N])
 Write any data to the MCP23017. More...
 
template<class... Args>
void writeI2C (uint8_t addr, Args... values)
 Write any data to the MCP23017. More...
 
uint16_t readGPIO ()
 Read the state of all GPIO pins. More...
 

Private Types

using RegisterEncoderType = RegisterEncoders< uint16_t, 8, EncoderPositionType, InterruptSafe >
 

Private Attributes

WireType * wire
 
uint8_t address
 
pin_t interrupt_pin
 
RegisterEncoderType encs
 

Static Private Attributes

static constexpr uint8_t I2C_BASE_ADDRESS = 0x20
 

Member Typedef Documentation

◆ RegisterEncoderType

using RegisterEncoderType = RegisterEncoders<uint16_t, 8, EncoderPositionType, InterruptSafe>
private

Definition at line 41 of file MCP23017Encoders.hpp.

◆ MCP23017Encoder

Proxy to access a single encoder of the 8 encoders managed by MCP23017Encoders.

Definition at line 231 of file MCP23017Encoders.hpp.

Constructor & Destructor Documentation

◆ MCP23017Encoders()

MCP23017Encoders ( WireType &  wire,
uint8_t  addr_offset = 0,
pin_t  interrupt_pin = NO_PIN 
)
inline

Constructor.

Parameters
wireThe Wire/I²C interface to use.
addr_offsetA number between 0 and 7 reflecting the state of the I2C address pins of the MCP23017.
interrupt_pinThe pin connected to the MCP23017 interrupt pin. This doesn't have to be an interrupt pin of the Arduino.
The interrupt pin of the MCP23017 is configured as open-drain active-low output, and the interrupt pins of GPIO banks A and B are mirrored/OR'ed together. This means that you only need to connect a single interrupt pin for each MCP23017, and you can connect the interrupt pins of multiple MCP23017s to a single Arduino pin.

Definition at line 106 of file MCP23017Encoders.hpp.

Member Function Documentation

◆ writeI2C() [1/2]

void writeI2C ( const uint8_t(&)  values[N])
inlineprotected

Write any data to the MCP23017.

Definition at line 49 of file MCP23017Encoders.hpp.

◆ writeI2C() [2/2]

void writeI2C ( uint8_t  addr,
Args...  values 
)
inlineprotected

Write any data to the MCP23017.

Parameters
addrThe address of the register to write to.
valuesThe values to write.

Definition at line 64 of file MCP23017Encoders.hpp.

◆ readGPIO()

uint16_t readGPIO ( )
inlineprotected

Read the state of all GPIO pins.

Definition at line 70 of file MCP23017Encoders.hpp.

◆ begin()

void begin ( )
inline

Initialize the MCP23017.

The configuration register is set to the right config, all GPIO pins are set to input mode, the pin change interrupts are enabled, and the internal pull-up resistors are enabled as well.

The interrupt pin on the Arduino is configured as input with the internal pull-up resistor enabled, because the MCP23017's interrupt output is configured in open-drain mode.

This function does not initialize the I²C interface. You have to call Wire.begin() before calling this function.

Initialize the state

Examples
MCP23017-Encoders-No-Interrupts.ino.

Definition at line 125 of file MCP23017Encoders.hpp.

◆ update()

void update ( )
inline

If the state of the MCP23017's GPIO changed, read the new state and update the encoder positions.

Can be called from within an ISR on boards that support I²C inside of ISRs, on the condition that InterruptSafe is set to true.

Don't call this function both from the ISR and from your main program, only call it from one of the two.

Examples
MCP23017-Encoders-Interrupts.ino.

Definition at line 179 of file MCP23017Encoders.hpp.

◆ read()

EncoderPositionType read ( uint8_t  idx) const
inline

Read the position of the given encoder.

Does not update the state, just reads it from the buffered position.

Don't call this function from within an ISR.

Parameters
idxThe index of the encoder to read [0, 7].

Definition at line 199 of file MCP23017Encoders.hpp.

◆ readAndReset()

EncoderPositionType readAndReset ( uint8_t  idx)
inline

Read the position of the given encoder and reset it to zero.

Does not update the state, just reads it from the buffered position.

Don't call this function from within an ISR.

Parameters
idxThe index of the encoder to read [0, 7].

Definition at line 211 of file MCP23017Encoders.hpp.

◆ write()

void write ( uint8_t  idx,
EncoderPositionType  pos 
)
inline

Set the position of the given encoder.

Don't call this function from within an ISR.

Parameters
idxThe index of the encoder to write [0, 7].
posThe position value to write.

Definition at line 225 of file MCP23017Encoders.hpp.

◆ operator[]()

MCP23017Encoder operator[] ( uint8_t  index)
inline

Get a proxy to one of the encoders managed by this MCP23017.

Parameters
indexThe index of the encoder to access.

Definition at line 240 of file MCP23017Encoders.hpp.

Member Data Documentation

◆ I2C_BASE_ADDRESS

constexpr uint8_t I2C_BASE_ADDRESS = 0x20
staticconstexprprivate

Definition at line 35 of file MCP23017Encoders.hpp.

◆ wire

WireType* wire
private

Definition at line 37 of file MCP23017Encoders.hpp.

◆ address

uint8_t address
private

Definition at line 38 of file MCP23017Encoders.hpp.

◆ interrupt_pin

pin_t interrupt_pin
private

Definition at line 39 of file MCP23017Encoders.hpp.

◆ encs

RegisterEncoderType encs
private

Definition at line 44 of file MCP23017Encoders.hpp.


The documentation for this class was generated from the following file: