I’m looking for information on programmatically controlling Hamilton Venus 6 software. I have working COM interface code for Venus 4 that uses objects like “Hamilton.VenusAppSrv” for method control, but these don’t work with Venus 6.
My use case is straightforward - I need to:
- Select/load method files
- Start, pause, and abort method runs
- Read and write method variables
Using COM object discovery, I found these interfaces in Venus 6:
- Hamilton.HxUserManager (user management functions only)
- HxMetEd.MethodView (exists but no accessible methods)
- HxMetEd.WorkflowData (only has UpdateRegisteredMethods)
None of these provide the method control functionality I need. Does anyone have documentation on the proper API for Venus 6 method control? Has Hamilton changed their approach for automation in Venus 6?
Any help would be greatly appreciated!
In Venus4, the interface is Hamilton.HxHSLRunControl, which you can use to load/start/pause the method, but I did not know how to read/write variables for I never did that. Hamilton.HxHSLRunControl is ActiveX, you can not used it in the way of COM.
Hamilton.HxHSLRunControl is legacy run control, there is a new run control in venus 6. But I think the legacy run control still can work, for the new control also uses Hamilton.HxHSLRunControl to run the method in electron.
Venus 6 includes a REST API for method control. It is not turned on by default, there’s instructions for starting the service here. I think like @Huajiang said you can still use the old ActiveX control.
The new API allows you to inject a variable value into a method. You have to load the method, inject the variable value(s), then start the method. I’m pretty sure the old API does not have the ability to set variable values.
1 Like
This is perfect, I noticed those REST API by inspect the remote web app for read only status. Initially I was trying to have small background app that converts the existing ActiveX interface to REST API since most of our control software relying on REST.
Looks like the REST API supports most of thing that I needed from this screenshot, I’ll give it try and check the swagger, see how I can input values from LIMS.
1 Like
@DCurrier , I was able to analyze, load, and start method. tried “/input” endpoint by setting variable name and value in payload, not exactly sure how to use input value in the venus method. trace shows the input value was not taken. Is there any documentations around the REST API?
I have not seen any additional documentation.
When I was testing it, I found that you load the method, wait for it to analyze, input the variable value, then start the method. I don’t think you need to do anything special to use the variable value, you just use it in the method. The key is to wait until the method analysis completes before sending the input variable values.
Here’s a simple method to get the serial number of the STAR and trace it along with Test_Variable:
And here is a simple python script to send load, input variables, and run the method:
import requests, json, time
headers={'Content-type':'application/json','Accept':'application/json'}
sim_state = True
method = r"C:\Program Files (x86)\Hamilton\Methods\Test Methods\API Input Value Test.hsl"
print("Hello Hamilton!")
response = requests.get('http://localhost:51745/api/vector/v2/system/version')
print("[" + str(response.status_code) + "] " + response.text + "\n")
if (response.status_code == 200):
print("<- Unload Method")
reponse = requests.post('http://localhost:51745/api/vector/v2/execution/unload-method')
print("[" + str(response.status_code) + "] " + response.text + "\n")
body = {"filePath": method, "simulation": sim_state, "parentWindowHandle": 0 }
request_body_load = json.dumps(body)
print("-> Load Method [" + method + "]")
response = requests.put('http://localhost:51745/api/vector/v2/execution/load', data=request_body_load, headers=headers)
print("[" + str(response.status_code) + "] " + response.text + "\n")
print("-- Check Ready State")
response = requests.get('http://localhost:51745/api/vector/v2/execution/loaded-method')
loaded_method_name = response.text
state = 0
while state == 0:
time.sleep(5)
response = requests.get('http://localhost:51745/api/vector/v2/execution/run-state')
running_state = response.text
print("Status: ", running_state, " Method: ", loaded_method_name)
state = int(running_state)
print("\n")
variables = {"variableNames": ["Test_Variable"], "variableValues": ["Value_From_Outside_Venus"]}
request_body = json.dumps(variables)
print("-> Load Parameters")
print(request_body)
response = requests.put('http://localhost:51745/api/vector/v2/execution/input', data=request_body, headers=headers)
print("[" + str(response.status_code) + "] " + response.text + "\n")
print("-- Start Method")
reponse = requests.post('http://localhost:51745/api/vector/v2/execution/start')
print("[" + str(response.status_code) + "] " + response.text + "\n")
print("-- Check Ready State")
state = 2
while state == 2:
time.sleep(15)
response = requests.get('http://localhost:51745/api/vector/v2/execution/run-state')
running_state = response.text
print("Status: ", running_state, " Method: ", loaded_method_name)
state = int(running_state)
print("\n")
print("-- Method Complete")
Here’s the trace for that method run:
1 Like
I’m getting “unrecognized token” error in the method trace.
for this “Test_Variable” that you mentioned in the code, do you need to declare this variable in the method? what type is it? Variables, Array of Variables?
also my API url shows as v1 instead of v2
FYI, here’s Nlog from ProgramData/Hamilton folder for the webAPI:
the setting variables section shows this:
SetVariables System.String[] Success.
2025-04-11 15:45:15.1357|INFO|Hamilton.WebAPI.Host.Controllers.V1.RunExecutorController|LoadMethod C:\Program Files (x86)\Hamilton\Methods\rest-api-test.hsl Method loaded.
2025-04-11 15:45:19.1799|INFO|Hamilton.WebAPI.Host.Controllers.V1.FileManagerController|GetRunHistoryData Success.
2025-04-11 15:45:19.2158|INFO|Hamilton.WebAPI.Host.Controllers.V1.RunExecutorController|GetScheduleData Success.
2025-04-11 15:45:20.1629|INFO|Hamilton.WebAPI.Host.Controllers.V1.RunExecutorController|SetVariables System.String[] Success.
2025-04-11 15:45:20.5730|INFO|Hamilton.WebAPI.Host.Controllers.V1.RunExecutorController|StartMethod Success.
2025-04-11 15:45:21.8682|INFO|Hamilton.WebAPI.Host.Controllers.V1.FileManagerController|GetRunHistoryData Success.
2025-04-11 15:45:21.9635|INFO|Hamilton.WebAPI.Host.Controllers.V1.RunExecutorController|GetCurrentRunData Success.
2025-04-11 15:45:21.9635|INFO|Hamilton.WebAPI.Host.Controllers.V1.RunExecutorController|GetScheduleData Failed. No schedule data returned.
2025-04-11 15:45:22.1022|INFO|Hamilton.WebAPI.Host.Controllers.V1.FileManagerController|GetRunHistoryData Success.
2025-04-11 15:45:22.8058|INFO|Hamilton.WebAPI.Host.Controllers.V1.RunExecutorController|GetScheduleData Success.
2025-04-11 15:45:22.8058|INFO|Hamilton.WebAPI.Host.Controllers.V1.FileManagerController|GetRunHistoryData Success.
2025-04-11 15:45:37.8047|INFO|Hamilton.WebAPI.Host.RunExecutor.RunExecutorClient|HandleMethodTerminated Host self-invoking UnloadMethod.
The Venus method I used to test the Input endpoint was just those two lines. I did not explicitly declare the variable before it was used in the TraceValues function. I suspect that Venus declares it in the hsl behind the scenes.
The V1 and V2 APIs are almost the same. I tried v1 and it still runs. (note the url changes more than v1 → v2)
My log does not have ‘System.String’ in the SetVariables line.
2025-04-14 13:12:53.1848|INFO|Hamilton.WebAPI.Host.Controllers.V1.RunExecutorController|GetLoadedMethod Success.
2025-04-14 13:12:53.1848|INFO|Hamilton.WebAPI.Host.Controllers.V1.RunExecutorController|GetLoadedMethod Success.
2025-04-14 13:12:53.2286|INFO|Hamilton.WebAPI.Host.Controllers.V1.RunExecutorController|GetScheduleData Success.
2025-04-14 13:12:53.5635|INFO|Hamilton.WebAPI.Host.Controllers.V1.RunExecutorController|GetRunState Success.
2025-04-14 13:12:53.5879|INFO|Hamilton.WebAPI.Host.Controllers.V1.RunExecutorController|SetVariables Success.
Are you sending the variable values like this?
{"variableNames": ["Test_Variable"], "variableValues": ["Value_From_Outside_Venus"]}
Its two arrays: variable names, and variable values.
I just tried on different instrument, and it does show v2 in the Swagger UI along with v1 REST API. and getting Input value from REST API just worked.
compared the Venus version, the problematic one has v6.0.2, and the working one has v6.2.1
I’m on 6.2.0, so that’s probably it. Good to know that if you want to input variable values it may not work in 6.0, but does work in 6.2.
Thank you so much @DCurrier for helping me out!
While I still have you, may I ask you how do you get run time data out? e.g. the consumable scan from autoloader?
The REST doesn’t have output, But I guess we can just use HSLHttp/Json lib to call LIMS consumable API directly.
Happy to help!
At the moment, I’m either not capturing any runtime data or I’m just saving it to a file. It looks like there’s an endpoint (/file-management/asset) that can fetch a file via the API. I have not tried it, but it seems like a good way to get data files back out from Venus.
If you come up with something, I’d like hear about it!
1 Like
The function ‘/api/vector/v2/execution/input’ to assign method variables only works in 6.2.1 or above.
Beware that this function currently only allows to pass variables BEFORE the run starts, and not once the run has started.
Usage:
-
Set the global variables in your method that you want to input via the API
-
PUT /api/vector/v2/execution/load
{
“filePath”: “C:\Program Files (x86)\Hamilton\Methods\NoDeck.hsl”,
“simulation”: true,
“parentWindowHandle”: 0
}
-
PUT /api/vector/v2/execution/input
{
“variableNames”: [ “var1”, “var2” ],
“variableValues”: [ "var1 value ", “var2 value” ]
}
//Note: only individual values are supported. Passing arrays is currently under development.
-
POST /api/vector/v2/execution/start
-
GET /api/vector/v2/execution/run-state
Returns the run state (integer) from this enum:
0 = Method not loaded,
1= Method loaded,
2= Running,
3= Aborting,
4= Aborted,
5= Processed,
6= Pausing,
7= Paused,
8= Starting,
9= Terminating,
10= Terminated,
11= Unknown
-
Once the run is finished, call this to unload the method and release all objects:
POST /api/vector/v2/execution/unload-method
4 Likes
In this link you can download:
- Code samples in .NET, React and Angular
- REST API Programmer´s manual (6.3 draft)
- A simple test HTML to demo the basic functions to load/start/unload a method and get the run state.
- A powershell to enable SwaggerUI. It must be run from an elevated PowerShell (Start > PowerShell > Run as Admin). The script will update the needed json file, restart the VENUS services and open SwaggerUi in the browser.
Alternatively can follow the instructions in the text file to do it manually.
The code samples and the manual will be installed with the upcoming VENUS 6.3 at Hamilton\Bin\WebAPI
Pass: Hamilton24
4 Likes
@AlvaroCuevas_Hamilton This is perfect, I wish you shown up few days earlier, but that was fun learning experience.
I was wondering if there’s API authentication like bearer token, seems like it’s mentioned in the user’s manual. Is that available in Venus v6.3 & WebAPI v3?
Yes, auth is coming in v3 of the API with 6.3
1 Like
