Qinstruments Api

QInstruments API for controlling hardware from QInstruments.

ATTRIBUTE	DESCRIPTION
`READ_FORMAT`	format for reading data TYPE: `str`
`WRITE_FORMAT`	format for writing data TYPE: `str`
`Data`	data type for data TYPE: `NamedTuple`
`BoolData`	data type for boolean data TYPE: `NamedTuple`
`FloatData`	data type for float data TYPE: `NamedTuple`
`IntData`	data type for integer data TYPE: `NamedTuple`

CLASS	DESCRIPTION
`QInstrumentsDevice`	provides an interface for available actions to control devices from QInstruments

Documentation last updated: 2025-02-22

QInstrumentsDevice

QInstrumentsDevice(
    port: str | None = None,
    baudrate: int = 9600,
    timeout: int = 1,
    *,
    init_timeout: int = 5,
    data_type: NamedTuple = Data,
    read_format: str = READ_FORMAT,
    write_format: str = WRITE_FORMAT,
    simulation: bool = False,
    verbose: bool = False,
    **kwargs,
)

Bases: SerialDevice

QInstrumentsDevice provides an interface for available actions to control devices from QInstruments, including orbital shakers, heat plates, and cold plates.

ATTRIBUTE	DESCRIPTION
`port`	device serial port TYPE: `str`
`baudrate`	device baudrate TYPE: `int`
`timeout`	device timeout TYPE: `int`
`connection_details`	connection details for the device TYPE: `dict`
`serial`	serial object for the device TYPE: `Serial`
`init_timeout`	timeout for initialization TYPE: `int`
`message_end`	message end character TYPE: `str`
`model`	device model TYPE: `str`
`flags`	flags for the device TYPE: `SimpleNamespace[str, bool]`
`is_connected`	whether the device is connected TYPE: `bool`
`verbose`	verbosity of class TYPE: `bool`

METHOD	DESCRIPTION
`clear`	clear the input and output buffers
`connect`	connect to the device
`disconnect`	disconnect from the device
`query`	query the device (i.e. write and read data)
`read`	read data from the device
`write`	write data to the device
`disableBootScreen`	permanent deactivation of the boot screen startup text
`disableCLED`	permanent deactivation of the LED indication lights
`enableBootScreen`	permanent activation of the boot screen startup text
`enableCLED`	permanent activation of the LED indication lights
`flashLed`	user device LED flashes five times
`getCLED`	returns the status LED state
`getDescription`	returns model type
`getErrorList`	returns a list with errors and warnings which can occur during processing
`getSerial`	returns the device serial number
`getVersion`	returns the firmware version number
`info`	retrieve the boot screen text
`resetDevice`	restarts the controller
`setBuzzer`	ring the buzzer for duration in milliseconds
`version`	returns the model type and firmware version number
`leaveEcoMode`	leaves the economical mode and switches into the normal operating state
`setEcoMode`	witches the shaker into economical mode and reduces electricity consumption
`getShakeAcceleration`	returns the acceleration/deceleration value
`getShakeAccelerationMax`	get the maximum acceleration/deceleration time in seconds
`getShakeAccelerationMin`	get the minimum acceleration/deceleration time in seconds
`getShakeActualSpeed`	returns the current mixing speed
`getShakeDefaultDirection`	returns the mixing direction when the device starts up
`getShakeDirection`	returns the current mixing direction
`getShakeMaxRpm`	returns the device specific maximum target speed (i.e. hardware limits)
`getShakeMinRpm`	returns the device specific minimum target speed (i.e. hardware limits)
`getShakeRemainingTime`	returns the remaining time in seconds if device was started with the command shakeOnWithRuntime
`getShakeSpeedLimitMax`	returns the upper limit for the target speed
`getShakeSpeedLimitMin`	returns the lower limit for the target speed
`getShakeState`	returns shaker state as an integer
`getShakeStateAsString`	returns shaker state as a string
`getShakeTargetSpeed`	returns the target mixing speed
`setShakeAcceleration`	sets the acceleration/deceleration value in seconds
`setShakeDefaultDirection`	permanently sets the default mixing direction after device start up
`setShakeDirection`	sets the mixing direction
`setShakeSpeedLimitMax`	permanently set upper limit for the target speed (between 0 to 3000)
`setShakeSpeedLimitMin`	permanently set lower limit for the target speed (between 0 to 3000)
`setShakeTargetSpeed`	set the target mixing speed
`shakeEmergencyOff`	stop the shaker immediately at an undefined position ignoring the defined deceleration time
`shakeGoHome`	move shaker to the home position and locks in place
`shakeOff`	stops shaking within the defined deceleration time, go to the home position and locks in place
`shakeOffNonZeroPos`	tops shaking within the defined deceleration time, do not go to home position and do not lock in home position
`shakeOffWithDeEnergizeSolenoid`	tops shaking within the defined deceleration time, go to the home position and locks in place for 1 second, then unlock home position
`shakeOn`	tarts shaking with defined speed with defined acceleration time
`shakeOnWithRuntime`	starts shaking with defined speed within defined acceleration time for given time value in seconds
`getTemp40Calibr`	returns the offset value at the 40°C calibration point
`getTemp90Calibr`	returns the offset value at the 90°C calibration point
`getTempActual`	returns the current temperature in celsius
`getTempLimiterMax`	returns the upper limit for the target temperature in celsius
`getTempLimiterMin`	returns the lower limit for the target temperature in celsius
`getTempMax`	returns the device specific maximum target temperature in celsius (i.e. hardware limits)
`getTempMin`	returns the device specific minimum target temperature in celsius (i.e. hardware limits)
`getTempState`	returns the state of the temperature control feature
`getTempTarget`	returns the target temperature
`setTemp40Calibr`	permanently sets the offset value at the 40°C calibration point in 1/10°C increments
`setTemp90Calibr`	permanently sets the offset value at the 90°C calibration point in 1/10°C increments
`setTempLimiterMax`	permanently sets the upper limit for the target temperature in 1/10°C increments
`setTempLimiterMin`	permanently sets the lower limit for the target temperature in 1/10°C increments
`setTempTarget`	sets target temperature between TempMin and TempMax in 1/10°C increments
`tempOff`	switches off the temperature control feature and stops heating/cooling
`tempOn`	switches on the temperature control feature and starts heating/cooling
`getElmSelftest`	returns whether the ELM self-test is enabled or disabled at device startup
`getElmStartupPosition`	returns whether ELM is unlocked after device startup
`getElmState`	returns the ELM status
`getElmStateAsString`	returns the ELM status as a string
`setElmLockPos`	close the ELM
`setElmSelftest`	permanently set whether the ELM self-test is enabled at device startup
`setElmStartupPosition`	permanently set whether the ELM is unlocked after device startup
`setElmUnlockPos`	open the ELM

Initialize QInstrumentsDevice class

PARAMETER	DESCRIPTION
`port`	serial port for the device. Defaults to None. TYPE: `str \| None` DEFAULT: `None`
`baudrate`	baudrate for the device. Defaults to 9600. TYPE: `int` DEFAULT: `9600`
`timeout`	timeout for the device. Defaults to 1. TYPE: `int` DEFAULT: `1`
`init_timeout`	timeout for initialization. Defaults to 5. TYPE: `int` DEFAULT: `5`
`data_type`	data type for data. Defaults to Data. TYPE: `NamedTuple` DEFAULT: `Data`
`read_format`	format for reading data. Defaults to READ_FORMAT. TYPE: `str` DEFAULT: `READ_FORMAT`
`write_format`	format for writing data. Defaults to WRITE_FORMAT. TYPE: `str` DEFAULT: `WRITE_FORMAT`
`simulation`	whether to simulate the device. Defaults to False. TYPE: `bool` DEFAULT: `False`
`verbose`	verbosity of class. Defaults to False. TYPE: `bool` DEFAULT: `False`

disableBootScreen

disableBootScreen()

Permanent deactivation of the boot screen startup text

disableCLED

disableCLED()

Permanent deactivation of the LED indication lights. The instrument will reset after this command.

enableBootScreen

enableBootScreen()

Permanent activation of the boot screen startup text

enableCLED

enableCLED()

Permanent activation of the LED indication lights. The instrument will reset after this command.

flashLed

flashLed()

User device LED flashes five times

getCLED

getCLED() -> bool | None

Returns the status LED state

RETURNS	DESCRIPTION
`bool \| None`	bool\|None: whether the LED is enabled

getDescription

getDescription() -> str

Returns model type

RETURNS	DESCRIPTION
`str`	model type TYPE: `str`

getElmSelftest

getElmSelftest() -> bool

Returns whether the ELM self-test is enabled or disabled at device startup

RETURNS	DESCRIPTION
`bool`	whether ELM self-test is enabled at device startup TYPE: `bool`

getElmStartupPosition

getElmStartupPosition() -> bool

Returns whether ELM is unlocked after device startup

RETURNS	DESCRIPTION
`bool`	whether ELM is unlocked after device startup TYPE: `bool`

getElmState

getElmState() -> int | None

Returns the ELM status

RETURNS	DESCRIPTION
`int \| None`	int\|None: ELM status as integer

getElmStateAsString

getElmStateAsString() -> str | None

Returns the ELM status as a string

RETURNS	DESCRIPTION
`str \| None`	str\|None: ELM status as string

getErrorList

getErrorList() -> list[str]

Returns a list with errors and warnings which can occur during processing

RETURNS	DESCRIPTION
`list[str]`	list[str]: list of errors and warnings

getSerial

getSerial() -> str

Returns the device serial number

RETURNS	DESCRIPTION
`str`	device serial number TYPE: `str`

getShakeAcceleration

getShakeAcceleration() -> float | None

Returns the acceleration/deceleration value

RETURNS	DESCRIPTION
`float \| None`	float\|None: acceleration/deceleration value

getShakeAccelerationMax

getShakeAccelerationMax() -> float | None

Get the maximum acceleration/deceleration time in seconds

RETURNS	DESCRIPTION
`float \| None`	float\|None: acceleration/deceleration time in seconds

getShakeAccelerationMin

getShakeAccelerationMin() -> float | None

Get the minimum acceleration/deceleration time in seconds

RETURNS	DESCRIPTION
`float \| None`	float\|None: acceleration/deceleration time in seconds

getShakeActualSpeed

getShakeActualSpeed() -> float | None

Returns the current mixing speed

RETURNS	DESCRIPTION
`float \| None`	float\|None: current mixing speed

getShakeDefaultDirection

getShakeDefaultDirection() -> bool | None

Returns the mixing direction when the device starts up

RETURNS	DESCRIPTION
`bool \| None`	bool\|None: whether mixing direction is counterclockwise

getShakeDirection

getShakeDirection() -> bool | None

Returns the current mixing direction

RETURNS	DESCRIPTION
`bool \| None`	bool\|None: whether mixing direction is counterclockwise

getShakeMaxRpm

getShakeMaxRpm() -> float | None

Returns the device specific maximum target speed (i.e. hardware limits)

RETURNS	DESCRIPTION
`float \| None`	float\|None: maximum target shake speed

getShakeMinRpm

getShakeMinRpm() -> float | None

Returns the device specific minimum target speed (i.e. hardware limits)

RETURNS	DESCRIPTION
`float \| None`	float\|None: minimum target shake speed

getShakeRemainingTime

getShakeRemainingTime() -> float | None

Returns the remaining time in seconds if device was started with the command shakeOnWithRuntime

RETURNS	DESCRIPTION
`float \| None`	float\|None: minimum target shake speed

getShakeSpeedLimitMax

getShakeSpeedLimitMax() -> float | None

Returns the upper limit for the target speed

RETURNS	DESCRIPTION
`float \| None`	float\|None: upper limit for the target speed

getShakeSpeedLimitMin

getShakeSpeedLimitMin() -> float | None

Returns the lower limit for the target speed

RETURNS	DESCRIPTION
`float \| None`	float\|None: lower limit for the target speed

getShakeState

getShakeState() -> int | None

Returns shaker state as an integer

RETURNS	DESCRIPTION
`int \| None`	int\|None: shaker state as integer

getShakeStateAsString

getShakeStateAsString() -> str | None

Returns shaker state as a string

RETURNS	DESCRIPTION
`str \| None`	str\|None: shaker state as string

getShakeTargetSpeed

getShakeTargetSpeed() -> float | None

Returns the target mixing speed

RETURNS	DESCRIPTION
`float \| None`	float\|None: target mixing speed

getTemp40Calibr

getTemp40Calibr() -> float | None

Returns the offset value at the 40°C calibration point

RETURNS	DESCRIPTION
`float \| None`	float\|None: offset value at the 40°C calibration point

getTemp90Calibr

getTemp90Calibr() -> float | None

Returns the offset value at the 90°C calibration point

RETURNS	DESCRIPTION
`float \| None`	float\|None: offset value at the 90°C calibration point

getTempActual

getTempActual() -> float | None

Returns the current temperature in celsius

RETURNS	DESCRIPTION
`float \| None`	float\|None: current temperature in celsius

getTempLimiterMax

getTempLimiterMax() -> float | None

Returns the upper limit for the target temperature in celsius

RETURNS	DESCRIPTION
`float \| None`	float\|None: upper limit for the target temperature in celsius

getTempLimiterMin

getTempLimiterMin() -> float | None

Returns the lower limit for the target temperature in celsius

RETURNS	DESCRIPTION
`float \| None`	float\|None: lower limit for the target temperature in celsius

getTempMax

getTempMax() -> float | None

Returns the device specific maximum target temperature in celsius (i.e. hardware limits)

RETURNS	DESCRIPTION
`float \| None`	float\|None: device specific maximum target temperature in celsius

getTempMin

getTempMin() -> float | None

Returns the device specific minimum target temperature in celsius (i.e. hardware limits)

RETURNS	DESCRIPTION
`float \| None`	float\|None: device specific minimum target temperature in celsius

getTempState

getTempState() -> bool

Returns the state of the temperature control feature

RETURNS	DESCRIPTION
`bool`	whether temperature control is enabled TYPE: `bool`

getTempTarget

getTempTarget() -> float | None

Returns the target temperature

RETURNS	DESCRIPTION
`float \| None`	float\|None: target temperature

getVersion

getVersion() -> str

Returns the firmware version number

RETURNS	DESCRIPTION
`str`	firmware version number TYPE: `str`

info

info()

Retrieve the boot screen text

leaveEcoMode

leaveEcoMode(timeout: int = 5)

Leaves the economical mode and switches into the normal operating state

PARAMETER	DESCRIPTION
`timeout`	number of seconds to wait before aborting. Defaults to 5. TYPE: `int` DEFAULT: `5`

query

query(
    data: Any,
    multi_out: bool = False,
    *,
    timeout: int | float = 0.3,
    format_in: str | None = None,
    format_out: str | None = None,
    data_type: NamedTuple | None = None,
    timestamp: bool = False,
) -> Any

Query the device (i.e. write and read data)

PARAMETER	DESCRIPTION
`data`	data to write to the device TYPE: `Any`
`multi_out`	whether to expect multiple outputs. Defaults to False. TYPE: `bool` DEFAULT: `False`
`timeout`	timeout for the query. Defaults to 0.3. TYPE: `int \| float` DEFAULT: `0.3`
`format_in`	format for writing data. Defaults to None. TYPE: `str \| None` DEFAULT: `None`
`format_out`	format for reading data. Defaults to None. TYPE: `str \| None` DEFAULT: `None`
`data_type`	data type for data. Defaults to None. TYPE: `NamedTuple \| None` DEFAULT: `None`
`timestamp`	whether to include a timestamp. Defaults to False. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Any`	str\|float\|None: response (string / float)

resetDevice

resetDevice(timeout: int = 30)

Restarts the controller

Note: This takes about 30 seconds for BS units and 5 for the Q1, CP models

PARAMETER	DESCRIPTION
`timeout`	number of seconds to wait before aborting. Defaults to 30. TYPE: `int` DEFAULT: `30`

setBuzzer

setBuzzer(duration: int)

Ring the buzzer for duration in milliseconds

PARAMETER	DESCRIPTION
`duration`	duration in milliseconds, from 50 to 999 TYPE: `int`

setEcoMode

setEcoMode(timeout: int = 5)

Switches the shaker into economical mode and reduces electricity consumption.

Note: all commands after this, other than leaveEcoMode, will return e

PARAMETER	DESCRIPTION
`timeout`	number of seconds to wait before aborting. Defaults to 5. TYPE: `int` DEFAULT: `5`

setElmLockPos

setElmLockPos(timeout: int = 5) -> bool

Close the ELM

PARAMETER	DESCRIPTION
`timeout`	number of seconds to wait before aborting. Defaults to 5. TYPE: `int` DEFAULT: `5`

RETURNS	DESCRIPTION
`bool`	whether the ELM was successfully closed TYPE: `bool`

setElmSelftest

setElmSelftest(enable: bool)

Permanently set whether the ELM self-test is enabled at device startup

PARAMETER	DESCRIPTION
`enable`	whether the ELM self-test is enabled at device startup TYPE: `bool`

setElmStartupPosition

setElmStartupPosition(unlock: bool)

Permanently set whether the ELM is unlocked after device startup

PARAMETER	DESCRIPTION
`unlock`	whether the ELM is unlocked after device startup TYPE: `bool`

setElmUnlockPos

setElmUnlockPos(timeout: int = 5) -> bool

Open the ELM

Note: The ELM should only be opened when the tablar is in the home position.

PARAMETER	DESCRIPTION
`timeout`	number of seconds to wait before aborting. Defaults to 5. TYPE: `int` DEFAULT: `5`

RETURNS	DESCRIPTION
`bool`	whether the ELM was successfully opened TYPE: `bool`

setShakeAcceleration

setShakeAcceleration(acceleration: int)

Sets the acceleration/deceleration value in seconds

PARAMETER	DESCRIPTION
`acceleration`	acceleration value TYPE: `int`

setShakeDefaultDirection

setShakeDefaultDirection(counterclockwise: bool)

Permanently sets the default mixing direction after device start up

PARAMETER	DESCRIPTION
`counterclockwise`	whether to set default mixing direction to counter clockwise TYPE: `bool`

setShakeDirection

setShakeDirection(counterclockwise: bool)

Sets the mixing direction

PARAMETER	DESCRIPTION
`counterclockwise`	whether to set mixing direction to counter clockwise TYPE: `bool`

setShakeSpeedLimitMax

setShakeSpeedLimitMax(speed: int)

Permanently set upper limit for the target speed (between 0 to 3000)

PARAMETER	DESCRIPTION
`speed`	upper limit for the target speed TYPE: `int`

setShakeSpeedLimitMin

setShakeSpeedLimitMin(speed: int)

Permanently set lower limit for the target speed (between 0 to 3000)

Note: Speed values below 200 RPM are possible, but not recommended

PARAMETER	DESCRIPTION
`speed`	lower limit for the target speed TYPE: `int`

setShakeTargetSpeed

setShakeTargetSpeed(speed: int)

Set the target mixing speed

Note: Speed values below 200 RPM are possible, but not recommended

PARAMETER	DESCRIPTION
`speed`	target mixing speed TYPE: `int`

setTemp40Calibr

setTemp40Calibr(temperature_calibration_40: float)

Permanently sets the offset value at the 40°C calibration point in 1/10°C increments

PARAMETER	DESCRIPTION
`temperature_calibration_40`	offset value (between 0°C and 99°C) TYPE: `float`

setTemp90Calibr

setTemp90Calibr(temperature_calibration_90: float)

Permanently sets the offset value at the 90°C calibration point in 1/10°C increments

PARAMETER	DESCRIPTION
`temperature_calibration_90`	offset value (between 0°C and 99°C) TYPE: `float`

setTempLimiterMax

setTempLimiterMax(temperature_max: float)

Permanently sets the upper limit for the target temperature in 1/10°C increments

PARAMETER	DESCRIPTION
`temperature_max`	upper limit for the target temperature (between -20.0°C and 99.9°C) TYPE: `float`

setTempLimiterMin

setTempLimiterMin(temperature_min: float)

Permanently sets the lower limit for the target temperature in 1/10°C increments

PARAMETER	DESCRIPTION
`temperature_min`	lower limit for the target temperature (between -20.0°C and 99.9°C) TYPE: `float`

setTempTarget

setTempTarget(temperature: float)

Sets target temperature between TempMin and TempMax in 1/10°C increments

PARAMETER	DESCRIPTION
`temperature`	target temperature (between TempMin and TempMax) TYPE: `float`

shakeEmergencyOff

shakeEmergencyOff()

Stop the shaker immediately at an undefined position ignoring the defined deceleration time

shakeGoHome

shakeGoHome(timeout: int = 5)

Move shaker to the home position and locks in place

Note: Minimum response time is less than 4 sec (internal failure timeout)

PARAMETER	DESCRIPTION
`timeout`	number of seconds to wait before aborting. Defaults to 5. TYPE: `int` DEFAULT: `5`

shakeOff

shakeOff()

Stops shaking within the defined deceleration time, go to the home position and locks in place

shakeOffNonZeroPos

shakeOffNonZeroPos()

Stops shaking within the defined deceleration time, do not go to home position and do not lock in home position

shakeOffWithDeEnergizeSolenoid

shakeOffWithDeEnergizeSolenoid()

Stops shaking within the defined deceleration time, go to the home position and locks in place for 1 second, then unlock home position

shakeOn

shakeOn()

Starts shaking with defined speed with defined acceleration time

shakeOnWithRuntime

shakeOnWithRuntime(duration: int)

Starts shaking with defined speed within defined acceleration time for given time value in seconds

PARAMETER	DESCRIPTION
`duration`	shake duration in seconds (from 0 to 999,999) TYPE: `int`

tempOff

tempOff()

Switches off the temperature control feature and stops heating/cooling

tempOn

tempOn()

Switches on the temperature control feature and starts heating/cooling

version

version() -> str

Returns the model type and firmware version number

RETURNS	DESCRIPTION
`str`	model type and firmware version number TYPE: `str`