KowaLensParser C++ library

v2.0.1

Table of contents

• Overview
• Versions
• Library files
• KowaLensParser class description
  • KowaLensParser class declaration
  • getVersion method
  • getCommand method
  • decodeResponse method
• Data structures
  • KowaLensCommand enum
  • KowaLensResponse enum
• Test application
• Build and connect to your project

Overview

The KowaLensParser is a C++ library for encoding control commands and checking responses for KOWA CCTV lenses. The library supports commands encoding and decoding response for KOWA lens models: LMZ1000AMPDC-XF, LMZ20750AMPDC-XF, LMZ20550AMPDC-XF, LMZ1236AMPDC-XF, LMZ0824AMPDC-XF, LMZ7527AMPDC-XF, LMZ2200AMPDC-XF, LMZ25300AMPDC-IR, LMZ16160AMPDC-IR, LMZ11176AMPDC-IR, LMZ1177AMPDC-IR, LMZ10360AMPDC-IR, LMZ14500AMPDC-IR, LMZ0812AMPDC-IR, LMZ300AMPDC. The library doesn’t have third party dependencies. Only test application depends on open source SerialPort library (provides methods 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	22.05.2022	- First version.
2.0.0	18.09.2024	- Interface changed. - Test application updated. - Documentation added.
2.0.1	27.09.2024	- KowaLensParser updated.

Library files

The library supplied by source code only. The user would be given a set of files in the form of a CMake project (repository). The repository structure is shown below:

CMakeLists.txt ------------------ Main CMake file.
src ----------------------------- Folder with library source code.
    CMakeLists.txt -------------- CMake file of the library.
    KowaLensParser.h ------------ Main library header file.
    KowaLensParser.cpp ---------- C++ implementation file.
    KowaLensParserVersion.h ----- Header file with library version.
    KowaLensParserVersion.h.in -- CMake service file to generate version header.
test ---------------------------- Folder with test application files.
    SerialPort ------------------ Folder with SerialPort library source code.
    CMakeLists.txt -------------- CMake file for test application.
    main.cpp -------------------- Source C++ file of test application.

KowaLensParser class description

KowaLensParser class declaration

KowaLensParser.h contains main class KowaLensParser declaration. Class declaration:

namespace cr
{
namespace kowa
{
/// KOWA lens protocol parser.
class KowaLensParser
{
public:

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

    /// Encode command.
    bool getCommand(uint8_t* command, KowaLensCommand id, uint16_t param1 = 0, uint16_t param2 = 0);

    /// Decode input data byte-by-byte.
    KowaLensResponse decodeResponse(uint8_t nextByte, uint16_t& value);
};
}
}

getVersion method

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

static std::string getVersion();

Method can be used without KowaLensParser class instance:

std::cout << "KowaLensParser v: " << KowaLensParser::getVersion();

Console output:

KowaLensParser v: 2.0.1

getCommand method

getCommand(…) method encodes KOWA lens command (preparing data). The KOWA lens control protocol based on PelcoD protocol which is support camera address. The library assign default address 1 to each command. Method declaration:

bool getCommand(uint8_t* command, KowaLensCommand id, uint16_t param1 = 0, uint16_t param2 = 0);

Parameter	Value
command	Pointer to the command buffer to be filled by the method. Size of command always 7 bytes. The size of the buffer must be at least 7 bytes.
id	Command ID according to KowaLensCommand enum.
param1	Parameter 1. The value of each parameter depends on the id (see KowaLensCommand enum).
param2	Parameter 2. The value of each parameter depends on the id (see KowaLensCommand enum).

Returns: TRUE if the command encoded or FALSE if not.

Below is an example of encoding command.

// Encoding
uint8_t packet[7];
parser.getCommand(data, KowaLensCommand::SET_ZOOM_POSITION, 1000);

// Sending to serial port.
serialPort.write(packet, 7);

decodeResponse method

decodeResponse(…) method decodes replies from lens. The library doesn’t decode ACK response. The data must be processed it byte by byte: user must call decodeResponse(…) method for each input bytes received from lens. Method declaration:

KowaLensResponse decodeResponse(uint8_t nextByte, uint16_t& value);

Parameter	Value
nextByte	Next byte in data to decode.
value	Output values depends on response according to KowaLensResponse enum

Returns: ID of response according to KowaLensResponse enum. If the method decoded a valid response, it returns the response ID. If no valid response is decoded, the method returns the ID KowaLensResponse::NONE.

Below is an example of decoding cameras response.

// Read data from serial port.
int bytes = serialPort.read(data, bufferSize);

// Check number of bytes.
if (bytes <= 0)
{
    cout << "No response!" << endl;
    continue;
}
// Decode data.
bool decodedResponse = false;
for (int i = 0; i < bytes; ++i)
{
    // Decode data.
    uint16_t value = 0;
    switch (parser.decodeResponse(data[i], value))
    {
    case KowaLensResponse::ACK:
    {
        cout << "ACK" << endl;
        decodedResponse = true;
        break;
    }
    case KowaLensResponse::FOCUS_POSITION:
    {
        cout << "FOCUS_POSITION : " << value << endl;
        decodedResponse = true;
        break;
    }
    case KowaLensResponse::ZOOM_POSITION:
    {
        cout << "ZOOM_POSITION : " << value << endl;
        decodedResponse = true;
        break;
    }
    case KowaLensResponse::IRIS_POSITION:
    {
        cout << "IRIS_POSITION : " << value << endl;
        decodedResponse = true;
        break;
    }
    case KowaLensResponse::FOCUS_SPEED:
    {
        cout << "FOCUS_SPEED : " << value << endl;
        decodedResponse = true;
        break;
    }
    case KowaLensResponse::ZOOM_SPEED:
    {
        cout << "ZOOM_SPEED : " << value << endl;
        decodedResponse = true;
        break;
    }
    case KowaLensResponse::IRIS_SPEED:
    {
        cout << "IRIS_SPEED : " << value << endl;
        decodedResponse = true;
        break;
    }
    case KowaLensResponse::OSD_SETTING_VALUE:
    {
        cout << "OSD_SETTING_VALUE : " << value << endl;
        decodedResponse = true;
        break;
    }
    default:
    {
        break;
    }
    }
}

Data structures

KowaLensParser.h file includes declaration of KowaLensCommand enum and KowaLensResponse enum.

KowaLensCommand enum

KowaLensCommand enum declared in KowaLensParser.h file. Enum represents all commands supported by KOWA lenses. Enum declaration:

namespace cr
{
namespace kowa
{
enum class KowaLensCommand
{
    /// Moving focus to NEAR side. The motor stops by the STOP command. No params.
    FOCUS_NEAR = 1,
    /// Moving focus to FAR side. The motor stops by the STOP command. No params.
    FOCUS_FAR,
    /// Moving zoom to WIDE side. The motor stops by the STOP command. No params.
    ZOOM_WIDE,
    /// Moving zoom to TELE side. The motor stops by the STOP command. No params.
    ZOOM_TELE,
    /// Moving iris to OPEN side. The motor stops by the STOP command. No params.
    IRIS_OPEN,
    /// Moving iris to CLOSE side. The motor stops by th e STOP command. No params.
    IRIS_CLOSE,
    /// Stop all motors (focus, zoom and iris). No params.
    STOP,
    /// Executing auto focus one time. No params.
    EXECUTE_AF,
    /// Set focus motor position (lens will start focus movement). Params: param1 (0x0000～0xFFFF) focus position.
    SET_FOCUS_POSITION,
    /// Set zoom motor position (lens will start zoom movement). Params: param1 (0x0000～0xFFFF) zoom position.
    SET_ZOOM_POSITION,
    /// Set iris motor position (lens will start iris movement). Params: param1 (0x0000～0xFFFF) iris position.
    SET_IRIS_POSITION,
    /// Inquiring the focus motor position. No params.
    INQUIRY_FOCUS_POSITION,
    /// Inquiring the zoom motor position. No params.
    INQUIRY_ZOOM_POSITION,
    /// Inquiring the iris motor position. No params.
    INQUIRY_IRIS_POSITION,
    /// Set the focus motor speed for one of 4 speed slots. Params:
    /// param1 - speed slot: 0 - slowest speed, 1 - low medium speed, 2 - high medium speed, 3 - fastest speed.
    /// param2 - speed value: 0x00 - 0xFF. Speed values will be stored in the lens memory.
    SET_CONTINUOUSLY_FOCUS_SPEED,
    /// Set the zoom motor speed for one of 4 speed slots. Params:
    /// param1 - speed slot: 0 - slowest speed, 1 - low medium speed, 2 - high medium speed, 3 - fastest speed.
    /// param2 - speed value: 0x00 - 0xFF. Speed values will be stored in the lens memory.
    SET_CONTINUOUSLY_ZOOM_SPEED,
    /// Set the iris motor speed for one of 4 speed slots. Params:
    /// param1 - speed slot: 0 - slowest speed, 1 - low medium speed, 2 - high medium speed, 3 - fastest speed.
    /// param2 - speed value: 0x00 - 0xFF. Speed values will be stored in the lens memory.
    SET_CONTINUOUSLY_IRIS_SPEED,
    /// Chose focus speed slot. Speed set by the SET_CONTINUOUSLY_FOCUS_SPEED command. Params: 
    /// param1 - speed slot: 0 - slowest speed, 1 - low medium speed, 2 - high medium speed, 3 - fastest speed.
    SET_FOCUS_SPEED,
    /// Chose zoom speed slot. Speed set by the SET_CONTINUOUSLY_ZOOM_SPEED command. Params: 
    /// param1 - speed slot: 0 - slowest speed, 1 - low medium speed, 2 - high medium speed, 3 - fastest speed.
    SET_ZOOM_SPEED,
    /// Chose iris speed slot. Speed set by the SET_CONTINUOUSLY_IRIS_SPEED command. Params: 
    /// param1 - speed slot: 0 - slowest speed, 1 - low medium speed, 2 - high medium speed, 3 - fastest speed.
    SET_IRIS_SPEED,
    /// Inquiring the focus motor speed from speed slot. Params:
    /// param1 - speed slot: 0 - slowest speed, 1 - low medium speed, 2 - high medium speed, 3 - fastest speed.
    INQUIRY_FOCUS_SPEED,
    /// Inquiring the zoom motor speed from speed slot. Params:
    /// param1 - speed slot: 0 - slowest speed, 1 - low medium speed, 2 - high medium speed, 3 - fastest speed.
    INQUIRY_ZOOM_SPEED,
    /// Inquiring the iris motor speed from speed slot. Params:
    /// param1 - speed slot: 0 - slowest speed, 1 - low medium speed, 2 - high medium speed, 3 - fastest speed.
    INQUIRY_IRIS_SPEED,
    /// Store the current position into the memory. Params:
    /// param1 - (01h-7Fh) The lens has 127 zoom and focus and iris position memories. The lens can storage
    /// the current zoom and focus and iris positions into the memory.
    SET_PRESET,
    /// Change the current position to the stored preset position. Params:
    /// param1 - (01h-7Fh) The  zoom  and  focus  and  iris  preset  positions  is  called  from  the
    /// preset memory, and the zoom and focus and iris positions are changed as the preset positions.
    CALL_PRESET,
    /// Clear the stored preset position. Params:
    /// param1 - (01h-7Fh) The preset position stored in the memory is cleared.
    CLEAR_PRESET,
    /// Set AF search limit range. Params:
    /// param1: 0 - Both A and B position are cleared.
    ///         1 - The current focus position is stored as the A position.
    ///         2 - The current focus position is stored as the B position.
    SET_AF_SEARCH_LIMIT_POSITION,
    /// Set the OSD setting value. Params two variants:
    /// 1:
    /// param1 - OSD ADDRESS－01h.
    /// param2 - OSD DATA MSB.
    /// 2:
    /// param1 - OSD ADDRESS.
    /// param2 - OSD DATA LSB.
    SET_OSD_SETTING_VALUE,
    /// Inquiring the OSD setting value. Params:
    /// param1 - OSD ADDRESS.
    INQUIRY_OSD_SETTING_VALUE
};
}
}

Table 2 - KowaLensCommand enum values description.

Command ID	Description
FOCUS_NEAR	Moving focus to NEAR side. The motor stops by the STOP command. No params.
FOCUS_FAR	Moving focus to FAR side. The motor stops by the STOP command. No params.
ZOOM_WIDE	Moving zoom to WIDE side. The motor stops by the STOP command. No params.
ZOOM_TELE	Moving zoom to TELE side. The motor stops by the STOP command. No params.
IRIS_OPEN	Moving iris to OPEN side. The motor stops by the STOP command. No params.
IRIS_CLOSE	Moving iris to CLOSE side. The motor stops by th e STOP command. No params.
STOP	Stop all motors. No params.
EXECUTE_AF	Executing auto focus one time. No params.
SET_FOCUS_POSITION	Set focus motor position (lens will start focus movement). Params: param1 (0x0000～0xFFFF) focus position.
SET_ZOOM_POSITION	Set zoom motor position (lens will start zoom movement). Params: param1 (0x0000～0xFFFF) zoom position.
SET_IRIS_POSITION	Set iris motor position (lens will start iris movement). Params: param1 (0x0000～0xFFFF) iris position.
INQUIRY_FOCUS_POSITION	Inquiring the focus motor position. No params.
INQUIRY_ZOOM_POSITION	Inquiring the zoom motor position. No params.
INQUIRY_IRIS_POSITION	Inquiring the iris motor position. No params.
SET_CONTINUOUSLY_FOCUS_SPEED	Set the zoom motor speed for one of 4 speed slots. Params: param1 - speed slot: 0 - slowest speed, 1 - low medium speed, 2 - high medium speed, 3 - fastest speed. param2 - speed value: 0x00 - 0xFF. Speed values will be stored in the lens memory.
SET_CONTINUOUSLY_ZOOM_SPEED	Set the focus motor speed for one of 4 speed slots. Params: param1 - speed slot: 0 - slowest speed, 1 - low medium speed, 2 - high medium speed, 3 - fastest speed. param2 - speed value: 0x00 - 0xFF. Speed values will be stored in the lens memory.
SET_CONTINUOUSLY_IRIS_SPEED	Set the iris motor speed for one of 4 speed slots. Params: param1 - speed slot: 0 - slowest speed, 1 - low medium speed, 2 - high medium speed, 3 - fastest speed. param2 - speed value: 0x00 - 0xFF. Speed values will be stored in the lens memory.
SET_FOCUS_SPEED	Chose focus speed slot. Speed set by the SET_CONTINUOUSLY_FOCUS_SPEED command. Params: param1 - speed slot: 0 - slowest speed, 1 - low medium speed, 2 - high medium speed, 3 - fastest speed.
SET_ZOOM_SPEED	Chose zoom speed slot. Speed set by the SET_CONTINUOUSLY_ZOOM_SPEED command. Params: param1 - speed slot: 0 - slowest speed, 1 - low medium speed, 2 - high medium speed, 3 - fastest speed.
SET_IRIS_SPEED	Chose iris speed slot. Speed set by the SET_CONTINUOUSLY_IRIS_SPEED command. Params: param1 - speed slot: 0 - slowest speed, 1 - low medium speed, 2 - high medium speed, 3 - fastest speed.
INQUIRY_FOCUS_SPEED	Inquiring the focus motor speed from speed slot. Params: param1 - speed slot: 0 - slowest speed, 1 - low medium speed, 2 - high medium speed, 3 - fastest speed.
INQUIRY_ZOOM_SPEED	Inquiring the zoom motor speed from speed slot. Params: param1 - speed slot: 0 - slowest speed, 1 - low medium speed, 2 - high medium speed, 3 - fastest speed.
INQUIRY_IRIS_SPEED	Inquiring the iris motor speed from speed slot. Params: param1 - speed slot: 0 - slowest speed, 1 - low medium speed, 2 - high medium speed, 3 - fastest speed.
SET_PRESET	Store the current position into the memory. Params: param1 - (01h-7Fh) The lens has 127 zoom and focus and iris position memories. The lens can storage the current zoom and focus and iris positions into the memory.
CALL_PRESET	Change the current position to the stored preset position. Params: param1 - (01h-7Fh) The zoom and focus and iris preset positions is called from the preset memory, and the zoom and focus and iris positions are changed as the preset positions.
CLEAR_PRESET	Clear the stored preset position. Params: param1 - (01h-7Fh) The preset position stored in the memory is cleared.
SET_AF_SEARCH_LIMIT_POSITION	Set AF search limit range. Params: param1: 0 - Both A and B position are cleared. 1 - The current focus position is stored as the A position. 2 - The current focus position is stored as the B position.
SET_OSD_SETTING_VALUE	Set the OSD setting value. Params two variants: 1: param1 - OSD ADDRESS－01h. param2 - OSD DATA MSB. 2: param1 - OSD ADDRESS. param2 - OSD DATA LSB.
INQUIRY_OSD_SETTING_VALUE	Inquiring the OSD setting value. Params: param1 - OSD ADDRESS.

KowaLensResponse enum

KowaLensResponse enum declared in KowaLensParser.h file. Enum represents all responses supported by KOWA lenses. Enum declaration:

namespace cr
{
namespace kowa
{
enum class KowaLensResponse
{
    /// Focus position. Params: value - focus position 0-0xFFFF.
    FOCUS_POSITION = 1,
    /// Zoom position. Params: value - focus position 0-0xFFFF.
    ZOOM_POSITION,
    /// Iris position. Params: value - focus position 0-0xFFFF.
    IRIS_POSITION,
    /// Focus motor speed. Params: value - focus speed 0-0xFF.
    FOCUS_SPEED,
    /// Zoom motor speed. Params: value - zoom speed 0-0xFF.
    ZOOM_SPEED,
    /// Iris motor speed. Params: value - iris speed 0-0xFF.
    IRIS_SPEED,
    /// OSD value from certain address. Params: value - preset value 0-0xFFFF.
    OSD_SETTING_VALUE,
    /// Input packet not detected.
    NONE
};
}
}

Table 3 - KowaLensResponse enum values description.

ID	Description
FOCUS_POSITION	Focus position. Params: value - focus position 0-0xFFFF.
ZOOM_POSITION	Zoom position. Params: value - focus position 0-0xFFFF.
IRIS_POSITION	Iris position. Params: value - focus position 0-0xFFFF.
FOCUS_SPEED	Focus motor speed. Params: value - focus speed 0-0xFF.
ZOOM_SPEED	Zoom motor speed. Params: value - zoom speed 0-0xFF.
IRIS_SPEED	Iris motor speed. Params: value - iris speed 0-0xFF.
OSD_SETTING_VALUE	OSD value from certain address. Params: value - preset value 0-0xFFFF.
NONE	Input packet not detected.

Build and connect to your project

Typical commands to build KowaLensParser library:

cd KowaLensParser
mkdir build
cd build
cmake ..
make

If you want connect KowaLensParser library to your CMake project as source code you can make follow. For example, if your repository has structure:

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

Create folder 3rdparty and copy folder of KowaLensParser repository there. New structure of your repository:

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

Create CMakeLists.txt file in 3rdparty folder. 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)

################################################################################
## CONFIGURATION
## 3rd-party submodules configuration
################################################################################
SET(${PARENT}_KOWA_LENS_PARSER                          ON  CACHE BOOL "" FORCE)
if (${PARENT}_KOWA_LENS_PARSER)
    SET(${PARENT}_KOWA_LENS_PARSER_TEST                 OFF CACHE BOOL "" FORCE)
endif()

################################################################################
## INCLUDING SUBDIRECTORIES
## Adding subdirectories according to the 3rd-party configuration
################################################################################
if (${PARENT}_KOWA_LENS_PARSER)
    add_subdirectory(KowaLensParser)
endif()

File 3rdparty/CMakeLists.txt adds folder KowaLensParser to your project and excludes test application (by default test applications and example are excluded from compiling if KowaLensParser is included as sub-repository). The new structure of your repository:

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

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

add_subdirectory(3rdparty)

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

target_link_libraries(${PROJECT_NAME} KowaLensParser)

Done!

Test application

Folder KowaLensParser/test contains the test application files. The test application allows you to generate some commands, send it to the lens over the 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), baudrate and camera address.

================================================
KowaLensParser v2.0.1 test
================================================

Enter serial port name: 
Enter serial port baudrate (default 9600): 9600
Enter camera address (default 1): 1 
Serial port /dev/serial/by-id/usb-FTDI_TTL232R_Kowa-if00-port0 open.

After user can choose command (enter command ID). Test application supports the following commands:

"================================================"
"Type of command:"
"0  - FOCUS_NEAR"
"1  - FOCUS_FAR"
"2  - ZOOM_WIDE"
"3  - ZOOM_TELE"
"4  - IRIS_OPEN"
"5  - IRIS_CLOSE"
"6  - STOP"
"7  - EXECUTE_AF"
"8  - SET_FOCUS_POSITION"
"9  - SET_ZOOM_POSITION"
"10 - SET_IRIS_POSITION"
"11 - INQUIRY_FOCUS_POSITION"
"12 - INQUIRY_ZOOM_POSITION"
"13 - INQUIRY_IRIS_POSITION"
"14 - SET_CONTINUOUSLY_FOCUS_SPEED (set speed to slot)"
"15 - SET_CONTINUOUSLY_ZOOM_SPEED (set speed to slot)"
"16 - SET_CONTINUOUSLY_IRIS_SPEED (set speed to slot)"
"17 - SET_FOCUS_SPEED (chose speed slot)"
"18 - SET_ZOOM_SPEED (chose speed slot)"
"19 - SET_IRIS_SPEED (chose speed slot)"
"20 - INQUIRY_FOCUS_SPEED"
"21 - INQUIRY_ZOOM_SPEED"
"22 - INQUIRY_IRIS_SPEED"
"23 - SET_PRESET"
"24 - CALL_PRESET"
"25 - CLEAR_PRESET"
"26 - SET_AF_SEARCH_LIMIT_POSITION"
"Command type: "