How to use HSL Automation Object

Hi there,

What exactly is an Object in HSL? The documentation is extremely sparse only references a single example.

For example, can I create a class in C++ and use HSL Objects to interface with it? And if so, what would that look like? This would be extremely useful.

1 Like

Afaik HSL isnt directly interoperable with other languages. Do you know about PyHamilton? You could take just the Venus layer of it and have any language sending HTTP packets to the Venus server.

I am aware of PyHamilton and PyLabRobot. They look like excellent tools and one day I would like to try them.

However, at my work I am not allowed to use anything that isn’t officially provided by Hamilton due to fears over damaging the machine, and potentially having a voided warranty as a result of using unofficial tools.

Ah, fair enough, very reasonable. With respect to PyHamilton, you are still running a Venus method in Run Control including everything associated with that (Venus safety features, log files, etc). It is just that the method is formatted in a way so as to allow command parameters to be passed from an outside source.

It’s not unlike reading in a csv worklist that has been created by some external program. Such a worklist might tell you what wells and plates you are aspirating from, but the execution is handled by Venus. Similarly, PyHamilton tells you what wells and plates you are aspirating from, but also what liquid class you are using, what volume, etc.

In any case I am familiar with such restrictions and understand that labs want to do things the traditional way, I just wanted to explain how it works under the hood in case there was confusion.


That is extremely helpful. I was under the impression that PyHamilton was just calling raw firmware commands under the hood.

Personally, I would much rather use Python to do this kind of programming. A lot of what I do is outside the bounds of what HSL can allow me to do in a reasonable amount of time, such as advanced sequence manipulation.

Honestly, this is bound to happen when you try and create a bespoke language. The language implementors (Hamilton) end up having to build and maintain an entire standard library of functions, down to trivial details like string handling, that would normally come for free in any other mature language. The result is that I spend a lot of my time getting over hurdles that have already been solved, instead of building my methods.

To be honest, if I were Hamilton, I would strongly consider making PyHamilton official and also releasing a C++ API. I simply don’t believe that custom languages are the way to go, and they have the effect of freezing you in time. You will spend all of your time implementing functions (e.g. HSL Dictionary) that have existed for decades in other languages and are very well tested. As for the Run Control and the Method Editor, that can easily be amended - the method editor can simply a convenience to insert autogenerated python snippets for example.

The fact that PyHamilton exists is a warning sign from industry professionals that HSL is simply way too cumbersome to use, especially as people start making comprehensive automation platforms that include much more than a single liquid handler. I believe that trying to maintain a custom (transpiled?) language implementation could end up hurting you in the long run.


I’m glad I could help! The confusion is understandable, because that is how PyLabRobot talks to the Hamilton. I’m happy to provide more info if you have any more questions about getting started. I’m also very curious to know what your application is.

1 Like

I just watched a YouTube video demonstration of PyHamilton (PyHamilton Getting Started Tutorial - YouTube) and wow! I am completely blown away. I was under the impression that I wouldn’t be able to see the logs or deck layout, and lose any and all safety features. I will relay this to my superiors and look into integrating this into my workflow

You’re concerned about Hamilton being frozen in time but then suggest a C++?

You have valid concerns but that’s funny.

Edit: ALso Venus 6 comes with an API, it’ll be interesting to see what it provides.


Agreed, I should have used a different language instead of C++ as an example, but my point still remains.

While a Python API would be a far easier choice as its easy to learn and has lots of community support, even C++ would still be far superior to HSL (well, except that external libraries can be a pain to install). C++ is also actively maintained with a well-maintained standard library.

Say what you want about C++, but it has strong-typing, lambdas, templates, structs (actual structs, not the weak HSL version), functional polymorphism, namespacing and classes, and a large collection of standard libraries implementing maps, vectors, sets, sorted sets, smart pointers, and on and on. With a custom language, all of that is squarely your responsibility or that of the language designer.

The VENUS 6 API appears to be a REST API. That isn’t nearly as powerful as having a programmatic API.

Contrary to popular belief, C++ has a massive community behind it. It is absolutely not a language I would describe as being frozen in time.

It is constantly being improved and maintained (latest version is C++20), and in fact a fair few of the developers of the Boost libraries (one of the most popular C++ library collections) also work on the C++ language itself, which is why libraries and features from Boost often seem to make their way into C++ core.

1 Like

You’re preaching to the choir but sadly we do not represent the majority.

The reality is that a vast majority of users love Drag and Drop interfaces and vendors love to protect their IP from idiots by limiting software/hardware capabilities through a limited API or custom language. I understand all of that. It allows for a MVP to hit the market sooner rather than later so the software team doesn’t have to account for every possible use case and it stops operators from bricking their systems.

ERGO a REST API is nice because they’re easy to build, maintain and expand upon plus they’re language agnostic. They also make integrations significantly easier. I’m actually building an API right now for a custom program (truthfully built in less than a couple of hours.) The PyHamilton use case or potentially yours represent a small and potentially smaller portion of the user base with the amount of low code/ no code vendors flooding SLAS and other conferences with their money.

And often when people do make their own custom libraries or program to upload onto GitHub, I find that it’s simply out of now knowing the platform software’s in and outs. The aforementioned is also bad because you have to become a software specialist and this is where I do feel that a programmatic API can help standardize this work. However it doesn’t even work that way in software, I’m less optimistic that we’ll arrive there in lab automation in my lifetime without serious AI advances or cross vendor coordination (not likely at all). However programmatic or REST API’s are a great start.

With that said, Tecan and Opentron have Python API’s (C# also for Tecan) and you can do some pretty cool stuff with it but you can also do all of that same cool stuff without as long as you know what you’re doing and you’re convinced that this is the correct tool for the task at hand. If it’s not, beg for more funding and new hardware lol.


Yes, it’s truly unfortunate. I have a feeling that vendor lock-in is the only real reason why there is a custom language. The two other concerns, which are Drag-and-Drop interfaces and safety against bricking, are completely solvable through good API design.

I was wrong with my comment about REST APIs being less powerful. I see your point

I used to play a game that was an RPG maker and they created their own pseudocoding language for the game. I forgot the name of the game but it was my first introduction to coding concepts. I feel like this practice used to be way more common and it’s possible that VENUS is simply old af and adhered to these custom practices as a standard of the time… not things you would build now.

I’m curious to see what Hamilton does with their successor to Venus (if it ever comes.) I feel bad for them though. I feel like the average Venus power user is a massive curmudgeon compared to others.


That’s not true. HSL can create registered COM objects, so a compiled .net/c# (or other) dll could be called by HSL. This is how Hamilton integrated Newtonsoft.Json.dll into HSLJson.

So to answer @Zach’s question, well, it depends on the object you are creating. As mentioned above, yes you should be able to create a c++ class, compile, register and createObject it. Normally there is external documentation, however I agree that in general the integration of external objects into HSL files is a very under-documented feature that could be very useful for the advanced programmer. Might be something to target once the backlog of beginners are trained, @EricSindelar_Hamilton?

(Also, as an aside, I don’t think “what about pyHamilton” is the answer to every question, especially when a specific question about hsl is asked for e.g… Yes, it is great and potentially powerful in RnD setups, but often there are hard business boundaries on the use of open-source code, especially when it interfaces with vital/expensive hardware.)


@Gareth this would be extremely useful for me! There is a lot I can work around with HSL, but some things I need the extra kick from C++ or other languages to make it work. Still, I’m not sure how to get started with integrating my own DLLs due to the lack of documentation.

@EricSindelar_Hamilton is there any documentation floating around for using the Automation Object library?

Edit: I suppose I can try and look at HSLJson and Newtonsoft JSON and see if I can piece together how to do it

Hi Zach,

I uploaded a ppt and pdf that provide a brief overview of HSL and library integration.

I hope this helps!



@Stefan I just tried the PyHamilton installer.

I am pissed. With no warning whatsoever, the PyHamilton installer went ahead and OVERWROTE files in the Hamilton config folder on the C-drive. No hint to, say, copy the Hamiltln folder just in case, no indication that it would touch this folder at all. As it was billed to me, this is just a Python package to do REST calls into VENUS. Now, the machine is fucking bricked. Nothing runs, not in any existing methods except for the simulator methods.

I’m about to get fired, for sure. This is unbelievable. Why is this changing the system?


Thank you so much for the documentation ! I’ve found some parts of HSL/C# integration by trial and error in the past, but that’s way better. If you have more documentation about advanced HSL like that please share them, I think it will benefit the users of this forum. Sometimes we are not even asking for HSL documents because we don’t imagine it would exist.
Something that would help is also documentation about the objects inherent to Venus. For instance “HXREGLib.HxRegistry.1” or others thare are used in the hsl librairies.


PS : Zach, I’ve never used PyHamilton, but you may want to try the repair feature of Venus. Just run the installer and it’s pretty good to reset files when it’s not working anymore (saved me in the past). Maybe wait for stefan’s response though. I have no idea what modifications are made by PyHamilton.

1 Like

You don’t have any backups?