sm-bluesky CLI Reference#
The sm-bluesky command-line interface provides tools to launch instrument servers and interact with running instances via quick payloads (commands).
Commands Overview#
The interface provides several primary commands:
start: Configures and spins up background services like instrument servers or the BlueAPI server.send: A lightweight diagnostic utility to send arbitrary string payloads to an active instrument server.client: Launches an interactive IPython session connected to the BlueAPI server.install-completion: Automatically installs completion for the CLI.
For extra information use:
-h,--help: Displays general or command-specific help menus.-v,--version: Displays the currently installed package version ofsm-bluesky.
🛠️ Detailed Usage#
1. Starting an Instrument Server#
Launches a dedicated hardware communication server. By default, it listens on all available interfaces (0.0.0.0) to ensure remote beamline workstations can reach the server.
sm-bluesky start sh_pulse_generator [FLAGS]
Flag |
Type |
Default |
Description |
|---|---|---|---|
–host |
str |
0.0.0.0 |
Binding host network address. |
–port |
int |
7891 |
TCP port boundary for socket listening. |
–ipv6 |
bool |
None |
Flags the socket to use IPv6 dual-stack addressing. |
sh_pulse_generator Specific FlAG#
Flag |
Type |
Default |
Description |
|---|---|---|---|
–usb-port |
str |
COM4 |
Target serial/USB backend port identifier. |
–baud-rate |
int |
9600 |
Serial connection baud rate. |
–timeout |
float |
1.0 |
Read/write timeout duration in seconds. |
–max-pulse-delay |
int |
1024 |
Boundary constraints for safe pulse adjustments. |
sm-bluesky start sh_pulse_generator --usb-port COM9 --port 8080
zurich_lockin_amplifier Specific Flags#
Flag |
Type |
Default |
Description |
|---|---|---|---|
–hf2-ip |
str |
172.23.110.84 |
HF2 Data Server IP. |
–hf2-port |
int |
8004 |
HF2 Data Server Port. |
–api-level |
int |
6 |
ziDAQ API Level (0, 1, 4, 5, or 6). |
–device-id |
str |
dev4206 |
HF2 Device ID. |
sm-bluesky start zurich_lockin_amplifier --hf2-ip 172.23.110.84 --port 7891
2. Sending Payloads (Commands)#
Sends a single string payload directly to an active server. It defaults to the local loopback address (127.0.0.1) to ensure accidental commands don’t interact with external instruments.
sm-bluesky send "PAYLOAD" [FLAGS]
Flag |
Type |
Default |
Description |
|---|---|---|---|
–host |
str |
127.0.0.1 |
Target server network address. |
–port |
int |
7891 |
Target server TCP communications port. |
–timeout |
float |
2.0 |
Connection timeout duration in seconds. |
# Verify status locally
sm-bluesky send "command_list"
# Adjust settings on a remote beamline server
sm-bluesky send "set_delay\t512" --host 192.168.1.50 --port 7891
3. Starting the BlueAPI Server#
Launches the BlueAPI REST server with your configuration.
sm-bluesky start blueapi --config path/to/config.yaml
Flag |
Type |
Default |
Description |
|---|---|---|---|
-c, –config |
Path |
None |
Path to BlueAPI YAML config file (Required). |
4. Launching the BlueAPI Interactive Client#
Opens an interactive IPython shell connected to your BlueAPI server, allowing you to run plans and interact with devices dynamically.
sm-bluesky client [FLAGS]
Flag |
Type |
Default |
Description |
|---|---|---|---|
-b, –beamline |
str |
None |
Target beamline name (e.g., iXX). |
-c, –config |
Path |
None |
Path to BlueAPI YAML config file. |
-s, –session |
str |
None |
Pre-assign the active instrument session (e.g. cm44186-1). |
-d, –dummy |
bool |
False |
Automatically set the active instrument session to ‘dummy’. |
(Note: You must provide either -b or -c)
# Connect using a local config
sm-bluesky client -c src/yaml_config/blueapi_config.yaml -s cm44186-1
# Connect using a known beamline alias
sm-bluesky client -b p99