|
MMDevice 70
|
Implement functionality common to all devices. More...
#include <DeviceBase.h>
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::Device * | GetDevice (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::Core * | GetCoreCallback () 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::Hub * | GetParentHub () 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. | |
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.
|
inlinevirtual |
Add to a property sequence.
This function is used by the Core to communicate a sequence to the device.
| name | name of the sequenceable property |
| value | value to append to sequence |
|
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().
|
inlinevirtual |
Clear a property sequence.
This function is used by the Core to communicate a sequence to the device.
| name | name of the sequenceable property |
|
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().
|
inline |
Create a new property for the device.
| name | property name |
| value | initial value |
| eType | property type (string, integer, or float) |
| readOnly | is the property read-only or not |
| pAct | function object called on the property actions |
| isPreInitProperty | whether 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().
|
inline |
Create a new property for the device.
| name | property name |
| value | initial value |
| eType | property type (string, integer, or float) |
| readOnly | is the property read-only or not |
| memberFunction | Function pointer to the device object "OnProperty" member function, e.g. &MyDevice::OnState |
| isPreInitProperty | whether to create a "pre-init" property, whose value will be available before Initialize() is called |
References CDeviceBase< T, U >::CreateProperty().
|
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.
|
inlineprotected |
Get the system ticks in microseconds.
OBSOLETE, use GetCurrentTime().
|
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.
|
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().
|
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().
|
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().
|
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.
|
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().
|
inlinevirtual |
Obtain the value of the property.
| name | property identifier (name) |
| value | the value of the property |
References CDeviceUtils::CopyLimitedString().
|
inline |
Obtain the value of the property.
| name | property identifier (name) |
| val | the value of the property |
|
inline |
Obtain the value of the property.
| name | property identifier (name) |
| val | the value of the property |
|
inlinevirtual |
Check whether the property is pre-init.
| name | property identifier (name) |
| preInit | true if property is pre-init |
|
inlinevirtual |
Provide lower limit for a property that has property limits.
| name | property identifier (name) |
| lowLimit | returns lower limit |
|
inlinevirtual |
Obtain the property name given the index.
Can be used for enumerating properties.
| uIdx | property index |
| name | property name |
References CDeviceUtils::CopyLimitedString().
|
inlinevirtual |
Check whether the property is read-only.
| name | property identifier (name) |
| readOnly | read-only or not |
|
inlinevirtual |
Provide the maximum number of events that can be executed by this sequenceable property.
| name | property identifier (name) |
| nrEvents | maximum number of events that can be handled by the device |
References CDeviceBase< T, U >::IsPropertySequenceable().
|
inlinevirtual |
Provide upper limit for a property that has property limits.
| name | property identifier (name) |
| hiLimit | returns upper limit |
|
inlinevirtual |
Return the allowed value of the property, given its index.
Intended for enumerating allowed property values.
| propertyName | |
| index | |
| value |
References CDeviceUtils::CopyLimitedString().
|
inlineprotected |
Get the received string from the serial port, waiting for the terminating character sequence.
| portName | |
| term | terminating string, e.g. CR or CR,LF, or something else |
| ans | answer string without the terminating characters |
|
inlineprotected |
TODO-BRIEF.
Not to be confused with MM::PortType MM::Serial::GetPortType() const.
|
inline |
Check if the property value is equal to a specific string.
| name | property identifier (name) |
| val | the value to compare to |
|
inlinevirtual |
Check whether the property can be run in a sequence.
| name | property identifier (name) |
| sequenceable | sequenceable or not |
Referenced by CDeviceBase< T, U >::GetPropertySequenceMaxLength(), CDeviceBase< T, U >::StartPropertySequence(), and CDeviceBase< T, U >::StopPropertySequence().
|
inlineprotected |
Output the specified text message to the log stream.
| msg | message text |
| debugOnly | if 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().
|
inlineprotected |
Output the specified text message to the log stream.
| msg | message text |
| debugOnly | if true the message will be sent only in the log-debug mode |
References MM::Core::LogMessage().
|
inlineprotected |
Output the text message of specified code to the log stream.
| errorCode | error code |
| debugOnly | if true the message will be sent only in the log-debug mode |
References CDeviceBase< T, U >::GetErrorText(), and MM::Core::LogMessage().
|
inlineprotected |
Output time difference between two time stamps.
Handy for hardware profiling.
| start | time stamp for start of process |
| end | time stamp for end of process |
| debugOnly | if true the message will be sent only in the log-debug mode |
References CDeviceBase< T, U >::LogTimeDiff().
|
inlineprotected |
Output time difference between two time stamps.
Handy for hardware profiling.
| start | time stamp for start of process |
| end | time stamp for end of process |
| message | message that will be displayed in output |
| debugOnly | if true the message will be sent only in the log-debug mode |
References MM::Core::LogMessage().
Referenced by CDeviceBase< T, U >::LogTimeDiff().
|
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.
|
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.
| name | name of the sequenceable property |
|
inlineprotected |
Send an ASCII string with the specified terminating characters to the serial port.
| portName | |
| command | command string |
| term | terminating string, e.g. CR or CR,LF, or something else |
|
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.
|
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.
|
inlinevirtual |
Set the property value.
| name | property name |
| value | property value |
|
inlinevirtual |
Start a (TTL-triggered) sequence for the given property.
Should be overridden by the device adapter (when a sequence is implemented).
| name | property for which the sequence should be started |
References CDeviceBase< T, U >::IsPropertySequenceable().
|
inlinevirtual |
Stop a (TTL-triggered) sequence for the given property.
Should be overridden by the device adapter (when a sequence is implemented).
| name | property for which the sequence should be stopped |
References CDeviceBase< T, U >::IsPropertySequenceable().
|
inlinevirtual |
Signal if the device responds to different delay settings.
Default device behavior is to ignore delays and use busy signals instead.