This document is split into two sections.
- The first section is relevant for VideometerLab version 4.3 and newer.
- The second section is relevant for VideometerLab version 4.3 and older.
- Overview
- Generic C# controller for Session
- Python implementation for controlling Session
- Python scripts
- Technical details
The communication protocol handles messages between the VideometerLab Session and an external controller. The external controller can for instance be a PLC, custom C# application, or custom Python scripts.
Videometer provides the following:
- An abstract C# class "ExternalSessionController" which anyone can inherit from and make a custom implementation.
- A C# implementation called "ExternalSerialSessionController" that communicates over a serial connection with Phyton scripts that can control the Session.
- Corresponding Phyton scripts to control the Session.
Both implementations work by controlling the Session by calling methods on the "IExternalSessionControllerListener" interface.
Below is listed the methods that are exposed by the generic C# controller that can be used to control Session from C# code.
An image is captured, analyzed, and the result is shown on screen. This corresponds to using the capture button in the GUI. The command takes the following arguments:
- Sample ID
- Operator initials
- Comment
Cleares the GUI and makes ready for beginning new measurements. There are no arguments to this method.
Stops the current measurement. This corresponds to using the stop button in the GUI. There are no arguments to this method.
Loads a specified light setup into the device. The name of the light setup is passed as an argument. The light setup must be saved in the active workspace.
Saves the active light setup to the active workspace. The name of the light setup is passed as an argument.
Performs an automatic light setup. There are no arguments to this method.
Acknowledge a failed light setup adjustment. The session itself does not clear a failed light setup adjustment: it leaves the session in SessionState.AdjustingLightSetupFailed, where it refuses further commands, until the controller that issued the adjustment acknowledges the failure. That way the external controller cannot continue to capture images without being aware of the light setup adjustment failure.
This method is called when ever the internal Session state changes. See diagram below.
Called if an error happens, for example, something in the pipeline of capturing, analyzing, or saving of results, failed for the current image. Used to inform external controllers that something went wrong.
This section explains an example of an external Session controller written in Python. The controller consists of two parts:
- A C# implementation called "ExternalSerialSessionController"
- Python scripts
It works by communicating over a serial connection between the "ExternalSerialSessionController" and the Python scripts.
Both the "ExternalSerialSessionController" and the Python scripts can be edited and customized to your needs/application.
Both is supplied in the Releases section.
This method initializes the connection between the Python scripts and the VideometerLab instrument. If a connection can not be established it is retried a number of times. This behavior cna be controlled by parameters in the top of the file VideometerLabDevice.py.
This method tells the VideometerLab instrument to capture an image. This image is analysed according to the loaded recipe. This method returns once the image have been captured and before the analysis begins.
This method waits for the current analysis to finish. If the VideometerLab instrument is currently analyzing an image, then this method waits for this analysis to finish. If the VideometerLab instrument is not currently analyzing an image, this method returns immediately.
A timeout parameter is provided that specifies the maximum time this method is allowed to wait before throwing an exception.
This method waits until the VideometerLab sphere has moved all the way up. If the VideometerLab sphere is already in its up position, then this method returns immediately.
A timeout parameter is provided that specifies the maximum time this method is allowed to wait before throwing an exception.
This method asks the VideometerLab software if the analysis of the previous image was successful or not. If the analysis of the previous image failed, an exception is throw containing an error message. This error message is identical to the error message shown in the VideometerLab software. This method can be used to make automatic decisions on how to handle analysis errors based on the individual error message.
Loads a specified light setup into the device. The name of the light setup is passed as an argument. The light setup must be saved in the active workspace.
Saves the active light setup to the active workspace. The name of the light setup is passed as an argument.
Performs an automatic light setup. There are no arguments to this method.
Videometer provides a Python class called VideometerLabDevice as well as scripts that use this class. These scripts are provided open-source, free of charge, and the user can freely customize them to their specific needs.
This file contains a Python implementation that can be used to control the VideometerLab instrument. All variables are defined at the top of the file, and it is not generally necessary to modify this file. All below scripts use the VideometerLabDevice class defined in this file.
This script do the following:
- Connected to the VideometerLab instrument
- Waited for any ongoing analysis to finish
- Captures a new image and starts the analysis according to the loaded recipe
- Waits for the VideometerLab sphere to move all the way up
This script does the following:
- Connected to the VideometerLab instrument
- Waits for the VideometerLab sphere to move all the way up
If the VideometerLab sphere is already all the way up then this script immediately.
This script does the following:
- Connected to the VideometerLab instrument
- Checks if the analysis of the previous image was successful or not.
If the analysis of the previous image failed an exception is throw containing an error message. This error message is identical to the error message shown in the VideometerLab software. This method can be used to make automatic decisions on how to handle analysis errors based on the individual error message.
This script does the following:
- Connected to the VideometerLab instrument
- Loads a specified light setup into the device.
This script does the following:
- Connected to the VideometerLab instrument
- Saves the active light setup to the active workspace
This script does the following:
- Connected to the VideometerLab instrument
- Performs an automatic light setup.
The Python scripts are written for an application where a robotic system is placing presenting samples to the VideometerLab instrument. This robotic system can execute the Python scripts as it means of communication with the VideometerLab instrument.
The suggested user flow is as follows:
- The human operator manually starts the VideometerLab Session and loads the necessary recipe
- Before the robot presents the first sample to the VideometerLab instrument, it calls the Python script "WaitForSphereUp.py" to ensure the VideometerLab sphere is up and thereby that the robot does not collide with the sphere.
- The robot presents a sample in the VideometerLab instrument and moves away so the sphere can move down without colliding with the robot arm.
- The robot calls the Python script "CaptureImage.py" to capture an image and start the analysis. Once the script returns, the robot can safely remove the sample again.
- Repeat from step 3.
Optionally, a call to the Python script "DidLastImageFail.py" can be added between step 4 and 5 and any custom error handling be done here.
To make your own session controller in C# you have to make a new class and inherent from the abstract class "ExternalSessionController". You then compile your dll and copy it into the VideometerLab installation folder. When you start Session, your external Session controller can now be used.
An example of this can be found in the "ExternalSerialSessionController" class.
To use our Python controller, you need to copy the dll "VM.Lab.Session.ExternalSerialSessionController.dll" into the VideometerLab installation folder. When you start Session you can now send commands to the VideometerLab instrument by executing the provided Python scripts.
Note that:
- The Python scripts assume that the VideometerLab PC and the external PC are connected by a serial cable.
- You will need to adjust the COM port number at the top of the file "VideometerLabDevice.py" to be the COM port number of the VideometerLab device.
- You will need to change the COM port number assigned by Windows to COM2 for the COM port on the PC that is connected to the external controller.
The assigned COM port number is changed using these steps:
- Open the Device Manager (Can be done by pressing the Windows Key + R. Type “devmgmt.msc” and press Enter.)
- Expand the Ports (COM & LPT) section
- Right-click the COM port and select Properties
- Click the Port Settings tab
- Click Advanced
- Change the COM port number in the dropdown
- Click OK
- Click OK
- If the COM port number is already in use restart your computer after following the above steps
You can customize our Python scripts to your liking. To make your own Session controller for Python, you can either:
- Use the "VM.Lab.Session.ExternalSerialSessionController.dll" as provided, but modify the Python scripts to your needs.
- Change the source code for the "ExternalSerialSessionController" class and modify the Python scripts to your needs.
You will need to import the Python library's "serial" and "time" to modify the VideometerLabDevice class.
The diagram below slows the Session state machine. These states can be used for custom implementation of the Session controllers.
- Overview
- Generic C# controller for Session
- Python implementation for controlling Session
- Python scripts
- Technical details
The communication protocol handles messages between the VideometerLab Session and an external controller. The external controller can for instance be a PLC, custom C# application, or custom Python scripts.
Videometer provides the following:
- An abstract C# class "SessionController" which anyone can inherit from and make a custom implementation.
- A C# implementation called "SerialSessionController" that communicates over a serial connection with Phyton scripts that can control the Session.
- Corresponding Phyton scripts to control the Session.
Both implementations work by controlling the Session by calling methods on the "ISessionControllerListener" interface.
Below is listed the methods that are exposed by the generic C# controller that can be used to control Session from C# code.
Starts a new measurement. This corresponds to using the play/start button in the GUI. An image is captured, analysed and the result is shown on screen. The command takes the following arguments:
- Sample Id
- Operator initials
- Comment
- Boolean indicating whether to suffix by timestamp
Pauses the current measurement. This corresponds to using the pause button in the GUI. There are no arguments to this method.
Finishes the current measurement. This corresponds to using the finish button in the GUI. There are no arguments to this method.
Cleares the GUI and makes ready for beginning new measurements. This corresponds to using the new button in the GUI. There are no arguments to this method.
This method is called when ever the internal Session state changes. See diagram below.
This method is called if the capture or analysis of an image fails. This can be used to transfer the error message to the external controller and have the external controller decide how to handle the error.
This section explains an example of an external Session controller written in Python. The controller consists of two parts:
- A C# implementation called "SerialSessionController"
- Python scripts
It works by communicating over a serial connection between the "SerialSessionController" and the Python scripts.
Both the "SerialSessionController" and the Python scripts can be edited and customized to your needs/application.
Both is supplied in the Releases section.
This method initializes the connection between the Python scripts and the VideometerLab instrument. If a connection can not be established it is retried a number of times. This behavior cna be controlled by parameters in the top of the file VideometerLabDevice.py.
This method tells the VideometerLab instrument to capture an image. This image is analysed according to the loaded recipe. This method returns once the image have been captured and before the analysis begins.
This method waits for the current analysis ot finish. If the VideometerLab instrument is currently analysing an image then this method waits for this analysis to finish. If the VideometerLab instrument is not currently analysing an image this method returns immediately.
A timeout parameter is provided the specifies the maximum time this method is allowed ot wait before throwing an exception.
This method waits until the VideometerLab sphere have moved all the way up. If the VideometerLab sphere is already in its up position then this method returns immediately.
A timeout parameter is provided the specifies the maximum time this method is allowed ot wait before throwing an exception.
This method askes the VideometerLab software if the analysis of the previous image was successful or not. If the analysis of the previous image failed an exception is throw containing an error message. This error message is identical to the error message shown in the VideometerLab software. This method can be used to make automatic decisions on how to handle analysis errors based on the individual error message.
Videometer provides a Python class called VideometerLabDevice as well as scripts that use this class. These scripts are provided open-source, free of charge and the user can freely customize them to their specific needs.
This file contains a Python implementation that can be used to control the VideometerLab instrument. All variables are defined at the top of the file, and it is not generally needed to modify this file. All below scripts uses the VideometerLabDevice class defined in this file.
This script do the following:
- Connected to the VideometerLab instrument
- Waited for any ongoing analysis to finish
- Captures a new image and starts the analysis according to the loaded recipe
- Waits for the VideometerLab sphere to move all the way up
This script do the following:
- Connected to the VideometerLab instrument
- Waits for the VideometerLab sphere to move all the way up
If the VideometerLab sphere is already all the way up then this script immediately.
This script do the following:
- Connected to the VideometerLab instrument
- Checks if the analysis of the previous image was successful or not.
If the analysis of the previous image failed an exception is throw containing an error message. This error message is identical to the error message shown in the VideometerLab software. This method can be used to make automatic decisions on how to handle analysis errors based on the individual error message.
The Python scripts is written for an application where a robotic system is placing presenting samples to the VideometerLab instrument. This robotic system can execute the Python scripts as it means of communication with the VideometerLab instrument.
The suggested user flow is as follows:
- The human operator manually starte the Videometer Session and loaded the needed recipe
- Before the robot presents the first sample to the VideometerLab instrument it calls the Python script "WaitForSphereUp.py" to ensure the VideometerLab sphere is up and thereby that the robot do not collide with the sphere.
- The robot presents a sample in the VideometerLab instrument and moves away so the sphere can move down without colliding with the robot arm.
- The robot calls the Python script "CaptureImage.py" to capture an image and start the analysis. Once the script returns the robot can safely remove the sample again.
- Repeat from step 3.
Optionally a call to the Python script "DidLastImageFail.py" can be added between step 4 and 5 and any custom error handling be done here.
In order to use make your own session controller in C# you simply have to make a new class and inherent from the abstract class "SessionController". You then compile your dll and copy it into the VideometerLab installation folder. When you start Session your external Session controller can now be used.
An example of this can be found in the "SerialSessionController" class.
In order to use our Python controller you need to copy the dll "VM.Lab.Session.SerialSessionController.dll" into the VideometerLab installation folder. When you start Session you can now send commands to the VideometerLab instrument by executing the provided Python scripts.
Note that:
- The Python scripts assume that the VideometerLab PC and the external PC is connected by a serial cable.
- You will need to adjust the COM port number in the top of the file "VideometerLabDevice.py" to be the COM port number of the VideometerLab device.
- You will need to change the COM port number assigned by Windows to COM2 for the COM port on the PC that is connected to the external controller.
The assigned COM port number is changed using these steps:
- Open the Device Manager (Can be done by pressing the Windows Key + R. Type “devmgmt.msc” and press Enter.)
- Expand the Ports (COM & LPT) section
- Right-click the COM port and select Properties
- Click the Port Settings tab
- Click Advanced
- Change the COM port number in the dropdown
- Click OK
- Click OK
- If the COM port number is already in use restart your computer after following the above steps
You can customize our Python scripts to your liking. In order to make your own Session controller for Python you can either:
- Simply use the "VM.Lab.Session.SerialSessionController.dll" as provided, but modify the Python scripts to your needs.
- Change the source code for the "SerialSessionController" class and modify the Python scripts to your needs.
You will need to import the Python library's "serial" and "time" to modify the VideometerLabDevice class.
The diagram below slows the Session state machine. These state can be used for custom implementation of the Session controllers.
