Interfaces

From SweepMe! Wiki
Jump to navigation Jump to search

Interfaces allow other programs to control SweepMe! remotely. They are a Pro feature.

The available interfaces are managed via the menu "Tools" → "Interfaces". Each interface can be started and stopped on demand or set to launch automatically with SweepMe!. The HTTP server, TCPIP, WebSocket and COM port interfaces share the same command vocabulary documented below. They only differ in the transport (HTTP, raw TCP, WebSocket, serial COM). The MCP server (from version 1.6) offers similar functions as tools for AI assistants.

Commands

Every interface forwards incoming requests to the SweepMe! ActionManager, which exposes a fixed set of named functions. Command names are lower case and use underscores. Arguments are separated by spaces (text protocol) or passed as a JSON array (JSON protocol). Each command returns either a plain string or a JSON-serializable object.

Status and info

  • hello: returns "hello". Useful as a heartbeat or smoke test.
  • get_version: returns the SweepMe! version string (e.g. "1.6.1.7").
  • is_running: returns true or false.
  • is_paused: returns true or false.
  • get_status: returns a JSON object with running, paused, version, current branch, time_elapsed, time_progress, time_index, time_stamp, time_left, and a data_saved flag.
  • get_measurement_progress: leaner status payload optimized for polling: running, paused, branch, max_branch, time_elapsed_s, time_progress, time_index, time_left_s.
  • get_functions: returns the list of command names that can be triggered without arguments. Pass the single argument false to get all registered commands, including those that require arguments or return data.

Parameter and data access

  • get_parameters: returns the list of available parameter keys (compare with the Parameters widget).
  • get_value: accepts one or more parameter keys and returns the values joined into a single space-separated string. Use it when you only need a short text, e.g. for the plain-text /api/ endpoint.
  • get_values: accepts one or more parameter keys and returns a JSON object mapping each requested key to its value. Unknown keys come back as "Error: key is unknown".
  • get_all_values: takes no arguments and returns every registered parameter as a JSON object.

Measurement control

  • run: start a measurement.
  • stop: stop the running measurement.
  • pause: pause the running measurement.
  • resume: resume after a pause.
  • toggle_pause: pause if running, resume if paused.
  • skip_current_branch: abort the current sequencer branch and continue with the next one.

File and save

  • set_filename: sets the file name field in the Save Bar.
  • set_folder: sets the folder field in the Save Bar.
  • save_data: saves the data of the last run (using the current Save Bar values).

Loading a sequence restores the folder and file name that are stored in the sequence, so call set_folder and set_filename after loading.

Sequence management

  • get_current_setting: returns the path of the currently loaded sequence (or setting) file, or an empty string if none is loaded.
  • load_sequence (from version 1.6.1.6): accepts an absolute path to a sequence file (.seq, or a legacy .set) and loads it. Only works when no measurement is running.
  • load_setting (SweepMe! 1.5 up to version 1.6.1.5): accepts an absolute path to a .set file and loads it. Only works when no measurement is running. There is no alias, so a client that has to work with both versions should try load_sequence first and fall back to load_setting.

Driver versions

  • get_driver_version: accepts a driver name and returns the active version string.
  • get_available_driver_versions: accepts a driver name and returns a list of version dicts (id, version, origin, path, active).
  • set_driver_version: accepts a driver name and a version id and switches the driver to that version. Only works when no measurement is running.

Module versions

  • get_module_version, get_available_module_versions, set_module_version: same as above, for modules.

Debug and utility

  • get_debug_log: returns the last lines of the debug log. Optional arguments: lines (int, default 100) and since_last_run (bool, default false).
  • print: prints the arguments to the Debug widget and returns "Ok".
  • debug: prints a timestamped debug message and returns "Ok".

Application control

  • close_sweepme: closes SweepMe! without asking about unsaved changes. Only works when no measurement is running.

Interfaces

The HTTP server, TCPIP and WebSocket interfaces all use port 8080 by default. To run more than one of them at the same time, give each a different port in the Interfaces dialog.

HTTP server

Exposes the commands as an HTTP service plus a built-in web dashboard.

POST /api/

Plain-text protocol. The request body is a single line of command arg1 arg2 ... separated by spaces. The response body is the return value as text. Convenient for shell tools and quick tests.

POST /json/

JSON protocol. The request body is {"command": "...", "args": [...], "kwargs": {...}}. The response is {"request": "...", "status": "SUCCESS"|"ERROR", "response": ...}, where response is the original return value (string, list, dict, ...).

GET /

Serves the dashboard: a web page with Run, Stop, Pause and Resume controls, live measurement progress, a parameter monitor, Save Bar controls, driver and module version management, a debug log viewer and a command runner. The page has no authentication, so the server should only be reachable from trusted networks.

The default port is 8080. Host and port are kept between sessions. To accept connections from other computers, set Host to the computer's LAN IP address (or 0.0.0.0) in the Interfaces dialog and open the port in the Windows firewall.

Example using PowerShell:

Invoke-RestMethod -Method Post -Uri http://localhost:8080/json/ -Body '{"command": "get_status", "args": []}'

TCPIP

Raw socket service: send a command with its arguments, separated by spaces, as a text message over a TCP connection (default port 8080). Responses come back on the same socket as plain text, like the HTTP /api/ endpoint. Use localhost when the controlling script runs on the same computer as SweepMe!, or the LAN IP address for remote control.

WebSocket

WebSocket service (default port 8080). Each WebSocket message is one command, and the reply arrives as the next message. Suited for browser-based dashboards or long-lived clients.

COM port

Connect to another computer over an RS-232 serial link and exchange commands as text lines. Default settings: baudrate 9600, line terminator \n (LF), 8 data bits, 1 stop bit, no parity. Use the "Find Ports" button in the Interfaces dialog to refresh the COM port list.

MCP server

From version 1.6, SweepMe! includes an MCP server that lets AI assistants control SweepMe! via the Model Context Protocol. No additional installation is needed in SweepMe!.

  1. Open "Tools" → "Interfaces" and select MCPserver.
  2. Optionally adjust the port (default 8082) and the host (default localhost).
  3. Click Start. The panel shows the URL to add to the AI client, e.g. http://localhost:8082/mcp.

The interface uses the "streamable HTTP" transport. The AI client must run on the same computer as SweepMe! (or in the same network, if another host is selected). AI services that connect to MCP servers from their own cloud, such as custom connectors in Claude or apps in ChatGPT on the web, cannot reach a lab computer. Do not expose the port to the internet, because the endpoint controls your instruments.

Available tools: get_status, get_sweepme_version, get_instance_info, get_measurement_progress, get_debug_log, start_run, stop_run, pause_run, resume_run, skip_current_branch, wait_for_completion, list_measurement_parameters, get_measurement_value, get_all_measurement_values, load_sequence, get_current_setting, set_filename, set_folder, save_data, the driver and module version tools, list_commands, call_command and close_sweepme.

How to choose an AI application and how to connect it to SweepMe! is described in AI applications. All tools are described in the MCP tool reference, and connection problems in Troubleshooting MCP connections.

Authentication and security

The interfaces currently have no authentication. Restrict the listening host to localhost or a trusted LAN when possible, and use a VPN if remote access from outside the lab is needed. From version 1.6, the HTTP server, WebSocket and MCP server interfaces reject requests from web pages of other websites, which protects against cross-origin and DNS rebinding attacks.

Encrypted connections (HTTPS, WSS) are not yet configurable in the user interface. See Use SSL in local networks.