A class that models a GPIO outputs pins expander through the use of 8-bits serial in paralell out (SIPO) shift registers. More...

#include <ShiftRegGPIOXpander_ESP32.h>

Public Member Functions
	ShiftRegGPIOXpander ()
	Class default constructor.

	ShiftRegGPIOXpander (uint8_t ds, uint8_t sh_cp, uint8_t st_cp, uint8_t srQty=1, uint8_t *initCntnt=nullptr)
	Class constructor.

	~ShiftRegGPIOXpander ()
	Class destructor.

bool	copyMainToAux (bool overWriteIfExists=true)
	Copies the Buffer content to the Auxiliary Buffer

void	discardAux ()
	Deletes the Auxiliary Buffer.

uint8_t	digitalReadSr (const uint8_t &srPin)
	Returns the state of the requested pin.

void	digitalWriteSr (const uint8_t srPin, const uint8_t value)
	Set a specific pin to either HIGH (0x01) or LOW (0x00).

void	digitalWriteSrAllReset ()
	Sets all the pins to LOW (0x00).

void	digitalWriteSrAllSet ()
	Sets all the pins to HIGH (0x01).

void	digitalWriteSrMaskReset (uint8_t *newResetMask)
	Modifies the Main buffer contents by resetting simultaneously certain pins.

void	digitalWriteSrMaskSet (uint8_t *newSetMask)
	Modifies the Main buffer contents by setting simultaneously certain pins.

void	digitalWriteSrToAux (const uint8_t srPin, const uint8_t value)
	Set a specific pin to either HIGH (0x01) or LOW (0x00) in the Auxiliary Buffer.

uint8_t *	getMainBuffPtr ()
	Retrieves the pointer to the Main Buffer.

uint8_t	getMaxPin ()
	Return the greatest valid pin number.

uint8_t	getSrQty ()
	Return the quantity of shift registers composing the GPIOXtender object.

bool	moveAuxToMain (bool flushASAP=true)
	Moves the data in the Auxiliary to the Main.

bool	stampOverMain (uint8_t *newCntntPtr)
	Sets all of the output pins of the shift register to new provided values at once.

bool	sendAllSRCntnt ()
	Flushes the contents of the Buffer to the GPIO Expander pins.

Detailed Description

A class that models a GPIO outputs pins expander through the use of 8-bits serial in paralell out (SIPO) shift registers.

The GPIO pins expansion modeled adds digital output pins managed by the use of an API similar to the built in Arduino platform tools. As the hardware is built using daisy-chained 74HCx595 shift registers, the connection pins to the hardware are needed as parameters to build the object, as the number of shift registers daisy-chain connected is needed

Constructor & Destructor Documentation

◆ ShiftRegGPIOXpander()

ShiftRegGPIOXpander::ShiftRegGPIOXpander	(	uint8_t	ds,
		uint8_t	sh_cp,
		uint8_t	st_cp,
		uint8_t	srQty = 1,
		uint8_t *	initCntnt = nullptr )

Class constructor.

Instantiates a ShiftRegGPIOXpander object, the parameters provide the pins used to communicate with the shift registers and the number of shift registers composing the expander. 8-bits will be added with every shift register connected in a daisy-chain arrangement.

Parameters

ds	MCU GPIO pin connected to the DS pin -a.k.a. serial data input (DIO)- pin of the 74HCx595 to send data serially to the expander
sh_cp	MCU GPIO pin connected to the SH_CP pin -a.k.a. shift register clock input- of the 74HCx595 to manage the communication's clock line to the expander
st_cp	MCU GPIO pin connected to the ST_CP pin -a.k.a. storage register clock input- to set (latch) the output pins from the internal buffer of the expander
srQty	Optional parameter. Quantity of shift registers set in daisy-chain configuration composing the expander.
initCntnt	Optional parameter. Initial value to be loaded into the Main Buffer, and thus will be the inital state of the Shift Register output pins. The value is provided in the form of a uint8_t*, and the constructor expects the data to be set in the memory area from the pointed address to the pointed address + (srQty - 1) consecutive bytes. If the parameter is not provided, or set to nullptr the inital value to be loaded into the Main Buffer will be 0x00 to all the shift registers positions.

Note: The object will create a dynamic array to buffer the information written to the shift registers, it will be referred to as the Main Buffer, the Buffer or the Main.
The action of sending the Buffer contents to the shift registers array will be reffered as Flushing. Every time the Buffer is flushed to the shift registers array the whole contents of that array will be sent.
A secondary dynamic array will be created for delayed operations purposes, that buffer will be referred to as the Auxiliary Buffer or the Auxiliary. The Auxiliary will be created every time it's needed and destroyed after it's temporary use becomes unnecesary. The Auxiliary will be used to allow several bit changing operations without the need of flushing the whole buffer for each bit change. The usual propper use of the mechanism will make all the bits changes that occur simultaneously to the Auxiliary Buffer and then moving the Auxiliary Buffer to the Main Buffer and flushing the Buffer.

Attention: There is no mechanism to flush the Auxiliary straight to the shift registers, every method that invokes a Main Buffer modification -see void digitalWrite(const uint8_t, const uint8_t) - and/or flushing -see bool sendAllSRCntnt() - will force first the Auxiliary to be moved over the Main Buffer, destroy the Auxiliary, perform the intended operation over the Main Buffer and then finally flush the resulting Main Buffer contents to the shift registers. This procedure is enforced to guarantee buffer contents consistency and avoid any loss of modifications done to the Auxiliary.

Here is the call graph for this function:

◆ ~ShiftRegGPIOXpander()

ShiftRegGPIOXpander::~ShiftRegGPIOXpander ( )

Class destructor.

Takes care of resources releasing

Member Function Documentation

◆ copyMainToAux()

bool ShiftRegGPIOXpander::copyMainToAux ( bool overWriteIfExists = true )

Copies the Buffer content to the Auxiliary Buffer

If there's no existent Auxiliary the method creates it and copies the content
If there's an Auxiliary, the method will proceed acording to the value passed in the parameter:

If the parameter passed is true the Auxiliary contents will be overwritten with the Buffer contents
If the parameter passed is true the Auxiliary will not be modified and the method will return a false to flag the failure of the operation

Parameters

overWriteIfExists Indicates the authorization to overwrite the Auxiliary with the contents of the Main Buffer if the Auxiliary exists at the moment of the invocation.

Returns: The success of the overwriting operation

Return values

true	The Auxiliary was non-existent, or existed and the parameter was true
false	The Auxiliary was existent and the parameter was false, not allowing the Auxiliary to be overwritten

Here is the caller graph for this function:

◆ digitalReadSr()

uint8_t ShiftRegGPIOXpander::digitalReadSr ( const uint8_t & srPin )

Returns the state of the requested pin.

Parameters

srPin Pin whose current value is required.

Returns: The state value of the requested pin, either HIGH (0x01) or LOW (0x00)

Return values

0x00	The pin state was LOW
0x01	The pin state was HIGH
0xFF	ERROR, the pin number was beyond implemented limit

Attention: The value is retrieved from the object's Buffer, not the real chip. If a change to the buffer was made by using the digitalWriteAux(const uint8_t, uint8_t) method (deferred update digital output pin value setting), without updating the Main Buffer an inconsistency difference might be expected, so the method checks for the Auxiliary existence, if it exists a moveAuxToMain(true) will be executed before returning the pin state.

Warning: If a moveAuxToMain(true) had to be executed, the Auxiliary will be destroyed. It's supposed every new need of the Auxiliary will automatically create a new instance of that buffer, but keep this concept in mind.

Here is the call graph for this function:

◆ digitalWriteSr()

void ShiftRegGPIOXpander::digitalWriteSr	(	const uint8_t	srPin,
		const uint8_t	value )

Set a specific pin to either HIGH (0x01) or LOW (0x00).

Parameters

srPin	a positive value indicating which pin to set. The valid range is 0 <= srPin <= (srQty*8)-1
value	Value to set for the indicated Pin

Here is the call graph for this function:

◆ digitalWriteSrMaskReset()

void ShiftRegGPIOXpander::digitalWriteSrMaskReset ( uint8_t * newResetMask )

Modifies the Main buffer contents by resetting simultaneously certain pins.

The pins to be reset are provided as a parameter pointer to a mask. Every bit position set (HIGH, 0x01) on the mask will be reset in the buffer, leaving the reset pins (LOW, 0x00) positions of the mask unmodified in the Main Buffer.

Parameters

newResetMask Pointer to the array containing the mask to modify the Main.

Note: The method provides a mechanism for clearing (reseting or lowering) various Main buffer bit positions in a single operation.

Attention: Any modifications made in the Auxiliary will be moved to the Main before applying the mask.; The Main Buffer will be flushed after the mask modificatons are applied.

Here is the call graph for this function:

◆ digitalWriteSrMaskSet()

void ShiftRegGPIOXpander::digitalWriteSrMaskSet ( uint8_t * newSetMask )

Modifies the Main buffer contents by setting simultaneously certain pins.

The pins to be set are provided as a parameter pointer to a mask. Every bit position set (HIGH, 0x01) on the mask will be set in the buffer, leaving the reset pins (LOW, 0x00) positions of the mask unmodified in the Main Buffer.

Parameters

newResetMask Pointer to the array containing the mask to modify the Main.

Note: The method provides a mechanism for seting (rising) various Main buffer bit positions in a single operation.

Attention: Any modifications made in the Auxiliary will be moved to the Main before applying the mask.; The Main Buffer will be flushed after the mask modificatons are applied.

Here is the call graph for this function:

◆ digitalWriteSrToAux()

void ShiftRegGPIOXpander::digitalWriteSrToAux	(	const uint8_t	srPin,
		const uint8_t	value )

Set a specific pin to either HIGH (0x01) or LOW (0x00) in the Auxiliary Buffer.

Parameters

srPin	a positive value indicating which pin to set. The valid range is 0 <= srPin <= (srQty*8)-1
value	Value to set for the indicated Pin

Attention: The pin modified in the Auxiliary will not be reflected on the pins of the GPIOXpander until the Auxiliary Buffer is copied into the Main Buffer and the latter one is flushed. This method main purpose is to modify more than one pin that must be modified at once and then proceed with the bool moveAuxToMain(bool)

Note: An alternative procedure in the line of the use of .print() and .println() methods is to invoke the several digitalWriteToAux() methods needed and then invoking a digitalWrite(const uint8_t, const uint8_t) for the last pin writing. This last method will take care of moving the Auxiliary to the Main, set that last pin value and flush the Main Buffer.

Here is the call graph for this function:

◆ discardAux()

void ShiftRegGPIOXpander::discardAux ( )

Deletes the Auxiliary Buffer.

Discards the contents of the Auxiliary Buffer, frees the memory allocated to it and nullyfies the corresponding memory pointer

Here is the caller graph for this function:

◆ getMainBuffPtr()

uint8_t * ShiftRegGPIOXpander::getMainBuffPtr ( )

Retrieves the pointer to the Main Buffer.

Returns: Pointer to the array of uint8_t holding the buffered shift registers values

Note: The returned array's length is equal to the number of shift registers set in daisy-chain, see uint8_t getSrQty() for information.

◆ getMaxPin()

uint8_t ShiftRegGPIOXpander::getMaxPin ( )

Return the greatest valid pin number.

The greatest valid pin number is directly related to the quantity of shift registers connected

Returns: uint8_t maxPin value

◆ getSrQty()

uint8_t ShiftRegGPIOXpander::getSrQty ( )

Return the quantity of shift registers composing the GPIOXtender object.

The value is passed as a parameter in the class constructor

Returns: uint8_t The number of shift registers represented by the object

◆ moveAuxToMain()

bool ShiftRegGPIOXpander::moveAuxToMain ( bool flushASAP = true )

Moves the data in the Auxiliary to the Main.

Moving the contents from the Auxiliary to the Main implies several steps:

Check the existence of the Auxiliary
Copy the contents from the Auxiliary to the Main
Delete the Auxiliary

Returns: The success of moving the data from the Auxiliar to the Main

Return values

true	There was an Auxiliary an it's value could be moved
false	There was no Auxiliary present, no data have been moved

Here is the call graph for this function:

Here is the caller graph for this function:

◆ sendAllSRCntnt()

bool ShiftRegGPIOXpander::sendAllSRCntnt ( )

Flushes the contents of the Buffer to the GPIO Expander pins.

The method will ensure the object buffer is updated -if there are modifications pending in the Auxiliary Buffer- enable the hardware to receive the information and invoke the needed methods to send serially the information required to each physical shift register.

Parameters

flushASAP indicates if the method should take care of sending the updated Main Buffer to the shift registers before exiting, or avoid doing so. The avoidance is related to the use of the method by another method or procedure that will take care of invoking a bool sendAllSRCntnt() by itself.

Returns: true if the operation succeeds

Note: The adoption of a boolean type return value is a consideration for future development that may consider the method operation to fail. At the time of this writing there's no conditions that would indicate otherwise

Warning: The Auxiliary buffer is a non permanent memory array, it will be deleted after moving it's contents to the Main Buffer

Here is the caller graph for this function:

◆ stampOverMain()

bool ShiftRegGPIOXpander::stampOverMain ( uint8_t * newCntntPtr )

Sets all of the output pins of the shift register to new provided values at once.

The method gives a tool to change all the shift registers pins in one operation instead of pin by pin. The method uses the provided pointer as a data source to overwrite the Main Buffer with the new contents.

Parameters

newCntntPtr A uint8_t* pointing the memory area containing the new values to be set to the buffer

Returns: Success in overwritting the Buffer

Return values

true	The Buffer was overwritten and the new contents flushed
false	The parameter passed was a nullptr/NULL and no overwritting was possible.

Attention: If there was an ongoing set of deferred pin modifications through the use of writes to the Auxiliary they will be all lost, as the first data consistency prevention of the method is to delete the Auxiliary.

Warning: As soon as the Main is overwritten with the new values, the Buffer will be flushed.

Here is the call graph for this function:

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ShiftRegGPIOXpander()

◆ ~ShiftRegGPIOXpander()

Member Function Documentation

◆ copyMainToAux()

◆ digitalReadSr()

◆ digitalWriteSr()

◆ digitalWriteSrMaskReset()

◆ digitalWriteSrMaskSet()

◆ digitalWriteSrToAux()

◆ discardAux()

◆ getMainBuffPtr()

◆ getMaxPin()

◆ getSrQty()

◆ moveAuxToMain()

◆ sendAllSRCntnt()

◆ stampOverMain()