SRGXVPort Class Reference

A class that models Virtual Ports from the resources provided by a ShiftRegGPIOXpander object. More...

#include <ShiftRegGPIOXpander_AVR.h>

Inheritance diagram for SRGXVPort:

Collaboration diagram for SRGXVPort:

Public Member Functions
	~SRGXVPort ()
	Class destructor.
bool	begin (uint16_t initCntnt)
	Begins the virtual port, setting the initial state of the VPort pins.
int	digitalRead (const uint8_t &srPin)
	Returns the state of the requested pin of the virtual port (SRGXVPort).
uint8_t	digitalReadSr (const uint8_t &srPin)
	Reads the state of a specific pin in the virtual port.
void	digitalWrite (const uint8_t &srPin, const uint8_t &value)
	Set a specific pin to either HIGH (0x01) or LOW (0x00).
bool	digitalWriteSr (const uint8_t &srPin, const uint8_t &value)
	Sets the state of a specific pin in the virtual port, either HIGH (0x01/Set) or LOW (0x00/Reset).
bool	flipBit (const uint8_t &srPin)
	Toggles the state of a specific pin in the virtual port.
ShiftRegGPIOXpander *	getSRGXPtr ()
	Returns a pointer to the ShiftRegGPIOXpander object that provides the resources for the virtual port.
uint8_t *	getStampMask ()
	Returns a pointer to the mask built to stamp the virtual port over the Main Buffer of the ShiftRegGPIOXpander object.
uint16_t	getVPortMaxVal ()
	Returns the maximum value that can be set in the virtual port.
uint16_t	readPort ()
	Reads the state of the virtual port as an unsigned integer value.
bool	resetBit (const uint8_t &srPin)
	Sets the state of a pin to LOW (0x00/Reset) in the virtual port.
bool	setBit (const uint8_t &srPin)
	Sets the state of a pin to HIGH (0x01/Set) in the virtual port.
bool	writePort (uint16_t newPortVal)
	Sets the state of the pins composing the SRGXVPort in the Main Buffer (i.e. the GPIOXpander pins) according to the provided value.
Public Member Functions inherited from ShiftRegGPIOXpander
	ShiftRegGPIOXpander ()
	Class default constructor.
	ShiftRegGPIOXpander (uint8_t ds, uint8_t sh_cp, uint8_t st_cp, uint8_t srQty=1)
	Class constructor.
	~ShiftRegGPIOXpander ()
	Class destructor.
bool	begin (uint8_t *initCntnt=nullptr)
	GPIOXpander object setup and activation.
bool	copyMainToAux (const bool &overWriteIfExists=true)
	Copies the Buffer content to the Auxiliary Buffer.
SRGXVPort	createSRGXVPort (const uint8_t &strtPin, const uint8_t &pinsQty)
	Instantiate a SRGXVPort object.
bool	digitalReadSgmntSr (const uint8_t &strtPin, const uint8_t &pinsQty, uint16_t &bffrSgmnt)
	Returns a 16-bits value containing a zero-based segment of the Main Buffer.
int	digitalRead (const uint8_t &srPin)
	Returns the state of the requested pin of the ShiftRegGPIOXpander.
uint8_t	digitalReadSr (const uint8_t &srPin)
	Returns the state of the requested pin.
bool	digitalToggleSr (const uint8_t &srPin)
	Toggles the state of a specific pin.
bool	digitalToggleSrAll ()
	Toggles the state of all the pins.
bool	digitalToggleSrMask (uint8_t *toggleMask)
	Toggles the state of the pins in the Main Buffer according to the provided mask.
bool	digitalToggleSrToAux (const uint8_t &srPin)
	Toggles the state of a specific pin in the Auxiliary Buffer.
void	digitalWrite (const uint8_t &srPin, const uint8_t &value)
	Set a specific pin to either HIGH (0x01) or LOW (0x00).
bool	digitalWriteSr (const uint8_t &srPin, const uint8_t &value)
	Set a specific pin to either HIGH (0x01) or LOW (0x00).
bool	digitalWriteSrAllReset ()
	Sets all the pins to LOW (0x00/Reset).
bool	digitalWriteSrAllSet ()
	Sets all the pins to HIGH (0x01).
bool	digitalWriteSrMaskReset (uint8_t *resetMask)
	Modifies the Main buffer contents by resetting simultaneously certain pins.
bool	digitalWriteSrMaskSet (uint8_t *setMask)
	Modifies the Main buffer contents by setting simultaneously certain pins.
bool	digitalWriteSrToAux (const uint8_t srPin, const uint8_t value)
	Set a specific pin to either HIGH (0x01) or LOW (0x00) in the Auxiliary Buffer.
bool	discardAux ()
	Deletes the Auxiliary Buffer.
void	end ()
	Method provided for ending any relevant activation procedures made by the begin(uint8_t*) method.
bool	flipBit (const uint8_t &srPin)
	Toggles the state of a specific pin in the Main Buffer.
uint8_t *	getMainBuffPtr ()
	Retrieves the pointer to the Main Buffer.
uint8_t	getMaxSRGXPin ()
	Return the greatest valid pin number.
uint8_t	getSrQty ()
	Return the quantity of shift registers composing the GPIOXtender object.
bool	isValid (SRGXVPort &VPort)
	Checks if the provided SRGXVPort object is valid.
bool	moveAuxToMain ()
	Moves the data in the Auxiliary to the Main.
bool	resetBit (const uint8_t &srPin)
	Sets a specific pin to LOW (0x00/Reset) in the Main Buffer.
bool	setBit (const uint8_t &srPin)
	Sets a specific pin to HIGH (0x01/Set) in the Main Buffer.
bool	stampMaskOverMain (uint8_t *maskPtr, uint8_t *valsPtr)
	Sets the value of several pins, scattered or contiguous, in the Main Buffer, according to the provided mask and values.
bool	stampOverMain (uint8_t *newCntntPtr)
	Sets all of the output pins of the shift register to new provided values at once.
bool	stampSgmntOverMain (uint8_t *newSgmntPtr, const uint8_t &strtPin, const uint8_t &pinsQty)
	Sets the value of a number of consecutive pins (the segment) in the Main Buffer.

Protected Member Functions
	SRGXVPort ()
	Default constructor.
	SRGXVPort (ShiftRegGPIOXpander *SRGXPtr, uint8_t strtPin, uint8_t pinsQty)
	Class constructor.

Friends
class	ShiftRegGPIOXpander

Detailed Description

A class that models Virtual Ports from the resources provided by a ShiftRegGPIOXpander object.

The Virtual Ports are sets of pins that can be used as a group, and are defined by the user. The pins are a contiguous subset of the pins available in the ShiftRegGPIOXpander object. The Virtual Ports main advantage is to provide a means to focus on a group of pins that are somehow associated: are meant to manage the communications with a specific device or group of devices, manage different related signals, etc.

The class objects provide the means to translate the pin numbers from the Virtual Port to the real pins in the ShiftRegGPIOXpander object.

A simple example use case is a crossroads traffic light controller, four different traffic lights, one for each direction, totalling 12 pins, might be solved by using a ShiftRegGPIOXpander object with 2 shift registers. Using the ShiftRegGPIOXpander object directly would require the user to remember that the first pin of the first traffic light is pin 0, the second traffic light starts at pin 3, and so on. Using a SRGXVPort object for each traffic light would allow the user to create a virtual port for each traffic light. Pin 0 of each virtual port would be the red light, pin 1 would be the yellow light, and pin 2 would be the green light. The user would then be able to use the virtual port objects to manipulate the traffic lights without having to convert each light to the real pin numbers in the ShiftRegGPIOXpander object, and make the addition of new traffic lights easier, as the managing methods would be the same for each virtual port.

Note

The SRGXVPort class has set a maximum of 16 pins that can be used in each virtual port. The number of pins assigned will be checked against the maximum number of pins available in the ShiftRegGPIOXpander object.

The open possibility of creating virtual ports that overlap pins in the ShiftRegGPIOXpander object is not considered a problem, even if one virtual port includes all the pins of another virtual port. Take as an example the case of the x86 Intel processors, where the 64-bits registers are a superset of the 32-bits registers, the 32-bits registers are a superset of the 16-bits registers and the 16-bits are superset of 8-bits registers, with the possibility of managing the 64 bits at once or subsets by using the corresponding designations provided. The user can manage the virtual ports as they see fit, but the library will not provide any mechanism to prevent overlapping virtual ports.

Warning

The SRGXVPort class uses the buffer memory provided by the ShiftRegGPIOXpander object to handle the pins state. The user might decide to use the SRGXVPort objects to manipulate the pins state, or use the ShiftRegGPIOXpander object directly. The classes are designed to allow the user to use both methods, but the user must be aware that the state of a pin might be modified by the shiftRegGPIOXpander object directly, and by any and all the SRGXPVPort objects that same pin is part of.

Constructor & Destructor Documentation

SRGXVPort()

SRGXVPort::SRGXVPort ( ShiftRegGPIOXpander * SRGXPtr, uint8_t strtPin, uint8_t pinsQty )

protected

Class constructor.

This constructor will instantiate a virtual port object that will allow the user to manipulate a subset of the pins available in the ShiftRegGPIOXpander object as a unit. The main driving concept is that the contiguous subset of pins are logically related, and thus might benefit of the chance to be manipulated as a single entity. The pins are numbered from 0 to pinsQty - 1, where pinsQty is the number of pins that compose the virtual port.

Parameters

SRGXPtr	A pointer to the ShiftRegGPIOXpander object that will provide the resources (pins) for the virtual port.
strtPin	The pin number from the ShiftRegGPIOXpander to be used as the first pin (pin 0) of the virtual port.
pinsQty	The number of pins that will compose the virtual port.

Note

This constructor is not accesible but through the ShiftRegGPIOXpander class, as it is a protected constructor. The user should use the createSRGXVPort(uint8_t&, uint8_t&) method to create a SRGXVPort object.

Attention

After using the constructor and to ensure a SRGXVport object was correctly instantiated use the ShiftRegGPIOXpander::isValid(SRGXVPort &) method.

Here is the call graph for this function:

Member Function Documentation

begin()

bool SRGXVPort::begin

(

uint16_t

initCntnt

)

Begins the virtual port, setting the initial state of the VPort pins.

Parameters

initCntnt

Initial value to be loaded into the virtual port pins.

digitalRead()

int SRGXVPort::digitalRead

(

const uint8_t &

srPin

)

Returns the state of the requested pin of the virtual port (SRGXVPort).

Parameters

srPin

Pin whose current value is required.

Returns

The state value of the requested pin, either HIGH (0x01/Set) or LOW (0x00/Reset)

Return values

0x00	The pin state was LOW
0x01	The pin state was HIGH
-1	ERROR, the pin number was beyond implemented number of pins of the SRGXVPort object.

Note

The method's name, digitalRead(), is identical to the Arduino's digitalRead() method to facilitate the addition of this library with the least amount of changes to existing code, just adding the SRGXVPort object instantitated before existing digitalRead() calls and providing the correct pin number as parameter.

Here is the call graph for this function:

digitalReadSr()

uint8_t SRGXVPort::digitalReadSr

(

const uint8_t &

srPin

)

Reads the state of a specific pin in the virtual port.

Parameters

srPin

Pin number whose state is to be read. The valid range is 0 <= srPin < _pinsQty.

Returns

The state value of the requested pin, either HIGH (0x01/Set) or LOW (0x00/Reset).

Here is the caller graph for this function:

digitalWrite()

void SRGXVPort::digitalWrite	(	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 < _pinsQty()
value	Value to set the indicated Pin.

Note

The method's name, digitalWrite(), is identical to the Arduino's digitalWrite() method to facilitate the addition of this library with the least amount of changes to existing code, just adding the SRGXVPort object instantitated before existing digitalRead() calls and providing the correct pin number as parameter.

Here is the call graph for this function:

digitalWriteSr()

bool SRGXVPort::digitalWriteSr	(	const uint8_t &	srPin,
		const uint8_t &	value )

Sets the state of a specific pin in the virtual port, either HIGH (0x01/Set) or LOW (0x00/Reset).

Parameters

srPin	Pin number whose state is to be set. The valid range is 0 <= srPin < _pinsQty.
value	The value to set the pin to, either HIGH (0x01/Set) or LOW (0x00/Reset).

Returns

The success of the operation.

Return values

true	The pin was in the valid range and was set in the Main Buffer, the change was flushed to the GPIO pin.
false	The pin was not in the valid range, and no action was taken.

Here is the caller graph for this function:

flipBit()

bool SRGXVPort::flipBit

(

const uint8_t &

srPin

)

Toggles the state of a specific pin in the virtual port.

If the pin state was HIGH (0x01/Set) it will be set to LOW (0x00/Reset), and vice versa. The method will flush the buffer, so the change will be reflected on the GPIO pin.

Parameters

srPin

Pin number whose state is to be toggled. The valid range is 0 <= srPin < _pinsQty.

Returns

The success of the operation.

Return values

true	The pin was in the valid range and was toggled in the Main Buffer.
false	The pin was not in the valid range, and no action was taken.

getSRGXPtr()

ShiftRegGPIOXpander * SRGXVPort::getSRGXPtr

(

)

Returns a pointer to the ShiftRegGPIOXpander object that provides the resources for the virtual port.

Returns

A ShiftRegGPIOXpander* pointer to the object that provides the resources for the virtual port.

Warning

The method might return a nullptr if the object constructor failed!! Is important to check the parameters passed to create the object were right and resulted in a valid object by using the ShiftRegGPIOXpander::isValid(SRGXVPort &) method.

Here is the caller graph for this function:

getStampMask()

uint8_t * SRGXVPort::getStampMask

(

)

Returns a pointer to the mask built to stamp the virtual port over the Main Buffer of the ShiftRegGPIOXpander object.

The mask is compatible with the stampMaskOverMain(uint8_t*, uint8_t*) method, and might be used to modify the Main Buffer of the ShiftRegGPIOXpander object by setting or resetting the pins in the virtual port.

Returns

uint8_t* A pointer to the stamp mask for the bits corresponding to the SRGXVPort and their positions.

getVPortMaxVal()

uint16_t SRGXVPort::getVPortMaxVal

(

)

Returns the maximum value that can be set in the virtual port.

The maximum value is calculated as (2^pinsQty) - 1, where pinsQty is the number of pins that compose the virtual port. The value is used to enforce the range of valid values that can be set in the virtual port.

Returns

uint16_t Maximum value that can be set in the virtual port.

readPort()

uint16_t SRGXVPort::readPort

(

)

Reads the state of the virtual port as an unsigned integer value.

The method reads the state of all the pins in the virtual port as a pinsQty binary number and returns the value as an unsigned integer. The bits in the returned value are ordered from the least significant bit (LSB) to the most significant bit (MSB), where the LSB corresponds to pin 0 of the virtual port and the MSB corresponds to pin pinsQty - 1.

Returns

The state of the virtual port as an unsigned integer value, where each bit represents the state of a pin in the virtual port.

Here is the call graph for this function:

resetBit()

bool SRGXVPort::resetBit

(

const uint8_t &

srPin

)

Sets the state of a pin to LOW (0x00/Reset) in the virtual port.

Parameters

srPin

The pin number whose state is to be reset. The valid range is 0 <= srPin < _pinsQty.

Returns

true The pin was in the valid range and was reset to LOW (0x00/Reset) in the Main Buffer.

false The pin was not in the valid range, and no action was taken.

setBit()

bool SRGXVPort::setBit

(

const uint8_t &

srPin

)

Sets the state of a pin to HIGH (0x01/Set) in the virtual port.

Parameters

srPin

The pin number whose state is to be set. The valid range is 0 <= srPin < _pinsQty.

Returns

true The pin was in the valid range and was set to HIGH (0x01/Set) in the Main Buffer.

false The pin was not in the valid range, and no action was taken.

writePort()

bool SRGXVPort::writePort

(

uint16_t

newPortVal

)

Sets the state of the pins composing the SRGXVPort in the Main Buffer (i.e. the GPIOXpander pins) according to the provided value.

The value is provided as an unsigned integer, where each bit represents the state of a pin in the virtual port. The bits are ordered from the least significant bit (LSB) to the most significant bit (MSB), where the LSB corresponds to pin 0 of the virtual port and the MSB corresponds to pin pinsQty - 1. The range of valid values is 0 <= newPortVal <= getVPortMaxVal().

Parameters

newPortVal

The value to set the virtual port to, where each bit represents the state of a pin in the virtual port. The valid range is 0 <= newPortVal <= _vportMaxVal.

Returns

A boolean indicating the success of the operation.

Return values

true	The value passed as parameter was in the valid range holdable by the port and the VPort pins value was set in the Main Buffer, the change was flushed to the GPIO pins.
false	The value passed as parameter was not in the valid range , and no action was taken.