Package org.eclipse.scanning.api.malcolm

Interface IMalcolmDevice

Type Parameters:
T - the type of the model for this malcolm device
All Superinterfaces:
IConfigurable<IMalcolmModel>, IDeviceRoleActor, ILevel, IModelProvider<IMalcolmModel>, INameable, IPausableDevice<IMalcolmModel>, IResettableDevice, IRunnableDevice<IMalcolmModel>, IRunnableEventDevice<IMalcolmModel>, IValidator<IMalcolmModel>
All Known Implementing Classes:
AbstractMalcolmDevice, DummyMalcolmDevice, MalcolmDevice, MalcolmDeviceProxy, ProcessingMalcolmDevice
public interface IMalcolmDevice extends IRunnableEventDevice<IMalcolmModel>, IValidator<IMalcolmModel>
This device talks to the middleware layer state machine for controlling the scan. If working inside Diamond there is a wiki here: http://confluence.diamond.ac.uk/display/MAP/WP4+Middlelayer+Design+Specification A version of this design is also in Malcolm.pdf in this package.

The name malcolm is chosen for the middleware layer between the Java OSGi server and the hardware - inspired by the sitcom 'Malcolm in the Middle' https://en.wikipedia.org/wiki/Malcolm_in_the_Middle

This interface attempts to mirror how the hardware in the python looks, hence the fact that it does not look very 'Java'. So instead of setPaused(boolean) we have pause() and resume().

Note that interrupting the thread running a malcolm call has no effect. The interrupt is ignored, except that the interrupt flag is set, i.e. Thread#isInterrupted() returns true for the current thread. This is particularly important for IRunnableDevice.run() as it is the only long-running method, and returning early while the actual malcolm device is still running could cause subsequent scans to fail. Usage:

IRunnableDeviceService service = ... // OSGi service
IMalcolmDevice malcolm = service.getRunnableDevice("malc");
IMalcolmModel model = new MalcolmModel();
model.setExposureTime(0.1)

malcolm.configure(model);
malcolm.run(); // blocks until finished

final State state = malcolm.getState();
// ... We did something!

  • Method Details

    • initialize

      void initialize() throws MalcolmDeviceException
      Initializes the connection to the actual malcolm device. This methods must be called before the malcolm device can be used.
      Throws:
      MalcolmDeviceException - if the malcolm device could not be initialized

    • isLocked

      boolean isLocked() throws MalcolmDeviceException
      Attempts to determine if the device is locked doing something like a configure or a run.
      Returns:
      true if not in locked state, otherwise false.
      Throws:
      MalcolmDeviceException

    • getAvailableAxes

      List<String> getAvailableAxes() throws ScanningException
      Returns the axes that this malcolm device can move.
      Returns:
      the axes this malcolm device can move, never null
      Throws:
      ScanningException

    • getConfiguredAxes

      List<String> getConfiguredAxes() throws ScanningException
      Returns the axes that this malcolm device is currently configured to move. Normally, the value returned is the same as getAvailableAxes(), except if the last time that malcolm was configured by calling
      invalid reference 
      IMalcolmDevice#configure(IMalcolmModel)
      , IMalcolmModel.getAxesToMove() was non-null, in which case it is the
      Returns:
      the axes that the malcolm device is currently configured to move
      Throws:
      ScanningException

    • getDetectorInfos

      List<MalcolmDetectorInfo> getDetectorInfos() throws MalcolmDeviceException
      Returns the MalcolmDetectorInfos for the detectors controlled by this malcolm device, describing their current state.
      Returns:
      detector infos
      Throws:
      MalcolmDeviceException

    • setPointGenerator

      void setPointGenerator(IPointGenerator<? extends IScanPointGeneratorModel> pointGenerator)
      Set the point generator for the malcolm device.
      Parameters:
      pointGenerator - point generator

    • getPointGenerator

      IPointGenerator<? extends IScanPointGeneratorModel> getPointGenerator()
      Get the point generator that this malcolm device has been configured with
      Returns:

    • setOutputDir

      void setOutputDir(String fileDir)
      Set the directory where malcolm will write its h5 files to. The directory should exist at the point that the malcolm device is configured, malcolm is not responsible for creating it.

    • getOutputDir

      String getOutputDir()
      Get the directory where malcolm will write its h5 files to.

    • addMalcolmListener

      void addMalcolmListener(IMalcolmEventListener listener)
      Add a listener to malcolm changes.
      Parameters:
      listener -

    • removeMalcolmListener

      void removeMalcolmListener(IMalcolmEventListener listener)
      Remove a listener to malcolm changes.
      Parameters:
      listener -

    • getDatasets

      MalcolmTable getDatasets() throws MalcolmDeviceException
      Returns a MalcolmTable object describing the datasets that this malcolm device is configured to create during a scan. This method should only be called after
      invalid reference 
      #configure(IMalcolmModel)
      has been called on this malcolm device.
      Returns:
      a table of the datasets created by this malcolm device
      Throws:
      MalcolmDeviceException - if the datasets table could not be returned for any reason

    • getVersion

      MalcolmVersion getVersion() throws MalcolmDeviceException
      Returns the version of this malcolm device.
      Returns:
      version
      Throws:
      MalcolmDeviceException - if the version cannot be returned for any reason

    • dispose

      void dispose() throws MalcolmDeviceException
      Disposes of the malcolm device causing it to disconnect from the underlying malcolm device.
      Throws:
      MalcolmDeviceException