MMDevice 70
Public Types | Public Member Functions | Protected Member Functions | List of all members
CDeviceBase< T, U > Class Template Reference

Implement functionality common to all devices. More...

#include <DeviceBase.h>

Inheritance diagram for CDeviceBase< T, U >:

Public Types

typedef MM::Action< U > CPropertyAction
 
typedef MM::ActionEx< U > CPropertyActionEx
 

Public Member Functions

virtual void SetModuleName (const char *name)
 Assign a name for the module (for use only by the calling code).
 
virtual void GetModuleName (char *name) const
 Return the module name (for use only by the calling code).
 
virtual void SetDescription (const char *descr)
 Assign description string for a device (for use only by the calling code).
 
virtual void GetDescription (char *name) const
 Return device description (for use only by the calling code).
 
virtual void SetLabel (const char *label)
 Set the device label (for use only by the calling code).
 
virtual void GetLabel (char *name) const
 Return the device label (for use only by the calling code).
 
virtual double GetDelayMs () const
 Return device delay used for synchronization by the calling code.
 
virtual void SetDelayMs (double delay)
 Set the device delay used for synchronization by the calling code.
 
virtual void SetCallback (MM::Core *cbk)
 Set the callback for accessing parent functionality (used only by the calling code).
 
virtual bool UsesDelay ()
 Signal if the device responds to different delay settings.
 
virtual unsigned GetNumberOfProperties () const
 Return the number of properties.
 
virtual int GetProperty (const char *name, char *value) const
 Obtain the value of the property.
 
int GetProperty (const char *name, double &val)
 Obtain the value of the property.
 
int GetProperty (const char *name, long &val)
 Obtain the value of the property.
 
bool IsPropertyEqualTo (const char *name, const char *val) const
 Check if the property value is equal to a specific string.
 
virtual int GetPropertyReadOnly (const char *name, bool &readOnly) const
 Check whether the property is read-only.
 
virtual int GetPropertyInitStatus (const char *name, bool &preInit) const
 Check whether the property is pre-init.
 
virtual int HasPropertyLimits (const char *name, bool &hasLimits) const
 
virtual int GetPropertyLowerLimit (const char *name, double &lowLimit) const
 Provide lower limit for a property that has property limits.
 
virtual int GetPropertyUpperLimit (const char *name, double &hiLimit) const
 Provide upper limit for a property that has property limits.
 
virtual int IsPropertySequenceable (const char *name, bool &sequenceable) const
 Check whether the property can be run in a sequence.
 
virtual int GetPropertySequenceMaxLength (const char *name, long &nrEvents) const
 Provide the maximum number of events that can be executed by this sequenceable property.
 
virtual int StartPropertySequence (const char *name)
 Start a (TTL-triggered) sequence for the given property.
 
virtual int StopPropertySequence (const char *name)
 Stop a (TTL-triggered) sequence for the given property.
 
virtual int ClearPropertySequence (const char *name)
 Clear a property sequence.
 
virtual int AddToPropertySequence (const char *name, const char *value)
 Add to a property sequence.
 
virtual int SendPropertySequence (const char *name)
 Send the property sequence to the device.
 
virtual bool GetPropertyName (unsigned uIdx, char *name) const
 Obtain the property name given the index.
 
virtual int GetPropertyType (const char *name, MM::PropertyType &pt) const
 Obtain property type (string, float, or integer).
 
virtual int SetProperty (const char *name, const char *value)
 Set the property value.
 
virtual bool HasProperty (const char *name) const
 Check if device supports a given property.
 
virtual unsigned GetNumberOfPropertyValues (const char *propertyName) const
 Return the number of allowed property values.
 
virtual bool GetPropertyValueAt (const char *propertyName, unsigned index, char *value) const
 Return the allowed value of the property, given its index.
 
int CreateProperty (const char *name, const char *value, MM::PropertyType eType, bool readOnly, MM::ActionFunctor *pAct=0, bool isPreInitProperty=false)
 Create a new property for the device.
 
int CreatePropertyWithHandler (const char *name, const char *value, MM::PropertyType eType, bool readOnly, int(U::*memberFunction)(MM::PropertyBase *pProp, MM::ActionType eAct), bool isPreInitProperty=false)
 Create a new property for the device.
 
int CreateIntegerProperty (const char *name, long value, bool readOnly, MM::ActionFunctor *pAct=0, bool isPreInitProperty=false)
 Create an integer-valued property for the device.
 
int CreateFloatProperty (const char *name, double value, bool readOnly, MM::ActionFunctor *pAct=0, bool isPreInitProperty=false)
 Create a float-valued property for the device.
 
int CreateStringProperty (const char *name, const char *value, bool readOnly, MM::ActionFunctor *pAct=0, bool isPreInitProperty=false)
 Create a string-valued property for the device.
 
int SetPropertyLimits (const char *name, double low, double high)
 Define limits for properties with a continuous range of values.
 
int SetAllowedValues (const char *name, std::vector< std::string > &values)
 Set an entire array of allowed values.
 
int ClearAllowedValues (const char *name)
 Clear allowed values, and make any value valid.
 
int AddAllowedValue (const char *name, const char *value)
 Add a single allowed value.
 
int AddAllowedValue (const char *name, const char *value, long data)
 Add a single allowed value, plus additional data.
 
int GetPropertyData (const char *name, const char *value, long &data)
 Obtain data field associated with the allowed property value.
 
int GetCurrentPropertyData (const char *name, long &data)
 Obtain data field associated with the currently applied property value.
 
int UpdateStatus ()
 Refresh the entire state of the device and synchronize property values with the actual state of the hardware.
 
int UpdateProperty (const char *name)
 Update property value from the hardware.
 
int ApplyProperty (const char *name)
 Apply the current property value to the hardware.
 
virtual bool GetErrorText (int errorCode, char *text) const
 Obtain the error text associated with the error code.
 
virtual bool SupportsDeviceDetection (void)
 
virtual MM::DeviceDetectionStatus DetectDevice (void)
 
virtual void SetParentID (const char *parentId)
 
virtual void GetParentID (char *parentID) const
 

Protected Member Functions

void SetErrorText (int errorCode, const char *text)
 Define the error text associated with the code.
 
const char * GetMorePropertyErrorInfo (void) const
 
void SetMorePropertyErrorInfo (const char *ptext) const
 
int LogMessage (const char *msg, bool debugOnly=false) const
 Output the specified text message to the log stream.
 
int LogMessage (const std::string &msg, bool debugOnly=false) const
 Output the specified text message to the log stream.
 
int LogMessageCode (const int errorCode, bool debugOnly=false) const
 Output the text message of specified code to the log stream.
 
int LogTimeDiff (MM::MMTime start, MM::MMTime end, const std::string &message, bool debugOnly=false) const
 Output time difference between two time stamps.
 
int LogTimeDiff (MM::MMTime start, MM::MMTime end, bool debugOnly=false) const
 Output time difference between two time stamps.
 
void InitializeDefaultErrorMessages ()
 Set up the standard set of error codes and error messages.
 
MM::DeviceGetDevice (const char *deviceLabel) const
 Get the handle (pointer) to the specified device label.
 
void GetLoadedDeviceOfType (MM::DeviceType devType, char *deviceName, const unsigned int deviceIterator)
 Provide access to the names of devices of a given type.
 
int WriteToComPort (const char *portLabel, const unsigned char *buf, unsigned bufLength)
 Send an array of bytes to the COM port.
 
int SendSerialCommand (const char *portName, const char *command, const char *term)
 Send an ASCII string with the specified terminating characters to the serial port.
 
int GetSerialAnswer (const char *portName, const char *term, std::string &ans)
 Get the received string from the serial port, waiting for the terminating character sequence.
 
int ReadFromComPort (const char *portLabel, unsigned char *buf, unsigned bufLength, unsigned long &read)
 Read the current contents of Rx serial buffer.
 
int PurgeComPort (const char *portLabel)
 Clear the serial port buffers.
 
MM::PortType GetSerialPortType (const char *portLabel)
 TODO-BRIEF.
 
int OnPropertiesChanged ()
 Signal that something changed in the property structure.
 
int OnPropertyChanged (const char *propName, const char *propValue)
 Signal to the core that a property value has changed.
 
int OnStagePositionChanged (double pos)
 Signal that the stage has arrived at a new position.
 
int OnXYStagePositionChanged (double xPos, double yPos)
 Signal that the XY stage has arrived at a new position.
 
int OnExposureChanged (double exposure)
 Signal that the exposure has changed.
 
int OnSLMExposureChanged (double exposure)
 Signal that the SLM exposure has changed.
 
int OnMagnifierChanged ()
 Signal that the magnifier has changed.
 
unsigned long GetClockTicksUs ()
 Get the system ticks in microseconds.
 
MM::MMTime GetCurrentMMTime ()
 Get current time.
 
bool IsCallbackRegistered () const
 Check if we have callback mechanism set up.
 
MM::CoreGetCoreCallback () const
 Get the callback object.
 
void EnableDelay (bool state=true)
 Enable response to delay settings.
 
void CreateHubIDProperty ()
 Create read-only property displaying parentID (hub label).
 
MM::HubGetParentHub () const
 Return the parent Hub device pointer, or null if there isn't any.
 
template<class T_HUB >
T_HUB * AssignToHub ()
 Return the parent Hub device pointer, or null if there isn't any.
 

Detailed Description

template<class T, class U>
class CDeviceBase< T, U >

Implement functionality common to all devices.

Typically used as the base class for actual device adapters. In general, derived class do not override DeviceBase methods, but rather take advantage of using them to simplify development of specific drivers.

Member Function Documentation

◆ AddToPropertySequence()

template<class T , class U >
virtual int CDeviceBase< T, U >::AddToPropertySequence ( const char *  name,
const char *  value 
)
inlinevirtual

Add to a property sequence.

This function is used by the Core to communicate a sequence to the device.

Parameters
namename of the sequenceable property
valuevalue to append to sequence

◆ AssignToHub()

template<class T , class U >
template<class T_HUB >
T_HUB * CDeviceBase< T, U >::AssignToHub ( )
inlineprotected

Return the parent Hub device pointer, or null if there isn't any.

Make sure the Parent ID has been assigned.

References CDeviceBase< T, U >::GetParentHub(), and CDeviceBase< T, U >::LogMessage().

◆ ClearPropertySequence()

template<class T , class U >
virtual int CDeviceBase< T, U >::ClearPropertySequence ( const char *  name)
inlinevirtual

Clear a property sequence.

This function is used by the Core to communicate a sequence to the device.

Parameters
namename of the sequenceable property

◆ CreateHubIDProperty()

template<class T , class U >
void CDeviceBase< T, U >::CreateHubIDProperty ( )
inlineprotected

Create read-only property displaying parentID (hub label).

By looking at this HubID property we can see which hub this peripheral belongs to. Can be called anywhere in the device code, but the most logical place is the constructor. Use is optional, to provide useful info.

References CDeviceBase< T, U >::CreateProperty().

◆ CreateProperty()

template<class T , class U >
int CDeviceBase< T, U >::CreateProperty ( const char *  name,
const char *  value,
MM::PropertyType  eType,
bool  readOnly,
MM::ActionFunctor pAct = 0,
bool  isPreInitProperty = false 
)
inline

Create a new property for the device.

Parameters
nameproperty name
valueinitial value
eTypeproperty type (string, integer, or float)
readOnlyis the property read-only or not
pActfunction object called on the property actions
isPreInitPropertywhether to create a "pre-init" property, whose value will be available before Initialize() is called

Referenced by CDeviceBase< T, U >::CreateFloatProperty(), CDeviceBase< T, U >::CreateHubIDProperty(), CDeviceBase< T, U >::CreateIntegerProperty(), CDeviceBase< T, U >::CreatePropertyWithHandler(), and CDeviceBase< T, U >::CreateStringProperty().

◆ CreatePropertyWithHandler()

template<class T , class U >
int CDeviceBase< T, U >::CreatePropertyWithHandler ( const char *  name,
const char *  value,
MM::PropertyType  eType,
bool  readOnly,
int(U::*)(MM::PropertyBase *pProp, MM::ActionType eAct)  memberFunction,
bool  isPreInitProperty = false 
)
inline

Create a new property for the device.

Parameters
nameproperty name
valueinitial value
eTypeproperty type (string, integer, or float)
readOnlyis the property read-only or not
memberFunctionFunction pointer to the device object "OnProperty" member function, e.g. &MyDevice::OnState
isPreInitPropertywhether to create a "pre-init" property, whose value will be available before Initialize() is called

References CDeviceBase< T, U >::CreateProperty().

◆ EnableDelay()

template<class T , class U >
void CDeviceBase< T, U >::EnableDelay ( bool  state = true)
inlineprotected

Enable response to delay settings.

If this flag is set, the device signals to the rest of the system that it will respond to delay settings.

◆ GetClockTicksUs()

template<class T , class U >
unsigned long CDeviceBase< T, U >::GetClockTicksUs ( )
inlineprotected

Get the system ticks in microseconds.

OBSOLETE, use GetCurrentTime().

◆ GetDelayMs()

template<class T , class U >
virtual double CDeviceBase< T, U >::GetDelayMs ( ) const
inlinevirtual

Return device delay used for synchronization by the calling code.

Delay of 0 means that the device should be synchronized by polling with the Busy() method.

◆ GetDevice()

template<class T , class U >
MM::Device * CDeviceBase< T, U >::GetDevice ( const char *  deviceLabel) const
inlineprotected

Get the handle (pointer) to the specified device label.

With this method we can get a handle to other devices loaded in the system, if we know the device name.

References MM::Core::GetDevice().

◆ GetLabel()

template<class T , class U >
virtual void CDeviceBase< T, U >::GetLabel ( char *  name) const
inlinevirtual

Return the device label (for use only by the calling code).

Labels are usually manipulated by the parent application and used for high-level programming.

References CDeviceUtils::CopyLimitedString().

◆ GetLoadedDeviceOfType()

template<class T , class U >
void CDeviceBase< T, U >::GetLoadedDeviceOfType ( MM::DeviceType  devType,
char *  deviceName,
const unsigned int  deviceIterator 
)
inlineprotected

Provide access to the names of devices of a given type.

deviceIterator determines which device in the list of devices of the given type will become accessible in deviceName. If deviceIterator exceeds the number of devices of the given type, no action will be taken (i.e., the memory pointed to by deviceName will be unchanged).

References MM::Core::GetLoadedDeviceOfType().

◆ GetNumberOfPropertyValues()

template<class T , class U >
virtual unsigned CDeviceBase< T, U >::GetNumberOfPropertyValues ( const char *  propertyName) const
inlinevirtual

Return the number of allowed property values.

If the set of property values is not defined, not bounded, or property does not exist, the call returns 0.

◆ GetParentHub()

template<class T , class U >
MM::Hub * CDeviceBase< T, U >::GetParentHub ( ) const
inlineprotected

Return the parent Hub device pointer, or null if there isn't any.

GetParentHub() call makes sure that the hub pointer belongs to a class from the same module (device library). This is to avoid using dynamic_cast<> which won't work for Linux.

References CDeviceBase< T, U >::GetCoreCallback(), and CDeviceBase< T, U >::IsCallbackRegistered().

Referenced by CDeviceBase< T, U >::AssignToHub().

◆ GetProperty() [1/3]

template<class T , class U >
virtual int CDeviceBase< T, U >::GetProperty ( const char *  name,
char *  value 
) const
inlinevirtual

Obtain the value of the property.

Parameters
nameproperty identifier (name)
valuethe value of the property

References CDeviceUtils::CopyLimitedString().

◆ GetProperty() [2/3]

template<class T , class U >
int CDeviceBase< T, U >::GetProperty ( const char *  name,
double &  val 
)
inline

Obtain the value of the property.

Parameters
nameproperty identifier (name)
valthe value of the property

◆ GetProperty() [3/3]

template<class T , class U >
int CDeviceBase< T, U >::GetProperty ( const char *  name,
long &  val 
)
inline

Obtain the value of the property.

Parameters
nameproperty identifier (name)
valthe value of the property

◆ GetPropertyInitStatus()

template<class T , class U >
virtual int CDeviceBase< T, U >::GetPropertyInitStatus ( const char *  name,
bool &  preInit 
) const
inlinevirtual

Check whether the property is pre-init.

Parameters
nameproperty identifier (name)
preInittrue if property is pre-init

◆ GetPropertyLowerLimit()

template<class T , class U >
virtual int CDeviceBase< T, U >::GetPropertyLowerLimit ( const char *  name,
double &  lowLimit 
) const
inlinevirtual

Provide lower limit for a property that has property limits.

Parameters
nameproperty identifier (name)
lowLimitreturns lower limit

◆ GetPropertyName()

template<class T , class U >
virtual bool CDeviceBase< T, U >::GetPropertyName ( unsigned  uIdx,
char *  name 
) const
inlinevirtual

Obtain the property name given the index.

Can be used for enumerating properties.

Parameters
uIdxproperty index
nameproperty name

References CDeviceUtils::CopyLimitedString().

◆ GetPropertyReadOnly()

template<class T , class U >
virtual int CDeviceBase< T, U >::GetPropertyReadOnly ( const char *  name,
bool &  readOnly 
) const
inlinevirtual

Check whether the property is read-only.

Parameters
nameproperty identifier (name)
readOnlyread-only or not

◆ GetPropertySequenceMaxLength()

template<class T , class U >
virtual int CDeviceBase< T, U >::GetPropertySequenceMaxLength ( const char *  name,
long &  nrEvents 
) const
inlinevirtual

Provide the maximum number of events that can be executed by this sequenceable property.

Parameters
nameproperty identifier (name)
nrEventsmaximum number of events that can be handled by the device

References CDeviceBase< T, U >::IsPropertySequenceable().

◆ GetPropertyUpperLimit()

template<class T , class U >
virtual int CDeviceBase< T, U >::GetPropertyUpperLimit ( const char *  name,
double &  hiLimit 
) const
inlinevirtual

Provide upper limit for a property that has property limits.

Parameters
nameproperty identifier (name)
hiLimitreturns upper limit

◆ GetPropertyValueAt()

template<class T , class U >
virtual bool CDeviceBase< T, U >::GetPropertyValueAt ( const char *  propertyName,
unsigned  index,
char *  value 
) const
inlinevirtual

Return the allowed value of the property, given its index.

Intended for enumerating allowed property values.

Parameters
propertyName
index
value

References CDeviceUtils::CopyLimitedString().

◆ GetSerialAnswer()

template<class T , class U >
int CDeviceBase< T, U >::GetSerialAnswer ( const char *  portName,
const char *  term,
std::string &  ans 
)
inlineprotected

Get the received string from the serial port, waiting for the terminating character sequence.

Parameters
portName
termterminating string, e.g. CR or CR,LF, or something else
ansanswer string without the terminating characters

◆ GetSerialPortType()

template<class T , class U >
MM::PortType CDeviceBase< T, U >::GetSerialPortType ( const char *  portLabel)
inlineprotected

TODO-BRIEF.

Not to be confused with MM::PortType MM::Serial::GetPortType() const.

◆ IsPropertyEqualTo()

template<class T , class U >
bool CDeviceBase< T, U >::IsPropertyEqualTo ( const char *  name,
const char *  val 
) const
inline

Check if the property value is equal to a specific string.

Parameters
nameproperty identifier (name)
valthe value to compare to
Returns
true only if property exists and is equal to, false otherwise

◆ IsPropertySequenceable()

template<class T , class U >
virtual int CDeviceBase< T, U >::IsPropertySequenceable ( const char *  name,
bool &  sequenceable 
) const
inlinevirtual

Check whether the property can be run in a sequence.

Parameters
nameproperty identifier (name)
sequenceablesequenceable or not

Referenced by CDeviceBase< T, U >::GetPropertySequenceMaxLength(), CDeviceBase< T, U >::StartPropertySequence(), and CDeviceBase< T, U >::StopPropertySequence().

◆ LogMessage() [1/2]

template<class T , class U >
int CDeviceBase< T, U >::LogMessage ( const char *  msg,
bool  debugOnly = false 
) const
inlineprotected

Output the specified text message to the log stream.

Parameters
msgmessage text
debugOnlyif true the message will be sent only in the log-debug mode

References MM::Core::LogMessage().

Referenced by CDeviceBase< T, U >::AssignToHub(), and CDeviceBase< T, U >::SetPropertyLimits().

◆ LogMessage() [2/2]

template<class T , class U >
int CDeviceBase< T, U >::LogMessage ( const std::string &  msg,
bool  debugOnly = false 
) const
inlineprotected

Output the specified text message to the log stream.

Parameters
msgmessage text
debugOnlyif true the message will be sent only in the log-debug mode

References MM::Core::LogMessage().

◆ LogMessageCode()

template<class T , class U >
int CDeviceBase< T, U >::LogMessageCode ( const int  errorCode,
bool  debugOnly = false 
) const
inlineprotected

Output the text message of specified code to the log stream.

Parameters
errorCodeerror code
debugOnlyif true the message will be sent only in the log-debug mode

References CDeviceBase< T, U >::GetErrorText(), and MM::Core::LogMessage().

◆ LogTimeDiff() [1/2]

template<class T , class U >
int CDeviceBase< T, U >::LogTimeDiff ( MM::MMTime  start,
MM::MMTime  end,
bool  debugOnly = false 
) const
inlineprotected

Output time difference between two time stamps.

Handy for hardware profiling.

Parameters
starttime stamp for start of process
endtime stamp for end of process
debugOnlyif true the message will be sent only in the log-debug mode

References CDeviceBase< T, U >::LogTimeDiff().

◆ LogTimeDiff() [2/2]

template<class T , class U >
int CDeviceBase< T, U >::LogTimeDiff ( MM::MMTime  start,
MM::MMTime  end,
const std::string &  message,
bool  debugOnly = false 
) const
inlineprotected

Output time difference between two time stamps.

Handy for hardware profiling.

Parameters
starttime stamp for start of process
endtime stamp for end of process
messagemessage that will be displayed in output
debugOnlyif true the message will be sent only in the log-debug mode

References MM::Core::LogMessage().

Referenced by CDeviceBase< T, U >::LogTimeDiff().

◆ OnPropertiesChanged()

template<class T , class U >
int CDeviceBase< T, U >::OnPropertiesChanged ( )
inlineprotected

Signal that something changed in the property structure.

Signals the need for GUI update. This function should be called only after the initialize function finished. Calling it in the constructor or in the Initialize function will cause other device adapters to be called before they are initialized.

◆ SendPropertySequence()

template<class T , class U >
virtual int CDeviceBase< T, U >::SendPropertySequence ( const char *  name)
inlinevirtual

Send the property sequence to the device.

This function is used by the Core to communicate a sequence to the device. It sends the sequence to the device by calling the property's functor.

Parameters
namename of the sequenceable property

◆ SendSerialCommand()

template<class T , class U >
int CDeviceBase< T, U >::SendSerialCommand ( const char *  portName,
const char *  command,
const char *  term 
)
inlineprotected

Send an ASCII string with the specified terminating characters to the serial port.

Parameters
portName
commandcommand string
termterminating string, e.g. CR or CR,LF, or something else

◆ SetDelayMs()

template<class T , class U >
virtual void CDeviceBase< T, U >::SetDelayMs ( double  delay)
inlinevirtual

Set the device delay used for synchronization by the calling code.

Delay of 0 means that the device should be synchronized by polling with the Busy() method.

◆ SetLabel()

template<class T , class U >
virtual void CDeviceBase< T, U >::SetLabel ( const char *  label)
inlinevirtual

Set the device label (for use only by the calling code).

Labels are usually manipulated by the parent application and used for high-level programming.

◆ SetProperty()

template<class T , class U >
virtual int CDeviceBase< T, U >::SetProperty ( const char *  name,
const char *  value 
)
inlinevirtual

Set the property value.

Parameters
nameproperty name
valueproperty value

◆ StartPropertySequence()

template<class T , class U >
virtual int CDeviceBase< T, U >::StartPropertySequence ( const char *  name)
inlinevirtual

Start a (TTL-triggered) sequence for the given property.

Should be overridden by the device adapter (when a sequence is implemented).

Parameters
nameproperty for which the sequence should be started

References CDeviceBase< T, U >::IsPropertySequenceable().

◆ StopPropertySequence()

template<class T , class U >
virtual int CDeviceBase< T, U >::StopPropertySequence ( const char *  name)
inlinevirtual

Stop a (TTL-triggered) sequence for the given property.

Should be overridden by the device adapter (when a sequence is implemented).

Parameters
nameproperty for which the sequence should be stopped

References CDeviceBase< T, U >::IsPropertySequenceable().

◆ UsesDelay()

template<class T , class U >
virtual bool CDeviceBase< T, U >::UsesDelay ( )
inlinevirtual

Signal if the device responds to different delay settings.

Default device behavior is to ignore delays and use busy signals instead.


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