PNP adapter that maintains a TCP server for a set of plug-and-play devices. More...

#include <CPnpAdapter.hpp>

Inheritance diagram for freedm::broker::device::CPnpAdapter:

Public Types
typedef boost::shared_ptr< CPnpAdapter >	Pointer
	Convenience type for a shared pointer to self. More...

Public Member Functions
	~CPnpAdapter ()
	Destructs the object. More...

std::set< std::string >	GetDevices () const
	Get the list of registered device names. More...

SignalValue	GetState (const std::string device, const std::string signal) const
	Retrieve data from rxBuffer. More...

void	Heartbeat ()
	Refreshes the internal countdown timer. More...

void	RegisterCommandInfo (const std::string device, const std::string signal, const std::size_t index)
	Registers a new device signal with the physical adapter. More...

void	RegisterDevice (const std::string devid)
	Register a device name with the adapter. More...

void	RegisterStateInfo (const std::string device, const std::string signal, const std::size_t index)
	Registers a new device signal with the physical adapter. More...

void	SetCommand (const std::string device, const std::string signal, const SignalValue value)
	Set data in txBuffer. More...

void	Start ()
	Starts the internal countdown timer. More...

void	Stop ()
	Stops the adapter. More...

Static Public Member Functions
static IAdapter::Pointer	Create (boost::asio::io_service &service, boost::property_tree::ptree &p, CTcpServer::Connection client)
	Creates a shared instance of the PNP adapter. More...

Protected Member Functions
void	RevealDevices ()
	Reveals devices in the device manager. More...

Protected Attributes
bool	m_buffer_initialized
	Flag that indicates whether the buffer is NaN. More...

std::map< const DeviceSignal, const std::size_t >	m_commandInfo
	Translates a device signal into its txBuffer (command) index. More...

std::vector< SignalValue >	m_rxBuffer
	The "state table" buffer received from the external host. More...

boost::shared_mutex	m_rxMutex
	Provides synchronization for m_rxBuffer. More...

std::map< const DeviceSignal, const std::size_t >	m_stateInfo
	Translates a device signal into its rxBuffer (state) index. More...

std::vector< SignalValue >	m_txBuffer
	The "command table" buffer sent to the external host. More...

boost::shared_mutex	m_txMutex
	Provides synchronization for m_txBuffer. More...

Private Member Functions
	CPnpAdapter (boost::asio::io_service &service, boost::property_tree::ptree &p, CTcpServer::Connection client)
	Initializes the TCP server and internal storage. More...

void	AfterWrite (const boost::system::error_code &e)
	Handles when a packet has been sent to the device. More...

std::string	GetCommandPacket ()
	Sends device commands to the current client. More...

void	HandleRead (const boost::system::error_code &e)
	Handles a packet received from the device. More...

void	ReadStatePacket (const std::string packet)
	Parses a state packet received from the client. More...

void	StartRead ()
	Schedules the next read operation. More...

void	StartWrite ()
	Schedules the next write operation. More...

void	Timeout (const boost::system::error_code &e)
	Tells the adapter factory to remove its reference to this object. More...

Private Attributes
boost::asio::streambuf	m_buffer
	Stream used to send and receive data. More...

CTcpServer::Connection	m_client
	TCP server for the PNP client. More...

boost::shared_ptr< boost::asio::deadline_timer >	m_countdown
	Countdown until the object destroys itself. More...

std::string	m_identifier
	Unique identifier of this adapter. More...

boost::asio::io_service &	m_ios
	The ioservice running this adapter. More...

bool	m_stopping
	Signifies that the adapter is to stop. More...

boost::mutex	m_stoppingMutex
	Protects access to m_stopping. More...

Detailed Description

The PNP adapter implements the plug-and-play session protocol. An object of this class will delete itself on expiration of an internal countdown timer unless the CPnpAdapter::Heartbeat function is called to refresh the timer. The adapter calls this function itself whenever it sends or receives data on its TCP server without incident.

Limitations:: A shared pointer to this class must never be stored except in the CAdapterFactory class. If a shared pointer is stored, then the session protocol will no longer function as intended.

Member Typedef Documentation

typedef boost::shared_ptr<CPnpAdapter> freedm::broker::device::CPnpAdapter::Pointer

Constructor & Destructor Documentation

freedm::broker::device::CPnpAdapter::~CPnpAdapter ( )

Destructor for the PNP adapter.

Precondition:: None.

Postcondition:: Destructs this object.

Limitations:: None.

freedm::broker::device::CPnpAdapter::CPnpAdapter	(	boost::asio::io_service &	service,
		boost::property_tree::ptree &	p,
		CTcpServer::Connection	client
	)

private

Constructs a new PNP adapter.

Precondition:: The ptree must have the 'identifier' and 'stateport' properties.

Postcondition:: Creates a new TCP server on the specified 'stateport'.

Postcondition:: Registers CPnpAdapter::HandleMessage with m_server.

Parameters

service	The i/o service for the TCP server.
p	The property tree that configures the adapter.
client	The TCP connection to use for this adapter.

Limitations:: None.

Member Function Documentation

void freedm::broker::device::CPnpAdapter::AfterWrite ( const boost::system::error_code & e )

private

Prepares the next read operation after a successful write.

Precondition:: None.

Postcondition:: If the m_stopping flag has been raised, stops the adapter.

Postcondition:: Otherwise, prepares the next read with CPnpAdapter::StartRead.

Parameters

e	The error code associated with the last write operation.

Limitations:: None.

IAdapter::Pointer freedm::broker::device::CPnpAdapter::Create	(	boost::asio::io_service &	service,
		boost::property_tree::ptree &	p,
		CTcpServer::Connection	client
	)

static

Creates a new shared instance of the PNP adapter.

Precondition:: None.

Postcondition:: Constructs a new PNP adapter.

Parameters

service	The i/o service for the internal TCP server.
p	The property tree that specifies the adapter configuration.
client	The TCP connection to use for this adapter.

Returns: shared_ptr to the new adapter.

Limitations:: None.

std::string freedm::broker::device::CPnpAdapter::GetCommandPacket ( )

private

Generates the next command packet from the current DGI commands.

Precondition:: None.

Postcondition:: Creates a command packet from the content of m_txBuffer.

Returns: A string that contains the next command packet.

Limitations:: None.

std::set< std::string > freedm::broker::device::IAdapter::GetDevices ( ) const

inherited

Accessor function for the registered device set.

Precondition:: None.

Postcondition:: Returns m_devices.

Returns: A set of device identifiers.

Limitations:: None.

SignalValue freedm::broker::device::IBufferAdapter::GetState	(	const std::string	device,
		const std::string	signal
	)		const

virtualinherited

Read the specified value from the rxBuffer.

Error Handling:: Throws std::exception if the value cannot be found.

Precondition:: The passed signal must be recognized by the adapter.

Postcondition:: Returns the value of the signal stored in m_rxBuffer.

Parameters

device	The unique identifier of a physical device.
signal	A power electronic reading related to the device.

Returns: SignalValue from the rxBuffer.

Limitations:: None.

Implements freedm::broker::device::IAdapter.

void freedm::broker::device::CPnpAdapter::HandleRead ( const boost::system::error_code & e )

private

Handles a packet received from the plug and play device.

Error Handling:: If an exception occurs, it will be caught and a bad request message will be sent to the client to indicate failure.

Precondition:: The packet must be stored in m_buffer.

Postcondition:: Processes the packet and prepares an appropriate response.

Parameters

e	The error code associated with the last read operation.

Limitations:: None.

void freedm::broker::device::CPnpAdapter::Heartbeat ( )

Refreshes the heartbeat countdown timer.

Precondition:: m_heartbeat must not have expired.

Postcondition:: Resets the countdown of the m_heartbeat timer.

Limitations:: This call will do nothing if the timer has already expired.

void freedm::broker::device::CPnpAdapter::ReadStatePacket ( const std::string packet )

private

Processes the content of a state packet received from the device.

Error Handling:: Throws a EBadRequest if the packet is malformed.

Precondition:: The packet format must adhere to the session protocol specifications.

Postcondition:: Extracts the device state information from packet.

Postcondition:: Updates m_rxBuffer with the new state information.

Parameters

packet The device packet that contains updated state information.

Limitations:: None.

void freedm::broker::device::IBufferAdapter::RegisterCommandInfo	(	const std::string	device,
		const std::string	signal,
		const std::size_t	index
	)

inherited

Registers a new device signal as command information with the adapter.

Error Handling:: Throws a std::runtime_error if the device signal is invalid or already registered with the adapter.

Precondition:: The parameters must not be empty.

Precondition:: The device signal must not already be registered.

Precondition:: The index must not be registered with another signal.

Postcondition:: m_commandInfo is updated to store the new device signal.

Parameters

device	The unique identifier of the device to register.
signal	The signal of the device that will be registered.
index	The numeric index associated with the device signal.

Limitations:: None.

void freedm::broker::device::IAdapter::RegisterDevice ( const std::string devid )

inherited

Adds a device name to the registered device set.

Precondition:: None.

Postcondition:: Inserts the device name into m_devices.

Parameters

devid The name of the device to register.

Limitations:: None.

void freedm::broker::device::IBufferAdapter::RegisterStateInfo	(	const std::string	device,
		const std::string	signal,
		const std::size_t	index
	)

inherited

Registers a new device signal as state information with the adapter.

Error Handling:: Throws a std::runtime_error if the device signal is invalid or already registered with the adapter.

Precondition:: The parameters must not be empty.

Precondition:: The device signal must not already be registered.

Precondition:: The index must not be registered with another signal.

Postcondition:: m_stateInfo is updated to store the new device signal.

Parameters

device	The unique identifier of the device to register.
signal	The signal of the device that will be registered.
index	The numeric index associated with the device signal.

Limitations:: None.

void freedm::broker::device::IAdapter::RevealDevices ( )

protectedinherited

Reveals the associated devices in the device manager.

Precondition:: No prior call has been made to this function.

Postcondition:: Calls CDeviceManger::RevealDevice for each known device.

Limitations:: This function can be called at most once.

void freedm::broker::device::IBufferAdapter::SetCommand	(	const std::string	device,
		const std::string	signal,
		const SignalValue	value
	)

virtualinherited

Update the specified value in the txBuffer.

Error Handling:: Throws std::exception if the value cannot be found.

Precondition:: The passed signal must be recognized by the adapter.

Postcondition:: Updates the value of the signal in m_txBuffer.

Parameters

device	The unique identifier of a physical device.
signal	A power electronic reading related to the device.
value	The desired new value for the device signal.

Limitations:: None.

Implements freedm::broker::device::IAdapter.

void freedm::broker::device::CPnpAdapter::Start ( )

virtual

Starts the internal countdown timer to destroy this object.

Precondition:: None.

Postcondition:: m_heartbeat set to call CPnpAdapter::Timeout on expiration.

Limitations:: None.

Implements freedm::broker::device::IAdapter.

void freedm::broker::device::CPnpAdapter::StartRead ( )

private

Schedules the next read from the plug and play device.

Precondition:: m_client must not be uninitialized.

Postcondition:: Clears the content of m_buffer prior to the read.

Postcondition:: Calls CPnpAdapter::Heartbeat to refresh the connection.

Postcondition:: Schedules the next socket connection on m_client.

Limitations:: None.

void freedm::broker::device::CPnpAdapter::StartWrite ( )

private

Schedules the next write to the plug and play device.

Precondition:: m_client must not be uninitialized.

Precondition:: m_buffer must contain the data to write.

Postcondition:: Calls CPnpAdapter::Heartbeat to refresh the connection.

Postcondition:: Sends the content of m_buffer to m_client.

Limitations:: None.

void freedm::broker::device::CPnpAdapter::Stop ( )

virtual

Stops the adapter. Thread-safe.

Precondition:: Adapter is started.

Postcondition:: Adapter is stopped.

Limitations:: This is NOT the way to stop the plug and play protocol from within the CPnpAdapter class. From within CPnpAdapter, you must instead call CAdapterFactory::RemoveAdapter, which calls this function. Otherwise, a reference to the adapter will exist forever and its devices will not be properly removed from the device manager.

Implements freedm::broker::device::IAdapter.

void freedm::broker::device::CPnpAdapter::Timeout ( const boost::system::error_code & e )

private

Stops the adapter due to timeout.

Precondition:: None.

Postcondition:: Calls CAdapterFactory::RemoveAdapter if the timer was not reset.

Parameters

e	The error code that signals if the timeout has been canceled.

Member Data Documentation

boost::asio::streambuf freedm::broker::device::CPnpAdapter::m_buffer

private

bool freedm::broker::device::IBufferAdapter::m_buffer_initialized

protectedinherited

CTcpServer::Connection freedm::broker::device::CPnpAdapter::m_client

private

std::map<const DeviceSignal, const std::size_t> freedm::broker::device::IBufferAdapter::m_commandInfo

protectedinherited

boost::shared_ptr<boost::asio::deadline_timer> freedm::broker::device::CPnpAdapter::m_countdown

private

std::string freedm::broker::device::CPnpAdapter::m_identifier

private

boost::asio::io_service& freedm::broker::device::CPnpAdapter::m_ios

private

std::vector<SignalValue> freedm::broker::device::IBufferAdapter::m_rxBuffer

protectedinherited

boost::shared_mutex freedm::broker::device::IBufferAdapter::m_rxMutex

mutableprotectedinherited

std::map<const DeviceSignal, const std::size_t> freedm::broker::device::IBufferAdapter::m_stateInfo

protectedinherited

bool freedm::broker::device::CPnpAdapter::m_stopping

private

boost::mutex freedm::broker::device::CPnpAdapter::m_stoppingMutex

private

std::vector<SignalValue> freedm::broker::device::IBufferAdapter::m_txBuffer

protectedinherited

boost::shared_mutex freedm::broker::device::IBufferAdapter::m_txMutex

mutableprotectedinherited

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

/home/docs/checkouts/readthedocs.org/user_builds/freedm/checkouts/latest/Broker/src/device/CPnpAdapter.hpp
/home/docs/checkouts/readthedocs.org/user_builds/freedm/checkouts/latest/Broker/src/device/CPnpAdapter.cpp

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation