Lab Equipment Automation Package
User-friendly package that enables flexible automation an reconfigurable setups for high-throughput experimentation and machine learning.
Control.lab.ly can be found on PyPI and can be easily installed with pip install.
$ pip install control-lab-ly
Simple start-up guide for basic usage of the package.
from controllably.Move.Cartesian import Ender
mover = Ender(...)
mover.safeMoveTo((x,y,z))
Use the built-in guide to read the documentation for the package.
from controllably import guide_me
guide_me()
Alternatively, details for each class / module / package can be explored by using the help function.
help(Ender)
For basic usage, this is all you need to know. Check the documentation for more details on each class and function.
For more advanced uses, Control.lab.ly provides a host of tools to streamline the development of lab equipment automation. This includes setting up configuration files and adding plugin drivers.
import controllably as lab
Optionally, you can set the safety policy for the session. This feature allows the user to prevent collisions before each movement is made. The safety policy has to be assigned before importing any of the Mover objects.
lab.set_safety('high') # Notifies; Pauses for input before every move action
lab.set_safety('low') # Notifies; Waits for countdown before every move action
lab.set_safety(None) # Carries out movement actions without delay
# Import control-lab-ly classes only after setting the safety policy
Create a /configs/MySetup folder that holds the configuration files for the setup, which includes config.yaml and layout.json.
lab.create_setup(setup_name = "MySetup")
config.yamlThis file stores the configuration and calibration values for your devices.
MyDevice: # device name
module: Move # top-level category
class: Cartesian.Ender # device class
settings:
port: COM1 # serial port address
setting_A: {'tuple': [300,0,200]} # use keys to define the type of iterable
setting_B: {'array': [[0,1,0],[-1,0,0]]} # only tuple and np.array supported
Each device configuration starts with the device name, then the following parameters:
module: top-level category (such as Make, Measure, Move,Transfer, View)
class: point to specific subclass using dot notation
settings: various initialisation settings
See the guide for more details on these parameters
Compound devices are similarly configured.
MyCompoundDevice: # compound device name
module: Compound
class: LiquidMover.LiquidMoverSetup
settings: # settings for your compound device
setting_C: True
component_config: # nest component configuration settings here
MyFirstDevice: # component device name
module: Transfer
class: Liquid.SyringeAssembly
settings: # settings for your component device
port: COM22
setting_D: 2
MySecondDevice: # component device name
module: Mover
class: Jointed.Dobot.M1Pro
settings: # settings for your compound device
ip_address: '192.0.0.1'
The configuration values for the component devices are nested under the
component_configsetting of the compound device.
Lastly, you can define shortcuts (or nicknames) to quickly access the components of compound devices.
SHORTCUTS:
First: 'MyCompoundDevice.MyFirstDevice'
Second: 'MyCompoundDevice.MySecondDevice'
A different serial port address or camera index may be used by different machines for the same device.
See Section 3 to find out how to manage the different addresses used by different machines.
layout.jsonThis file stores the layout configuration of your physical workspace, also known as a Deck.
See Section 2 on how to load this information into the setup.
Optional: if your setup does not involve moving objects around in a pre-defined workspace, a layout configuration may not be required
This package uses the same Labware files as those provided by Opentrons, which can be found here, and custom Labware files can be created here. Labware files are JSON files that specifies the external and internal dimensions of a Labware block / object.
{
"reference_points":{
"1": [11.1,22.2,33.3],
"2": [44.4,55.5,66.6],
"3": [77.7,88.8,99.9]
},
"slots":{
"1": {
"name": "MyLabware01",
"exclusion_height": -1,
"filepath": "MyREPO/.../MyLabware01.json"
},
"2": {
"name": "MyLabware02",
"exclusion_height": 0,
"filepath": "MyREPO/.../MyLabware02.json"
},
"3": {
"name": "MyLabware03",
"exclusion_height": 10,
"filepath": "MyREPO/.../MyLabware03.json"
}
}
}
In
reference_points, the bottom-left coordinates of each slot on the deck are defined. Slots are positions where Labware blocks may be placed.
In
slots, thenameof the Labware and thefilepathto the JSON file containing Labware details are defined. The filepath starts with the name of the repository's base folder.
Theexclusion_heightis the height (in mm) above the dimensions of the Labware block to steer clear from when performing movement actions. Values less than 0 means the Labware is not avoided.
(Note: Labware avoidance only applies to final coordinates (i.e. destination). Does not guarantee collision avoidance when using point-to-point move actions. UsesafeMoveTo()instead.)
The initialisation of the setup occurs when importing setup from configs.MySetup. With setup, you can access all the devices that you have defined in Section 1.1.
### main.py ###
# Add repository folder to sys.path
from pathlib import Path
import sys
REPO = 'MyREPO'
ROOT = str(Path().absolute()).split(REPO)[0]
sys.path.append(f'{ROOT}{REPO}')
# Import the initialised setup
from configs.MySetup import setup
setup.MyDevice
setup.First
Optional: if your setup does not involve moving items around in a pre-defined workspace, a Deck may not be required
To load a Deck from the layout file, use the loadDeck() function of a Mover object (or its subclasses).
from configs.MySetup import setup, LAYOUT_FILE
setup.Mover.loadDeck(LAYOUT_FILE)
LAYOUT_FILEcontains the details that has been defined inlayout.json(see Section 1.2)
To load a Labware onto the deck, use the loadLabware() method of the Deck object.
setup.Mover.deck.loadLabware(...)
This package uses the same Labware files as those provided by Opentrons, which can be found here, and custom Labware files can be created here. Labware files are JSON files that specifies the external and internal dimensions of a Labware block / object.
A /configs folder will have been created in the base folder of your project repository to store all configuration related files from which the package will read from, in Section 1. A template of registry.yaml has also been added to the /configs folder to manage the machine-specific addresses of your connected devices (e.g. serial port and camera index).
### registry.yaml ###
'012345678901234': # insert your machine's 15-digit ID here
cam_index: # camera index of the connected imaging devices
__cam_01__: 1 # keep the leading and trailing double underscores
__cam_02__: 0
port: # addresses of serial ports
__MyDevice__: COM1 # keep the leading and trailing double underscores
__MyFirstDevice__: COM22
Use the
Helper.get_node()function to get the 15-digit unique identifier of your machine
Use theHelper.get_port()function to get the serial port addresses of your connect devices
lab.Helper.get_node() # Get your machine's ID (15-digit)
lab.Helper.get_ports() # Get the port addresses of connected devices
Afterwards, change the value for the serial port address in the config.yaml file to match the registry.
### config.yaml ###
MyDevice:
module: Move
class: Cartesian.Ender
settings:
port: __MyDevice__ # serial port address
Optional: if drivers for your hardware components are already included, plugins may not be required
User-defined plugins can be easily written and integrated into Control.lab.ly. All available classes and functions can be found in lab.modules.
lab.guide_me() # Use guide to view imported objects
lab.modules.at.Make.Something.Good.MyClass # Access the class
You can import the class and register the object using the Factory.register() function.
from my_module import MyClass
lab.Factory.register(MyClass, "Make.Something.Good")
Alternatively, you can automatically register all Classes and Functions in a Python module just by importing it.
- Declare a
__where__global variable to indicate where to register the module- At the end of the .py file, import and call the
include_this_module()function
### my_module.py ###
__where__ = "Make.Something.Good" # Where to register this module to
def MyClass: # Main body of code goes here
...
def my_function:
...
from controllably import include_this_module # Registers only the Classes and Functions
include_this_module() # defined above in this .py file
The Classes and Functions in the module will be registered when you import the module.
### main.py ###
from my_module import MyClass, my_function
@kylejeanlewis
@mat-fox
@Quijanove
@AniketChitre
Issues and feature requests are welcome!
This project is distributed under the MIT License.
Feature enhancements, bug fixes and patches. First released 24 Apr 2024.
delay parameter in Keithley.programs.IV_ScanKeithleyDeviceKeithleyDevice, Peltier, ForceSensorFeature enhancements, bug fixes and patches. First released 11 Apr 2024.
TriContinent.pullback()Well properties and option in return list of wells by rows instead of columnsPeltier (setTemperature() and getTemperature())Ender (setTemperature() and getTemperature())Keithley.setFunction()IV_Scan to take either currents or voltagesFeature enhancements, bug fixes and patches. First released 19 Feb 2024.
PiezoRoboticsDeviceKeithleyDevice: DAQ6510 and SMU2450KeithleyDeviceclearErrors(), setDisplay(), setFunction()Mover tools, so that they reflect the actual physical travel times more accuratelySentronProbe toolFeature enhancements, bug fixes and patches. First released 22 Aug 2023.
ForceClampSetup classLoadCell classBalance class (subclass of LoadCell)LEDArray to delay timing loop by 0.1sPiezoRoboticsDevicegetTemperature() across multiple classes to standardise outputMover class
move() and safeMoveTo()Cartesian class
setSpeed() and setSpeedFraction()Primitiv class
Grbl and Primitiv as a subclass name to retain compatibilitymoveTo() and _query() methods to use jogging modegetAcceleration(), getCoordinates(), getMaxSpeed()Ender class
Marlin and Ender as a subclass name to retain compatibilitygetAcceleration(), getCoordinates(), getMaxSpeed()setSpeed() (absolute speed in mm/s) and setSpeedFraction() (proportional speed to max speed)Dobot class
stop() methodAX8 class
invertPalette() method_decode_from_modbus() and _encode_to_modbus()KeithleyDevice() class
ip_address property_read() methodreadline() methoddisconnect() methoddevice.run() instead of device.start()Thermal classimutils packageBug fixes and patches. First released 12 Jul 2023.
Device classes in init files to view documentationupdate_root_direcctory() function to Helperreset_input_buffer() instead of flushInput() for pyserial.Serial objectsDeck, Labware, and Well to camelCaseDeck.isExcluded() to apply strict inequalities when determining out-of-range coordinatesLiquidMover to insert a portion of tip into rack before ejectingSpinner
_query() methodMeasure objects pass through to devicesPiezoRoboticsDevice
Mover
setFlag() to print kwargs instead of raising error if assigned values are not booleansafe_height (if defined) instead of z-coordinate of home in safeMoveTo()getSettings() methodGantry class
_query()Ender
getTemperature(), holdTemperature(), isAtTemperature() methodssetTemperature() to use Marlin code to wait for temperaturePrimitiv class
getStatus() and stop() methods_get_settings() methodM1Pro.setHandedness()Sartorius class
tip_inset_mm now an instance attribute with initialisation parameterstip_on flag to False when performing eject()Bug fixes and feature enhancements. First released 15 Jun 2023.
ForceSensor - DIY force sensor (#55)BioShake - orbital shaker from QInstruments (#56)SentronProbe - pH meter probe from Sentron (#75)Maker
execute() abstract method and implemented in subclassesGuide - documentation guideMakerPanel - daptive GUI controls for Maker objects (#87)M1Pro
Peltier
getTemperatures() to getTemperature()isReady() to isAtTemperature()set_point to set_temperatureEnder
set_point to set_temperatureTriContinent
step_limit to limitsGUI codehelper and factoryAnalyse sub-package removedControl.Schedule sub-package removedBug fixes and minor feature enhancements. First released 08 May 2023.
LiquidMover
LiquidMover.touchTip() method to touch the pipette tip against the walls of the vessel to remove excess liquid on the outside of the tip (#62)LiquidMover (#61)Liquid objects (#70)MassBalance
pd.concat() instead of pd.DataFrame.append(), which is going ot be deprecated (#63)MassBalance tries to zero() while recording data (#60)Image class and methods into functions within a module (#54)time.time() to time.perf_counter() (#68)Sartorius (#73) and let speed return to a global default value (#72)Major overhaul in package structure. Standardisation of methods and consolidation of common methods. First released 12 Apr 2023.
misc.py into individual files._flags to a public attribute flags(0.0.4.x) Introduced control for Peltier device and TriContinent Series C syringe pumps. First released 10 Mar 2023.
(0.0.3.x) Minor changes to movement robot safety and pipette control. Introduced control for LED array. First released 08 Mar 2023.
(0.0.2.x) Updates in setting up configuration files. First released 24 Feb 2023.
(0.0.1.x) First release of Control.lab.ly distributed on 23 Feb 2023.
(0.0.0.x) Pre-release packaging checks
Peltier (#23)
TriContinent and TriContinentEnsemble (#25)
empty, fill, initialise, move actions, set speeds and valves, and waitaspirate, dispense, and primeDeck, added exclusion zones when reading the layout.json file and new method is_excluded() to check if target coordinate is within the exclusion zoneMover, update isFeasible() method to check if target coordinates violates the deck's exclusion zoneset_safety() defines safety modes when starting a new session to pause for input (in "high" safety setting) and to wait for safety countdown (in "low" safety setting)Make.Light.LEDArray for controlling LEDs in the photo-reactor, as well as timing the LED "on" durations (#35)CompoundSetup classDeck.at() method for directly referencing slots using either index numbers or namesCompoundSetup class for common methods of Compound devicesload_deck() function to load Deck after initialisationSartorius
lab.create_setup()FAQs
Lab Equipment Automation Package
We found that control-lab-ly demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.