carma::canbus::Device Class Reference

Abstract base class for all CAN Bus devices. More...

#include <carma/canbus/Device.h>

Inheritance diagram for carma::canbus::Device:

Public Member Functions
carma::canbus::Message	createDummyMsg () const
	Create a dummy CAN message. More...
carma::canbus::Message	createMsgToAllNodes (msgType messageId) const
	Create a CAN message addressed to all nodes of this type. More...
carma::canbus::Message	createMsgToHost (msgType messageId) const
	Create a CAN message addressed from this Device to the host. More...
carma::canbus::Message	createMsgToNode (msgType messageId) const
	Create a CAN message addressed to this device from the host. More...
	Device (apiType api, nodeType node, CanOutput &io)
	Device constructor. More...
apiType	getApi () const
	Return api code of device. More...
char	getApiVersion () const
	Get API Version of this Device. More...
boardType	getBoardType () const
	Return board type id of device. More...
busIdType	getBusId () const
	Return bus Id that node resides on. More...
virtual MsgIdInfoMap	getControls () const
	Return a map of devices controls. More...
virtual MsgIdInfoMap	getHalfSecMonitors () const =0
	Return a map of devices half second monitor points. More...
keyType	getKey () const
	Create a key unique to this api and node. More...
double	getLastRxTime () const
	Get Last RX Time for device. More...
unsigned int	getNlatePackets () const
	Get number of late packets. More...
nodeType	getNode () const
	Return node location code of device. More...
serialNumberType	getSerialNumber () const
	Return serial number of device. More...
virtual MsgIdInfoMap	getSlowMonitors () const =0
	Return a map of devices slow monitor points. More...
deviceStateType	getState () const
	Status access routine. More...
virtual void	processMsg (msgType messageId, std::vector< byteType > &data, bool sim)=0
	Process a CAN message. More...
void	reset ()
	Perform a software reset of module. More...
void	setBoardType (boardType bt)
	Set board type of device. More...
void	setBusId (busIdType busId)
	Set busId of device. More...
virtual void	setLastRxTime (double rxMjd)
	Set latest rx time. More...
void	setSerialNumber (serialNumberType sn)
	Set serial number of device. More...
virtual void	setState (deviceStateType state)
	Set state of device. More...
virtual carma::canbus::Message	simulateMsg (msgType messageId)=0
	Simulate a CAN message. More...
void	startChannelOneFastSampling (unsigned short fastItem)
	Start fast sampling the specified data item on channel 1. More...
void	startChannelTwoFastSampling (unsigned short fastItem)
	Start fast sampling the specified data item on channel 2. More...
void	stopChannelOneFastSampling ()
	Stop fast sampling on channel 1 This routine will stop fast sampling on channel 1 regardless of whether this node is fast sampling the channel or not! In other words the request goes out globally. More...
void	stopChannelTwoFastSampling ()
	Stop fast sampling on channel 2 This routine will stop fast sampling on channel 2 regardless of whether this node is fast sampling the channel or not! In other words the request goes out globally. More...
virtual void	updateFrameData ()
	Update device or monitor data on frame timescale... More...
virtual	~Device ()
	Device destructor. More...

Static Public Member Functions
static keyType	createKey (apiType api, nodeType node)

Protected Member Functions
void	incrementLatePacketCount ()
	Increment the late packet count by 1. More...
bool	isPacketLate (double window=100.0)
	Determine if the last packet sent from this device was late. More...
void	resetLatePacketCount ()
	Reset the late packet count to 0. More...
void	setApiVersion (char api)
	Set API Version. More...

Protected Attributes
const apiType	api_
CanOutput &	io_
	Reference to CanOutput object. More...
const keyType	key_
const nodeType	node_

Static Protected Attributes
static const msgType	RESET = 0x0000
	Software reset message id. More...
static const msgType	START_CHANNEL_1_FAST_SAMPLING = 0x0004
	Begin channel 1 fast sampling message id. More...
static const msgType	START_CHANNEL_2_FAST_SAMPLING = 0x0005
	Begin channel 2 fast sampling message id. More...
static const msgType	STOP_CHANNEL_1_FAST_SAMPLING = 0x0002
	Stop channel 1 fast sampling message id. More...
static const msgType	STOP_CHANNEL_2_FAST_SAMPLING = 0x0003

Detailed Description

Abstract base class for all CAN Bus devices.

Device provides an abstract base class for CANbus devices 

implementing the Carma CANbus Message ID Protocol. It is intended that all API CAN device implementations will derive directly from this class and define all API specific details such as control interfaces, how to pack/unpack CAN messages, message ids, and where to place monitor data. These details are described in the Carma CANbus API documents available here. Implementation is mostly accomplished by overloading the Device::processMsg routine and defining additional control methods that may or may not be exposed to higher level processes through CORBA or some other means. By using Device as a base class for all CANbus devices, it is possible for the carma::canbus::Master class to easily manage multiple types of devices with different API ids while only retaining a list of pointers to this abstract base class. As a result, the carma::canbus::Master class handles nearly all of the details and bookeeping regarding retrieval and processing of CAN messages.

Device State. It is essential that anybody deriving from this base understands how the state of a Device is set and used. There are four possible states that a Device may have which are defined by the carma::canbus::deviceStateEnum enumeration. This state can be set and retrieved with the Device::getState and Device::setState methods. All devices are initialized to OFFLINE unless explicitly reinitialized in the derived class. The carma::canbus::Master class will automatically maintain the state of any CAN devices registered with it. It will set any ONLINE or STARTING Device to OFFLINE if no CAN messages are received from it in a designated time frame of about 1 second for ONLINE devices and 20 seconds for STARTING devices. Likewise, Master will set modules ONLINE when receiving packets from it - first transitioning through STARTING if the modules sends out a slow monitor packet for identification purposes.

Memory allocation. Any implementor of the device class will need to be cognizant of how memory should be created and destroyed for their device. In particular any Device implementation that is also inheriting from a CORBA control interface cannot simply call delete. They should instead call CORBA routines to decrement reference counts and destroy memory. Please see Henning & Vinoski, Ch 11.7 pg 493 for detailed information on deleting CORBA servant objects.

Node 0 Devices. As described in the Carma CANbus Message ID Protocol. a CAN address with a node location code of 0 has a special meaning. Addresses containing this node id will be processed by all CAN Devices with the same API Id. This enables one to issue a single control command to all CAN modules of the same type at once. Likewise, a Device class derivative with a node id of 0 refers to all CAN modules of that API. Users may declare a node 0 Device if more than one identical CAN Device exists which needs to be controlled homogenously. This node will not receive monitor packets and should exist purely for control purposes. This can be asserted programatically by declaring the node 0 device constant and I urge users to do so when possible. It may not be possible to declare node 0 devices constant if your device class inherits from an IDL interface but if using tie classes or composition there should be no barriers to doing so.

Definition at line 92 of file Device.h.

Constructor & Destructor Documentation

carma::canbus::Device::Device	(	apiType	api,
		nodeType	node,
		CanOutput &	io
	)

Device constructor.

Constructs a device with the given api and node.

Parameters

api	unique code identifying a specific set of instructions and CAN message formats.
node	unique location id on a CAN bus.
io	Reference to CanOutput class - should be obtained from downcasting the canbus::Master reference in inherited canbus::Master class.

virtual carma::canbus::Device::~Device ( )

virtual

Device destructor.

Device class destructor is declared virtual here because in general the Master class will maintain only a container of Device class pointers. When this container or any of the objects in the container are destroyed, we must assure that the associated object destructors get called as well (i.e. not just the Device destructor but the destructor for it's derivatives as well).

Member Function Documentation

carma::canbus::Message carma::canbus::Device::createDummyMsg

(

)

const

Create a dummy CAN message.

Dummy messages are required because the XAC module is not fast enough to pull messages off the bus at bus speed. Message will be addressed to the bus that the module currently resides on. If it needs to go to a different bus or all busses, change accordingly on the returned message prior to posting.

carma::canbus::Message carma::canbus::Device::createMsgToAllNodes

(

msgType

messageId

)

const

Create a CAN message addressed to all nodes of this type.

Returns a message with the api of this device object and a node of 0 indicating all nodes with this api. The host bit is addressed to the nodes and the BUSID is set to carma::canbus::ALL_BUSSES.

Parameters

messageId

Message id or command id to place in CAN address.

carma::canbus::Message carma::canbus::Device::createMsgToHost

(

msgType

messageId

)

const

Create a CAN message addressed from this Device to the host.

Returns a message with the api and node of this device object, the input msg id, the host bit addressed to the host and the current bus id of the node. This is most convenient for creating simulated messages in the overridden simulateMsg routine. Note that the returned message contains no data.

Parameters

messageId

Message id or command id to place in address.

carma::canbus::Message carma::canbus::Device::createMsgToNode

(

msgType

messageId

)

const

Create a CAN message addressed to this device from the host.

Returns a message with the api and node of this device object, the input msg id, the host bit addressed to the node and the current bus id of the node. This is most convenient for creating control messages.

Parameters

messageId

Message id or command id to place in address.

apiType carma::canbus::Device::getApi

(

)

const

Return api code of device.

Returns

8 bit api code.

char carma::canbus::Device::getApiVersion

(

)

const

Get API Version of this Device.

The API Version indicates exactly which version of the CARMA CANbus API document was used to create this Device. The corresponding CAN node will likewise broadcast the API version it was created from to the host machine. These versions should match!!!

See Also

Device::setApiVersion

CorbaXacDevice::processSystemMonitorPacket4

boardType carma::canbus::Device::getBoardType

(

)

const

Return board type id of device.

Returns

8 bit board type id.

busIdType carma::canbus::Device::getBusId

(

)

const

Return bus Id that node resides on.

Returns

bus Id of device.

virtual MsgIdInfoMap carma::canbus::Device::getControls ( ) const

virtual

Return a map of devices controls.

This method returns a map of control messages that can be sent to the device from this class. It must be defined by the implementor.

Returns

MsgIdInfoMap containing a string description of the CAN message keyed by it's message id.

Reimplemented in carma::antenna::ovro::CryoCompressor.

virtual MsgIdInfoMap carma::canbus::Device::getHalfSecMonitors ( ) const

pure virtual

Return a map of devices half second monitor points.

This routine returns a map of the half second CAN messages that are processed by this Device class. These CAN messages will contain the half second monitor points as described in the CANbus API for the Device. This function is necessary for properly simulating a device when the device is OFFLINE, since master first calls this method to determine which messages to simulate on a half second timescale.

Returns

MsgIdInfoMap containing a string description of the CAN message keyed by it's message id.

See Also

Device::simulateMsg

carma::canbus::Master

Implemented in sza::antenna::canbus::CanDevice, carma::antenna::ovro::Drive, carma::antenna::common::AntennaIF, carma::antenna::common::SisReceiver, carma::antenna::ovro::Encoder, carma::antenna::ovro::Tiltmeter, carma::downconverter::LoMonitor, carma::antenna::ovro::SecondaryMirror, carma::downconverter::QuadratureModulator, carma::antenna::ovro::CryoCompressor, carma::downconverter::NoiseSource, carma::downconverter::SpectralDownconverter, carma::antenna::common::LOReferenceMonitor, carma::antenna::ovro::Tiltmeter, carma::antenna::ovro::Optics, carma::downconverter::Downconverter, carma::antenna::ovro::GunnPll, carma::downconverter::LoControl, carma::antenna::common::Varactor, carma::antenna::ovro::YigPll, carma::antenna::ovro::CryoTemperatures, carma::antenna::ovro::EnvironmentalMonitor, and carma::downconverter::BlockDownconverter.

keyType carma::canbus::Device::getKey

(

)

const

Create a key unique to this api and node.

double carma::canbus::Device::getLastRxTime

(

)

const

Get Last RX Time for device.

The last rx time is the mjd time of the last CAN message received for this device. Note that it does not apply to simulated CAN messages.

Returns

MJD of last message received.

unsigned int carma::canbus::Device::getNlatePackets

(

)

const

Get number of late packets.

Late packets are packets which arive outside of a designated time window around the frame-time (half second) clock tick. CAN modules should be closely synchronized to the CAN host system time and broadcast their monitor packets on these half-second boundaries. It is the responsibility of the developer implementing a particular device class to update the number of late packets using the protected Device::nLatePackets_ variable. In general, this value is a good indicator of the system and/or module timing health.

Returns

number of late packets for this device

See Also

Device::isPacketLate

nodeType carma::canbus::Device::getNode

(

)

const

Return node location code of device.

Returns

9 bit node id.

serialNumberType carma::canbus::Device::getSerialNumber

(

)

const

Return serial number of device.

Returns

9 bit serial number id.

virtual MsgIdInfoMap carma::canbus::Device::getSlowMonitors ( ) const

pure virtual

Return a map of devices slow monitor points.

This routine returns a map of slow CAN messages (5 second) that are processed by this Device class. These messages will contain the 'slow' monitor points as described in the CANbus API for the device. It must be defined by the implementor of this base class and is needed to properly simulate a device when OFFLINE.

Returns

MsgIdInfoMap containing a string description of the CAN message keyed by it's message id.

See Also

Device::simulateMsg

carma::canbus::Master

Implemented in sza::antenna::canbus::CanDevice, carma::antenna::ovro::Drive, carma::antenna::common::AntennaIF, carma::antenna::common::SisReceiver, carma::antenna::ovro::Tiltmeter, carma::antenna::ovro::Encoder, carma::downconverter::LoMonitor, carma::antenna::ovro::SecondaryMirror, carma::downconverter::QuadratureModulator, carma::antenna::ovro::CryoCompressor, carma::downconverter::NoiseSource, carma::downconverter::SpectralDownconverter, carma::antenna::common::LOReferenceMonitor, carma::antenna::ovro::Tiltmeter, carma::antenna::ovro::Optics, carma::downconverter::Downconverter, carma::antenna::ovro::GunnPll, carma::canbus::devices::XacDevice, carma::antenna::ovro::YigPll, carma::antenna::common::Varactor, carma::downconverter::LoControl, carma::antenna::ovro::EnvironmentalMonitor, carma::antenna::ovro::CryoTemperatures, and carma::downconverter::BlockDownconverter.

deviceStateType carma::canbus::Device::getState

(

)

const

Status access routine.

Returns

status of device.

void carma::canbus::Device::incrementLatePacketCount ( )

protected

Increment the late packet count by 1.

bool carma::canbus::Device::isPacketLate ( double  window = 100.0 )

protected

Determine if the last packet sent from this device was late.

This method should be used within an implemented processMsg method to determine if the message being processed is 'late'. Late packets are packets which arive outside of a designated time frame (default to 100ms, 10ms buffer window before half second tick and 100ms after). This should only be used to check monitor and slow monitor packets after the device is determined to be ONLINE.

Parameters

window

Valid time period after half second tick in ms.

Returns

true if packet is late, false otherwise.

See Also

carma::canbus::Device::incrementLatePacketCount

carma::canbus::Device::resetLatePacketCount

carma::canbus::Device::getNlatePackets

virtual void carma::canbus::Device::processMsg ( msgType  messageId, std::vector< byteType > &  data, bool  sim  )

pure virtual

Process a CAN message.

This routine is responsible for defining how to process CAN message data based on the type of message received (msgType). It should encapsulate either directly or indirectly all details related to unpacking CAN messages, processing the data and placing it into the monitor system. The sim flag indicates that the message came from a simulated source.

Parameters

messageId	the 10bit canbus::msgType indicating message function.
data	reference to a byte vector containing raw CAN data.
sim	Flag indicating if the message is a simulated one - this can be used to set Device state to ONLINE.

See Also

Device::setState

Device::simulateMsg

Implemented in sza::antenna::canbus::CanDevice, carma::antenna::ovro::Tiltmeter, carma::downconverter::LoMonitor, carma::antenna::ovro::CryoCompressor, carma::downconverter::QuadratureModulator, carma::downconverter::NoiseSource, carma::downconverter::SpectralDownconverter, carma::antenna::ovro::Tiltmeter, carma::antenna::ovro::Optics, carma::antenna::ovro::YigPll, and carma::antenna::ovro::CryoTemperatures.

void carma::canbus::Device::reset

(

)

Perform a software reset of module.

Software resets differ from hardware resets in that they are triggered via a CAN message rather than writing the buswide dio line high (canbus::CanDio::reset). Thus they can be directed to individual devices.

Exceptions

carma::canbus::TxBufferFullException

via CanIo::postMessage.

See Also

carma::canbus::CanIo::postMessage.

void carma::canbus::Device::resetLatePacketCount ( )

protected

Reset the late packet count to 0.

A developer may want to do this when a device goes OFFLINE and perhaps a new device is plugged in or a new firmware version is installed. In general it is probably easiest to just reset it when a device requests initialization.

void carma::canbus::Device::setApiVersion ( char  api )

protected

Set API Version.

The API Version should be obtained from the CANbus API document used to create a particular device class.

Parameters

ver	API Version

See Also

Device::getApiVersion

void carma::canbus::Device::setBoardType

(

boardType

bt

)

Set board type of device.

void carma::canbus::Device::setBusId

(

busIdType

busId

)

Set busId of device.

This routine is called internally by canbus::Master whenever it receives a CAN message addressed to the Device. The busId is generally construted from the Janz CAN device name to assure uniqueness. The user in general should not have to set a Devices busId explicitly.

Parameters

busId

of device.

virtual void carma::canbus::Device::setLastRxTime ( double  rxMjd )

virtual

Set latest rx time.

This method should be called to set the MJD of the last time a message was received for this device. In general it is called every time a message is received addressed to a particular device. There are however caveats related to simulating OFFLINE nodes.

Parameters

rxMjd

Mean Julian Day of message rx.

See Also

Device::simulateMsg

void carma::canbus::Device::setSerialNumber

(

serialNumberType

sn

)

Set serial number of device.

virtual void carma::canbus::Device::setState ( deviceStateType  state )

virtual

Set state of device.

The implementor should define the logic that sets the state to ONLINE. This is generally determined by checking the Devices lastRxTime variable via Device::getLastRxTime. canbus::Master is responsible for setting a devices state to OFFLINE when messages haven't been received for that device in a certain amount of time.

Parameters

state

device state.

Reimplemented in carma::canbus::devices::XacDevice.

virtual carma::canbus::Message carma::canbus::Device::simulateMsg ( msgType  messageId )

pure virtual

Simulate a CAN message.

This routine is intended to simulate CAN messages when the Device is in the OFFLINE state. An implementer of this class is required to overload this method and return the appropriate carma::canbus::Message for a given msgType (message id). The Message is automatically placed into the shared CAN Message queue and processed by Master exactly as if it came from the CANbus. This enables a user to completely emulate the CANbus device and Janz hardware as well, while exercising the majority of code involved in processing a CAN message. Note that the msgTypes which simulateMsg is called for by canbus::Master are retrieved via the above Device::getHalfSecMonitors and Device::getSlowMonitors routines, thus simulateMsg must properly handle all msgTypes returned from these routines.

Parameters

messageId

10bit id indicating message function.

See Also

carma::canbus::Message::setRxMjd

carma::canbus::Device::getSlowMonitors

carma::canbus::Device::getHalfSecMonitors

carma::canbus::Device::setLastRxTime

carma::canbus::Device::setState

carma::canbus::Device::createMsgToHost

carma::canbus::Device::createMsgToNode

Implemented in sza::antenna::canbus::CanDevice, carma::antenna::ovro::Drive, carma::antenna::common::AntennaIF, carma::antenna::ovro::Tiltmeter, carma::antenna::common::SisReceiver, carma::downconverter::LoMonitor, carma::antenna::ovro::SecondaryMirror, carma::downconverter::QuadratureModulator, carma::downconverter::SpectralDownconverter, carma::antenna::ovro::CryoCompressor, carma::downconverter::NoiseSource, carma::antenna::common::LOReferenceMonitor, carma::downconverter::Downconverter, carma::antenna::ovro::Tiltmeter, carma::antenna::ovro::GunnPll, carma::antenna::ovro::Optics, carma::antenna::ovro::Encoder, carma::antenna::ovro::YigPll, carma::antenna::ovro::EnvironmentalMonitor, carma::antenna::ovro::CryoTemperatures, carma::antenna::common::Varactor, carma::downconverter::LoControl, and carma::downconverter::BlockDownconverter.

void carma::canbus::Device::startChannelOneFastSampling

(

unsigned short

fastItem

)

Start fast sampling the specified data item on channel 1.

This routine starts fast sampling as described in the CARMA CANbus API template. It first issues a request to all nodes to stop fast sampling on channel one to reasonably assure that only one module is using the channel.

Parameters

fastItem

Id of data item to fast sample. This id is API specific.

Exceptions

carma::canbus::TxBufferFullException

via CanIo::postMessage.

See Also

carma::canbus::CanIo::postMessage.

void carma::canbus::Device::startChannelTwoFastSampling

(

unsigned short

fastItem

)

Start fast sampling the specified data item on channel 2.

This routine starts fast sampling as described in the CARMA CANbus API template. It first issues a request to all nodes to stop fast sampling on channel two to reasonably assure that only one module is using the channel.

Parameters

fastItem

Id of data item to fast sample. This id is API specific.

Exceptions

carma::canbus::TxBufferFullException

via CanIo::postMessage.

See Also

carma::canbus::CanIo::postMessage.

void carma::canbus::Device::stopChannelOneFastSampling

(

)

Stop fast sampling on channel 1 This routine will stop fast sampling on channel 1 regardless of whether this node is fast sampling the channel or not! In other words the request goes out globally.

void carma::canbus::Device::stopChannelTwoFastSampling

(

)

Stop fast sampling on channel 2 This routine will stop fast sampling on channel 2 regardless of whether this node is fast sampling the channel or not! In other words the request goes out globally.

virtual void carma::canbus::Device::updateFrameData ( )

virtual

Update device or monitor data on frame timescale...

This routine is called every half second for every device registered with a carma::canbus::Master derivative. The default implementation does nothing but a user should overload it to guarantee that certain monitor points are updated every half second regardless of CAN activity. A good example of this is a monitor point representing Device state (ONLINE, OFFLINE, etc). We don't want a monitor point representing this state to be persistent because we want the monitor system to invalidate it if the application quits or data is otherwise not moving through the system. Thus we need to explicitly set the monitor point every half second. There are probably many monitor points where the same mechanism is needed. See the Carma Monitor System for more info or carma::monitor.

Reimplemented in carma::antenna::common::AntennaIF, carma::downconverter::SpectralDownconverter, carma::downconverter::Downconverter, carma::downconverter::LoMonitor, carma::downconverter::QuadratureModulator, carma::downconverter::NoiseSource, carma::antenna::common::SisReceiver, carma::antenna::ovro::Tiltmeter, carma::antenna::ovro::SecondaryMirror, carma::antenna::ovro::GunnPll, carma::antenna::ovro::CryoCompressor, carma::antenna::common::LOReferenceMonitor, carma::antenna::ovro::Tiltmeter, carma::antenna::ovro::Optics, carma::antenna::ovro::YigPll, carma::antenna::ovro::EnvironmentalMonitor, carma::downconverter::LoControl, carma::antenna::common::Varactor, carma::antenna::ovro::CryoTemperatures, and carma::downconverter::BlockDownconverter.

Member Data Documentation

CanOutput& carma::canbus::Device::io_

protected

Reference to CanOutput object.

This reference is for use by Device derivatives to post messages to the CAN bus. Note that only output access is allowed since the carma::canbus::Master class is responsible for handling input from the CANbus.

Definition at line 495 of file Device.h.

carma::canbus::Device::RESET = 0x0000

staticprotected

Software reset message id.

Definition at line 481 of file Device.h.

carma::canbus::Device::START_CHANNEL_1_FAST_SAMPLING = 0x0004

staticprotected

Begin channel 1 fast sampling message id.

Definition at line 484 of file Device.h.

carma::canbus::Device::START_CHANNEL_2_FAST_SAMPLING = 0x0005

staticprotected

Begin channel 2 fast sampling message id.

Definition at line 485 of file Device.h.

carma::canbus::Device::STOP_CHANNEL_1_FAST_SAMPLING = 0x0002

staticprotected

Stop channel 1 fast sampling message id.

Definition at line 482 of file Device.h.

---

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

• carma/canbus/Device.h