A synchronous serial implementation using DigitalPin objects. More...

#include <DigitalPinMasterSyncSerial.hpp>

Inheritance diagram for duds::hardware::interface::DigitalPinMasterSyncSerial:

Collaboration diagram for duds::hardware::interface::DigitalPinMasterSyncSerial:

Public Member Functions
	DigitalPinMasterSyncSerial ()

	DigitalPinMasterSyncSerial (Flags flags, int period)

	DigitalPinMasterSyncSerial (const DigitalPinSet &pset, Flags flags, int period)

	DigitalPinMasterSyncSerial (DigitalPinSet &&pset, Flags flags, int period)

	~DigitalPinMasterSyncSerial ()

void	clockFrequency (unsigned int freq)
	Changes the maximum clock frequency. More...

void	clockPeriod (unsigned int nanos)
	Changes the minimum clock period. More...

void	setChipSelect (const ChipSelect &cs)
	Sets the ChipSelect object to use for selections. More...

void	setPins (const PinIndex &pi)
	Sets the pins to use based on names already set in the PinIndex. More...

void	setPins (const std::shared_ptr< PinIndex > &pi)
	Sets the pins to use based on names already set in the PinIndex. More...

void	setPins (const std::shared_ptr< PinStore > &store, unsigned int clock, unsigned int data)
	Sets the pins to use for half-duplex operation. More...

void	setPins (const std::shared_ptr< PinStore > &store, unsigned int clock, unsigned int output, unsigned int input)
	Sets the pins to use for full-duplex operation. More...

Public Member Functions inherited from duds::hardware::interface::MasterSyncSerial
	MasterSyncSerial ()
	Builds a MasterSyncSerial with an invalid clock period and all configuration flags clear. More...

	MasterSyncSerial (Flags flags, int period)
	Builds a MasterSyncSerial object. More...

virtual	~MasterSyncSerial ()=0
	Derived class destructors should assure that communication has stopped by calling forceClose(). More...

std::unique_ptr< MasterSyncSerialAccess >	access ()
	Obtain access for communication; transitions the object from the ready (MssReady) to the open (MssOpen) state. More...

void	access (MasterSyncSerialAccess &acc)
	Obtain access for communication; transitions the object from the ready (MssReady) to the open (MssOpen) state. More...

std::unique_ptr< MasterSyncSerialAccess >	accessStart ()
	Obtain access for communication; transitions the object from the ready (MssReady) to the communicating (MssCommunicating) state. More...

void	accessStart (MasterSyncSerialAccess &acc)
	Obtain access for communication; transitions the object from the ready (MssReady) to the communicating (MssCommunicating) state. More...

unsigned int	clockFrequency () const noexcept
	Computes and returns the maximum clock frequency in Hertz. More...

unsigned int	clockPeriod () const noexcept
	Returns the minimum clock period in nanoseconds. More...

Flags	configFlags () const noexcept
	Returns the current set of configuration flags. More...

virtual void	converse (Conversation &conv)
	Has a half-duplex Conversation with the connected device. More...

bool	inUse () const noexcept
	Returns true when this serial interface is in use by checking for the existence of an access object. More...

Public Member Functions inherited from duds::hardware::interface::Conversationalist
virtual	~Conversationalist ()=0
	Allow proper destruction using a Conversationalist pointer. More...

Protected Member Functions
virtual void	close ()
	Relinquishes the access objects. More...

virtual void	open ()
	Gets the required access objects. More...

virtual void	start ()
	Selects the device, which may be the same as doing nothing. More...

virtual void	stop ()
	Deselects the device and assures the clock is in the idle state. More...

virtual void	transfer (const std::uint8_t __restrict__ out, std::uint8_t __restrict__ in, int bits)
	Moves data about. More...

Protected Member Functions inherited from duds::hardware::interface::MasterSyncSerial
void	clockFrequency (unsigned int freq)
	Changes the maximum clock frequency. More...

void	clockPeriod (unsigned int nanos)
	Changes the minimum clock period. More...

void	condStart ()
	Calls start() if not currently communicating (clear MssCommunicating flag). More...

void	condStop ()
	Calls stop() if currently communicating (set MssCommunicating flag). More...

void	converseAlreadyOpen (Conversation &conv)
	Has a half-duplex Conversation with the connected device. More...

void	forceClose ()
	Attempts to forcibly cease communications by calling condStop() and close(). More...

virtual void	receive (std::uint8_t *buff, duds::general::Bits bits)
	Receives bits of data. More...

virtual void	transfer (const std::uint8_t __restrict__ out, std::uint8_t __restrict__ in, duds::general::Bits bits)=0
	Sends and/or receives bits of data. More...

virtual void	transmit (const std::uint8_t *buff, duds::general::Bits bits)
	Sends bits of data. More...

Private Types
enum	PinPos { ClockPin, DataPin, InputPin, OutputPin = DataPin }
	Pin positions of the items in the pin set. More...

Static Private Member Functions
static void	checkPins (const DigitalPinSet &ps, Flags cfg)
	Checks the pins' capabilities to assure they can be used in the intended role. More...

Private Attributes
union {
struct {
unsigned int clk
	The pin ID for the clock. More...

unsigned int dat
	The pin ID for data, output if full-duplex. More...

unsigned int datI
	The pin ID for data input if full-duplex. More...

}

unsigned int pins [3]
	The pin IDs to use. More...

};

DigitalPinSetAccess	acc

DigitalPinAccess	acc [3]
	Access objects for the pins. More...

ChipAccess	chipAcc
	Chip access for for serial interfaces that require chip selection. More...

DigitalPinSet	pins

ChipSelect	sel
	Chip selection for serial interfaces that require it. More...

std::shared_ptr< PinStore >	store
	The store of pins that manages the pins used by this serial interface. More...

Additional Inherited Members
Public Types inherited from duds::hardware::interface::MasterSyncSerial
typedef duds::general::BitFlags< struct MssFlags >	Flags
	Configuration flags for various synchronous serial options. More...

Static Public Attributes inherited from duds::hardware::interface::MasterSyncSerial
static constexpr Flags	MssClockIdleHigh = Flags(2)
	Before communication begins, and after it ends, the clock line should have a high logic level. More...

static constexpr Flags	MssCommunicating = Flags(128)
	Indicates that communication is underway. More...

static constexpr Flags	MssConfigMask = Flags(31)
	All the flags that are used for configuration rather than the current state. More...

static constexpr Flags	MssFirstDerivedClassFlag = Flags(256)
	The first flag that may be defined by a derived class. More...

static constexpr Flags	MssFullDuplex = Flags(16)
	Communication is full duplex. More...

static constexpr Flags	MssMSbFirst = Flags(8)
	Send data MSb first, little endian. More...

static constexpr Flags	MssOpen = Flags(64)
	Indicates that all required resources for communication have been acquired. More...

static constexpr Flags	MssOutFallInRise = Flags(4)
	Output on the falling edge of the clock and read on the rising edge. More...

static constexpr Flags	MssReady = Flags(32)
	Indictates that all required resources for communication have been identified and passed a validity check. More...

static constexpr Flags	MssSpiMode0
	Flags for SPI mode 0. More...

static constexpr Flags	MssSpiMode0LSb = MssOutFallInRise \| MssFullDuplex
	Flags for SPI mode 0 with the LSb transfered first. More...

static constexpr Flags	MssSpiMode1 = MssMSbFirst \| MssFullDuplex
	Flags for SPI mode 1. More...

static constexpr Flags	MssSpiMode1LSb = MssFullDuplex
	Flags for SPI mode 1 with the LSb transfered first. More...

static constexpr Flags	MssSpiMode2
	Flags for SPI mode 2. More...

static constexpr Flags	MssSpiMode2LSb = MssClockIdleHigh \| MssFullDuplex
	Flags for SPI mode 2 with the LSb transfered first. More...

static constexpr Flags	MssSpiMode3
	Flags for SPI mode 3. More...

static constexpr Flags	MssSpiMode3LSb
	Flags for SPI mode 3 with the LSb transfered first. More...

static constexpr Flags	MssUseSelect = Flags(1)
	Use a select line to tell a device to pay attention to the master. More...

Protected Attributes inherited from duds::hardware::interface::MasterSyncSerial
Flags	flags
	Configuration flags. More...

unsigned int	minHalfPeriod
	The minimum time between changing the clock edge in nanoseconds. More...

Detailed Description

A synchronous serial implementation using DigitalPin objects.

The DigitalPin objects provide an abstraction to the hardware. The pins must all be managed by the same PinStore object. The PinStore provides thread-safe operation; multiple DigitalPinMasterSyncSerial objects and other things may share pins.

Author: Jeff Jackowski.

Definition at line 24 of file DigitalPinMasterSyncSerial.hpp.

Member Enumeration Documentation

◆ PinPos

enum duds::hardware::interface::DigitalPinMasterSyncSerial::PinPos

private

Pin positions of the items in the pin set.

Enumerator
ClockPin	The clock pin.
DataPin	The data pin for half-duplex. Used for full-duplex output.
InputPin	The input pin for full-duplex.
OutputPin	The output pin for full-duplex.

Definition at line 46 of file DigitalPinMasterSyncSerial.hpp.

Constructor & Destructor Documentation

◆ DigitalPinMasterSyncSerial() [1/4]

duds::hardware::interface::DigitalPinMasterSyncSerial::DigitalPinMasterSyncSerial ( )

Definition at line 23 of file DigitalPinMasterSyncSerial.cpp.

◆ DigitalPinMasterSyncSerial() [2/4]

duds::hardware::interface::DigitalPinMasterSyncSerial::DigitalPinMasterSyncSerial	(	Flags	flags,
		int	period
	)

Parameters

flags	The flags specifying the low-level details of the serial protocol.
period	The minimum clock period in nanoseconds.

Definition at line 26 of file DigitalPinMasterSyncSerial.cpp.

◆ DigitalPinMasterSyncSerial() [3/4]

duds::hardware::interface::DigitalPinMasterSyncSerial::DigitalPinMasterSyncSerial	(	const DigitalPinSet &	pset,
		Flags	flags,
		int	period
	)

Definition at line 29 of file DigitalPinMasterSyncSerial.cpp.

◆ DigitalPinMasterSyncSerial() [4/4]

duds::hardware::interface::DigitalPinMasterSyncSerial::DigitalPinMasterSyncSerial	(	DigitalPinSet &&	pset,
		Flags	flags,
		int	period
	)

Definition at line 35 of file DigitalPinMasterSyncSerial.cpp.

◆ ~DigitalPinMasterSyncSerial()

duds::hardware::interface::DigitalPinMasterSyncSerial::~DigitalPinMasterSyncSerial ( )

Definition at line 41 of file DigitalPinMasterSyncSerial.cpp.

Member Function Documentation

◆ checkPins()

void duds::hardware::interface::DigitalPinMasterSyncSerial::checkPins	(	const DigitalPinSet &	ps,
		Flags	cfg
	)

staticprivate

Checks the pins' capabilities to assure they can be used in the intended role.

This is not a member function because it must not update the data in a DigitalPinMasterSyncSerial object, and the data it might use should not be set until after this function succeeds, so there is no need to use member variables or functions. This assists with a proper error response.

Parameters

ps	The pin set with all the pins to use indexed as in PinPos.
cfg	The configuration flags. Presently only needed to check for the intent to use full or half duplex communication.

Exceptions

PinRangeError	Half-duplex needs 3 pins. Full-duplex needs 4. If this is thrown, the number of pins supplied in ps is wrong.
PinUnsupportedOperation	One of the pins lacks the needed input and/or output capability. Which pin is mentioned in the data attached to the exception by usage name and ID.

Definition at line 45 of file DigitalPinMasterSyncSerial.cpp.

Referenced by setPins().

◆ clockFrequency()

void duds::hardware::interface::DigitalPinMasterSyncSerial::clockFrequency ( unsigned int freq )

Changes the maximum clock frequency.

Precondition: No communication must be taking place; the object must not be in the MssCommunicating state.

Postcondition: minHalfPeriod has half the period of the clock in nanoseconds.

Parameters

freq	The requested maximum clock frequence in hertz.

Exceptions

SyncSerialInUse Called while communication is in progress.

Definition at line 188 of file DigitalPinMasterSyncSerial.cpp.

◆ clockPeriod()

void duds::hardware::interface::DigitalPinMasterSyncSerial::clockPeriod ( unsigned int nanos )

Changes the minimum clock period.

Precondition: No communication must be taking place; the object must not be in the MssCommunicating state.

Postcondition: minHalfPeriod has half the period of the clock in nanoseconds.

Parameters

nanos The requested minimum clock period in nanoseconds.

Exceptions

SyncSerialInUse Called while communication is in progress.

Definition at line 192 of file DigitalPinMasterSyncSerial.cpp.

◆ close()

void duds::hardware::interface::DigitalPinMasterSyncSerial::close ( )

protectedvirtual

Relinquishes the access objects.

Implements duds::hardware::interface::MasterSyncSerial.

Definition at line 214 of file DigitalPinMasterSyncSerial.cpp.

◆ open()

void duds::hardware::interface::DigitalPinMasterSyncSerial::open ( )

protectedvirtual

Gets the required access objects.

Note: This function may block.

Implements duds::hardware::interface::MasterSyncSerial.

Definition at line 196 of file DigitalPinMasterSyncSerial.cpp.

◆ setChipSelect()

void duds::hardware::interface::DigitalPinMasterSyncSerial::setChipSelect ( const ChipSelect & cs )

Sets the ChipSelect object to use for selections.

Precondition: The MssUseSelect flag is set.

Parameters

cs	The ChipSelect object to use. It must be configured and have a manager. This means the following members of cs will all return true: ChipSelect::isUsable() ChipSelect::isConfigured() ChipSelect::haveManager()

Exceptions

SyncSerialSelectNotUsed	This object is not configured to use chip selection.
ChipSelectBadManager	cs does not have an associated ChipSelectManager.
ChipSelectInvalidChip	cs does not have a chip ID to select.
SyncSerialInUse	Called while communication is in progress.

Definition at line 164 of file DigitalPinMasterSyncSerial.cpp.

Referenced by setPins().

◆ setPins() [1/4]

void duds::hardware::interface::DigitalPinMasterSyncSerial::setPins ( const PinIndex & pi )

Sets the pins to use based on names already set in the PinIndex.

The names are:

clock
data (half-duplex)
input (full-duplex)
output (full-duplex)
Parameters

pi The index with the pin names.

Exceptions

PinDoesNotExist One of the names is not present in pi.

SyncSerialInUse Called while communication is in progress.

Definition at line 80 of file DigitalPinMasterSyncSerial.cpp.

Referenced by setPins().

◆ setPins() [2/4]

void duds::hardware::interface::DigitalPinMasterSyncSerial::setPins ( const std::shared_ptr< PinIndex > & pi )

inline

Sets the pins to use based on names already set in the PinIndex.

The names are:

clock
data (half-duplex)
input (full-duplex)
output (full-duplex)
Parameters

pi The index with the pin names.

Exceptions

PinDoesNotExist One of the names is not present in pi.

SyncSerialInUse Called while communication is in progress.

Definition at line 172 of file DigitalPinMasterSyncSerial.hpp.

◆ setPins() [3/4]

void duds::hardware::interface::DigitalPinMasterSyncSerial::setPins	(	const std::shared_ptr< PinStore > &	store,
		unsigned int	clock,
		unsigned int	data
	)

Sets the pins to use for half-duplex operation.

Parameters

store	The PinStore that manages the pins to use.
clock	The ID for the clock pin.
data	The ID for the data pin.

Exceptions

SyncSerialNotFullDuplex	This object is configured for full-duplex operation.
PinDoesNotExist	One of the pins does not exist in store.
PinUnsupportedOperation	The input and output capabilities of one of the pins is not suitable for its role, like a clock that cannot output.
SyncSerialInUse	Called while communication is in progress.

Definition at line 117 of file DigitalPinMasterSyncSerial.cpp.

◆ setPins() [4/4]

void duds::hardware::interface::DigitalPinMasterSyncSerial::setPins	(	const std::shared_ptr< PinStore > &	store,
		unsigned int	clock,
		unsigned int	output,
		unsigned int	input
	)

Sets the pins to use for full-duplex operation.

Parameters

store	The PinStore that manages the pins to use.
clock	The ID for the clock pin.
output	The ID for the output data pin.
input	The ID for the intput data pin.

Exceptions

SyncSerialNotHalfDuplex	This object is configured for half-duplex operation.
PinDoesNotExist	One of the pins does not exist in store.
PinUnsupportedOperation	The input and output capabilities of one of the pins is not suitable for its role, like a clock that cannot output.
SyncSerialInUse	Called while communication is in progress.