KowaProtocolParser C++ library
v1.0.3
Table of contents
- Overview
- Versions
- Library files
- KowaProtocolParser class description
- Data structures
- Build and connect to your project
- Simple example
- Test application
Overview
KowaProtocolParser is a C++ library to encode (prepare) control commands for low-light KOWA camera. The library includes method for preparing commands (encoding). It uses C++17 standard and compatible with any Windows and Linux. The library provides simple interface and doesn’t have third party dependencies to be installed in OS. Also, the library provides test application to control camera via serial port. Test application depends on open source SerialPort (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 | 07.03.2024 | - First version. |
| 1.0.1 | 25.04.2024 | - Code reviewed. - Documentation updated. |
| 1.0.2 | 25.04.2024 | - Documentation updated. |
| 1.0.3 | 31.07.2024 | - CMake structure updated. |
Library files
The library supplied as 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 of the library.
src --------------------------------- Folder with library source code.
CMakeLists.txt ------------------ CMake file of the library.
KowaProtocolParser.h ------------ Main library header file.
KowaProtocolParser.cpp ---------- C++ implementation file.
KowaProtocolParserVersion.h ----- Header file with library version.
KowaProtocolParserVersion.h.in -- File for CMake to generate version header.
test -------------------------------- Folder for test application files.
3rdaprty ------------------------ Folder with third-party libraries.
CMakeLists.txt -------------- CMake file for 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.
KowaProtocolParser class description
Class declaration
KowaProtocolParser.h file contains KowaProtocolParser class declaration.
class KowaProtocolParser
{
public:
/// Get library version.
static std::string getVersion();
/// Method to encode Kowa camera command.
bool getCommand(uint8_t* data,
int& size,
KowaSC200PK1CCommand id,
int cameraId = 0x31,
int arg1 = 0,
int arg2 = 0);
}
getVersion method
The getVersion() method returns string of current version of KowaProtocolParser class. Method declaration:
static std::string getVersion();
Method can be used without KowaProtocolParser class instance. Example:
std::cout << "KowaProtocolParser version: " << KowaProtocolParser::getVersion();
Console output:
KowaProtocolParser version: 1.0.3
getCommand method
The getCommand(…) method encodes (prepares data) control command for camera. Method declaration:
bool getCommand(uint8_t* data, int& size, KowaSC200PK1CCommand id,
int cameraId = 0x31, int arg1 = 0, int arg2 = 0);
| Parameter | Description |
|---|---|
| data | Pointer to buffer for encoded data. |
| size | Size of encoded command. |
| id | Command ID according to KowaSC200PK1CCommand enum. |
| cameraId | Camera ID. Default 0x31. |
| arg1 | First command argument. The value of argument depends on command ID (KowaSC200PK1CCommand enum). Some commands don’t have arguments. |
| arg2 | Second command argument. The value of argument depends on command ID (KowaSC200PK1CCommand enum). Some commands don’t have arguments. |
Returns: TRUE if command is prepared or FALSE if not.
Data structures
KowaSC200PK1CCommand enum
enum class KowaSC200PK1CCommand
{
/// Display mode. Command arguments:
/// arg1: 0 - OFF.
/// 1 - ON.
DISPLAY_MODE = 1,
/// Position. Command arguments:
/// arg1 - horizontal 0(left) to 255(right).
/// arg2 - vertical 0(top) to 255(bottom).
POSITION,
/// ALC mode. Command arguments:
/// arg1: 0 - OFF.
/// 1 - S/N.
/// 2 - STD.
/// 3 - MOVE.
/// 4 - MANUAL.
ALC_MODE,
/// Long shutter mode. Command arguments:
/// arg1: 0 - x1.
/// 1 - x2.
/// 2 - x4.
/// 3 - x8.
/// 4 - x16.
LONG_SHUTTER_MODE,
/// Fast shutter mode. Command arguments:
/// arg1: 0 - OFF.
/// 1 - 1/125.
/// 2 - 1/250.
/// 3 - 1/500.
/// 4 - 1/1000.
/// 5 - 1/2000.
/// 6 - 1/4000.
/// 7 - 1/10000.
/// 8 - 1/50.
/// 9 - 1/60.
FAST_SHUTTER_MODE,
/// Auto level. Command arguments:
/// arg1 - 0(dark) to 31(bright).
AUTO_LEVEL,
/// Gain mode. Command arguments:
/// arg1: 0 - AGC.
/// 1 - H AGC.
/// 2 - MANUAL.
/// You can change to MANUAL only when IR cut filter changing mode is
/// COLOR or B/W and ALC mode is OFF or MANUAL.
GAIN_MODE,
/// Flicker less. Command arguments:
/// arg1: 0 - OFF.
/// 1 - ON.
FLICKER_LESS_MODE,
/// BLC mode. Command arguments:
/// arg1: 0 - OFF.
/// 1 - ON.
/// 2 - SPOT.
BLC_MODE,
/// White balance mode. Command arguments:
/// arg1: 0 - ATW1.
/// 1 - ATW2.
/// 2 - AWC.
/// 3 - MANUAL.
/// 4 - AWC exec.
WHITE_BALANCE_MODE,
/// White balance gain for manual mode. Command arguments:
/// arg1 - RED 0-255.
/// arg2 - BLUE 0-255.
WHITE_BALANCE_GAIN_FOR_MANUAL_MODE,
/// IR cut filter changing mode. Command arguments:
/// arg1: 0 - AUTO.
/// 1 - REMOTE.
/// 2 - COLOR.
/// 3 - B/W.
CHANGING_MODE,
/// IR cut filter changing level. Command arguments:
/// arg1: 0 - DARK.
/// 1 - MID.
/// 2 - BRIGHT.
/// 3 - MANUAL.
CHANGING_LEVEL,
/// Remote control palarity for REMOTE mode. Command arguments:
/// arg1: 0 - MAKE.
/// 1 - BREAK.
REMOTE_CONTROL_POLARITY,
/// Changing level for manual mode. COmmand arguments:
/// arg1 - from color to B/W from 40 to 215.
/// arg2 - from B/W to color mode from 40 to 215.
CHANGING_LEVEL_FOR_MANUAL_MODE,
/// Chroma level. Command arguments:
/// arg1 - level from 0 to 255.
CHROMA_LEVEL,
/// Detail. Command arguments:
/// arg1 - 0(weak) to 15(strong).
DETAIL,
/// Black level. Command arguments:
/// arg1 - 0(dark) to 24(bright).
BLACK_LEVEL,
/// Gamma. Command arguments:
/// arg1: 0 - 0.45.
/// 1 - 0.75.
/// 2 - 1.0.
GAMMA,
/// DNR mode. Command arguments:
/// arg1: 0 - OFF.
/// 1 - LOW.
/// 2 - HIGH.
DNR_MODE,
/// Defog mode. Command arguments:
/// arg1: 0 - OFF.
/// 1 - LOW.
/// 2 - MIDDLE.
/// 3 - HIGH.
DEFOG_MODE,
/// Wide dynamic range mode. Command arguments:
/// arg1: 0 - OFF.
/// 1 - WDR.
/// 2 - Auto Knee.
/// 3 - Black Stretch.
WDR_MODE,
/// Color matrix. Command arguments:
/// arg1: Hue:
/// 0 - RED.
/// 1 - GREEN.
/// 2 - BLUE.
/// 3 - YELLOW.
/// 4 - CYAN.
/// 5 - MAGENTA.
/// Saturation:
/// 6 - RED.
/// 7 - GREEN.
/// 8 - BLUE.
/// 9 - YELLOW.
/// 10 - CYAN.
/// 11 - MAGENTA.
/// arg2 - For Hue: 0(small) to 255(big).
/// For saturation 0(-) to 255(+).
COLOR_MATRIX,
/// HD SDI format. Command arguments:
/// arg1: 0 - 1080/59.94i.
/// 1 - 1080/29.97p.
/// 2 - 720/59.94p.
/// 3 - 720/29.97p.
/// 4 - 1080/30p.
/// 5 - 720/60p.
/// 6 - 720/30p.
/// 7 - 1080/50i.
/// 8 - 1080/25p.
/// 9 - 720/50p.
/// 10 - 720/25p.
HD_SDI_FORMAT,
/// SDTV format. Command arguments:
/// arg1: 0 - NTSC-J 0.0IRE.
/// 1 - NTSC-M (7.5IRE).
/// 2 - PAL-B (0.0IRE).
SDTV_FORMAT,
/// SDTV aspect. Command arguments:
/// arg1: 0 - Side cut.
/// 1 - Letter box.
/// 2 - Squeeze.
SDTV_ASPECT,
/// SDTV color brush. Command arguments:
/// arg1: 0 - Color brush off.
/// 1 - Color brush on.
SDTV_COLOR_BRUSH_MODE,
/// Genlock mode. Command arguments:
/// arg1: 0 - OFF.
/// 1 - ON.
GENLOCK_MODE,
/// Genlock horizontal phase adjustment. Command arguments:
/// arg1 - 0 to 255.
GENLOCK_HORIZONTAL_PHASE_ADJUSTMENT,
/// Digital zoom. Command arguments:
/// arg1 - 10(x1.0) to 100(x10.0).
DIGITAL_ZOOM,
/// Flip and mirror. Command arguments:
/// arg1: 0 - Normal.
/// 1 - Mirror.
/// 2 - Flip.
/// 3 - Flip and mirror.
FLIP_AND_MIRROR,
/// Manual gain. Command arguments:
/// arg1 - 0 to 4095.
/// Only for Gain mode=MANUAL
/// The number is dB value timed 10 (0.3dB pitch)
/// 0.0[dB]: 0 = 0x000.
/// 30.0[dB]: 300 = 0x12C.
/// 72.0[dB]: 720 = 0x2D0.
MANUAL_GAIN,
/// Iris speed. Command arguments:
/// arg1: 0 - Normal.
/// 1 - x2.0(slowest).
/// 2 - x1.8.
/// 3 - x1.5.
/// 4 - x1.2.
/// 5 - x0.9.
/// 6 - x0.7.
/// 7 - x0.5.
/// 8 - x0.2(fastest).
IRIS_SPEED,
/// Base shutter speed. Command arguments.
/// arg1: 0 - OFF.
/// 1 - 1/125.
/// 2 - 1/250.
/// 3 - 1/500.
/// 4 - 1/1000.
/// 5 - 1/2000.
/// 6 - 1/4000.
/// 7 - 1/10000.
/// 8 - 1/50.
/// 9 - 1/60.
BASED_SHUTTER_SPEED,
/// High speed shutter limit. Command arguments:
/// arg1: 0 - OFF.
/// 1 - 1/125.
/// 2 - 1/250.
/// 3 - 1/500.
/// 4 - 1/1000.
/// 5 - 1/2000.
/// 6 - 1/4000.
/// 7 - 1/10000.
/// 8 - 1/50.
/// 9 - 1/60.
HIGH_SPEED_SHUTTER_LIMIT,
/// Save. Send SAVE command otherwise the parameters set by remote
/// control is canceled after power off/on.
SAVE,
/// Cancel.
CANCEL,
/// Reset to default.
RESET,
/// Product name request.
REQUEST_PRODUCT_NAME,
/// Main version request.
REQUEST_MAIN_VERSION,
/// Firmware version request.
REQUEST_FIRMWARE,
/// FPGA version request.
REQUEST_FPGA_VERSION,
/// Menu On.
MENU_ON,
/// Menu Off.
MENU_OFF,
/// Menu enter key.
MENU_ENTER_KEY,
/// Menu left key.
MENU_LEFT_KEY,
/// Menu right key.
MENU_RIGHT_KEY,
/// Menu down key.
MENU_DOWN_KEY,
/// Menu up key.
MENU_UP_KEY
};
Table 2 - KowaSC200PK1CCommand enum class description.
| Parameter | Description | Argument 1 | Argument 2 |
|---|---|---|---|
| DISPLAY_MODE | Display mode | 0 - OFF. 1 - ON. | Not used. |
| POSITION | Position | horizontal 0 (left) to 255 (right). | vertical 0 (top) to 255 (bottom). |
| ALC_MODE | ALC mode | 0 - OFF. 1 - S/N. 2 - STD. 3 - MOVE. 4 - MANUAL. | Not used. |
| LONG_SHUTTER_MODE | Long shutter mode | 0 - x1. 1 - x2. 2 - x4. 3 - x8. 4 - x16. | Not used. |
| FAST_SHUTTER_MODE | Fast shutter mode | 0 - OFF. 1 - 1/125. 2 - 1/250. 3 - 1/500. 4 - 1/1000. 5 - 1/2000. 6 - 1/4000. 7 - 1/10000. 8 - 1/50. 9 - 1/60. | Not used. |
| AUTO_LEVEL | Auto level | 0 (dark) to 31(bright). | Not used. |
| GAIN_MODE | Gain mode | 0 - AGC. 1 - H AGC. 2 - MANUAL. | Not used. |
| FLICKER_LESS_MODE | Flicker less | 0 - OFF. 1 - ON. | Not used. |
| BLC_MODE | BLC mode | 0 - OFF. 1 - ON. 2 - SPOT. | Not used. |
| WHITE_BALANCE_MODE | White balance mode | 0 - ATW1. 1 - ATW2. 2 - AWC. 3 - MANUAL. 4 - AWC exec. | Not used. |
| WHITE_BALANCE_GAIN_FOR_MANUAL_MODE | White balance gain for manual mode | RED 0-255. | BLUE 0-255. |
| CHANGING_MODE | IR cut filter changing mode | 0 - AUTO. 1 - REMOTE. 2 - COLOR. 3 - B/W. | Not used. |
| CHANGING_LEVEL | IR cut filter changing level | 0 - DARK. 1 - MID. 2 - BRIGHT. 3 - MANUAL. | Not used. |
| REMOTE_CONTROL_POLARITY | Remote control palarity for REMOTE mode | 0 - MAKE. 1 - BREAK. | Not used. |
| CHANGING_LEVEL_FOR_MANUAL_MODE | Changing level for manual mode | From color to B/W from 40 to 215. | From B/W to color mode from 40 to 215. |
| CHROMA_LEVEL | Chroma level | level from 0 to 255. | Not used. |
| DETAIL | Detail | 0 (weak) to 15 (strong). | Not used. |
| BLACK_LEVEL | Black level | 0 (dark) to 24 (bright). | Not used. |
| GAMMA | Gamma | 0 - 0.45. 1 - 0.75. 2 - 1.0. | Not used. |
| DNR_MODE | DNR mode | 0 - OFF. 1 - LOW. 2 - HIGH. | Not used. |
| DEFOG_MODE | Defog mode | 0 - OFF. 1 - LOW. 2 - MIDDLE. 3 - HIGH. | Not used. |
| WDR_MODE | Wide dynamic range mode | 0 - OFF. 1 - WDR. 2 - Auto Knee. 3 - Black Stretch. | Not used. |
| COLOR_MATRIX | Color matrix | Hue: 0 - RED. 1 - GREEN. 2 - BLUE. 3 - YELLOW. 4 - CYAN. 5 - MAGENTA. Saturation: 6 - RED. 7 - GREEN. 8 - BLUE. 9 - YELLOW. 10 - CYAN. 11 - MAGENTA. | For Hue: 0 (small) to 255 (big). For saturation 0 (-) to 255 (+). |
| HD_SDI_FORMAT | HD SDI format | 0 - 1080/59.94i. 1 - 1080/29.97p. 2 - 720/59.94p. 3 - 720/29.97p. 4 - 1080/30p. 5 - 720/60p. 6 - 720/30p. 7 - 1080/50i. 8 - 1080/25p. 9 - 720/50p. 10 - 720/25p. | Not used. |
| SDTV_FORMAT | SDTV format | 0 - NTSC-J 0.0IRE. 1 - NTSC-M (7.5IRE). 2 - PAL-B (0.0IRE). | Not used. |
| SDTV_ASPECT | SDTV aspect | 0 - Side cut. 1 - Letter box. 2 - Squeeze. | Not used. |
| SDTV_COLOR_BRUSH_MODE | SDTV color brush | 0 - Color brush off. 1 - Color brush on. | Not used. |
| GENLOCK_MODE | Genlock mode | 0 - OFF. 1 - ON. | Not used. |
| GENLOCK_HORIZONTAL_PHASE_ADJUSTMENT | Genlock horizontal phase adjustment | 0 to 255. | Not used. |
| DIGITAL_ZOOM | Digital zoom | 10 (x1.0) to 100 (x10.0) | Not used. |
| FLIP_AND_MIRROR | Flip and mirror | 0 - Normal. 1 - Mirror. 2 - Flip. 3 - Flip and mirror. | Not used. |
| MANUAL_GAIN | Manual gain. Only for Gain mode=MANUAL. The number is dB value timed 10 (0.3dB pitch) | 0 to 4095. | Not used. |
| IRIS_SPEED | Iris speed | 0 - Normal. 1 - x2.0(slowest). 2 - x1.8. 3 - x1.5. 4 - x1.2. 5 - x0.9. 6 - x0.7. 7 - x0.5. 8 - x0.2(fastest). | Not used. |
| BASED_SHUTTER_SPEED | Base shutter speed | 0 - OFF. 1 - 1/125. 2 - 1/250. 3 - 1/500. 4 - 1/1000. 5 - 1/2000. 6 - 1/4000. 7 - 1/10000. 8 - 1/50. 9 - 1/60. | Not used. |
| HIGH_SPEED_SHUTTER_LIMIT | High speed shutter limit | 0 - OFF. 1 - 1/125. 2 - 1/250. 3 - 1/500. 4 - 1/1000. 5 - 1/2000. 6 - 1/4000. 7 - 1/10000. 8 - 1/50. 9 - 1/60. | Not used. |
| SAVE | Save | Not used. | Not used. |
| CANCEL | Cancel | Not used. | Not used. |
| RESET | Reset to default | Not used. | Not used. |
| REQUEST_PRODUCT_NAME | Product name request | Not used. | Not used. |
| REQUEST_MAIN_VERSION | Main version request | Not used. | Not used. |
| REQUEST_FIRMWARE | Firmware version request | Not used. | Not used. |
| REQUEST_FPGA_VERSION | FPGA version request | Not used. | Not used. |
| MENU_ON | Menu On | Not used. | Not used. |
| MENU_OFF | Menu Off | Not used. | Not used. |
| MENU_ENTER_KEY | Menu enter key | Not used. | Not used. |
| MENU_LEFT_KEY | Menu left key | Not used. | Not used. |
| MENU_RIGHT_KEY | Menu right key | Not used. | Not used. |
| MENU_DOWN_KEY | Menu down key | Not used. | Not used. |
| MENU_UP_KEY | Menu up key | Not used. | Not used. |
Build and connect to your project
Typical commands to build KowaProtocolParser library:
cd KowaProtocolParser
mkdir build
cd build
cmake ..
make
If you want to connect KowaProtocolParser 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 3rdparty folder in your repository and copy folder of KowaProtocolParser repository there. The new structure of your repository will be as follows:
CMakeLists.txt
src
CMakeList.txt
yourLib.h
yourLib.cpp
3rdparty
KowaProtocolParser
Create CMakeLists.txt file in 3rdparty folder. CMakeLists.txt should be containing:
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}_SUBMODULE_KOWA_PROTOCOL_PARSER ON CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_KOWA_PROTOCOL_PARSER)
SET(${PARENT}_KOWA_PROTOCOL_PARSER ON CACHE BOOL "" FORCE)
SET(${PARENT}_KOWA_PROTOCOL_PARSER_TEST OFF CACHE BOOL "" FORCE)
endif()
################################################################################
## INCLUDING SUBDIRECTORIES
## Adding subdirectories according to the 3rd-party configuration
################################################################################
if (${PARENT}_SUBMODULE_KOWA_PROTOCOL_PARSER)
add_subdirectory(KowaProtocolParser)
endif()
File 3rdparty/CMakeLists.txt adds folder KowaProtocolParser to your project and excludes test application from compiling (by default test application is excluded from compiling if KowaProtocolParser is included as sub-repository). The new structure of your repository:
CMakeLists.txt
src
CMakeList.txt
yourLib.h
yourLib.cpp
3rdparty
CMakeLists.txt
KowaProtocolParser
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 KowaProtocolParser library in your src/CMakeLists.txt file:
target_link_libraries(${PROJECT_NAME} KowaProtocolParser)
Done!
Simple example
The following example shows how to encode a command for Kowa camera. The example encodes a command to set digital zoom to 20. The command is encoded and stored in the command buffer. The size of the command is stored in the size variable.
uint8_t command[32];
int size = 0;
KowaProtocolParser parser;
if (!parser.getCommand(command, size, KowaSC200PK1CCommand::DIGITAL_ZOOM, 0x31, 20))
cout << " ERROR: Can't encode command" << endl;
Test application
Folder KowaProtocolParser/test contains the test application files. The test application allows you to generate some commands, send it to the lens over the serial port and then print coming data. Once started, the user must enter the serial port name (full name for Linux or just the port number for Windows), baudrate and camera ID.
Test application output will look like :
===========================================
Kowa Protocol Parser v1.0.3 test
===========================================
Set serial port name: <cameraName>
Set baudrate (9600, 19200, 38400): 9600
Set camera ID (49-255): 49
Serial port open!
===========================================
==========================================
Commands:
1 DISPLAY_MODE 2 POSITION
3 ALC_MODE 4 LONG_SHUTTER_MODE
5 FAST_SHUTTER_MODE 6 AUTO_LEVEL
7 GAIN_MODE 8 FLICKER_LESS_MODE
9 BLC_MODE 10 WHITE_BALANCE_MODE
11 WHITE_BALANCE_GAIN_FOR_MANUAL_MODE 12 CHANGING_MODE
13 CHANGING_LEVEL 14 REMOTE_CONTROL_POLARITY
15 CHANGING_LEVEL_FOR_MANUAL_MODE 16 CHROMA_LEVEL
17 DETAIL 18 BLACK_LEVEL
19 GAMMA 20 DNR_MODE
21 DEFOG_MODE 22 WDR_MODE
23 COLOR_MATRIX 24 HD_SDI_FORMAT
25 SDTV_FORMAT 26 SDTV_ASPECT
27 SDTV_COLOR_BRUSH_MODE 28 GENLOCK_MODE
29 GENLOCK_HORIZONTAL_PHASE_ADJUSTMENT 30 DIGITAL_ZOOM
31 FLIP_AND_MIRROR 32 MANUAL_GAIN
33 IRIS_SPEED 34 BASED_SHUTTER_SPEED
35 HIGH_SPEED_SHUTTER_LIMIT 36 SAVE
37 CANCEL 38 RESET
39 REQUEST_PRODUCT_NAME 40 REQUEST_MAIN_VERSION
41 REQUEST_FIRMWARE 42 REQUEST_FPGA_VERSION
43 MENU_ON
44 MENU_OFF 45 MENU_ENTER_KEY
46 MENU_LEFT_KEY 47 MENU_RIGHT_KEY
48 MENU_DOWN_KEY 49 MENU_UP_KEY
==========================================
Choose command: