Page History

...

Blocking vs nonblocking moves
The LSC interface provides two types of moves: blocking, and nonblocking. When started, a blocking move blocks MATLAB execution until the move is complete. When a nonblocking move is started, control is returned to MATLAB immediately after the move is initiated, so that MATLAB execution can continue. For nonblocking moves, the LSC interface allows a callback to be supplied, which fires when the move is complete.

How LSC works

Roughly speaking, you can think of LSC properties and methods and being are roughly split into two groups: those intended for the subclass writer (you), and those intended for the LSC user (whoever or whatever interacts with the class, eg ; most often, this will be the ScanImage application).

The properties you should focus on are the abstract properties, many of which have "Raw" in their names: positionAbsoluteRaw, velocityRaw, etc. You will implement these properties to provide properties of appropriately for your device, within a coordinate system and unit system of your choosing.

On the other hand, a user users of your LSC class will interact with the "non-Raw" properties: postionAbsolute, velocity, and so on. These properties provide access your to the Raw properties, but with an additional layer of code that performs unit conversion and coordinate transformation. Users of your LSC class in general will transformations. In general, LSC users do not interact with the " Raw " properties.

The situation with methods is the same. You As an LSC class author, you should focus on the abstract methods which have "Hook" in their names, such as moveStartHook. Meanwhile, users of your class will use the corresponding "non-Hook" methods, such as moveStartAbsolute. The code for moveStartAbsolute calls your moveStartHook method, but has an additional layer of code.

...

If so, you may want to subclass from dabs.interfaces.LSCSerial rather than LinearStageController. LSCSerial is itself a subclass of LSC and provides initialization of the MATLAB serial port, along with an instance of an RS232DeviceBasic object which is a serial port interface with some built-in convenience functionality.

...

The LSC interface currently uses three dimensions (X, Y, and Z) for input and output of position values. However, some devices only control one or two physical dimensions. In this case, your subclass will need to specify a nondefault value of numDeviceDimensions when calling the LSC constructor. This value specifies the number of dimensions controlled by your device.

...

Some devices have various move-related modes. For example, the sutter.MP285 has a "coarse" resolution for faster, less accurate moves, and a "fine" resolution for slower, more accurate moves.

...

If your device responds when a move is complete, then you should probably set nonblockingMoveCompletedDetectionStrategy to 'callback'. Otherwise, set it to 'poll'. Specification of this property is necessary for LSC to implement its move interface, which supports both blocking and nonblocking moves (see above).

...

• Some properties are known in advance and will not change at run-time. Examples are : positionUnits or velocityUnits, or resolutionBestfor example. These properties are implemented as regular (non-Dependent) properties, and are given default values directly in the properties block. In some cases, it may make sense to allow these properties to be optionally constructor-initialized, eg if their value depends on a firmware version which can vary from device to device. For the MP285, the positionUnits falls into this "set-it-and-forget-it" category.
• Some properties change at runtime, and involve read-only queries to the hardware. An example is positionAbsoluteRaw. These properties are implemented as Dependent properties, with get-methods that send the appropriate query commands to the hardware.
• Some properties not only change at runtime, but can be set to new values, as well as queried. An example of such a property is velocity, implemented as a Dependent property with both a set-method and a get-method. The set-method sends the appropriate set-command (and value-to-be-set) to the hardware to set the value on the device.

...

• In some cases, a property "does not apply" to a device. accelerationRaw, for example, does not apply to the MP285. To make MP285 a concrete class, accelerationRaw must be defined somewhere in a properties block; however, for the MP285, the this property doesn't do anything (its get-method always returns NaN, and there is no set-method). Your

...

• LSC subclass may similarly "omit" inapplicable properties. Note however that

...

• ScanImage

...

• will expect certain properties to be

...

• present and working. See #Minimal LSC Implementation for ScanImage below.

• The MP285 has two "resolutionModes", 'fine' and 'coarse'. Each mode has its own velocity setting, so that the resolutionMode is queried when setting/getting the velocity property. The details related to resolutionMode are specific to MP285 and may not apply to your device; however they do illustrate the general pattern of having more than one mode.

...

The LSC interface includes more than is absolutely required by ScanImage, because it was designed with the idea that it would provide a stage controller interface that would to be generally useful, independent of any single application.

That said, you are probably reading this page because you are a ScanImage user with a custom stage. At the moment, ScanImage requires the following properties and methods of LSC to be implemented/functional:

Properties

1. nonblockingMoveCompletedDetectionStrategy
2. isMoving (get only)
3. positionAbsoluteRaw (get only)
4. positionDeviceUnits (get only)resolution (get only)

Methods

1. moveStartHook

...

1. getResolutionBestHook (This method has a default implementation in LSC, but if the default method doesn't apply to your device then you should provide an override.)

Testing

When your subclass is complete, it is critical to test its operation with real hardware in a "safe" setting before live use. Implementing an LSC subclass involves a fair amount of complexity and some amount of testing/debugging time will likely be necessary to ensure reliable operation. Using an LSC without proper testing could lead to wild stage moves and damage to your rig.