Provides an interface for communicating with a RTDS simulation model. More...

#include <CRtdsAdapter.hpp>

Inheritance diagram for freedm::broker::device::CRtdsAdapter:

Public Types
typedef boost::shared_ptr< CRtdsAdapter >	Pointer
	Pointer to an CRtdsAdapter object. More...

Public Member Functions
	~CRtdsAdapter ()
	Destructor. 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	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 adapter. More...

void	Stop ()
	Shut down communication to FPGA. More...

Static Public Member Functions
static IAdapter::Pointer	Create (boost::asio::io_service &service, const boost::property_tree::ptree &ptree)
	Create a CRtdsAdapter object and returns a pointer to it. 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
	CRtdsAdapter (boost::asio::io_service &service, const boost::property_tree::ptree &ptree)
	Constructor. More...

void	Connect ()
	Creates a socket connection to the given hostname and port number. More...

void	EndianSwapIfNeeded (std::vector< SignalValue > &v)
	Swaps the endianness of all SignalValues in a vector. More...

void	ReverseBytes (char *buffer, const int numBytes)
	Reverses all of the bytes in a buffer. More...

void	Run (const boost::system::error_code &e)
	Continuous loop for sending and receiving to/from RTDS. More...

Private Attributes
std::string	m_host
	The hostname of the remote host. More...

std::string	m_port
	The port number of the remote host. More...

boost::asio::deadline_timer	m_runTimer
	Timer object to set communication cycle pace. More...

boost::asio::ip::tcp::socket	m_socket
	Socket to use for the TCP connection. More...

Detailed Description

This class handles communications to and from the RTDS simulation model via an FPGA device. It serves as client to the FPGA's server, retrieving values from and transmitting commands to the RTDS.

Interaction Peers:: The FPGA device used by FREEDM research at Florida State University directly communicates with CRtdsAdapter. For more details about the code on the FPGA, please contact Dr. Mischa Steurer steur.nosp@m.er@c.nosp@m.aps.f.nosp@m.su.e.nosp@m.du

Limitations:: We assume any multiplexing/demultiplexing (if needed) of readings from multiple microgrids simulated by the RTDS model is done FPGA-side.

Member Typedef Documentation

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

Constructor & Destructor Documentation

freedm::broker::device::CRtdsAdapter::~CRtdsAdapter ( )

Closes the socket before destroying an object instance.

Precondition:: None.

Postcondition:: Closes m_socket.

Limitations:: None.

freedm::broker::device::CRtdsAdapter::CRtdsAdapter	(	boost::asio::io_service &	io_service,
		const boost::property_tree::ptree &	ptree
	)

private

Constructs an RTDS client.

Shared Memory Blocks:: Uses the passed io_service.

Precondition:: None.

Postcondition:: CRtdsAdapter created.

Parameters

io_service	The io_service to be used to communicate with the FPGA.
ptree	The property tree specifying this adapter's device signals.

Limitations:: None

Member Function Documentation

void freedm::broker::device::CRtdsAdapter::Connect ( )

private

Creates a TCP socket connection to the adapter's target host and port.

Error Handling:: Throws a std::runtime_error for connection errors.

Precondition:: hostname and service specify a valid endpoint.

Postcondition:: m_socket is connected to the passed service.

Limitations:: None.

IAdapter::Pointer freedm::broker::device::CRtdsAdapter::Create	(	boost::asio::io_service &	service,
		const boost::property_tree::ptree &	ptree
	)

static

Creates an RTDS client on the given io_service.

Shared Memory Blocks:: Uses the passed io_service

Precondition:: None.

Postcondition:: CRtdsAdapter object is returned for use.

Parameters

service	The io_service to be used to communicate with the FPGA.
ptree	The property tree specifying this adapter's device signals.

Returns: Shared pointer to the new CRtdsAdapter object.

Limitations:: None

void freedm::broker::device::CRtdsAdapter::EndianSwapIfNeeded ( std::vector< SignalValue > & v )

private

Converts the SignalValues in the passed vector from big-endian to little-endian, or vice-versa, if the DGI is running on a little-endian system.

Precondition:: None.

Postcondition:: The elements of data are converted in endianness if the DGI is running on a little-endian system. Otherwise, nothing happens.

Parameters

v	The vector of SignalValues to be endian-swapped.

Limitations:: Assumes the existence of UNIX byte order macros.

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::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::CRtdsAdapter::ReverseBytes	(	char *	buffer,
		const int	numBytes
	)

private

A utility function for converting byte order from big endian to little endian and vice versa. This needs to be called on a SINGLE WORD of the data since it actually just reverses the bytes.

Precondition:: None

Postcondition:: The bytes in the buffer are now reversed

Parameters

buffer	the data to be reversed
numBytes	the number of bytes in the buffer

void freedm::broker::device::CRtdsAdapter::Run ( const boost::system::error_code & e )

private

This is the main communication engine.

Device I/O:: At every timestep, a message is sent to the FPGA via TCP socket connection, then a message is retrieved from FPGA via the same connection. On the FPGA side, it's the reverse order – receive and then send. Both DGI and FPGA receive functions will block until a message arrives, creating a synchronous, lock-step communication between DGI and the FPGA. We keep the timestep (a static member of CRtdsAdapter) very small so that how frequently send and receive get executed is dependent on how fast the FPGA runs.

Error Handling:: Throws std::runtime_error if reading from or writing to socket fails.

Precondition:: Connection with FPGA is established.

Postcondition:: All values in the receive buffer are sent to the FPGA. All values in the send buffer are updated with data from the FPGA.

Limitations:: This function uses synchronous communication.

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::CRtdsAdapter::Start ( )

virtual

Starts sending and receiving data with the adapter.

Precondition:: The adapter has not yet been started.

Postcondition:: CRtdsAdapter::Run is called to start the adapter.

Limitations:: All devices must be added to the adapter before this call.

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

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

virtual

Stops the adapter. Thread-safe.

Precondition:: None.

Postcondition:: Adapter is stopped and can be freed

Limitations:: None.

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

Member Data Documentation

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

protectedinherited

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

protectedinherited

std::string freedm::broker::device::CRtdsAdapter::m_host

private

std::string freedm::broker::device::CRtdsAdapter::m_port

private

boost::asio::deadline_timer freedm::broker::device::CRtdsAdapter::m_runTimer

private

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

protectedinherited

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

mutableprotectedinherited

boost::asio::ip::tcp::socket freedm::broker::device::CRtdsAdapter::m_socket

mutableprivate

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

protectedinherited

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/CRtdsAdapter.hpp
/home/docs/checkouts/readthedocs.org/user_builds/freedm/checkouts/latest/Broker/src/device/CRtdsAdapter.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