Reference
QInstruments BioShake
Get a QInstruments BioShake (3000, 3000-T, 5000, D30, Q1, Q2 and their elm variants) connected through GroundControl and run a first shake from Python.
This page gets you from an unboxed BioShake to a first shake driven from Python. It does not replace the QInstruments manual: speeds, loads and safety are the vendor's domain.
The code on this page is not yet run by the docs pipeline; it follows the connector's public
interface (
unitelabs-qinstruments-bioshake 0.3.0). It gains a "tested against" label once the
snippet pipeline lands.What you need
| Item | Detail |
|---|---|
| Instrument | Any BioShake model listed above, powered on, plate adapter mounted |
| Cable | The USB (RS-232) cable QInstruments ships; the device appears as a serial port |
| Connector | QINSTRUMENTS BioShake from the UniteLabs registry — one connector drives every QInstruments model, including the ColdPlate, TiltStation and TurnStation |
| Vendor software | None. Close any QInstruments or third-party tool that holds the serial port |
| Machine | Windows, Linux or macOS running GroundControl |
| Access | A tenant and the SDK installed — see Setup |
Install and configure the connector
- In GroundControl, add a connector and pick QINSTRUMENTS BioShake from the registry; GroundControl downloads the build for your operating system (how to add a connector).
- Fill in the configuration. The fields that matter:
Field Value deviceYour exact model, e.g. BioShake 3000-T elm. The list holds every QInstruments device this connector supports — pick the BioShake entry, not TiltStation or TurnStation, even if they appear firstserial_numberThe serial printed on the device label (max 10 characters); leave empty to skip the identity check portThe serial port the BioShake appears on, e.g. COM3or/dev/ttyUSB0simulatedfalsefor the real device (trueruns the connector's built-in simulator) - Start the connector. In GroundControl it shows the modules
ConfigurationService,ShakeController,TemperatureController(T variants) andElmController/ClampController(elm variants). If it reportsDeviceIdentityError, the port or the serial number is wrong.
First successful test
A ten-second shake at a gentle speed, then a state read-back. Run it in a notebook or an async
script with the SDK authenticated (Connect to Platform).
import asyncio
from unitelabs.sdk import AsyncApiClient
client = AsyncApiClient()
shaker = await client.get_service_by_name(name="QINSTRUMENTS BioShake")
# Identify what is connected and make sure it is awake (Eco Mode rejects every command).
print(await shaker.configuration_service.get_device_info())
await shaker.configuration_service.leave_eco_mode()
# Shake for 10 s at 500 rpm with a 5 s ramp, then confirm the shaker is back home.
await shaker.shake_controller.start_shaking_with_runtime(runtime=10, target_speed=500, acceleration_time=5)
await asyncio.sleep(12)
print(await shaker.shake_controller.get_shaker_state_with_description())
Expected: the device info line names your model and firmware; the plate shakes for ten seconds; the final state reads as stopped in the home position.
Known quirks and errors
| You see | It means | Do this |
|---|---|---|
EcoModeActive | The device is in Eco Mode and rejects every command | await shaker.configuration_service.leave_eco_mode() first; disable Eco Mode on the device if it keeps returning |
DeviceIdentityError | Wrong serial number in the configuration, or no device on the port | Check port; clear serial_number to skip the identity check |
DeviceSelftestException — "activate the boot screen text first" | Self-test results are only readable when the boot screen text is on | await shaker.configuration_service.enable_boot_screen(), then reset_device_with_self_tests() |
ShakerError (code 103) | The shaker was not initialised after power-on | Power-cycle, then await shaker.configuration_service.reset() before shaking |
ElmAlreadyLocked / ElmAlreadyUnlocked | The lock is already in the requested state | Nothing — the call is idempotent in effect; read get_elm_state_as_string() first if you need to branch |
ReleaseBlocked | The clamp cannot release while the shaker moves | stop_shaking() (waits for home position), then clamp_controller.release() |
OverheatError | Over-temperature protection tripped | Let the device cool; on code 33020 power-cycle it |
| GroundControl shows "TiltStation" for a BioShake | The device field was left on the first list entry | Set device to your BioShake model and restart the connector |
Speed limits differ per model: read them with get_device_specific_minimum_shaking_speed() and
get_device_specific_maximum_shaking_speed() before choosing a target.
More snippets
- Temperature (T variants):
set_target_temperature(target_temp=37.0), thenturn_temperature_control_on(); follow it withsubscribe_current_temperature(). - Hold the plate:
elm_controller.lock_elm()before shaking a loose plate,unlock_elm()afterstop_shaking(). - Emergency stop:
shake_controller.emergency_stop()stops at an undefined position — follow withmove_to_home_position()before a gripper approaches.
Connector reference
The full list of modules and actions with a copy-paste line per method is generated from the
connector's release data in a later step. Until then, browse the modules in GroundControl or with
print(shaker.modules.keys()) and print(shaker.shake_controller.actions.keys()).Vendor documentation
Operating limits, plate adapters, maintenance and safety are covered by QInstruments' BioShake operating manual shipped with the device. This page only covers getting it connected and tested.
Last updated