From 85e0b790f10c4a410a09c81dadc2d3366607e6e4 Mon Sep 17 00:00:00 2001 From: David Meyer Date: Thu, 22 Jul 2021 16:43:15 -0400 Subject: [PATCH 1/4] Add small section for listing 3rd party devices repos to the docs. --- docs/source/user_devices.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/source/user_devices.rst b/docs/source/user_devices.rst index db2fb1a6..13fb59cd 100644 --- a/docs/source/user_devices.rst +++ b/docs/source/user_devices.rst @@ -13,4 +13,12 @@ This import statement assumes your custom device follows the new device structur Note that both the `userlib` path and the `user_devices` folder name can be custom configured in the `labconfig.ini` file. The `user_devices` folder must be in the `userlib` path. If a different `user_devices` folder name is used, the import uses that folder name in place of `user_devices` in the above import statement. -Note that we highly encourage everyone that adds support for new hardware to consider making a pull request to **labscript-devices** so that it may be added to the mainline and more easily used by other groups. \ No newline at end of file +Note that we highly encourage everyone that adds support for new hardware to consider making a pull request to **labscript-devices** so that it may be added to the mainline and more easily used by other groups. + +3rd Party Devices +----------------- + +Below is a list of 3rd party devices developed by users of **labscript** that can be used via the `user_devices` mechanism described above. If you would like to add your repository to this list, :doc:`please contact us or make a pull request`. + +* `NAQS Lab `__ +* `https://github.com/zakv/RbLab_user_devices `__ \ No newline at end of file From 24a5248babe536dc3ebcfbb1b1c04ded06e9fcf9 Mon Sep 17 00:00:00 2001 From: David Meyer Date: Fri, 23 Jul 2021 14:39:23 -0400 Subject: [PATCH 2/4] Add disclaimer to 3rd party devices description. --- docs/source/user_devices.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/source/user_devices.rst b/docs/source/user_devices.rst index 13fb59cd..a016ffa2 100644 --- a/docs/source/user_devices.rst +++ b/docs/source/user_devices.rst @@ -18,7 +18,9 @@ Note that we highly encourage everyone that adds support for new hardware to con 3rd Party Devices ----------------- -Below is a list of 3rd party devices developed by users of **labscript** that can be used via the `user_devices` mechanism described above. If you would like to add your repository to this list, :doc:`please contact us or make a pull request`. +Below is a list of 3rd party devices developed by users of **labscript** that can be used via the `user_devices` mechanism described above. These repositories are not tested or maintained by the **labscript** development team. As such, there is no guarantee they will work as **labscript** is developed. They are also not guaranteed to be free of lab-specific implementation details that may prevent direct use in your apparatus. They are provided by users to benefit the community in supporting new and/or unusual devices, and can often serve as a good reference when developing your own devices. Please direct any questions regarding these repositories to their respective owners. * `NAQS Lab `__ -* `https://github.com/zakv/RbLab_user_devices `__ \ No newline at end of file +* `Vladan Vuletic Group Rb Lab, MIT `__ + +If you would like to add your repository to this list, :doc:`please contact us or make a pull request`. \ No newline at end of file From 50f8b27aeb89e37bebbec31cb0699a39bdc590d6 Mon Sep 17 00:00:00 2001 From: David Meyer Date: Mon, 26 Jul 2021 08:04:50 -0400 Subject: [PATCH 3/4] Update docs formatting such that not more than one sentence is on a line. --- docs/source/adding_devices.rst | 25 +++++++++++----- docs/source/devices.rst | 11 +++++-- docs/source/devices/andorsolis.rst | 6 ++-- docs/source/devices/flycapture2.rst | 19 ++++++++---- docs/source/devices/ni_daqs.rst | 11 +++++-- docs/source/devices/opalkellyXEM3001.rst | 4 ++- docs/source/devices/prawnblaster.rst | 7 +++-- docs/source/devices/pulseblaster.rst | 9 ++++-- docs/source/devices/pulseblaster_no_dds.rst | 11 +++++-- docs/source/devices/pylon.rst | 33 ++++++++++++++++----- docs/source/devices/spinnaker.rst | 13 +++++--- docs/source/introduction.rst | 3 +- docs/source/user_devices.rst | 15 ++++++++-- 13 files changed, 123 insertions(+), 44 deletions(-) diff --git a/docs/source/adding_devices.rst b/docs/source/adding_devices.rst index 31ed0edf..453dbf24 100644 --- a/docs/source/adding_devices.rst +++ b/docs/source/adding_devices.rst @@ -12,15 +12,23 @@ Though not strictly required, you should also consider providing a `runviewer_pa General Strategy ~~~~~~~~~~~~~~~~ -As a general rule, it is best to model new hardware implementations off of a currently implemented device that has similar functionality. If the functionality is similar enough, it may even be possible to simply sub-class the currently implemented device, which is likely preferrable. +As a general rule, it is best to model new hardware implementations off of a currently implemented device that has similar functionality. +If the functionality is similar enough, it may even be possible to simply sub-class the currently implemented device, which is likely preferrable. -Barring the above simple solution, one must work from scratch. It is best to begin by determining the **labscript** device class to inherit from: `Psuedoclock`, `Device`, `IntermediateDevice`. The first is for implementing Psuedoclock devices, the second is for generic devices that are not hardware timed by a pseudoclock, and the last is for hardware timed device that are connected to another device controlled via labscript. +Barring the above simple solution, one must work from scratch. +It is best to begin by determining the **labscript** device class to inherit from: `Psuedoclock`, `Device`, `IntermediateDevice`. +The first is for implementing Psuedoclock devices, the second is for generic devices that are not hardware timed by a pseudoclock, and the last is for hardware timed device that are connected to another device controlled via labscript. -The `labscript_device` implements general configuration parameters, many of which are passed to the `BLACS_worker`. It also implements the `generate_code` method which converts **labscript** high-level instructions and saves them to the h5 file. +The `labscript_device` implements general configuration parameters, many of which are passed to the `BLACS_worker`. +It also implements the `generate_code` method which converts **labscript** high-level instructions and saves them to the h5 file. -The `BLACS_tab` defines the GUI widgets that control the device. This typically takes the form of using standard widgets provided by **labscript** for controlling **labscript** output primitives (ie `AnalogOut`, `DigitalOut`,`DDS`, etc). This configuration is done in the `initialiseGUI` method. This also links directly to the appropriate BLACS workers. +The `BLACS_tab` defines the GUI widgets that control the device. +This typically takes the form of using standard widgets provided by **labscript** for controlling **labscript** output primitives (ie `AnalogOut`, `DigitalOut`,`DDS`, etc). +This configuration is done in the `initialiseGUI` method. +This also links directly to the appropriate BLACS workers. -The `BLACS_worker` handles communication with the hardware itself and often represents the bulk of the work required to implement a new labscript device. In general, it should provide five different methods: +The `BLACS_worker` handles communication with the hardware itself and often represents the bulk of the work required to implement a new labscript device. +In general, it should provide five different methods: * `init`: This method initialised communications with the device. Not to be confused with the standard python class `__init__` method. * `program_manual`: This method allows for user control of the device via the `BLACS_tab`, setting outputs to the values set in the `BLACS_tab` widgets. @@ -37,7 +45,9 @@ There are currently two supported file organization styles for a labscript-devic The old style has the `labscript_device`, `BLACS_tab`, `BLACS_worker`, and `runviewer_parser` all in the same file, which typically has the same name as the `labscript_device` class name. -The new style allows for arbitrary code organization, but typically has a folder named after the `labscript_device` with each device component in a different file (ie `labscript_devices.py`, `BLACS_workers.py`, etc). With this style, the folder requires an `__init__.py` file (which can be empty) as well as a `register_classes.py` file. This file imports :obj:`` via +The new style allows for arbitrary code organization, but typically has a folder named after the `labscript_device` with each device component in a different file (ie `labscript_devices.py`, `BLACS_workers.py`, etc). +With this style, the folder requires an `__init__.py` file (which can be empty) as well as a `register_classes.py` file. +This file imports :obj:`` via .. code-block:: python @@ -56,4 +66,5 @@ This function informs **labscript** where to find the necessary classes during i Contributions to **labscript-devices** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you decide to implement a labscript-device for controlling new hardware, we highly encourage you to consider making a pull-request to the **labscript-devices** repository in order to add your work to the **labscript-suite**. Increasing the list of supported devices is an important way for the **labscript-suite** to continue to grow, allowing new users to more quickly get up and running with hardware they may already have. \ No newline at end of file +If you decide to implement a labscript-device for controlling new hardware, we highly encourage you to consider making a pull-request to the **labscript-devices** repository in order to add your work to the **labscript-suite**. +Increasing the list of supported devices is an important way for the **labscript-suite** to continue to grow, allowing new users to more quickly get up and running with hardware they may already have. \ No newline at end of file diff --git a/docs/source/devices.rst b/docs/source/devices.rst index 2cadc4fe..6237a18e 100644 --- a/docs/source/devices.rst +++ b/docs/source/devices.rst @@ -7,7 +7,9 @@ Here is a list of all the currently supported devices. Pseudoclocks ~~~~~~~~~~~~ -Pseudoclocks provide the timing backbone of the labscript_suite. These devices produce hardware-timed clocklines that trigger other device outputs and acquisitions. Many pseudoclock devices also include other types of outputs, including digital voltage and DDS frequency synthesizers. +Pseudoclocks provide the timing backbone of the labscript_suite. +These devices produce hardware-timed clocklines that trigger other device outputs and acquisitions. +Many pseudoclock devices also include other types of outputs, including digital voltage and DDS frequency synthesizers. .. toctree:: :maxdepth: 2 @@ -22,7 +24,8 @@ Pseudoclocks provide the timing backbone of the labscript_suite. These devices p NI DAQS ~~~~~~~~~~~~ -The NI_DAQmx device provides a generic interface for National Instruments data acquisition hardware. This includes digital and analog voltage I/O. These input/outputs can be either static or hardware-timed dynamically changing variables. +The NI_DAQmx device provides a generic interface for National Instruments data acquisition hardware. +This includes digital and analog voltage I/O. These input/outputs can be either static or hardware-timed dynamically changing variables. .. toctree:: :maxdepth: 2 @@ -32,7 +35,9 @@ The NI_DAQmx device provides a generic interface for National Instruments data a Cameras ~~~~~~~~~~~~ -The camera devices provide interfaces for using various scientific cameras to acquire hardware-timed images during an experiment. They are organized by the programming API the underlies the communication to the device. The "master" camera class which provides the core functionality and from which the others derive is the IMAQdx class. +The camera devices provide interfaces for using various scientific cameras to acquire hardware-timed images during an experiment. +They are organized by the programming API the underlies the communication to the device. +The "master" camera class which provides the core functionality and from which the others derive is the IMAQdx class. .. toctree:: :maxdepth: 2 diff --git a/docs/source/devices/andorsolis.rst b/docs/source/devices/andorsolis.rst index 58ae3776..26093386 100644 --- a/docs/source/devices/andorsolis.rst +++ b/docs/source/devices/andorsolis.rst @@ -3,7 +3,8 @@ Andor Solis Cameras A labscript device for controlling Andor scientific cameras via the Andor SDK3 interface. -Presently, this device is hard-coded for use with the iXon camera. Minor modifications can allow use with other Andor cameras, so long as they are compatible with the Andor SDK3 library. +Presently, this device is hard-coded for use with the iXon camera. +Minor modifications can allow use with other Andor cameras, so long as they are compatible with the Andor SDK3 library. .. autosummary:: labscript_devices.AndorSolis.labscript_devices @@ -13,7 +14,8 @@ Presently, this device is hard-coded for use with the iXon camera. Minor modific Installation ~~~~~~~~~~~~ -The Andor SDK is available from Andor as a paid product (typically purchased with the camera). It must be installed with the SDK directory added to the system path. +The Andor SDK is available from Andor as a paid product (typically purchased with the camera). +It must be installed with the SDK directory added to the system path. Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/source/devices/flycapture2.rst b/docs/source/devices/flycapture2.rst index 1ae73faf..1f8041d9 100644 --- a/docs/source/devices/flycapture2.rst +++ b/docs/source/devices/flycapture2.rst @@ -1,7 +1,9 @@ FlyCapture2 Cameras =================== -This device allows control of FLIR (formerly Point Grey) scientific cameras via the `FlyCapture2 SDK `_ with the now deprecated PyCapture2 wrapper. In order to use this device, both the SDK and the python wrapper must be installed. Note that PyCapture2 only supports up to Python 3.6. +This device allows control of FLIR (formerly Point Grey) scientific cameras via the `FlyCapture2 SDK `_ with the now deprecated PyCapture2 wrapper. +In order to use this device, both the SDK and the python wrapper must be installed. +Note that PyCapture2 only supports up to Python 3.6. The new FLIR SDK is supported using the :doc:`SpinnakerCamera labscript device `. @@ -15,21 +17,28 @@ Installation First ensure that the FlyCapture2 SDK is installed. -The python wrapper is available via FLIR and is only released for Python up to 3.6. It must be installed separately, pointed to the correct conda environment during install. +The python wrapper is available via FLIR and is only released for Python up to 3.6. +It must be installed separately, pointed to the correct conda environment during install. -For GigE cameras, ensure that the network interface card (NIC) on the computer with the BLACS controlling the camera has enabled Jumbo Frames. That maximum allowed value (typically 9000) is preferable to avoid dropped frames. +For GigE cameras, ensure that the network interface card (NIC) on the computer with the BLACS controlling the camera has enabled Jumbo Frames. +That maximum allowed value (typically 9000) is preferable to avoid dropped frames. Usage ~~~~~ -Like the :doc:`IMAQdxCamera ` device, the bulk of camera configuration is performed using a dictionary of kwargs, where the key names and values mirror those provided by the FlyCapture2 SDK interface. Which parameters can/need to be set depend on the communication interface. Discovery of what parameters are available can be done in three ways: +Like the :doc:`IMAQdxCamera ` device, the bulk of camera configuration is performed using a dictionary of kwargs, where the key names and values mirror those provided by the FlyCapture2 SDK interface. +Which parameters can/need to be set depend on the communication interface. +Discovery of what parameters are available can be done in three ways: 1. Careful reading of the FlyCapture2 SDK docs. 2. Mirroring the FlyCap Viewer parameter names and values. 3. Connecting to the camera with a minimal configuration, viewing the current parameters dictionary, and copying the relevant values to the connection table (preferred). -The python structure for setting these values differs somewhat from other camera devices in labscript, taking the form of nested dictionaries. This structure most closely matches the structure of the FlyCapture2 SDK in that each camera property has multiple sub-elements that control the feature. In this implementation, the standard camera properties are set using keys with ALL CAPS. The control of the Trigger Mode and Image Mode properties is handled separately, using a slightly different nesting structure than the other properties. +The python structure for setting these values differs somewhat from other camera devices in labscript, taking the form of nested dictionaries. +This structure most closely matches the structure of the FlyCapture2 SDK in that each camera property has multiple sub-elements that control the feature. +In this implementation, the standard camera properties are set using keys with ALL CAPS. +The control of the Trigger Mode and Image Mode properties is handled separately, using a slightly different nesting structure than the other properties. Below is a generic configuration for a Point Grey Blackfly PGE-23S6M-C device. diff --git a/docs/source/devices/ni_daqs.rst b/docs/source/devices/ni_daqs.rst index d5600996..d89b1edf 100644 --- a/docs/source/devices/ni_daqs.rst +++ b/docs/source/devices/ni_daqs.rst @@ -56,7 +56,8 @@ NI Multifunction DAQs generally provide hardware channels for :class:`StaticDigitalOut `, :class:`AnalogOut `, :class:`DigitalOut `, -and :class:`AnalogIn ` labscript quantities for use in experiments. Exact numbers of channels, performance, and configuration depend on the model of DAQ used. +and :class:`AnalogIn ` labscript quantities for use in experiments. +Exact numbers of channels, performance, and configuration depend on the model of DAQ used. .. code-block:: python @@ -78,7 +79,9 @@ and :class:`AnalogIn ` labscript quantit AnalogOut('daq_ao0',daq,'ao0') AnalogIn('daq_ai1',daq,'ai1') -NI DAQs are also used within labscript to provide a :class:`WaitMonitor `. When configured, the `WaitMonitor` allows for arbitrary-length pauses in experiment execution, waiting for some trigger to restart. The monitor provides a measurement of the duration of the wait for use in interpreting the resulting data from the experiment. +NI DAQs are also used within labscript to provide a :class:`WaitMonitor `. +When configured, the `WaitMonitor` allows for arbitrary-length pauses in experiment execution, waiting for some trigger to restart. +The monitor provides a measurement of the duration of the wait for use in interpreting the resulting data from the experiment. Configuration uses three digital I/O connections on the DAQ: @@ -98,7 +101,9 @@ An example configuration of a `WaitMonitor` using a NI DAQ is shown here # Necessary to ensure even number of digital out lines in shot DigitalOut('daq_do1',daq,'port0/line1') -Note that the counter connection is specified using the logical label `'ctr0'`. On many NI DAQs, the physical connection to this counter is PFI9. The physical wiring for this configuration would have port0/line0 wired directly to PFI9, with PFI1 being sent to the master pseudoclock retriggering system in case of timeout. If timeouts are not expected/represent experiment failure, this physical connection can be omitted. +Note that the counter connection is specified using the logical label `'ctr0'`. On many NI DAQs, the physical connection to this counter is PFI9. +The physical wiring for this configuration would have port0/line0 wired directly to PFI9, with PFI1 being sent to the master pseudoclock retriggering system in case of timeout. +If timeouts are not expected/represent experiment failure, this physical connection can be omitted. Detailed Documentation diff --git a/docs/source/devices/opalkellyXEM3001.rst b/docs/source/devices/opalkellyXEM3001.rst index 58798d60..fdd2b264 100644 --- a/docs/source/devices/opalkellyXEM3001.rst +++ b/docs/source/devices/opalkellyXEM3001.rst @@ -6,7 +6,9 @@ A pseudoclocking labscript device based on the OpalKelly XEM3001 integration mod Installation ~~~~~~~~~~~~ -Firmware (.bit) files for the FPGA are available `here `_ and should be placed in the labscript_devices folder along with the `CiceroOpalKellyXEM3001.py` file. The Opal Kelly SDK, which provides the python bindings, is also required. The python bindings will need to either be added to the PATH or manually copied to the site-packages of the virtual environment that BLACS is running in. +Firmware (.bit) files for the FPGA are available `here `_ and should be placed in the labscript_devices folder along with the `CiceroOpalKellyXEM3001.py` file. +The Opal Kelly SDK, which provides the python bindings, is also required. +The python bindings will need to either be added to the PATH or manually copied to the site-packages of the virtual environment that BLACS is running in. Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/source/devices/prawnblaster.rst b/docs/source/devices/prawnblaster.rst index 4f382fc5..c491bf85 100644 --- a/docs/source/devices/prawnblaster.rst +++ b/docs/source/devices/prawnblaster.rst @@ -30,9 +30,12 @@ The PrawnBlaster takes advantage of the specs of the Pico to provide the followi Installation ~~~~~~~~~~~~ -In order to turn the standard Pico into a PrawnBlaster, you need to load the custom firmware available in the `Github repo `_ onto the board. The simplest way to do this is by holding the reset button on the board while plugging the USB into a computer. This will bring up a mounted folder that you copy-paste the firmware to. Once copied, the board will reset and be ready to go. +In order to turn the standard Pico into a PrawnBlaster, you need to load the custom firmware available in the `Github repo `_ onto the board. +The simplest way to do this is by holding the reset button on the board while plugging the USB into a computer. +This will bring up a mounted folder that you copy-paste the firmware to. Once copied, the board will reset and be ready to go. -Note that this device communicates using a virtual COM port. The number is assigned by the controlling computer and will need to be determined in order for BLACS to connect to the PrawnBlaster. +Note that this device communicates using a virtual COM port. +The number is assigned by the controlling computer and will need to be determined in order for BLACS to connect to the PrawnBlaster. Usage ~~~~~ diff --git a/docs/source/devices/pulseblaster.rst b/docs/source/devices/pulseblaster.rst index cbdf1ae7..0e03ba15 100644 --- a/docs/source/devices/pulseblaster.rst +++ b/docs/source/devices/pulseblaster.rst @@ -1,14 +1,19 @@ Pulseblaster ============ -This labscript device controls the Spincore PulseblaserDDS-II-300-AWG. The Pulseblaster is a programmable pulse generator that is the typical timing backbone of an experiment (ie it generates the pseudoclock timing pulses that control execution of other devices in the experiment). This labscript device is the master implementation of the various Pulseblaster devices. Other Pulseblaster labscript devices subclass this device and make the relevant changes to hard-coded values. Most importantly, the `core_clock_freq` must be manually set to match that of the Pulseblaster being used in order for the timing of the programmed pulses to be correct (in the `labscript_device` and the `BLACS_worker`). +This labscript device controls the Spincore PulseblaserDDS-II-300-AWG. +The Pulseblaster is a programmable pulse generator that is the typical timing backbone of an experiment (ie it generates the pseudoclock timing pulses that control execution of other devices in the experiment). +This labscript device is the master implementation of the various Pulseblaster devices. +Other Pulseblaster labscript devices subclass this device and make the relevant changes to hard-coded values. +Most importantly, the `core_clock_freq` must be manually set to match that of the Pulseblaster being used in order for the timing of the programmed pulses to be correct (in the `labscript_device` and the `BLACS_worker`). This particular version of Pulseblaster has a 75 MHz core clock frequency and also has DDS synthesizer outputs. Installation ~~~~~~~~~~~~ -Use of the Pulseblaster requires driver installation available from the manufacturer `here `_. The corresponding python wrapper, `spinapi `_ is available via pip. +Use of the Pulseblaster requires driver installation available from the manufacturer `here `_. +The corresponding python wrapper, `spinapi `_ is available via pip. .. code-block:: bash diff --git a/docs/source/devices/pulseblaster_no_dds.rst b/docs/source/devices/pulseblaster_no_dds.rst index e965e216..20964037 100644 --- a/docs/source/devices/pulseblaster_no_dds.rst +++ b/docs/source/devices/pulseblaster_no_dds.rst @@ -4,7 +4,10 @@ Pulseblaster (-DDS) Overview ~~~~~~~~ -This labscript device controls the Spincore Pulseblasers that do not have DDS outputs. The Pulseblaster is a programmable pulse generator that is the typical timing backbone of an experiment (ie it generates the pseudoclock timing pulses that control execution of other devices in the experiment). This labscript device inherits from the :doc:`Pulseblaster ` device. The primary difference is the removal of code handling DDS outputs. +This labscript device controls the Spincore Pulseblasers that do not have DDS outputs. +The Pulseblaster is a programmable pulse generator that is the typical timing backbone of an experiment (ie it generates the pseudoclock timing pulses that control execution of other devices in the experiment). +This labscript device inherits from the :doc:`Pulseblaster ` device. +The primary difference is the removal of code handling DDS outputs. The labscript-suite currently supports a number of no-dds variants of the Pulseblaster device, each with different numbers of outputs and clock frequencies: @@ -33,13 +36,15 @@ The ESR-Pro series of PulseBlasters have the Short Pulse Feature, which allows f "FIVE_PERIOD", 101, 5, 10 "ON", 111, \- , "Short Pulse Disabled" -Currently, the PulseBlaster labscript device does not use this functionality. However, in order to get any output at all, bits 21-23 must be set high manually. +Currently, the PulseBlaster labscript device does not use this functionality. +However, in order to get any output at all, bits 21-23 must be set high manually. Installation ~~~~~~~~~~~~ -Use of the Pulseblaster requires driver installation available from the manufacturer `here `_. The corresponding python wrapper, `spinapi `_ is available via pip. +Use of the Pulseblaster requires driver installation available from the manufacturer `here `_. +The corresponding python wrapper, `spinapi `_ is available via pip. .. code-block:: bash diff --git a/docs/source/devices/pylon.rst b/docs/source/devices/pylon.rst index 53ac8ac7..4a157993 100644 --- a/docs/source/devices/pylon.rst +++ b/docs/source/devices/pylon.rst @@ -4,7 +4,8 @@ Pylon Cameras Overview ~~~~~~~~ -This device allows control of Basler scientific cameras via the `Pylon API `_ with the `PyPylon python wrapper `_. In order to use this device, both the Basler Pylon API and the PyPylon wrapper must be installed. +This device allows control of Basler scientific cameras via the `Pylon API `_ with the `PyPylon python wrapper `_. +In order to use this device, both the Basler Pylon API and the PyPylon wrapper must be installed. .. autosummary:: labscript_devices.PylonCamera.labscript_devices @@ -14,7 +15,9 @@ This device allows control of Basler scientific cameras via the `Pylon API `_ (after signing up for a free account with Basler). It is advisable to use the Pylon Viewer program that comes with the SDK to test communications with the camera. +First ensure that the Basler Pylon SDK is installed. +It is available for free `here `_ (after signing up for a free account with Basler). +It is advisable to use the Pylon Viewer program that comes with the SDK to test communications with the camera. The python wrapper is installed via pip: @@ -24,14 +27,19 @@ The python wrapper is installed via pip: At present, the wrapper is tested and confirmed compatible with Pylon 5 for USB3 and GigE interface cameras. -For GigE cameras, ensure that the network interface card (NIC) on the computer with the BLACS controlling the camera has enabled Jumbo Frames. That maximum allowed value (typically 9000) is preferable to avoid dropped frames. +For GigE cameras, ensure that the network interface card (NIC) on the computer with the BLACS controlling the camera has enabled Jumbo Frames. +That maximum allowed value (typically 9000) is preferable to avoid dropped frames. -For USB3 cameras, care should be taken to use a USB3 host that is compatible with the Basler cameras. Basler maintains a list of compatible host controllers. The cameras will work on any USB3 port, but non-compatible hosts will not allow for the faster performance. +For USB3 cameras, care should be taken to use a USB3 host that is compatible with the Basler cameras. +Basler maintains a list of compatible host controllers. +The cameras will work on any USB3 port, but non-compatible hosts will not allow for the faster performance. Usage ~~~~~ -Like the :doc:`IMAQdxCamera ` device, the bulk of camera configuration is performed using a dictionary of kwargs, where the key names and values mirror those provided by the Pylon SDK interface. Which parameters can/need to be set depend on the communication interface. Discovery of what parameters are available can be done in three ways: +Like the :doc:`IMAQdxCamera ` device, the bulk of camera configuration is performed using a dictionary of kwargs, where the key names and values mirror those provided by the Pylon SDK interface. +Which parameters can/need to be set depend on the communication interface. +Discovery of what parameters are available can be done in three ways: 1. Careful reading of the Pylon SDK docs. 2. Mirroring the Pylon Viewer parameter names and values. @@ -95,7 +103,10 @@ Below are generic configurations for GigE and USB3 based cameras. Utilities ~~~~~~~~~ -The Pylon labscript device includes a script in the `testing` subfolder that can automatically determine the full-frame sensor readout time and maximum possible framerate. This tool helps in correctly determining the appropriate `minimum_recovery_time` to set for each device. The minimum recovery time is a function of the model used, the communication bus used, and minor details of the setup (such as host controller firmwares, cable lengths, host computer workload, etc). As a result, live testing of the device is often needed to accurately determine the actual recovery time needed between shots. +The Pylon labscript device includes a script in the `testing` subfolder that can automatically determine the full-frame sensor readout time and maximum possible framerate. +This tool helps in correctly determining the appropriate `minimum_recovery_time` to set for each device. +The minimum recovery time is a function of the model used, the communication bus used, and minor details of the setup (such as host controller firmwares, cable lengths, host computer workload, etc). +As a result, live testing of the device is often needed to accurately determine the actual recovery time needed between shots. The script is run from within the testing folder using @@ -105,9 +116,15 @@ The script is run from within the testing folder using with `[camera_sn]` being the serial number of the camera to connect to and test. -The script reports the minimum recovery time between two shots of 1 ms exposure each, without the use of overlapped exposure mode. Editing the script to include your typical experiment parameters will help in more accurately determining your minimum recovery time. Typically, the minimum recovery time should be slightly longer than the reported sensor readout time. +The script reports the minimum recovery time between two shots of 1 ms exposure each, without the use of overlapped exposure mode. +Editing the script to include your typical experiment parameters will help in more accurately determining your minimum recovery time. +Typically, the minimum recovery time should be slightly longer than the reported sensor readout time. -Note that in overlapped exposure mode, a second exposure is begun before the first exposure has finished reading out and *must* end after the readout of the first exposure frame is complete. This allows for a series of two exposures with shorter delay between them, at the expense of limitations on the length of the second exposure. The script will also report the minimum time between the end of one exposure and the beginning of the second (nominally `readout_time - exposure_time`). Note that this feature is automatically handled at the Pylon API level; this labscript device is not actively aware of it. As a result, incorrect uses of overlapped mode will not be caught at compile time, but rather during the shot as hardware errors. +Note that in overlapped exposure mode, a second exposure is begun before the first exposure has finished reading out and *must* end after the readout of the first exposure frame is complete. +This allows for a series of two exposures with shorter delay between them, at the expense of limitations on the length of the second exposure. +The script will also report the minimum time between the end of one exposure and the beginning of the second (nominally `readout_time - exposure_time`). +Note that this feature is automatically handled at the Pylon API level; this labscript device is not actively aware of it. +As a result, incorrect uses of overlapped mode will not be caught at compile time, but rather during the shot as hardware errors. Detailed Documentation diff --git a/docs/source/devices/spinnaker.rst b/docs/source/devices/spinnaker.rst index e231cc95..e9452720 100644 --- a/docs/source/devices/spinnaker.rst +++ b/docs/source/devices/spinnaker.rst @@ -1,7 +1,8 @@ Spinnaker Cameras ================= -This device allows control of FLIR scientific cameras via the `Spinnaker SDK `_ with the PySpin wrapper. In order to use this device, both the SDK and the python wrapper must be installed. +This device allows control of FLIR scientific cameras via the `Spinnaker SDK `_ with the PySpin wrapper. +In order to use this device, both the SDK and the python wrapper must be installed. .. autosummary:: labscript_devices.SpinnakerCamera.labscript_devices @@ -13,14 +14,18 @@ Installation First ensure that the Spinnaker SDK is installed. -The python wrapper is available via FLIR. It must be installed separately and pointed to the correct conda environment during install. +The python wrapper is available via FLIR. +It must be installed separately and pointed to the correct conda environment during install. -For GigE cameras, ensure that the network interface card (NIC) on the computer with the BLACS controlling the camera has enabled Jumbo Frames. The maximum allowed value (typically 9000) is preferable to avoid dropped frames. +For GigE cameras, ensure that the network interface card (NIC) on the computer with the BLACS controlling the camera has enabled Jumbo Frames. +The maximum allowed value (typically 9000) is preferable to avoid dropped frames. Usage ~~~~~ -Like the :doc:`IMAQdxCamera ` device, the bulk of camera configuration is performed using a dictionary of kwargs, where the key names and values mirror those provided by the Spinnaker SDK interface. Which parameters can/need to be set depend on the communication interface. Discovery of what parameters are available can be done in three ways: +Like the :doc:`IMAQdxCamera ` device, the bulk of camera configuration is performed using a dictionary of kwargs, where the key names and values mirror those provided by the Spinnaker SDK interface. +Which parameters can/need to be set depend on the communication interface. +Discovery of what parameters are available can be done in three ways: 1. Careful reading of the Spinnaker SDK docs. 2. Mirroring the SpinView parameter names and values. diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index c8932647..7bf6d337 100644 --- a/docs/source/introduction.rst +++ b/docs/source/introduction.rst @@ -21,4 +21,5 @@ Each "device" is made up of four classes that handle the various tasks. - Defines a software interface that interprets hardware instructions in a shot h5 file and displays them in the :doc:`runviewer ` GUI. -The **labscript_suite** provides an extensive :doc:`list of device classes ` for commercially available hardware. Furthermore, it is simple to add local :doc:`user devices ` to control instruments not already within the labscript-suite. +The **labscript_suite** provides an extensive :doc:`list of device classes ` for commercially available hardware. +Furthermore, it is simple to add local :doc:`user devices ` to control instruments not already within the labscript-suite. diff --git a/docs/source/user_devices.rst b/docs/source/user_devices.rst index a016ffa2..a1978387 100644 --- a/docs/source/user_devices.rst +++ b/docs/source/user_devices.rst @@ -1,7 +1,9 @@ User Devices ============ -Adding custom devices for use in the labscript-suite can be done using the `user_devices` mechanism. This mechanism provides a simple way to add support for a new device without directly interacting with the **labscript-devices** repository. This is particularly useful when using standard installations of labscript, using code that is proprietary in nature, or code that, while functional, is not mature enough for widespread dissemination. +Adding custom devices for use in the labscript-suite can be done using the `user_devices` mechanism. +This mechanism provides a simple way to add support for a new device without directly interacting with the **labscript-devices** repository. +This is particularly useful when using standard installations of labscript, using code that is proprietary in nature, or code that, while functional, is not mature enough for widespread dissemination. This is done by adding the **labscript-device** code into the `userlib/user_devices` folder. Using the custom device in a **labscript** connection table is then done by: @@ -11,14 +13,21 @@ This is done by adding the **labscript-device** code into the `userlib/user_devi This import statement assumes your custom device follows the new device structure organization. -Note that both the `userlib` path and the `user_devices` folder name can be custom configured in the `labconfig.ini` file. The `user_devices` folder must be in the `userlib` path. If a different `user_devices` folder name is used, the import uses that folder name in place of `user_devices` in the above import statement. +Note that both the `userlib` path and the `user_devices` folder name can be custom configured in the `labconfig.ini` file. +The `user_devices` folder must be in the `userlib` path. +If a different `user_devices` folder name is used, the import uses that folder name in place of `user_devices` in the above import statement. Note that we highly encourage everyone that adds support for new hardware to consider making a pull request to **labscript-devices** so that it may be added to the mainline and more easily used by other groups. 3rd Party Devices ----------------- -Below is a list of 3rd party devices developed by users of **labscript** that can be used via the `user_devices` mechanism described above. These repositories are not tested or maintained by the **labscript** development team. As such, there is no guarantee they will work as **labscript** is developed. They are also not guaranteed to be free of lab-specific implementation details that may prevent direct use in your apparatus. They are provided by users to benefit the community in supporting new and/or unusual devices, and can often serve as a good reference when developing your own devices. Please direct any questions regarding these repositories to their respective owners. +Below is a list of 3rd party devices developed by users of **labscript-suite** that can be used via the `user_devices` mechanism described above. +These repositories are not tested or maintained by the **labscript-suite** development team. +As such, there is no guarantee they will work with current or future versions of the **labscript-suite**. +They are also not guaranteed to be free of lab-specific implementation details that may prevent direct use in your apparatus. +They are provided by users to benefit the community in supporting new and/or unusual devices, and can often serve as a good reference when developing your own devices. +Please direct any questions regarding these repositories to their respective owners. * `NAQS Lab `__ * `Vladan Vuletic Group Rb Lab, MIT `__ From 2eaf0ba1c82e4176f619aed8fc522e18ae04473f Mon Sep 17 00:00:00 2001 From: David Meyer Date: Tue, 10 Aug 2021 09:21:12 -0400 Subject: [PATCH 4/4] Fixing minor typos. --- docs/source/user_devices.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/user_devices.rst b/docs/source/user_devices.rst index a1978387..23ca36fc 100644 --- a/docs/source/user_devices.rst +++ b/docs/source/user_devices.rst @@ -1,7 +1,7 @@ User Devices ============ -Adding custom devices for use in the labscript-suite can be done using the `user_devices` mechanism. +Adding custom devices for use in the **labscript-suite** can be done using the `user_devices` mechanism. This mechanism provides a simple way to add support for a new device without directly interacting with the **labscript-devices** repository. This is particularly useful when using standard installations of labscript, using code that is proprietary in nature, or code that, while functional, is not mature enough for widespread dissemination. @@ -22,7 +22,7 @@ Note that we highly encourage everyone that adds support for new hardware to con 3rd Party Devices ----------------- -Below is a list of 3rd party devices developed by users of **labscript-suite** that can be used via the `user_devices` mechanism described above. +Below is a list of 3rd party devices developed by users of the **labscript-suite** that can be used via the `user_devices` mechanism described above. These repositories are not tested or maintained by the **labscript-suite** development team. As such, there is no guarantee they will work with current or future versions of the **labscript-suite**. They are also not guaranteed to be free of lab-specific implementation details that may prevent direct use in your apparatus.