Click here to download SDK as zip file (Includes examples, .NET library, and documentation for off-line reference).

Nuget package can be found here

For general Topas4 information see here

Click here to download WinTopas4 application installer.

Topas4Server version 0.7.0.0 or later required. Topas4Server version 1.3.0.0 or later required for motor reset (homing) functionality. Topas4Server version 1.4.2.0 or later required for saved motor positions functionality.

Principal concepts

Topas4 software system consists of server application and client applications. For each physical device there will be only one server application and it must be running all the time. All client applications can control the device by using REST API, which is implemented by server application. Server application and all client applications provided by Light Conversion (WinTopas4, PowerScanner-T4, spectraLight and others) are written in a way to allow multiple clients to use the same device at the same time. Below are listed key concepts of Topas4 API.

1. Topas4 Server application must be running all the time to access the device.
2. Other Topas4 client applications (e.g. WinTopas4) might be running at the same time as the custom client application written by the API user, but that is not required.
3. Server and client applications might be running on the same PC, or on different PCs. Operating system or even lack of it isn't significant for client applications.
4. The only way to control the device is via REST API, using JSON as data serialization format.
5. All the actions/operations are non-blocking: command to move motor or set target wavelength will return immediately, not waiting for physical action to complete. To know when and whether action has completed, use other API calls.
6. There is no concept of connecting to/disconnecting from a device or a session.
7. API calls that change systems state (e.g. “move motor”, but not “get motor position”) must come from PC with authorized IP address to increase safety.
8. Topas4 Server applications location uses UDP multicast (.NET SDK includes location function, example in Python is provided too).

.NET SDK

While all functionality of the device is exposed via REST APIs, managed .NET library is provided. While it’s only the thin wrapper over REST API, in most cases using it should be easier and faster way to achieve the desired functionality. In case programming language/environment of your choice does not allow to use managed dynamic link libraries, you can use REST API without any loss of functionality.

Detailed description of all sub-services

• Wavelength control

Set wavelength, get available interactions with their calibration ranges, get currently set wavelength.

• Shutter and interlock

Open and close shutter, get current state of shutter and interlock.

• Motors

Get properties of motors, move single motor to specific position independent of wavelength set.

• Authentication

Methods to authenticate controlling PC using interlock.

• Smooth wavelength setter

Methods to use saved motor positions

• Saved motor positions

Smooth wavelength scanner allows to scan wavelength continuously without losing output with high speed by adjusting motors speeds and accelerations on the fly. This functionality is included in Public API. However, please notice, that it’s currently most complicated feature in Topas4 and is harder to use, less reliable and less stable than rest of the API.

Examples

To get started quickly please see provided examples for these languages/tools (download link is on the top of the page):

• C# (.NET SDK)
• Python (both .NET SDK and raw REST API examples are provided)
• Visual Basic (.NET SDK)
• LabVIEW (.NET SDK)
• Matlab (.NET SDK)
• Postman (Collection)

These operations are included in examples:

• Locate devices
• Open/close shutter
• Get current shutter state
• Get all available interactions with their wavelength ranges
• Set wavelength using specific interaction
• Inform user about actions he has to perform after setting wavelength (if any)
• Tweak position of single motor

Additionally, you don’t need a real physical device to start using API. In WinTopas4 application click Tools>Launch Demo Device and select one of the demo devices. You can use this demo device just as the real physical device. Known limitations:

• Interlock can’t be activated
• By default, access is granted for all callers to change systems state
• SmoothWavelengthSetter will abort any movement very quickly, as demo motors move with infinite acceleration

When running all examples (except Postman) make sure to provide correct serial number of your own device. Place to do so is clearly marked in code, e.g

static void Main (string[] args) {
            var serialNumber = "00666"; //change to actual serial number of your own device.
            var example = new Topas4SDKExample (serialNumber);
            example.Run ();
        }

If you want to use Postman collection correct environment variable “url” must be set. It should look like http://127.0.0.1:8000/00666/v0/PublicAPI, where 00666 is replaced with serial number of your device, and correct IP address and port is supplied too.

Migrating from WinTopas3

WinTopas3 API provided two different ways to control device. Some of the functions can be accessed via TCP/IP or COM port, with WinTopas3 application listening for incoming commands. Another way to control device is using unmanaged dynamic link library TopasAPI.dll. In this case WinTopas3 application cannot be running at the same time and all the required functionality must be implemented by the user. In contrast to this Topas4 system provides only one way to access and control device. There is no backward compatibility between WinTopas3 APIs and Topas4 API. Please read section Principal Concepts to understand key concepts of Topas4 API, as they are quite different compared to both of the WinTopas3 APIs.