stingrayparser_web_logo

StingrayParser C++ library

v2.0.5

Table of contents

Overview

The StingrayParser C++ library is designed to control Stingray SWIR lenses. The library includes basic methods for preparing commands (encoding) and interpreting lens responses (decoding). It uses the C++17 standard and is compatible with Windows and Linux on CPU. The library provides a simple interface and doesn’t have third-party dependencies. Additionally, the library provides a test application to test communication with lenses via serial ports. The test application depends on the open-source SerialPort library (provides functions to work with serial ports, source code included, Apache 2.0 license).

Versions

Table 1 - Library versions.

Version Release date What’s new
1.0.0 20.06.2023 First version.
2.0.0 29.12.2023 - StingrayParser class interface updated.
- Test application updated.
2.0.1 29.04.2024 - Documentation updated.
2.0.2 23.05.2024 - Documentation updated.
2.0.3 31.07.2024 - CMake structure updated.
2.0.4 26.10.2025 - SerialPort submodule update for test application.
2.0.5 07.11.2025 - Fix command encode mistakes.
- test application updated.

Library files

The library is supplied as source code only. The user will be provided with a set of files in the form of a CMake project (repository). The repository structure is shown below:

CMakeLists.txt ------------------ Main CMake file of the library.
src ----------------------------- Folder with library source code.
    CMakeLists.txt -------------- CMake file of the library.
    StingrayParser.h ------------ Main library header file.
    StingrayParser.cpp ---------- C++ implementation file.
    StingrayParserVersion.h ----- Header file with library version.
    StingrayParserVersion.h.in -- File for CMake to generate version header.
test ---------------------------- Folder for test application.
    3rdparty -------------------- Folder with third-party libraries.
        CMakeLists.txt ---------- CMake file to include third-party libraries.
        SerialPort -------------- Folder with SerialPort library source code.
    CMakeLists.txt -------------- CMake file for test application.
    main.cpp -------------------- Source C++ file of test application.

StingrayParser class description

StingrayParser class declaration

The StingrayParser.h file contains the StingrayParser class declaration.

class StingrayParser
{
public:

    /// Get library version.
    static std::string getVersion();

    /// Method to encode Stingray lens command.
    bool getCommand(uint8_t* data, int& size, StingrayCommand id, int arg = 0);

    /// Process response for STATUS command.
    void decodeResponse(uint8_t* data, int size, int &zoom, int &focus);
};

getVersion method

The getVersion() method returns the version string of the current StingrayParser class. Method declaration:

static std::string getVersion();

This method can be used without a StingrayParser class instance. Example:

std::cout << "StingrayParser version: " << StingrayParser::getVersion();

Console output:

StingrayParser version: 2.0.5

getCommand method

The getCommand(…) method encodes (prepares data for) control commands for the lens. The lens does not send data on its own, but only responds to requests. Method declaration:

bool getCommand(uint8_t* data, int& size, StingrayCommand id, int arg = 0);
Parameter Description
data Pointer to buffer for encoded data.
size Encoded command size.
id Command ID from StingrayCommand enum
arg Command argument. The value of argument depends on command ID (see StingrayCommand enum). Some commands don’t have arguments.

Returns: TRUE if the command is prepared or FALSE if not.

Below is an example of a zoom tele command and an example of a focus to absolute position command.

// Init variables.
uint8_t buffer[256];
uint8_t size;

// Prepare zoom tele command.
StingrayParser parser;
parser.getCommand(buffer, size, StingrayCommand::ZOOM_TELE);

// Send command.
serialPort.write(buffer, size);

// Prepare focus to abs pos command.
parser.getCommand(buffer, size, StingrayCommand::FOCUS_TO_ABS_POS, 5000);

// Send command.
serialPort.write(buffer, size);

decodeResponse method

The decodeResponse(…) method processes responses and provides zoom or focus position if available. In the current version of the library, only zoom and focus position response decoding is implemented. Method declaration:

void decodeResponse(uint8_t* data, int size, int &zoom, int &focus);
Parameter Description
data Pointer to data.
size Data size.
zoom Returned zoom position value or -1 if no zoom position in response.
focus Returned focus position value or -1 if no focus position in response.

To retrieve the zoom position, focus position, or both, you must initially send REQUEST_ZOOM_POS, REQUEST_FOCUS_POS, or REQUEST_STATUS respectively. The data buffer received in response should be passed to the decodeResponse function. This function updates the zoom variable with the new zoom value, or sets it to -1 if the received buffer does not contain zoom data. The same process applies to the focus variable.

Please note that the buffer might contain only a portion of the response or multiple responses. In the case of partial data, decodeResponse will update the zoom or focus variables upon its next call, which should contain the end of the response.

Below is an example of sending a REQUEST_STATUS request and getting zoom and focus position:

uint8_t buffer[256];
int size = 0;
StingrayParser parser;

while (true)
{
    // Prepare request.
    parser.getCommand(buffer, size, StingrayCommand::REQUEST_STATUS);
    
    // Send request.
    serialPort.write(buffer, size);
    
    // Wait some time. Recommended 40 msec.
    
    // Read response from serial port. You can wait 40 msec.
    int bytes = serialPort.read(buffer, 256);
    
    // Decode response.
    int zoomPos = 0;
    int focusPos = 0;
    parser.decodeResponse(buffer, bytes, zoomPos, focusPos);
        
    // Check if zoom updated  
    if (zoomPos != -1) {
        // zoomPos contains updated value of zoom
    }
        
    // Check if focus updated  
    if (focusPos != -1) {
        // focusPos contains updated value of focus
    } 
}

StingrayCommand enum 

enum class StingrayCommand
{
    /// Focus to absolute position. Argument: focus position 0 - 10000.
    FOCUS_TO_ABS_POS = 1,
    /// Focus to relative position. Argument: focus increment +-(0 - 10000).
    FOCUS_TO_RELATIVE_POS,
    /// Move focus far. Argument: focus speed 0 - 255.
    FOCUS_FAR,
    /// Move focus near. Argument: focus speed 0 - 255.
    FOCUS_NEAR,
    /// Focus stop. No arguments.
    FOCUS_STOP,
    /// Request focus position. No arguments.
    REQUEST_FOCUS_POS,
    /// Store current focus position for next system boot/reset. No arguments.
    STORE_FOCUS_POS,
    /// Zoom to absolute position. Argument: zoom position 0 - 10000.
    ZOOM_TO_ABS_POS,
    /// Zoom to relative position. Argument: zoom increment +-(0 - 10000).
    ZOOM_TO_RELATIVE_POS,
    /// Move zoom wide. Argument: zoom speed 0 - 255.
    ZOOM_WIDE,
    /// Move zoom tele. Argument: zoom speed 0 - 255.
    ZOOM_TELE,
    /// Zoom stop. No arguments.
    ZOOM_STOP,
    /// Request zoom position. No arguments.
    REQUEST_ZOOM_POS,
    /// Store current zoom position for next system boot/reset. No arguments.
    STORE_ZOOM_POS,
    /// Request status. No arguments.
    REQUEST_STATUS,
    /// Request system information. No arguments.
    REQUEST_SYSTEM_INFO,
    /// Change verbose level. Arguments: 0, 1 or 2.
    CHANGE_VERBOSE_LEVEL,
    /// Reset. No arguments.
    RESET,
    /// Stop zoom and focus motion. No arguments.
    STOP,
    /// Query zoom/focus motors tolerance. No arguments.
    REQUEST_TOLERANCE,
    /// Command Acknowledgement Toggle. Argument: 0 or 1.
    SET_ACK_RESPONSE
};

Table 2 - StingrayCommand enum class description.

Parameter Description Argument
FOCUS_TO_ABS_POS Move focus to absolute position Focus position: 0 - 10000
FOCUS_TO_RELATIVE_POS Move focus to relative position Focus increment: -10000 - +10000
FOCUS_FAR Move focus far Focus speed: 0 - 255
FOCUS_NEAR Move focus near Focus speed: 0 - 255
FOCUS_STOP Stop focus movement No arguments
REQUEST_FOCUS_POS Request focus position No arguments
STORE_FOCUS_POS Store current focus position for next system boot/reset No arguments
ZOOM_TO_ABS_POS Move zoom to absolute position Zoom position: 0 - 10000
ZOOM_TO_RELATIVE_POS Move zoom to relative position Zoom increment: -10000 - +10000
ZOOM_WIDE Move zoom wide Zoom speed: 0 - 255
ZOOM_TELE Move zoom tele Zoom speed: 0 - 255
ZOOM_STOP Stop zoom movement No arguments
REQUEST_ZOOM_POS Request zoom position No arguments
STORE_ZOOM_POS Store current zoom position for next system boot/reset No arguments
REQUEST_STATUS Request status. Current zoom and focus position will be returned. No arguments
REQUEST_SYSTEM_INFO Request system information No arguments
CHANGE_VERBOSE_LEVEL Change verbose level Arguments: 0, 1 or 2
0 - Default. Simple output for computer use
1 - Focus will report step count when reaching destination instead of NOERROR, otherwise same as 0.
2 - Provide error codes in plain English
RESET Reset. No arguments
STOP Stop zoom and focus motion No arguments
REQUEST_TOLERANCE Query zoom & focus motors tolerance No arguments
SET_ACK_RESPONSE Acknowledgement Toggle. When this command is on most commands that don’t normally have a response i.e. ‘F=XXXX’ will now respond with ‘COMMAND=ACK’ to signal the lens driver successfully received the command. Argument: 0 or 1
0 - off
1 - on

Build and connect to your project

Typical commands to build the StingrayParser library:

cd StingrayParser
mkdir build
cd build
cmake ..
make

If you want to connect StingrayParser library to your CMake project as source code, you can do the following. For example, if your repository has structure:

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp

Create a 3rdparty folder and copy the StingrayParser repository folder there. The new structure of your repository will be as follows:

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp
3rdparty
    StingrayParser

Create a CMakeLists.txt file in the 3rdparty folder. The CMakeLists.txt should contain:

cmake_minimum_required(VERSION 3.13)

################################################################################
## 3RD-PARTY
## dependencies for the project
################################################################################
project(3rdparty LANGUAGES CXX)

################################################################################
## SETTINGS
## basic 3rd-party settings before use
################################################################################
# To inherit the top-level architecture when the project is used as a submodule.
SET(PARENT ${PARENT}_YOUR_PROJECT_3RDPARTY)
# Disable self-overwriting of parameters inside included subdirectories.
SET(${PARENT}_SUBMODULE_CACHE_OVERWRITE OFF CACHE BOOL "" FORCE)

################################################################################
## INCLUDING SUBDIRECTORIES
## Adding subdirectories according to the 3rd-party configuration
################################################################################
add_subdirectory(StingrayParser)

The 3rdparty/CMakeLists.txt file adds the StingrayParser folder to your project and excludes test applications and examples from compilation (by default, the test application is excluded from compilation when StingrayParser is included as a sub-repository). The new structure of your repository:

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp
3rdparty
    CMakeLists.txt
    StingrayParser

Next, you need to include the ‘3rdparty’ folder in the main CMakeLists.txt file of your repository. Add the following string at the end of your main CMakeLists.txt:

add_subdirectory(3rdparty)

Next, you have to include StingrayParser library in your src/CMakeLists.txt file:

target_link_libraries(${PROJECT_NAME} StingrayParser)

Done!

Test application

The StingrayParser/test folder contains the test application files. The test application allows you to generate any command, send it to the lens over a serial port, receive and decode the response. Once started, the user must enter the serial port name (full name for Linux or just the port number for Windows):

===========================================
StingrayParser test v2.0.5
===========================================

Set COM port num (1,2,3,...): 2
Serial port open!

After that, the user can choose a command (enter command ID):

===========================================

1 - FOCUS_TO_ABS_POS
2 - FOCUS_TO_RELATIVE_POS
3 - FOCUS_FAR
4 - FOCUS_NEAR
5 - FOCUS_STOP
6 - REQUEST_FOCUS_POS
7 - STORE_FOCUS_POS
8 - ZOOM_TO_ABS_POS
9 - ZOOM_TO_RELATIVE_POS
10 - ZOOM_WIDE
11 - ZOOM_TELE
12 - ZOOM_STOP
13 - REQUEST_ZOOM_POS
14 - STORE_ZOOM_POS
15 - REQUEST_STATUS
16 - REQUEST_SYSTEM_INFO
17 - CHANGE_VERBOSE_LEVEL
18 - RESET
19 - STOP
20 - REQUEST_TOLERANCE
21 - SET_ACK_RESPONSE
==========================================

Choose command:

Then, the corresponding command will be generated and sent to the lens.

Table of contents