Understanding the 6 main files in VENUS

[Brad]

Hi All,

Methods in VENUS generally have 6 main files: .sub, .med, .stp, .hsl, .lay, and .res

Could a Hamilton expert, perhaps @BrandonBare_Hamilton, explain a bit more about these files, with an emphasis on the following:

What is the use of each of these files
What is generally contained in each of these files
When are the files referenced
Are the finals text or binary
Any other nifty info for each of the file types.

I am particularly interested in information about the .sub ,.stp, and .res files

We can file this under things that I should know, but don’t.

[zachary.milot]

@Brad

.sub, .med, .stp, .hsl, .lay, and .res

The best way I can describe it is in terms of ordering coffee:

1. .med (method):

This is like the order the customer gives to the barista. It specifies exactly what you want (e.g., a latte with two shots of espresso, oatmilk, no sugar). It’s the detailed instructions for execution.

2. .hsl (Hamilton Standard Language):

This is the recipe for making the coffee. It tells you what type of coffee, the proportions, the process, and how everything comes together to make the drink.

You can edit these more finite instructions by editing the method/changing how you order but sometimes you need to go in and edit the details which is possible. This should always be a direct copy of what is in the method editor (any HSL edits are only in the .hsl file and do not sync back to the .med file)

3. .stp (steps/3D layout):

This represents the blueprint of the workstation where the coffee is made. It’s how all the components (espresso machine, milk frother, syrup bottles, etc.) are set up to allow the barista to follow the order.

4. .lay (layout):

This is like the table or counter arrangement where the coffee will be served or where additional components (saucer, stirrer, napkins) are placed. It describes the presentation environment.

5. .res (resources):

Think of this as the physical tools and ingredients—the coffee beans, milk, sugar, cups, and even the machines themselves. These are the essential elements required to make the drink.

6. .sub (submethod):

This is like the special preparation for specific components, such as frothing milk, grinding beans, or preparing a flavored syrup. These are the individual tasks or subprocesses that feed into the larger method.

Feel free to let me know if there is any clarification @BrandonBare_Hamilton or if I got anything wrong but this is how I see the these file types.

[Brad]

Thanks Zac, nice anology!

We normally think that most of these critical files are cached and compiled at runtime, however when we look at our trace and the list of the files used, we do not see [methodName].stp listed in our files.

Today, we had an interesting occurrence where VENUS went to reference the .stp file mid-run and could not find it for whatever reason and the method aborted. The .stp was clearly in the right location, we can see it just fine, so we are interested in when this file is used and why it is not listed in the list of files at the end of our .trc logfile.

Any thoughts?

[Huajiang]

hsl and method files (.hsl, .sub, .stp and .med)

hsl files (.hsl, .sub) is the code for main function and sub functions, which are text and can be viewed by any text editor, but it will be different from hsl editor. But these file are protected by checksum, you can not edit with other editors.

stp file stores the property of hsl files (like readonly) and parameters for each instrument step.

You can call it hamilton configuration file (HxCfgFile), the files for method (.med, .stp), deck layout (.lay), labware (.tml, .rck and .cnt) and configuration (.config) are in this format. This file is binary, but you can convert it to text by HxCfgFilConverter.exe. This file contains datas of dictionary like structure.

.med file is a hamilton configuration file, it contains the parameter for editing method. I do not think it is necessary for running, only display line number of running.

There is another workflow file (.wrl), which is about the same as .med file and used for store the parameter for editing workflow instead of method.

deck layout files (.lay and .res)

.lay file is also a hamilton configuration file, it contain all the datas of deck layout.

.res file is text format, you can see its content, and it store the resources defination.

[cwehrhan]

Hi Huajiang,

I was wondering if you knew what the seemingly random numeric values surrounding the steps were? I thought they were registry addresses but unsure!

[zachary.milot]

@cwehrhan The values surrounding the steps in your Venus script are Activity IDs. They serve as markers to denote which resources are being utilized during a specific function call and allow the scheduler to map this information to a database or scheduler system for tracking and task execution purposes.

Activity IDs connect specific steps in your script to the resources they use. This is particularly useful for ensuring that resources aren’t over-allocated and for enabling parallel task execution where possible. Thisis mostly used in systems running the Venus Scheduler (not included with Venus 5 but comes out of the box with Venus 6.

When using the scheduler, these IDs help define task dependencies, execution order, and resource availability. They ensure that each activity is properly tracked and aligned with system constraints and task durations . This can be best seen in the graphic below showing where these IDs can indicate that the hardware in the ML_Star Pipetting arm is used and when other tasks cant be run in parallel if that resource is being used:

These IDs are not mandatory, and are somewhat difficult to generate manually when writing in raw HSL (Hamilton Script Language). This isnt a huge deal when you’re not leveraging the scheduler, however if you’re writing bespoke HSL code you can get the codes by integrating your code in line with the insert HSL code and use the method editor to organize your code. To edit these in the method editor you can right click a group or a specific line in the editor and click Activity…

This will bring up the menu to be able to adjust the needed metadata included with this value. this includes but is not limited to the color which will be displayed within the scheduler upon runtime, the resource activity display name and the seconds which these resources will be utilized for.

It is always best to color code and I’ve always followed the color guide provided by hamilton below as the display names in the scheduler run control can get cut off easily. The color code is below:

If you don’t already know any lines starting with // (comment lines) are safe to omit without runtime errors, except for one key exception: the checksum comment at the end of the code. If your system is configured to verify checksums, this comment ensures the integrity of the compiled file and must remain in place.

Your initial thought of registry addresses, it’s understandable as they are numerical and may seem arbitrary at first glance. However, their primary role is to streamline scheduling and resource allocation rather than referencing memory or registry locations.

[cwehrhan]

My coworker pointed out to me that the bracketed section is in the registry. What this means, I am not sure!

[Brad]

@EricSindelar_Hamilton @BrandonBare_Hamilton can you help educate us?

[Huajiang]

It is the Type ID of COM object “Hamilton.HxStepAssignExpression”, which is editor of following step (x=1;).

[BrandonBare_Hamilton]

Hi @Brad,

@Huajiang 's posts pretty much covered it, but in an effort to hit what they pointed out as well as additional information I have consolidated within a single post below:

The 6 main files that make up a method can be broken down by 3 main categories: Execution Files, Layout Files, and Method Editor Files.

Execution Files are files used by Run Control to perform the actions that were coded. They are the lowest level of code that can be written within VENUS and are required for Run Control. These files include hsl and sub. They are ASCII based files that can opened with the HSL Method Editor or any text-based program.

hsl

• Libraries that are referenced are stored within this file
• All main Method tab steps are stored within this file
• If a device is used (ML_STAR for example), it is defined within this file using a layout file as reference
• When a method is being written with Method Editor, the steps are shown within the file with commented tags that reference line number and a unique value that is used to sync up all the files that contain the information that was stored

sub

• An extension of the hsl file but for any logic that has been stored within a submethod tab in the method
• The sub file will be referenced by the hsl and its functions are called within the hsl file as if they were library calls
• Utilizes the same comment tags as the hsl file
• Includes the OnAbort tab from the method editor file as it is considered a submethod as well

Layout Files store all the information regarding the deck. References to the ML_STAR device as well as any other device originating within the layout are also stored here (TrackGripper, EntryExit, etc). These files include lay and res files. The files are formatted by default as binary but can be configured to be ASCII as well. Anything that requires direct control over a system requires a Layout file that references a device to be controlled (ML_STAR).

lay

• Includes all of the labware information for the deck layout which includes file paths for labware, coordinates, sequences, properties, etc
• The deck layout editor parses/edits this file and displays the information as 3D visualizations of components in space
• the lay files are referenced by the hsl so that access to the relevant sequence and positions can be interpreted and sent to the Run Control program which turns each ML_STAR step into a firmware command to be sent to the instrument

res

• Stores resource information that was set by the Deck Layout editor
• By default, a ML_STAR resource is created, but this information is only needed for scheduled methods
• Defaults to ASCII based and can be opened with any text-based editor

Method Editor Files are files that are used by the Method Editor as an in between to store every single line of code within the method. These files include the med and stp files and are by default stored as binary but can also be configured to be ASCII. The method editor will read through every line within the hsl file and match the unique key associated with each step to a dictionary style lookup table with the same key within the med file. The result is the line of code that can be seen within the Method Editor.

med

• Includes every non device function within the hsl and sub files that are connected by a unique key value
• Parameters needed to show this line within the method editor are stored here (image of step, properties of the function, etc)
• Any custom dialog within the method will also have the information compiled within this file
• It is the lookup table for the method editor to turn line-based code into visual based code

stp

• Includes all the device-based commands within the method with their own unique key that corresponds to when they are used within the hsl or sub files
• Includes all error handling options and selected settings that were set for the command that was referenced
• Read only property for the med file is stored within this file to disable editing of the med file within the method editor

All of these files are utilized to read/write a method using the Method Editor. All of these files are also saved with a check sum that will throw an error at run time during analysis if any one of the files were edited outside of the Method Editor. Only hsl, sub, lay, and res files are needed for run control to analyze and compile the method.

The hsl, sub, med, and stp files must all have the same file name and be within the same folder. The lay and res files also must be within the same folder and share a file name, but does not have to be the same as the method.

Example:

Method Editor

hsl File

med File

DataDef,HxPars,3,6d371dbe_77f2_427f_a51d45f7aa65f862,
[
"1ReturnValue",
"t_strLabID",
"1FunctionName",
"SeqGetLabwareId",
"3FieldCount",
"1",
"(FunctionPars",
"3-534642658",
"0",
"(-533921770",
"(0",
"3-534642680",
"0",
"3-534642681",
"91",
"3-534642682",
"91",
"1-534642683",
"sequenceObj",
"1-534642685",
"C:\\Program Files (x86)\\Hamilton\\Library\\HSLSeqLib.hsl",
"3-534642642",
"4756",
"1-533921767",
"",
"3-533921768",
"0",
"3-534642677",
"2",
"1-533921769",
"",
")",
")",
"1-533921771",
"",
"1-534642685",
"HSLSeqLib.hsl",
"3-534642677",
"1",
")",
"3ParsCommandVersion",
"2",
"(BlockData",
"(1",
"1-533921782",
"SingleLibFunction.bmp",
"1-533921779",
"t_strLabID = SeqGetLabwareId(ML_STAR.SMP_CAR_24_15x100_A00_0001);",
")",
")",
"1Timestamp",
"2024-12-04 10:06:18",
"(ParamValue",
"1Value.0",
"ML_STAR.SMP_CAR_24_15x100_A00_0001",
")",
"(Variables",
"(-533921792",
"(SeqGetLabwareId",
"(0",
"10",
"FunctionName",
")",
")",
")",
"(-534118398",
"(t_strLabID",
"(0",
"10",
"ReturnValue",
")",
")",
")",
"(-534118399",
"(ML_STAR.SMP_CAR_24_15x100_A00_0001",
"(0",
"10",
"ParamValue",
"11",
"Value.0",
")",
")",
")",
")",
")"
];


DataDef,HxPars,3,2bf60795_6fbf_4115_a570f9b8dc10287d,
[
"1ReturnValue",
"t_strPosID",
"1FunctionName",
"SeqGetPositionId",
"3FieldCount",
"1",
"(FunctionPars",
"3-534642658",
"0",
"(-533921770",
"(0",
"3-534642680",
"0",
"3-534642681",
"90",
"3-534642682",
"90",
"1-534642683",
"sequenceObj",
"1-534642685",
"C:\\Program Files (x86)\\Hamilton\\Library\\HSLSeqLib.hsl",
"3-534642642",
"4676",
"1-533921767",
"",
"3-533921768",
"0",
"3-534642677",
"2",
"1-533921769",
"",
")",
")",
"1-533921771",
"",
"1-534642685",
"HSLSeqLib.hsl",
"3-534642677",
"1",
")",
"3ParsCommandVersion",
"2",
"(BlockData",
"(1",
"1-533921782",
"SingleLibFunction.bmp",
"1-533921779",
"t_strPosID = SeqGetPositionId(ML_STAR.SMP_CAR_24_15x100_A00_0001);",
")",
")",
"1Timestamp",
"2024-12-04 10:06:57",
"(ParamValue",
"1Value.0",
"ML_STAR.SMP_CAR_24_15x100_A00_0001",
")",
"(Variables",
"(-533921792",
"(SeqGetPositionId",
"(0",
"10",
"FunctionName",
")",
")",
")",
"(-534118398",
"(t_strPosID",
"(0",
"10",
"ReturnValue",
")",
")",
")",
"(-534118399",
"(ML_STAR.SMP_CAR_24_15x100_A00_0001",
"(0",
"10",
"ParamValue",
"11",
"Value.0",
")",
")",
")",
")",
")"
];

[osand317]

@BrandonBare_Hamilton thanks for this! Could you expand on how to configure normally-binary files to be stored as ASCII? Is this a setting that can be permanently enabled for all files, or are you just referring to one-off conversions using the converter tool?

[BrandonBare_Hamilton]

Hi @osand317 ,

They are one-off conversions using the tool. Upon saving a method, the relevant files will automatically be converted back to binary.