DUDS
Distributed Update of Data from Something
duds::hardware::interface::DigitalPinSetAccess Class Reference

Provides access to multiple pins on a DigitalPort. More...

#include <DigitalPinSetAccess.hpp>

Inheritance diagram for duds::hardware::interface::DigitalPinSetAccess:
Collaboration diagram for duds::hardware::interface::DigitalPinSetAccess:

Public Member Functions

 DigitalPinSetAccess ()=default
 Constructs an access object with nothing to access. More...
 
 ~DigitalPinSetAccess ()
 Relinquish access on destruction. More...
 
bool canBeInput (unsigned int pos) const
 Returns true if the pin can operate as an input. More...
 
bool canBeOutput (unsigned int pos) const
 Returns true if the pin can operate as an output. More...
 
bool canFloat (unsigned int pos) const
 Returns true if the pin can provide a non-input high impedence state (or maybe allow input state?). More...
 
DigitalPinCap capabilities (unsigned int pos) const
 Returns the capabilities of the specified pin. More...
 
std::vector< DigitalPinCapcapabilities () const
 Returns the capabilities of all the pins in this set. More...
 
DigitalPinConfig configuration (unsigned int pos) const
 Returns the current configuration of the specified pin. More...
 
std::vector< DigitalPinConfigconfiguration () const
 Returns the current configuration all pins in this set. More...
 
bool exists (unsigned int pos) const
 Returns true if the given position is for an existent pin rather than a gap or a position past the end. More...
 
unsigned int globalId (unsigned int pos) const
 Returns the global pin ID of the pin at the given position inside this set of pins. More...
 
std::vector< unsigned int > globalIds () const
 Returns a vector of global pin IDs for the pins accessed by this object. More...
 
bool havePins () const
 Returns true if this object has been given any pins to access. More...
 
bool independentConfig () const
 Returns true if all pins on the port always have an independent configuration from all other pins. More...
 
bool input (unsigned int pos) const
 Samples the input state of a pin. More...
 
std::vector< bool > input () const
 Samples the input state of all the pins. More...
 
std::vector< bool > input (const std::vector< unsigned int > &pos) const
 Samples the input state of a subset of the pins. More...
 
bool isInput (unsigned int pos) const
 Returns true if the pin is configured as an input. More...
 
bool isOutput (unsigned int pos) const
 Returns true if the pin is configured as an output. More...
 
unsigned int localId (unsigned int pos) const
 Returns the local pin ID of the pin at the given position inside this set of pins. More...
 
const std::vector< unsigned int > & localIds () const
 Provides access to the internal vector of local pin IDs. More...
 
DigitalPinConfig modifyConfig (unsigned int pos, const DigitalPinConfig &conf) const
 Modifies the configuration of a pin. More...
 
void modifyConfig (const DigitalPinConfig &conf) const
 Sets the configuration for all the pins. More...
 
void modifyConfig (std::vector< DigitalPinConfig > &conf) const
 Sets the configuration for all the pins. More...
 
void modifyConfig (const std::vector< unsigned int > &pos, std::vector< DigitalPinConfig > &conf) const
 Sets the configuration for a subset of the pins. More...
 
DigitalPinSetAccessoperator= (DigitalPinSetAccess &&old) noexcept
 A move assignment. More...
 
void output (unsigned int pos, bool state) const
 Changes the output state of a pin. More...
 
void output (const std::vector< bool > &state) const
 Changes the output state of all the pins. More...
 
void output (bool state) const
 Changes the output state of all the pins. More...
 
void output (const std::vector< unsigned int > &pos, const std::vector< bool > &state) const
 Changes the output state of a subset of the pins. More...
 
DigitalPinRejectedConfiguration::Reason proposeConfig (unsigned int pos, DigitalPinConfig &conf) const
 Propose a new configuration for the given pin using the current configuration as the initial configuration. More...
 
DigitalPinRejectedConfiguration::Reason proposeConfig (unsigned int pos, DigitalPinConfig &proposed, DigitalPinConfig &initial) const
 Propose a new configuration for the given pin using a hypothetical given initial configuration. More...
 
bool proposeConfig (std::vector< DigitalPinConfig > &propConf, std::vector< DigitalPinConfig > &initConf, std::function< void(DigitalPinRejectedConfiguration::Reason)> insertReason=std::function< void(DigitalPinRejectedConfiguration::Reason)>())
 Propose a new configuration for the entire pin set using a hypothetical given initial configuration. More...
 
void retire () noexcept
 Relinquish access. More...
 
void retire (unsigned int pos)
 Relinquish access to a single pin. More...
 
bool simultaneousOperations () const
 True if the port supports operating on multiple pins simultaneously. More...
 
unsigned int size () const
 Returns the number of pins in this access object. More...
 
std::vector< unsigned int > subset (const std::vector< unsigned int > &pos) const
 Produces a vector with port local pin IDs that are a subset of the pins in this access object. More...
 
template<typename Int >
void write (Int val, int bits) const
 Writes out a number in binary to the pins. More...
 
template<typename Int >
void write (Int val) const
 Writes out a number in binary to the pins. More...
 
- Public Member Functions inherited from duds::hardware::interface::DigitalPinAccessBase
DigitalPortport () const
 Returns a pointer to the port that controls the pin(s) that are operated through this object. More...
 

Private Member Functions

 DigitalPinSetAccess (DigitalPort *port, std::vector< unsigned int > &&pids)
 Used by DigitalPort. More...
 
void reserveAdditional (unsigned int len)
 Reserves additional space in pins so that upcoming pushes onto the vector will not cause multiple memory reallocations. More...
 

Private Attributes

friend DigitalPort
 
std::vector< unsigned int > pinvec
 The port local pin IDs this object may use. More...
 

Additional Inherited Members

- Protected Member Functions inherited from duds::hardware::interface::DigitalPinAccessBase
 DigitalPinAccessBase ()
 Cannot be constructed using this base class, but allows the construction of a useless access object without a DigitalPort. More...
 
 DigitalPinAccessBase (DigitalPort *port)
 Initializes the port pointer. More...
 
 ~DigitalPinAccessBase ()=default
 Cannot be destructed using this base class to avoid the need for a virtual destructor. More...
 
DigitalPinAccessBaseoperator= (DigitalPinAccessBase &&old) noexcept
 Allows moving access objects. More...
 
void reset ()
 Loses the pointer to the DigitalPort rendering the access object useless. More...
 
- Protected Attributes inherited from duds::hardware::interface::DigitalPinAccessBase
PortData portdata
 Port specific information. More...
 

Detailed Description

Provides access to multiple pins on a DigitalPort.

This allows using multiple pins in a single operation.

Todo:
Allow a DigitalPort implementation to provide bit flags for use as a mask of the pins to access. The size of the mask will need to be dynamic, like std::vector<bool>. The mask will need to be available as integers with the flags, sort of like std::bitset<T>::to_ulong(). The size of the mask must not be limited to what fits in a single integer, unlike std::bitset.
Author
Jeff Jackowski

Definition at line 31 of file DigitalPinSetAccess.hpp.

Constructor & Destructor Documentation

◆ DigitalPinSetAccess() [1/2]

duds::hardware::interface::DigitalPinSetAccess::DigitalPinSetAccess ( DigitalPort port,
std::vector< unsigned int > &&  pids 
)
inlineprivate

Used by DigitalPort.

Definition at line 39 of file DigitalPinSetAccess.hpp.

◆ DigitalPinSetAccess() [2/2]

duds::hardware::interface::DigitalPinSetAccess::DigitalPinSetAccess ( )
default

Constructs an access object with nothing to access.

◆ ~DigitalPinSetAccess()

duds::hardware::interface::DigitalPinSetAccess::~DigitalPinSetAccess ( )
inline

Relinquish access on destruction.

Definition at line 56 of file DigitalPinSetAccess.hpp.

Member Function Documentation

◆ canBeInput()

bool duds::hardware::interface::DigitalPinSetAccess::canBeInput ( unsigned int  pos) const
inline

Returns true if the pin can operate as an input.

Parameters
posThe position of the pin in this set.

Definition at line 419 of file DigitalPinSetAccess.hpp.

◆ canBeOutput()

bool duds::hardware::interface::DigitalPinSetAccess::canBeOutput ( unsigned int  pos) const
inline

Returns true if the pin can operate as an output.

Parameters
posThe position of the pin in this set.

Definition at line 426 of file DigitalPinSetAccess.hpp.

◆ canFloat()

bool duds::hardware::interface::DigitalPinSetAccess::canFloat ( unsigned int  pos) const
inline

Returns true if the pin can provide a non-input high impedence state (or maybe allow input state?).

Parameters
posThe position of the pin in this set.

Definition at line 438 of file DigitalPinSetAccess.hpp.

◆ capabilities() [1/2]

DigitalPinCap duds::hardware::interface::DigitalPinSetAccess::capabilities ( unsigned int  pos) const
inline

Returns the capabilities of the specified pin.

Parameters
posThe position of the pin in this set.

Definition at line 137 of file DigitalPinSetAccess.hpp.

◆ capabilities() [2/2]

std::vector<DigitalPinCap> duds::hardware::interface::DigitalPinSetAccess::capabilities ( ) const
inline

Returns the capabilities of all the pins in this set.

Any gaps in the set (ID is -1) will have a value of DigitalPinCap::Nonexistent.

Definition at line 145 of file DigitalPinSetAccess.hpp.

Referenced by canBeInput(), canBeOutput(), and canFloat().

◆ configuration() [1/2]

DigitalPinConfig duds::hardware::interface::DigitalPinSetAccess::configuration ( unsigned int  pos) const
inline

Returns the current configuration of the specified pin.

Parameters
posThe position of the pin in this set.

Definition at line 152 of file DigitalPinSetAccess.hpp.

◆ configuration() [2/2]

std::vector<DigitalPinConfig> duds::hardware::interface::DigitalPinSetAccess::configuration ( ) const
inline

Returns the current configuration all pins in this set.

Any gaps in the set (ID is -1) will have a configuration of DigitalPinConfig::OperationNoChange.

Definition at line 160 of file DigitalPinSetAccess.hpp.

Referenced by isInput(), and isOutput().

◆ exists()

bool duds::hardware::interface::DigitalPinSetAccess::exists ( unsigned int  pos) const
inline

Returns true if the given position is for an existent pin rather than a gap or a position past the end.

Parameters
posThe position to check.

Definition at line 105 of file DigitalPinSetAccess.hpp.

◆ globalId()

unsigned int duds::hardware::interface::DigitalPinSetAccess::globalId ( unsigned int  pos) const
inline

Returns the global pin ID of the pin at the given position inside this set of pins.

Parameters
posThe position of the pin in this set.

Definition at line 129 of file DigitalPinSetAccess.hpp.

Referenced by capabilities(), configuration(), input(), modifyConfig(), output(), proposeConfig(), and subset().

◆ globalIds()

std::vector<unsigned int> duds::hardware::interface::DigitalPinSetAccess::globalIds ( ) const
inline

Returns a vector of global pin IDs for the pins accessed by this object.

Definition at line 91 of file DigitalPinSetAccess.hpp.

◆ havePins()

bool duds::hardware::interface::DigitalPinSetAccess::havePins ( ) const
inline

Returns true if this object has been given any pins to access.

Definition at line 97 of file DigitalPinSetAccess.hpp.

Referenced by retire().

◆ independentConfig()

bool duds::hardware::interface::DigitalPinSetAccess::independentConfig ( ) const
inline

Returns true if all pins on the port always have an independent configuration from all other pins.

Definition at line 398 of file DigitalPinSetAccess.hpp.

◆ input() [1/3]

bool duds::hardware::interface::DigitalPinSetAccess::input ( unsigned int  pos) const
inline

Samples the input state of a pin.

Parameters
posThe position of the pin in this set.
Exceptions
PinWrongDirectionThis pin is not configured as an input.

Definition at line 315 of file DigitalPinSetAccess.hpp.

◆ input() [2/3]

std::vector<bool> duds::hardware::interface::DigitalPinSetAccess::input ( ) const
inline

Samples the input state of all the pins.

Returns
The input from the pins.
Exceptions
PinWrongDirectionNot all the pins are not configured as an input.

Definition at line 323 of file DigitalPinSetAccess.hpp.

◆ input() [3/3]

std::vector<bool> duds::hardware::interface::DigitalPinSetAccess::input ( const std::vector< unsigned int > &  pos) const
inline

Samples the input state of a subset of the pins.

Parameters
posA vector of the pins to sample specified by their position in this pin set.
Returns
The input from the pins in the same order as pos.
Exceptions
PinWrongDirectionA pin in pos is not configured as an input.

Definition at line 333 of file DigitalPinSetAccess.hpp.

◆ isInput()

bool duds::hardware::interface::DigitalPinSetAccess::isInput ( unsigned int  pos) const
inline

Returns true if the pin is configured as an input.

Parameters
posThe position of the pin in this set.

Definition at line 405 of file DigitalPinSetAccess.hpp.

◆ isOutput()

bool duds::hardware::interface::DigitalPinSetAccess::isOutput ( unsigned int  pos) const
inline

Returns true if the pin is configured as an output.

Parameters
posThe position of the pin in this set.

Definition at line 412 of file DigitalPinSetAccess.hpp.

◆ localId()

unsigned int duds::hardware::interface::DigitalPinSetAccess::localId ( unsigned int  pos) const
inline

Returns the local pin ID of the pin at the given position inside this set of pins.

Parameters
posThe position of the pin in this set.

Definition at line 120 of file DigitalPinSetAccess.hpp.

◆ localIds()

const std::vector<unsigned int>& duds::hardware::interface::DigitalPinSetAccess::localIds ( ) const
inline

Provides access to the internal vector of local pin IDs.

Definition at line 84 of file DigitalPinSetAccess.hpp.

Referenced by duds::hardware::interface::linux::GpioDevPort::madeAccess().

◆ modifyConfig() [1/4]

DigitalPinConfig duds::hardware::interface::DigitalPinSetAccess::modifyConfig ( unsigned int  pos,
const DigitalPinConfig conf 
) const
inline

Modifies the configuration of a pin.

If the port implementation is a derivative of DigitalPortDependentPins, the change may affect multiple pins, and the configuration of other pins may prevent the requested change.

Parameters
posThe position of the pin in this set.
confThe requested new configuration.
Returns
The actual new configuration.

Definition at line 265 of file DigitalPinSetAccess.hpp.

Referenced by duds::hardware::devices::displays::HD44780::preparePins(), and duds::hardware::devices::displays::ST7920::preparePins().

◆ modifyConfig() [2/4]

void duds::hardware::interface::DigitalPinSetAccess::modifyConfig ( const DigitalPinConfig conf) const

Sets the configuration for all the pins.

Bug:
The set may not have a gap (pin ID -1). This will result in a DigitalPinConfigError exception being thrown.
Parameters
confThe configuration to set for all pins.
Exceptions
DigitalPinConfigError

Definition at line 61 of file DigitalPinSetAccess.cpp.

◆ modifyConfig() [3/4]

void duds::hardware::interface::DigitalPinSetAccess::modifyConfig ( std::vector< DigitalPinConfig > &  conf) const
inline

Sets the configuration for all the pins.

Parameters
confThe new configuration. The vector makes a parallel data structure with the pins stroed in this object. If a gap exists (ID is -1), the configuration must be set to DigitalPinConfig::OperationNoChange.
Exceptions
DigitalPinConfigRangeErrorThe size of conf is not the same as size().
DigitalPinConfigError

Definition at line 289 of file DigitalPinSetAccess.hpp.

◆ modifyConfig() [4/4]

void duds::hardware::interface::DigitalPinSetAccess::modifyConfig ( const std::vector< unsigned int > &  pos,
std::vector< DigitalPinConfig > &  conf 
) const
inline

Sets the configuration for a subset of the pins.

Parameters
posA vector of the pins to use specified by their position in this pin set.
confThe new configuration. The vector makes a parallel data structure with the specified subset of pins. If a gap exists (ID is -1), the configuration must be set to DigitalPinConfig::OperationNoChange.
Exceptions
DigitalPinConfigRangeErrorThe size of conf is not the same as the size of pos.
DigitalPinConfigError

Definition at line 304 of file DigitalPinSetAccess.hpp.

◆ operator=()

DigitalPinSetAccess & duds::hardware::interface::DigitalPinSetAccess::operator= ( DigitalPinSetAccess &&  old)
noexcept

A move assignment.

This requires a call to DigitalPort::updateAccess(), which needs to synchronize on its internal data. As a result, move assignments are not speedy. However, they assure pin access is transfered without being lost.

Definition at line 21 of file DigitalPinSetAccess.cpp.

Referenced by ~DigitalPinSetAccess().

◆ output() [1/4]

void duds::hardware::interface::DigitalPinSetAccess::output ( unsigned int  pos,
bool  state 
) const
inline

Changes the output state of a pin.

If the pin is not currently configured to output, the configuration will not change, but the new output state will be used when the pin becomes an output in the future.

Parameters
posThe position of the pin in this set.
stateThe new output state.

Definition at line 343 of file DigitalPinSetAccess.hpp.

Referenced by duds::hardware::devices::displays::HD44780::initialize(), duds::hardware::devices::displays::ST7920::initialize(), and output().

◆ output() [2/4]

void duds::hardware::interface::DigitalPinSetAccess::output ( const std::vector< bool > &  state) const
inline

Changes the output state of all the pins.

If a pin is not currently configured to output, the configuration will not change, but the new output state will be used when the pin becomes an output in the future.

Parameters
stateThe new output states. The vector makes a parallel data structure with the pins in this set (pinvec). Gaps (ID of -1) are not presently supported.

Definition at line 354 of file DigitalPinSetAccess.hpp.

◆ output() [3/4]

void duds::hardware::interface::DigitalPinSetAccess::output ( bool  state) const

Changes the output state of all the pins.

If a pin is not currently configured to output, the configuration will not change, but the new output state will be used when the pin becomes an output in the future.

Bug:
The set may not have a gap (pin ID -1). This will result in a DigitalPinConfigError exception being thrown.
Parameters
stateThe new output state for all pins.

Definition at line 66 of file DigitalPinSetAccess.cpp.

◆ output() [4/4]

void duds::hardware::interface::DigitalPinSetAccess::output ( const std::vector< unsigned int > &  pos,
const std::vector< bool > &  state 
) const
inline

Changes the output state of a subset of the pins.

If a pin is not currently configured to output, the configuration will not change, but the new output state will be used when the pin becomes an output in the future.

Parameters
posA vector of the pins to use specified by their position in this pin set.
stateThe new output states. The vector makes a parallel data structure with the specified subset of pins. Gaps (ID of -1) are not presently supported.

Definition at line 377 of file DigitalPinSetAccess.hpp.

◆ proposeConfig() [1/3]

DigitalPinRejectedConfiguration::Reason duds::hardware::interface::DigitalPinSetAccess::proposeConfig ( unsigned int  pos,
DigitalPinConfig conf 
) const
inline

Propose a new configuration for the given pin using the current configuration as the initial configuration.

The pin's configuration is not changed; this only checks for a valid supported change.

Parameters
confThe proposed configuration.
posThe position of the pin in this set.
Returns
The reason the configuration is bad, or DigitalPinRejectedConfiguration::NotRejected if it can be used.

Definition at line 185 of file DigitalPinSetAccess.hpp.

◆ proposeConfig() [2/3]

DigitalPinRejectedConfiguration::Reason duds::hardware::interface::DigitalPinSetAccess::proposeConfig ( unsigned int  pos,
DigitalPinConfig proposed,
DigitalPinConfig initial 
) const
inline

Propose a new configuration for the given pin using a hypothetical given initial configuration.

The pin's configuration is not changed; this only checks for a valid supported change.

Parameters
proposedThe proposed configuration.
initialThe initial configuration. It should be a valid configuration for the pin and port, but it doesn't need to be the current configuration.
posThe position of the pin in this set.
Returns
The reason the configuration is bad, or DigitalPinRejectedConfiguration::NotRejected if it can be used.

Definition at line 204 of file DigitalPinSetAccess.hpp.

◆ proposeConfig() [3/3]

bool duds::hardware::interface::DigitalPinSetAccess::proposeConfig ( std::vector< DigitalPinConfig > &  propConf,
std::vector< DigitalPinConfig > &  initConf,
std::function< void(DigitalPinRejectedConfiguration::Reason)>  insertReason = std::function<void(DigitalPinRejectedConfiguration::Reason)>() 
)
inline

Propose a new configuration for the entire pin set using a hypothetical given initial configuration.

The configuration is not changed; this only checks for a valid supported change.

Parameters
propConfThe proposed configuration.
initConfThe initial configuration. It should be a valid configuration for the pins and port, but it doesn't need to be the current configuration.
insertReasonA function that, if specified, will be called for each pin, in the order specified by this set, with the rejection reason for that pin. The reason will be DigitalPinRejectedConfiguration::NotRejected if the pin's proposed configuration is good. The function is optional.
Returns
True if the proposed configuration is good. False if there was any rejection.

Definition at line 228 of file DigitalPinSetAccess.hpp.

◆ reserveAdditional()

void duds::hardware::interface::DigitalPinSetAccess::reserveAdditional ( unsigned int  len)
private

Reserves additional space in pins so that upcoming pushes onto the vector will not cause multiple memory reallocations.

Parameters
lenThe anticipated number of items about to be added.

Definition at line 14 of file DigitalPinSetAccess.cpp.

Referenced by duds::hardware::interface::DigitalPort::access(), and DigitalPinSetAccess().

◆ retire() [1/2]

void duds::hardware::interface::DigitalPinSetAccess::retire ( )
noexcept

◆ retire() [2/2]

void duds::hardware::interface::DigitalPinSetAccess::retire ( unsigned int  pos)

Relinquish access to a single pin.

Good idea? Leave -1 in its spot, unless at end which can be removed.

Parameters
posThe pin's position within the access object.

◆ simultaneousOperations()

bool duds::hardware::interface::DigitalPinSetAccess::simultaneousOperations ( ) const
inline

True if the port supports operating on multiple pins simultaneously.

If false, the pins may be modified on over a period of time in an implementation defined order.

Definition at line 391 of file DigitalPinSetAccess.hpp.

◆ size()

unsigned int duds::hardware::interface::DigitalPinSetAccess::size ( ) const
inline

Returns the number of pins in this access object.

The count includes pins set as -1; gaps in the pins to access.

Definition at line 112 of file DigitalPinSetAccess.hpp.

◆ subset()

std::vector< unsigned int > duds::hardware::interface::DigitalPinSetAccess::subset ( const std::vector< unsigned int > &  pos) const

Produces a vector with port local pin IDs that are a subset of the pins in this access object.

Parameters
posThe pins to find specified by their position in this pin set. Values of -1 are copied into the result to maintain any gaps.
Returns
The pins identified by their port local IDs.
Warning
This function does not check for repeated values.
Exceptions
PinDoesNotExistA specified position is outside the bounds of this set.

Definition at line 44 of file DigitalPinSetAccess.cpp.

Referenced by configuration(), input(), modifyConfig(), and output().

◆ write() [1/2]

template<typename Int >
void duds::hardware::interface::DigitalPinSetAccess::write ( Int  val,
int  bits 
) const
inline

Writes out a number in binary to the pins.

The LSb is given to the pin at position 0, the next bit to position 1, and so on. As with the other output functions, the pin configuration will not be changed.

Template Parameters
IntThe integer type used to hold the number.
Parameters
valThe number to write.
bitsThe number of bits to write. This may not exceed the number of pins in this set. If it exceeds the number of bits in Int, the more significant bits will be zero.
Exceptions
PinRangeErrorThe number of bits to write is less than 1 or greater than the number of pins in this set.
DigitalPinNumericRangeErrorThe given value is too large to fit in the requested number of bits.
Bug:
Will fail for unsigned types with negative values.

Definition at line 456 of file DigitalPinSetAccess.hpp.

Referenced by duds::hardware::devices::displays::HD44780::sendByte(), duds::hardware::devices::displays::ST7920::sendByte(), and write().

◆ write() [2/2]

template<typename Int >
void duds::hardware::interface::DigitalPinSetAccess::write ( Int  val) const
inline

Writes out a number in binary to the pins.

The LSb is given to the pin at position 0, the next bit to position 1, and so on. All the pins in this set will be used. As with the other output functions, the pin configuration will not be changed.

Template Parameters
IntThe integer type used to hold the number.
Parameters
valThe number to write.

Definition at line 499 of file DigitalPinSetAccess.hpp.

Member Data Documentation

◆ DigitalPort

friend duds::hardware::interface::DigitalPinSetAccess::DigitalPort
private

Definition at line 47 of file DigitalPinSetAccess.hpp.

◆ pinvec

std::vector<unsigned int> duds::hardware::interface::DigitalPinSetAccess::pinvec
private

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