Switch all Keysight devices from firmware update mode to USBTMC mode.

Some Keysight USB modular instruments (e.g., U2700 series) power on in firmware update mode and require a vendor-specific command to switch to normal USBTMC operation.

After calling this function, devices will re-enumerate on the USB bus. Wait a moment, then call usbtmc_list_devices() to discover them.

Returns: dict: Result containing: - unlocked_count (int): Number of successfully unlocked devices - total_found (int): Total devices found in firmware mode - message (str): Success or informational message - errors (list[str], optional): List of error messages if any device failed

List all available USBTMC devices connected via USB.

This is typically the first step in the workflow:

1. usbtmc_list_devices() - Discover available devices

2. usbtmc_connect() - Connect to a device and get device_id

3. Use device_id for operations (send/query/etc.)

4. usbtmc_disconnect() - Close connection when done

Returns: dict: Result containing: - count (int): Number of devices found - devices (list[dict]): List of device info dictionaries, each containing: - manufacturer (str): Device manufacturer name - product (str): Device product/model name - serial_number (str): Unique device serial number

Example: >>> result = usbtmc_list_devices() >>> result { "count": 1, "devices": [ { "manufacturer": "Keysight Technologies", "product": "DSO-X 3024A", "serial_number": "MY12345678" } ] }

List all currently connected (active) USBTMC devices.

Returns: dict: Result containing: - count (int): Number of connected devices - devices (list[dict]): List of connected device info, each containing: - device_id (int): Unique identifier for the connection - manufacturer (str): Device manufacturer name - product (str): Device product/model name - serial_number (str): Device serial number

Example: >>> result = usbtmc_list_connected_devices() >>> result { "count": 1, "devices": [ { "device_id": 0, "manufacturer": "Keysight Technologies", "product": "DSO-X 3024A", "serial_number": "MY12345678" } ] }

Connect to a USBTMC device and receive a device_id for subsequent operations.

The device_id is used to identify the connection in all subsequent operations. If multiple devices match the criteria, the connection will fail - provide more specific criteria to uniquely identify the target device.

Args: params (ConnectInput): Connection parameters containing: - manufacturer (str, optional): Device manufacturer name to match - product (str, optional): Device product name to match - serial_number (str, optional): Unique device serial number (most specific)

Returns: dict: Result containing on success: - device_id (int): Unique identifier for this connection (use for all subsequent operations) - manufacturer (str): Device manufacturer name - product (str): Device product/model name - serial_number (str): Device serial number - message (str): Success message

On error:
    - error (str): Error message describing the failure

Note: Maximum 16 simultaneous connections are supported.

Disconnect from a specific USBTMC device.

Args: params (DeviceIdInput): Input containing: - device_id (int): The unique identifier returned by usbtmc_connect()

Returns: dict: Result containing: - success (bool): Whether the disconnection was successful - device_id (int): The disconnected device_id - product (str): Product name of the disconnected device - message (str): Success or error message

Clear the device input/output buffers and reset communication state.

Use this to recover from communication errors or stuck states.

Args: params (DeviceIdInput): Input containing: - device_id (int): The unique identifier returned by usbtmc_connect()

Returns: dict: Result containing: - success (bool): Whether the clear operation was successful - device_id (int): The target device_id - message (str): Success or error message

Send a SCPI command to a specific USBTMC device.

Use for SET commands (without '?') that configure device settings. For QUERY commands (with '?'), use usbtmc_query() instead.

This function only sends data; use usbtmc_receive() to read responses, or use usbtmc_query() for send+receive in one operation.

Args: params (SendInput): Input containing: - device_id (int): The unique identifier returned by usbtmc_connect() - command (str): SCPI command string to send

Returns: dict: Result containing: - success (bool): Whether the send was successful - device_id (int): The target device_id - command (str): The command that was sent - message (str): Success or error message

Receive data from a specific USBTMC device.

Args: params (ReceiveInput): Input containing: - device_id (int): The unique identifier returned by usbtmc_connect() - max_bytes (int): Maximum bytes to read (default: 1024)

Returns: dict: Result containing: - success (bool): Whether data was received - device_id (int): The target device_id - data (str or None): Received data string, or None if no data/timeout - message (str): Success or error message

Send a SCPI command and immediately receive the response.

Use for QUERY commands (with '?') that request information from the device. For SET commands (without '?'), use usbtmc_send() instead.

This is a convenience function combining send and receive operations.

Args: params (QueryInput): Input containing: - device_id (int): The unique identifier returned by usbtmc_connect() - command (str): SCPI command string to send (usually ends with '?') - wait_time (float): Time to wait between send and receive (default: 0.1s) - max_bytes (int): Maximum bytes to read (default: 1024)

Returns: dict: Result containing: - success (bool): Whether the query was successful - device_id (int): The target device_id - command (str): The command that was sent - response (str or None): Response data, or None if no data/timeout - message (str): Success or error message

Note: Wait time recommendations: - Simple queries (*IDN?, status): 0.1s (default) - Querying existing measurements: 0.1s - After changing settings: 0.5-2.0s

Capture screenshot from a Keysight/Agilent oscilloscope.

Args: params (DeviceIdInput): Input containing: - device_id (int): The unique identifier returned by usbtmc_connect()

Returns: Image

Capture screenshot from a Tektronix oscilloscope.

Args: params (DeviceIdInput): Input containing: - device_id (int): The unique identifier returned by usbtmc_connect()

Returns: Image