Adding an instrument
Onboard a new lab instrument to Data Hub end to end: register it, activate it, and start uploading runs.
This guide walks through adding a new lab instrument to Data Hub end to end: registering it on the instrument PC, having an admin activate it, and starting to upload runs. Registration is done by a lab operator; activation (Step 2) is an admin action.
Prerequisites
- uv installed on the instrument PC: it handles Python for you, so no separate Python install is needed.
- A personal access token (
dhub_…). Ask an admin if you don't have one; see Managing tokens. - Access to the instrument PC where the files are generated.
Step 1: Install the watcher and register the instrument
Follow Installing a watcher. During
data-hub-watcher init, choose Register a new instrument and provide:
- Instrument ID: a kebab-case identifier (e.g.,
bio-rad-cfx96). This becomes the storage key prefix and the permanent identifier across the system. - Display name: a human-readable name (e.g., "Bio-Rad CFX96"). Defaults to a title-cased version of the ID.
The instrument is created with status pending.
Step 2: Activate the instrument (admin)
An admin must confirm the instrument before the watcher can upload.
Open the Data Hub web app and navigate to the Instruments page.
Find the new instrument; it has a yellow pending badge.
Click Confirm next to it. The status changes to active.
See Managing instruments for the full admin view.
Step 3: Start watching
On the instrument PC:
data-hub-watcher watchThe watcher detects new files, groups them into runs, uploads them, and reports everything to the API. Files become viewable in the web dashboard immediately after upload.
What you get
Once the instrument is active and the watcher is running:
- The watcher uploads raw files to cloud storage.
- Runs and files appear in the web dashboard.
- Files are downloadable via pre-signed URLs.
- Watcher health monitoring (heartbeats, events) works in the dashboard.
- Slack notifications fire whenever a new run is created.
Some instruments also support automated preprocessing (metadata extraction, image processing, and similar) that runs server-side as files arrive. Adding a new processor requires changes to the Data Hub codebase; see Adding a new instrument in the data-hub developer docs.
Installing a watcher
Set up the Data Hub watcher on a lab instrument PC to monitor a directory, upload new files, and report run data to the web app.
Run as a Windows service
Install and operate the Data Hub watcher as a Windows service so it starts automatically on boot, survives logouts, and auto-updates in the background.