Using the SPECTRAN V6 DLL
Quote from mm_dev on 12/05/2021, 14:24Starting with version 1.5.152.8795, the windows version of the RTSA-Suite PRO includes a DLL to directly interface with SPECTRAN V6 devices.
Inside the "sdk" folder in the installation directory you can find the header files, import library and several usage examples.
Additionally we'll provide an overview here:
- Download and install Aaronia RTSA-Suite PRO version 1.5.152.8795 or later
- Ensure the Spectran V6 is working correctly with the installed version of the Aaronia RTSA-Suite PRO.
- Additional requirements: Microsoft Visual Studio 2019 C/C++ x64 runtime and build toolsTo use the RTSAAPI with Visual Studio 2019, assuming the RTSA Suite Pro is installed at C:\Program Files\Aaronia AG\Aaronia RTSA-Suite PRO, configure your project as follows:
- Ensure that the active project configuration is using a x64 target
- "C/C++" -> "General" -> "Additional Include Directories": Add "C:\Program Files\Aaronia AG\Aaronia RTSA-Suite PRO\sdk"
- "Linker" -> "General" -> "Additional Library Directories": Add "C:\Program Files\Aaronia AG\Aaronia RTSA-Suite PRO\sdk"There are then two ways to load the library:
a) Let the linker do the job, to do so change the VS project config as follows
- "Linker" -> "Input" -> "Additional Dependencies": Add "AaroniaRTSAAPI.lib"
- "Debugging" -> "Environment": Add "PATH=C:\Program Files\Aaronia AG\Aaronia RTSA-Suite PRO;%PATH%"
b) Load the library at runtime using Win32 functions like thisHMODULE mod = ::LoadLibraryEx(L"AaroniaRTSAAPI.dll", NULL, 0);
if (!mod)
{
TCHAR pf[MAX_PATH], ld[MAX_PATH];// Find dll default installation location
::SHGetSpecialFolderPath(0, pf, CSIDL_PROGRAM_FILES, FALSE);
::StringCbPrintf(ld, sizeof(ld), L"%s\\Aaronia AG\\Aaronia RTSA-Suite PRO\\AaroniaRTSAAPI.dll", pf);// Load library from explicit location, using the dll folder as an addition to the search path for dependent dlls
mod = ::LoadLibraryEx(ld, NULL, LOAD_LIBRARY_SEARCH_DEFAULT_DIRS | LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR);if (!mod)
{
// ERROR WHILE LOADING LIBRARY
}
}IMPORTANT: The AaroniaRTSAAPI.dll must be used from within the RTSA-Suite PRO installation directory, else your project might silently fail due to the API not finding the necessary libraries.
- In the source code, add
#include <aaroniartsaapi.h>
to declare the functions from the RTSA API
- Before using any other API function, the library must be initialized with
AARTSAAPI_Init(n);
where n is one of the AARTSAAPI_MEMORY_* values that define the amount of memory to be used by the library.
- At Application shutdown the
AARTSAAPI_Shutdown();
function should be called to release any allocated memory and close any device handles.The library provides the following functions in aaroniartsaapi.h, please see the examples and the comments inside the header file for more details:
// Library Management
AARTSAAPI_Init(uint32t memory)
AARTSAAPI_Shutdown(void)
AARTSAAPI_Version(void)
AARTSAAPI_Open(AARTSAAPI_Handle * handle)
AARTSAAPI_Close(AARTSAAPI_Handle * handle)// Device Management
AARTSAAPI_RescanDevices(AARTSAAPI_Handle * handle, int timeout)
AARTSAAPI_ResetDevices(AARTSAAPI_Handle * handle)
AARTSAAPI_EnumDevice(AARTSAAPI_Handle * handle, const wchar_t * type, int32_t index, AARTSAAPI_DeviceInfo * dinfo)
AARTSAAPI_OpenDevice(AARTSAAPI_Handle * handle, AARTSAAPI_Device * dhandle, const wchar_t * type, const wchar_t * serialNumber)
AARTSAAPI_CloseDevice(AARTSAAPI_Handle * handle, AARTSAAPI_Device * dhandle)
AARTSAAPI_ConnectDevice(AARTSAAPI_Device * dhandle)
AARTSAAPI_DisconnectDevice(AARTSAAPI_Device * dhandle)
AARTSAAPI_StartDevice(AARTSAAPI_Device * dhandle)
AARTSAAPI_StopDevice(AARTSAAPI_Device * dhandle)
AARTSAAPI_GetDeviceState(AARTSAAPI_Device * dhandle)// I/O Handling
AARTSAAPI_AvailPackets(AARTSAAPI_Device * dhandle, int32_t channel, int32_t * num)
AARTSAAPI_GetPacket(AARTSAAPI_Device * dhandle, int32_t channel, int32_t index, AARTSAAPI_Packet * packet)
AARTSAAPI_ConsumePackets(AARTSAAPI_Device * dhandle, int32_t channel, int32_t num)
AARTSAAPI_GetMasterStreamTime(AARTSAAPI_Device * dhandle, double & stime)
AARTSAAPI_SendPacket(AARTSAAPI_Device * dhandle, int32_t channel, const AARTSAAPI_Packet * packet)// Configuration
AARTSAAPI_ConfigRoot(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * config)
AARTSAAPI_ConfigHealth(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * config)
AARTSAAPI_ConfigFirst(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * group, AARTSAAPI_Config * config)
AARTSAAPI_ConfigNext(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * group, AARTSAAPI_Config * config)
AARTSAAPI_ConfigFind(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * group, AARTSAAPI_Config * config, const wchar_t * name)
AARTSAAPI_ConfigGetName(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * config, wchar_t * name)
AARTSAAPI_ConfigGetInfo(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * config, AARTSAAPI_ConfigInfo * cinfo)AARTSAAPI_ConfigSetString(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * config, const wchar_t *value)
AARTSAAPI_ConfigGetString(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * config, wchar_t * value, int64_t * size)
AARTSAAPI_ConfigSetFloat(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * config, double value)
AARTSAAPI_ConfigGetFloat(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * config, double * value)
AARTSAAPI_ConfigSetInteger(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * config, int64_t value)
AARTSAAPI_ConfigGetInteger(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * config, int64_t * value)Notes:
- ConfigGetString and ConfigSetString can be used for all value types and will output or interpret the parameter as string.
- Config*Integer can be used for enum value types to get/set the index of the current value within the list of available values (obtainable by ConfigGetInfo).
- When passing a value that does not exactly match one of the listed values the behavior is undefined.
Starting with version 1.5.152.8795, the windows version of the RTSA-Suite PRO includes a DLL to directly interface with SPECTRAN V6 devices.
Inside the "sdk" folder in the installation directory you can find the header files, import library and several usage examples.
Additionally we'll provide an overview here:
- Download and install Aaronia RTSA-Suite PRO version 1.5.152.8795 or later
- Ensure the Spectran V6 is working correctly with the installed version of the Aaronia RTSA-Suite PRO.
- Additional requirements: Microsoft Visual Studio 2019 C/C++ x64 runtime and build tools
To use the RTSAAPI with Visual Studio 2019, assuming the RTSA Suite Pro is installed at C:\Program Files\Aaronia AG\Aaronia RTSA-Suite PRO, configure your project as follows:
- Ensure that the active project configuration is using a x64 target
- "C/C++" -> "General" -> "Additional Include Directories": Add "C:\Program Files\Aaronia AG\Aaronia RTSA-Suite PRO\sdk"
- "Linker" -> "General" -> "Additional Library Directories": Add "C:\Program Files\Aaronia AG\Aaronia RTSA-Suite PRO\sdk"
There are then two ways to load the library:
a) Let the linker do the job, to do so change the VS project config as follows
- "Linker" -> "Input" -> "Additional Dependencies": Add "AaroniaRTSAAPI.lib"
- "Debugging" -> "Environment": Add "PATH=C:\Program Files\Aaronia AG\Aaronia RTSA-Suite PRO;%PATH%"
b) Load the library at runtime using Win32 functions like this
HMODULE mod = ::LoadLibraryEx(L"AaroniaRTSAAPI.dll", NULL, 0);
if (!mod)
{
TCHAR pf[MAX_PATH], ld[MAX_PATH];// Find dll default installation location
::SHGetSpecialFolderPath(0, pf, CSIDL_PROGRAM_FILES, FALSE);
::StringCbPrintf(ld, sizeof(ld), L"%s\\Aaronia AG\\Aaronia RTSA-Suite PRO\\AaroniaRTSAAPI.dll", pf);// Load library from explicit location, using the dll folder as an addition to the search path for dependent dlls
mod = ::LoadLibraryEx(ld, NULL, LOAD_LIBRARY_SEARCH_DEFAULT_DIRS | LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR);if (!mod)
{
// ERROR WHILE LOADING LIBRARY
}
}
IMPORTANT: The AaroniaRTSAAPI.dll must be used from within the RTSA-Suite PRO installation directory, else your project might silently fail due to the API not finding the necessary libraries.
- In the source code, add
#include <aaroniartsaapi.h>
to declare the functions from the RTSA API
- Before using any other API function, the library must be initialized with
AARTSAAPI_Init(n);
where n is one of the AARTSAAPI_MEMORY_* values that define the amount of memory to be used by the library.
- At Application shutdown the
AARTSAAPI_Shutdown();
function should be called to release any allocated memory and close any device handles.
The library provides the following functions in aaroniartsaapi.h, please see the examples and the comments inside the header file for more details:
// Library Management
AARTSAAPI_Init(uint32t memory)
AARTSAAPI_Shutdown(void)
AARTSAAPI_Version(void)
AARTSAAPI_Open(AARTSAAPI_Handle * handle)
AARTSAAPI_Close(AARTSAAPI_Handle * handle)
// Device Management
AARTSAAPI_RescanDevices(AARTSAAPI_Handle * handle, int timeout)
AARTSAAPI_ResetDevices(AARTSAAPI_Handle * handle)
AARTSAAPI_EnumDevice(AARTSAAPI_Handle * handle, const wchar_t * type, int32_t index, AARTSAAPI_DeviceInfo * dinfo)
AARTSAAPI_OpenDevice(AARTSAAPI_Handle * handle, AARTSAAPI_Device * dhandle, const wchar_t * type, const wchar_t * serialNumber)
AARTSAAPI_CloseDevice(AARTSAAPI_Handle * handle, AARTSAAPI_Device * dhandle)
AARTSAAPI_ConnectDevice(AARTSAAPI_Device * dhandle)
AARTSAAPI_DisconnectDevice(AARTSAAPI_Device * dhandle)
AARTSAAPI_StartDevice(AARTSAAPI_Device * dhandle)
AARTSAAPI_StopDevice(AARTSAAPI_Device * dhandle)
AARTSAAPI_GetDeviceState(AARTSAAPI_Device * dhandle)
// I/O Handling
AARTSAAPI_AvailPackets(AARTSAAPI_Device * dhandle, int32_t channel, int32_t * num)
AARTSAAPI_GetPacket(AARTSAAPI_Device * dhandle, int32_t channel, int32_t index, AARTSAAPI_Packet * packet)
AARTSAAPI_ConsumePackets(AARTSAAPI_Device * dhandle, int32_t channel, int32_t num)
AARTSAAPI_GetMasterStreamTime(AARTSAAPI_Device * dhandle, double & stime)
AARTSAAPI_SendPacket(AARTSAAPI_Device * dhandle, int32_t channel, const AARTSAAPI_Packet * packet)
// Configuration
AARTSAAPI_ConfigRoot(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * config)
AARTSAAPI_ConfigHealth(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * config)
AARTSAAPI_ConfigFirst(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * group, AARTSAAPI_Config * config)
AARTSAAPI_ConfigNext(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * group, AARTSAAPI_Config * config)
AARTSAAPI_ConfigFind(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * group, AARTSAAPI_Config * config, const wchar_t * name)
AARTSAAPI_ConfigGetName(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * config, wchar_t * name)
AARTSAAPI_ConfigGetInfo(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * config, AARTSAAPI_ConfigInfo * cinfo)
AARTSAAPI_ConfigSetString(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * config, const wchar_t *value)
AARTSAAPI_ConfigGetString(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * config, wchar_t * value, int64_t * size)
AARTSAAPI_ConfigSetFloat(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * config, double value)
AARTSAAPI_ConfigGetFloat(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * config, double * value)
AARTSAAPI_ConfigSetInteger(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * config, int64_t value)
AARTSAAPI_ConfigGetInteger(AARTSAAPI_Device * dhandle, AARTSAAPI_Config * config, int64_t * value)
Notes:
- ConfigGetString and ConfigSetString can be used for all value types and will output or interpret the parameter as string.
- Config*Integer can be used for enum value types to get/set the index of the current value within the list of available values (obtainable by ConfigGetInfo).
- When passing a value that does not exactly match one of the listed values the behavior is undefined.
Quote from CorNicWest on 24/06/2022, 10:26Would it be possible to configure/distribute the DLL with the Linux installation in order to interface directly with the Spectran V6 from an Ubuntu dev environment? Could the DLL be easily built with gcc?
Would it be possible to configure/distribute the DLL with the Linux installation in order to interface directly with the Spectran V6 from an Ubuntu dev environment? Could the DLL be easily built with gcc?
Quote from mm_dev on 27/06/2022, 08:40At the moment we do not have a linux build as the library relies on some win32 functionality for locating the RTSA installation (which is needed for initialization).
At the moment we do not have a linux build as the library relies on some win32 functionality for locating the RTSA installation (which is needed for initialization).
Quote from CorNicWest on 28/06/2022, 07:08Thanks for the reply. Any ideas on if this will be implemented in the future?
Thanks for the reply. Any ideas on if this will be implemented in the future?
Quote from fw_dev on 16/11/2022, 13:19Good news regarding the Linux question: Internal testing of the native Linux API has started. I'm confident it'll be released by the end of this year!
Good news regarding the Linux question: Internal testing of the native Linux API has started. I'm confident it'll be released by the end of this year!
Quote from CorNicWest on 16/11/2022, 20:04That is good news! Thanks for the update, keep me posted
That is good news! Thanks for the update, keep me posted
Quote from fw_dev on 30/11/2022, 11:08With the upcoming RTSA Suite PRO release (Build >=12135) the .so API will be part of the Linux version. Also the API samples have been ported to CMake to get you started and are now available at: https://github.com/aaronia-open-source/RTSA-API-Samples
With the upcoming RTSA Suite PRO release (Build >=12135) the .so API will be part of the Linux version. Also the API samples have been ported to CMake to get you started and are now available at: https://github.com/aaronia-open-source/RTSA-API-Samples
Quote from Ron95 on 30/11/2023, 02:34Hi,
res = AARTSAAPI_OpenDevice(&h, &d, L"spectranv6/sweepsa", dinfo.serialNumber);
res = AARTSAAPI_ConfigFind(&d, &root, &config, L"device/receiverchannel")
spectranv6/sweepsa anddevice/receiverchannel is 2 of the examples command I get to know from the sample code.
May I know where can I get the full list of command or programming manual for spectranv6?
Thanks in advance!
Best regards,
Ron95
Hi,
res = AARTSAAPI_OpenDevice(&h, &d, L"spectranv6/sweepsa", dinfo.serialNumber);
res = AARTSAAPI_ConfigFind(&d, &root, &config, L"device/receiverchannel")
spectranv6/sweepsa anddevice/receiverchannel is 2 of the examples command I get to know from the sample code.
May I know where can I get the full list of command or programming manual for spectranv6?
Thanks in advance!
Best regards,
Ron95
Quote from mm_dev on 30/11/2023, 09:52Best to use the ConfigTree example to generate a list of all available settings. Or use the Blockgraph Explorer in the RTSA to identify the internal names of each setting (not all settings are available in the SDK though).
Best to use the ConfigTree example to generate a list of all available settings. Or use the Blockgraph Explorer in the RTSA to identify the internal names of each setting (not all settings are available in the SDK though).