Device & Property objects#
pymmcore-plus
offers two classes that provide a more object-oriented interface
to common operations and queries performed on devices and their properties.
In the original CMMCore
API, there are a lot of methods that accept a
deviceLabel
string as the first argument (and perhaps additional arguments)
and query something about that device (e.g.
getDeviceLibrary
,
getDeviceType
,
waitForDevice
, etc...). In pymmcore-plus
, the
Device
class acts as a "view" onto a specific device, and
these methods are implemented as methods (that no longer require the deviceLabel
argument),
and the deviceLabel
is passed to the constructor.
Similarly, there are many methods in the CMMCore
API that require both a
device label and a device property name, and modify that specific property (e.g.
isPropertySequenceable
,
getProperty
,
isPropertyReadOnly
, etc...). Here, the
DeviceProperty
class acts as a "view" onto a specific
device property, with an object-oriented interface to these methods.
pymmcore_plus.DeviceAdapter
#
Convenience view onto a device-adapter library.
This is the type of object that is returned by
pymmcore_plus.CMMCorePlus.getAdapterObject
Parameters:
Name | Type | Description | Default |
---|---|---|---|
library_name |
str
|
Device this property belongs to |
required |
mmcore |
CMMCorePlus
|
CMMCorePlus instance |
required |
Source code in pymmcore_plus/core/_adapter.py
12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 |
|
available_devices() -> tuple[Device, ...]
property
#
Get available devices offered by this device adapter.
Returns:
Type | Description |
---|---|
tuple[Device, ...]
|
Tuple of |
Source code in pymmcore_plus/core/_adapter.py
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 |
|
core() -> CMMCorePlus
property
#
Return the CMMCorePlus
instance to which this Device is bound.
Source code in pymmcore_plus/core/_adapter.py
36 37 38 39 |
|
loaded_devices() -> tuple[Device, ...]
property
#
Get currently loaded devices controlled this adapter.
Returns:
Type | Description |
---|---|
tuple[Device, ...]
|
Tuple of loaded |
Source code in pymmcore_plus/core/_adapter.py
70 71 72 73 74 75 76 77 78 79 |
|
name() -> str
property
#
Return the short name of this device adapter library.
Source code in pymmcore_plus/core/_adapter.py
31 32 33 34 |
|
unload() -> None
#
Forcefully unload this library.
Source code in pymmcore_plus/core/_adapter.py
81 82 83 |
|
pymmcore_plus.Device
#
Convenience view onto a device.
This is the type of object that is returned by
pymmcore_plus.CMMCorePlus.getDeviceObject
Parameters:
Name | Type | Description | Default |
---|---|---|---|
device_label |
str
|
Device this property belongs to |
UNASIGNED
|
mmcore |
CMMCorePlus
|
CMMCorePlus instance |
None
|
Examples:
>>> core = CMMCorePlus()
>>> device = Device("Camera", core)
>>> device.isLoaded()
>>> device.load("NotALib", "DCam") # useful error
>>> device.load("DemoCamera", "DCam")
>>> device.initialize()
>>> device.load("DemoCamera", "DCam") # no-op w/ useful warning
>>> device.properties # tuple of DeviceProperty objects
>>> device.description()
>>> device.isBusy()
>>> device.wait()
>>> device.type()
>>> device.schema() # JSON schema of device properties
Source code in pymmcore_plus/core/_device.py
16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 |
|
UNASIGNED = '__UNASIGNED__'
class-attribute
#
propertyChanged = _DevicePropValueSignal(device_label, None, self._mmc)
instance-attribute
#
core() -> CMMCorePlus
property
#
Return the CMMCorePlus
instance to which this Device is bound.
Source code in pymmcore_plus/core/_device.py
83 84 85 86 |
|
delayMs() -> float
#
Return action delay in ms for this device.
Source code in pymmcore_plus/core/_device.py
92 93 94 |
|
description() -> str
#
Return device description.
Source code in pymmcore_plus/core/_device.py
104 105 106 |
|
detect() -> DeviceDetectionStatus
#
Tries to communicate to device through a given serial port.
Used to automate discovery of correct serial port. Also configures the serial port correctly.
Source code in pymmcore_plus/core/_device.py
178 179 180 181 182 183 184 |
|
getPropertyObject(property_name: str) -> DeviceProperty
#
Return a DeviceProperty
object bound to this device on this core.
Source code in pymmcore_plus/core/_device.py
127 128 129 |
|
initialize() -> None
#
Initialize device.
Source code in pymmcore_plus/core/_device.py
131 132 133 |
|
isBusy() -> bool
#
Return busy status for this device.
Source code in pymmcore_plus/core/_device.py
88 89 90 |
|
isLoaded() -> bool
#
Return True
if device is loaded.
Source code in pymmcore_plus/core/_device.py
174 175 176 |
|
label() -> str
writable
property
#
Return the assigned label of this device.
Source code in pymmcore_plus/core/_device.py
72 73 74 75 |
|
library() -> str
#
Return device library (aka module, device adapter) name.
Source code in pymmcore_plus/core/_device.py
108 109 110 |
|
load(adapter_name: str = '', device_name: str = '', device_label: str = '') -> None
#
Load device from the plugin library.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
adapter_name |
str
|
The name of the device adapter module (short name, not full file name).
(This is what is returned by |
''
|
device_name |
str
|
The name of the device. The name must correspond to one of the names
recognized by the specific plugin library. (This is what is returned by
|
''
|
device_label |
str
|
The name to assign to the device. If not specified, the device will be
assigned a default name: |
''
|
Source code in pymmcore_plus/core/_device.py
135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 |
|
name() -> str
#
Return the device name (this is not the same as the assigned label).
Source code in pymmcore_plus/core/_device.py
112 113 114 |
|
properties() -> tuple[DeviceProperty, ...]
property
#
Get all properties supported by device as DeviceProperty objects.
Source code in pymmcore_plus/core/_device.py
120 121 122 123 124 125 |
|
propertyNames() -> tuple[str, ...]
#
Return all property names supported by this device.
Source code in pymmcore_plus/core/_device.py
116 117 118 |
|
schema() -> DeviceSchema
#
Return dict in JSON-schema format for properties of device_label
.
Source code in pymmcore_plus/core/_device.py
200 201 202 |
|
setDelayMs(delayMs: float) -> None
#
Override the built-in value for the action delay.
Source code in pymmcore_plus/core/_device.py
96 97 98 |
|
supportsDetection() -> bool
#
Return whether or not the device supports automatic device detection.
(i.e. whether or not detectDevice() may be safely called).
Source code in pymmcore_plus/core/_device.py
186 187 188 189 190 191 192 193 194 |
|
type() -> DeviceType
#
Return device type.
Source code in pymmcore_plus/core/_device.py
196 197 198 |
|
unload() -> None
#
Unload device from the core and adjust all configuration data.
Source code in pymmcore_plus/core/_device.py
170 171 172 |
|
usesDelay() -> bool
#
Return True
if the device will use the delay setting or not.
Source code in pymmcore_plus/core/_device.py
100 101 102 |
|
wait() -> None
#
Block the calling thread until device becomes non-busy.
Source code in pymmcore_plus/core/_device.py
204 205 206 |
|
pymmcore_plus.DeviceProperty
#
Convenience view onto a device property.
This is the type of object that is returned by
pymmcore_plus.CMMCorePlus.getPropertyObject
Parameters:
Name | Type | Description | Default |
---|---|---|---|
device_label |
str
|
Device this property belongs to |
required |
property_name |
str
|
Name of this property |
required |
mmcore |
CMMCorePlus
|
CMMCorePlus instance |
required |
Examples:
>>> core = CMMCorePlus()
>>> prop = DeviceProperty("Objective", "Label", core)
>>> prop.isValid() # points to a loaded device property in core
>>> prop.value
>>> prop.value = "Objective-2" # setter
>>> prop.isReadOnly()
>>> prop.hasLimits()
>>> prop.range()
>>> prop.dict() # all the info in one dict.
Source code in pymmcore_plus/core/_property.py
30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 |
|
InfoDict = InfoDict
class-attribute
#
device = device_label
instance-attribute
#
name = property_name
instance-attribute
#
allowedValues() -> tuple[str, ...]
#
Return allowed values for this property, if contstrained.
Source code in pymmcore_plus/core/_property.py
147 148 149 150 151 152 153 154 155 156 157 |
|
core() -> CMMCorePlus
property
#
Return the CMMCorePlus
instance to which this Property is bound.
Source code in pymmcore_plus/core/_property.py
77 78 79 80 |
|
deviceType() -> DeviceType
#
Return DeviceType
of the device owning this property.
Source code in pymmcore_plus/core/_property.py
143 144 145 |
|
dict() -> InfoDict
#
Return dict of info about this Property.
Returns an InfoDict
with the
following keys: "valid", "value", "type", "device_type", "read_only",
"pre_init", "range", "allowed"
.
If the device is invalid or not loaded, the "valid"
key will be False
and the rest of the keys will be None
.
Source code in pymmcore_plus/core/_property.py
186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 |
|
fromCache() -> Any
#
Return cached property value.
Source code in pymmcore_plus/core/_property.py
95 96 97 |
|
hasLimits() -> bool
#
Return True
if property has limits.
Source code in pymmcore_plus/core/_property.py
123 124 125 |
|
isLoaded() -> bool
#
Return true if the device name is loaded.
Source code in pymmcore_plus/core/_property.py
73 74 75 |
|
isPreInit() -> bool
#
Return True
if property must be defined prior to initialization.
Source code in pymmcore_plus/core/_property.py
119 120 121 |
|
isReadOnly() -> bool
#
Return True
if property is read only.
Source code in pymmcore_plus/core/_property.py
115 116 117 |
|
isSequenceable() -> bool
#
Return True
if property can be used in a sequence.
Source code in pymmcore_plus/core/_property.py
159 160 161 |
|
isValid() -> bool
#
Return True
if device is loaded and has a property by this name.
Source code in pymmcore_plus/core/_property.py
69 70 71 |
|
loadSequence(eventSequence: Sequence[str]) -> None
#
Transfer a sequence of events/states/whatever to the device.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
eventSequence |
Sequence[str]
|
The sequence of events/states that the device will execute in response to external triggers |
required |
Source code in pymmcore_plus/core/_property.py
167 168 169 170 171 172 173 174 175 176 |
|
lowerLimit() -> float
#
Return lower limit if property has limits, or 0 otherwise.
Source code in pymmcore_plus/core/_property.py
127 128 129 |
|
range() -> tuple[float, float]
#
Return (lowerLimit, upperLimit) range tuple.
Source code in pymmcore_plus/core/_property.py
135 136 137 |
|
sequenceMaxLength() -> int
#
Return maximum number of property events that can be put in a sequence.
Source code in pymmcore_plus/core/_property.py
163 164 165 |
|
setValue(val: Any) -> None
#
Functional alternate to property setter.
Source code in pymmcore_plus/core/_property.py
99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 |
|
startSequence() -> None
#
Start an ongoing sequence of triggered events in a property.
Source code in pymmcore_plus/core/_property.py
178 179 180 |
|
stopSequence() -> None
#
Stop an ongoing sequence of triggered events in a property.
Source code in pymmcore_plus/core/_property.py
182 183 184 |
|
type() -> PropertyType
#
Return PropertyType
of this property.
Source code in pymmcore_plus/core/_property.py
139 140 141 |
|
upperLimit() -> float
#
Return upper limit if property has limits, or 0 otherwise.
Source code in pymmcore_plus/core/_property.py
131 132 133 |
|
value() -> Any
writable
property
#
Return current property value, cast to appropriate type if applicable.
Source code in pymmcore_plus/core/_property.py
82 83 84 85 86 87 88 |
|
valueChanged() -> _DevicePropValueSignal
cached
property
#
Source code in pymmcore_plus/core/_property.py
65 66 67 |
|