OwlCamera C++ library

v3.0.0

Table of contents

• Overview
• Versions
• Library files
• OwlCamera class description
  • OwlCamera class declaration
  • getVersion method
  • openCamera method
  • initCamera method
  • closeCamera method
  • isCameraOpen method
  • isCameraConnected method
  • setParam method
  • getParam method
  • getParams method
  • executeCommand method
  • decodeAndExecuteCommand method
  • encodeSetParamCommand method of Camera class
  • encodeCommand method of Camera class
  • decodeCommand method of Camera class
• Data structures
  • CameraCommand enum
  • CameraParam enum
• Example
• CameraParams class description
  • CameraParams class declaration
  • Serialize camera params
  • Deserialize camera params
  • Read and write camera params to JSON file
• Build and connect to your project
• Test application

Overview

The OwlCamera C++ library is a software controller for Raptor Owl 640 cameras. The OwlCamera library inherits the Camera interface. It depends on the following libraries: Camera interface library (provides interface and data structures to control cameras, source code included, Apache 2.0 license), Logger logging library (provides functions to print log information in console and files, source code included, Apache 2.0 license), OwlParser (provides functions for encoding commands and decoding responses, source code included) and SerialPort (provides functions to work with serial ports, source code included, Apache 2.0 license). The OwlCamera library provides a simple interface to be integrated in any C++ projects. The library repository (folder) is provided as source code and doesn’t have third-party dependencies to be specially installed in the OS. It is developed with C++17 standard and compatible with Linux and Windows.

Versions

Table 1 - Library versions.

Version	Release date	What’s new
1.0.0	30.05.2023	- First version.
2.0.0	07.03.2024	- Interface updated. - Test application updated. - Documentation updated.
2.0.1	29.03.2024	- Code review and documentation update.
2.0.2	23.05.2024	- Documentation updated. - Submodules updated.
2.0.3	07.08.2024	- CMake updated.
2.0.4	16.09.2024	- Fix connection status.
2.0.5	05.10.2024	- Add NUC command.
2.0.6	22.11.2024	- Add NUC mode control.
2.0.7	03.04.2025	- Logger submodule update.
2.0.8	19.07.2025	- Fix NUC mode options control.
2.0.9	26.10.2025	- OwlParser submodule update. - SerialPort submodule update.
3.0.0	21.03.2026	- Updated OwlParser submodules. - Added new commands support.

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 of the library.
3rdparty ------------------- Folder with third-party libraries.
    CMakeLists.txt --------- CMake file to include third-party libraries.
    Camera ----------------- Folder with Camera library source code.
    Logger ----------------- Folder with Logger library source code.
    OwlParser -------------- Folder with OwlParser library source code.
    SerialPort ------------- Folder with SerialPort library source code.
src ------------------------ Folder with source code of the library.
    CMakeLists.txt --------- CMake file of the library.
    OwlCamera.cpp ---------- C++ implementation file.
    OwlCamera.h ------------ Header file which includes OwlCamera class declaration.
    OwlCameraVersion.h ----- Header file which includes version of the library.
    OwlCameraVersion.h.in -- CMake service file to generate version file.
test ----------------------- Folder with source code of the test application.
    CMakeLists.txt --------- CMake file of test application.
    main.cpp --------------- Test application source code.

OwlCamera class description

OwlCamera Class declaration

The OwlCamera interface class declared in OwlCamera.h file. The OwlCamera class inherits Camera interfaces. Class declaration:

namespace cr
{
namespace camera
{
class OwlCamera : public cr::camera::Camera
{
public:

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

  /// Init camera controller.
  bool openCamera(std::string initString) override;

  /// Init camera controller by parameters class.
  bool initCamera(CameraParams& params) override;

  /// Close camera serial port.
  void closeCamera() override;

  /// Get camera connection status.
  bool isCameraOpen() override;

  /// Get camera open status.
  bool isCameraConnected() override;

  /// Set the camera controller param.
  bool setParam(CameraParam id, float value) override;

  /// Get the camera controller param.
  float getParam(CameraParam id) override;

  /// Get the camera controller params.
  void getParams(CameraParams& params) override;

  /// Execute camera controller action command.
  bool executeCommand(CameraCommand id) override;

  /// Decode and execute command.
  bool decodeAndExecuteCommand(uint8_t* data, int size) override;
};
}
}

getVersion method

The getVersion() returns string of OwlCamera class version. Method declaration:

static std::string getVersion();

Method can be used without OwlCamera class instance:

std::cout << "OwlCamera class version: " << OwlCamera::getVersion();

Console output:

OwlCamera class version: 3.0.0

openCamera method

The openCamera(…) opens serial port to communicate with camera. Method declaration:

bool openCamera(std::string initString) override;

Parameter	Value
initString	Initialization string. Uses first segment before ‘;’ as serial port name, or whole string if no ‘;’. Baudrate is 115200 by default.

Returns: TRUE if the camera controller initialized or FALSE if not.

initCamera method

The initCamera(…) initializes controller and sets camera params (Camera interface). The method will call openCamera(…) method and after will set given camera params with setParam(…) method. Method declaration:

bool initCamera(CameraParams& params) override;

Parameter	Value
params	CameraParams class object.

Returns: TRUE if the controller initialized and camera parameters were set or FALSE if not.

closeCamera method

The closeCamera() method closes serial port. Method declaration:

void closeCamera() override;

isCameraOpen method

The isCameraOpen() method returns controller initialization status. Open status shows if the controller initialized (serial port open) but doesn’t show if controller has communication with equipment. For example, if serial port is open (opens serial port file in OS) but equipment can be not active (no power). In this case open status just shows that the serial port is open. Method declaration:

bool isCameraOpen() override;

Returns: TRUE if the controller initialized (serial port open) or FALSE if not.

isCameraConnected method

The isCameraConnected() shows if the controller receives responses from equipment (camera). For example, if serial port open but equipment not active (no power). In this case isCameraOpen(…) method will return TRUE but isCameraConnected() method will return FALSE. Method declaration:

bool isCameraConnected() override;

Returns: TRUE if the controller has data exchange with equipment or FALSE if not.

setParam method

The setParam(…) method sets new camera controller parameter value. Method declaration:

bool setParam(CameraParam id, float value) override;

Parameter	Description
id	Camera controller parameter ID according to CameraParam enum.
value	Parameter value. Value depends on parameter ID.

Returns: TRUE if the parameter was set or FALSE if not.

getParam method

The getParam(…) method is intended to obtain a Camera parameter value. Method declaration:

float getParam(CameraParam id) override;

Parameter	Description
id	Camera controller parameter ID according to CameraParam enum.

Returns: parameter value or -1 if the parameter is not supported.

getParams method

The getParams(…) method is intended to obtain Camera parameters structure. Method declaration:

void getParams(CameraParams& params) override;

Parameter	Description
params	Reference to CameraParams class instance.

executeCommand method

The executeCommand(…) method is intended to execute a Camera action command. Method declaration:

bool executeCommand(CameraCommand id) override;

Parameter	Description
id	Camera controller command ID according to CameraCommand enum.

Returns: TRUE if the command was executed or FALSE if not.

decodeAndExecuteCommand method

The decodeAndExecuteCommand(…) method decodes and executes a command on the controller side. The method will decode commands encoded by encodeCommand(…) and encodeSetParamCommand(…) methods of the Camera interface class. If the command is decoded, the method will call the setParam(…) or executeCommand(…) methods for the camera interface. This method is thread-safe. This means that the method can be safely called from any thread. Method declaration:

bool decodeAndExecuteCommand(uint8_t* data, int size) override;

Parameter	Description
data	Pointer to input command data.
size	Size of command. Must be 11 bytes for SET_PARAM and 7 bytes for COMMAND.

Returns: TRUE if command decoded (SET_PARAM or COMMAND) and executed (action command or set param command).

encodeSetParamCommand method of Camera class

The encodeSetParamCommand(…) static method encodes command to change any remote camera parameter. To control a camera remotely, the developer has to design his own protocol and according to it encode the command and deliver it over the communication channel. To simplify this, the Camera class contains static methods for encoding the control command. The Camera class provides two types of commands: a parameter change command (SET_PARAM) and an action command (COMMAND). encodeSetParamCommand(…) designed to encode SET_PARAM command. Method declaration:

static void encodeSetParamCommand(uint8_t* data, int& size, CameraParam id, float value);

Parameter	Description
data	Pointer to data buffer for encoded command. Must have size >= 11.
size	Size of encoded data. Will be 11 bytes.
id	Parameter ID according to CameraParam enum.
value	Parameter value.

encodeSetParamCommand(…) is static and used without Camera class instance. This method used on client side (control system). Command encoding example:

// Buffer for encoded data.
uint8_t data[11];
// Size of encoded data.
int size = 0;
// Random parameter value.
float outValue = (float)(rand() % 20);
// Encode command.
Camera::encodeSetParamCommand(data, size, CameraParam::ROI_X0, outValue);

encodeCommand method of Camera class

The encodeCommand(…) static method encodes action command for camera remote control. To control a camera remotely, the developer has to design his own protocol and according to it encode the command and deliver it over the communication channel. To simplify this, the Camera class contains static methods for encoding the control command. The Camera class provides two types of commands: a parameter change command (SET_PARAM) and an action command (COMMAND). encodeCommand(…) designed to encode COMMAND command (action command). Method declaration:

static void encodeCommand(uint8_t* data, int& size, CameraCommand id);

Parameter	Description
data	Pointer to data buffer for encoded command. Must have size >= 7.
size	Size of encoded data. Will be 7 bytes.
id	Command ID according to CameraCommand enum.

encodeCommand(…) is static and used without Camera class instance. This method used on client side (control system). Command encoding example:

// Buffer for encoded data.
uint8_t data[7];
// Size of encoded data.
int size = 0;
// Encode command.
Camera::encodeCommand(data, size, CameraCommand::NUC);

decodeCommand method of Camera class

The decodeCommand(…) static method decodes command on camera controller side encoded by encodeSetParamCommand(…) or encodeCommand(…). Method declaration:

static int decodeCommand(uint8_t* data, int size, CameraParam& paramId, CameraCommand& commandId, float& value);

Parameter	Description
data	Pointer to input command.
size	Size of command. Must be 11 bytes for SET_PARAM and 7 bytes for COMMAND.
paramId	Camera parameter ID according to CameraParam enum. After decoding SET_PARAM command the method will return parameter ID.
commandId	Camera command ID according to CameraCommand enum. After decoding COMMAND the method will return command ID.
value	Camera parameter value (after decoding SET_PARAM command).

Returns: 0 - in case decoding COMMAND, 1 - in case decoding SET_PARAM command or -1 in case errors.

Data structures

CameraCommand enum

Enum declaration:

namespace cr
{
namespace camera
{
enum class CameraCommand
{
    /// Restart camera controller.
    RESTART = 1,
    /// Do NUC.
    NUC,
    /// Apply settings.
    APPLY_PARAMS,
    /// Save params.
    SAVE_PARAMS,
    /// Menu on.
    MENU_ON,
    /// Menu off.
    MENU_OFF,
    /// Menu set.
    MENU_SET,
    /// Menu up.
    MENU_UP,
    /// Menu down.
    MENU_DOWN,
    /// Menu left.
    MENU_LEFT,
    /// Menu right.
    MENU_RIGHT,
    /// Freeze, Argument: time msec.
    FREEZE,
    /// Disable freeze.
    DEFREEZE
};
}
}

Table 2 - Camera commands description.

Command	Description
RESTART	Reset command.
NUC	NUC (Flat Field Correction) command.
APPLY_PARAMS	Not supported by OwlCamera library.
SAVE_PARAMS	Not supported by OwlCamera library.
MENU_ON	Not supported by OwlCamera library.
MENU_OFF	Not supported by OwlCamera library.
MENU_SET	Not supported by OwlCamera library.
MENU_UP	Not supported by OwlCamera library.
MENU_DOWN	Not supported by OwlCamera library.
MENU_LEFT	Not supported by OwlCamera library.
MENU_RIGHT	Not supported by OwlCamera library.
FREEZE	Not supported by OwlCamera library.
DEFREEZE	Not supported by OwlCamera library.

CameraParam enum

Enum declaration:

namespace cr
{
namespace camera
{
enum class CameraParam
{
    /// Video frame width. Value from 0 to 16384.
    WIDTH = 1,
    /// Video frame height Value from 0 to 16384.
    HEIGHT,
    /// Display menu mode.
    DISPLAY_MODE,
    /// Video output type.
    VIDEO_OUTPUT,
    /// Logging mode.
    LOG_MODE,
    /// Exposure mode.
    EXPOSURE_MODE,
    /// Exposure time of the camera sensor.
    EXPOSURE_TIME,
    /// White balance mode.
    WHITE_BALANCE_MODE,
    /// White balance area.
    WHITE_BALANCE_AREA,
    /// White dynamic range mode.
    WIDE_DYNAMIC_RANGE_MODE,
    /// Image stabilization mode.
    STABILIZATION_MODE,
    /// ISO sensitivity.
    ISO_SENSITIVITY,
    /// Scene mode.
    SCENE_MODE,
    /// FPS.
    FPS,
    /// Brightness mode.
    BRIGHTNESS_MODE,
    /// Brightness. Value 0 - 100%.
    BRIGHTNESS,
    /// Contrast. Value 1 - 100%.
    CONTRAST,
    /// Gain mode.
    GAIN_MODE,
    /// Gain. Value 1 - 100%.
    GAIN,
    /// Sharpening mode.
    SHARPENING_MODE,
    /// Sharpening. Value 1 - 100%.
    SHARPENING,
    /// Palette.
    PALETTE,
    /// Analog gain control mode.
    AGC_MODE,
    /// Shutter mode.
    SHUTTER_MODE,
    /// Shutter position. 0 (full close) - 65535 (full open).
    SHUTTER_POSITION,
    /// Shutter speed. Value: 0 - 100%.
    SHUTTER_SPEED,
    /// Digital zoom mode.
    DIGITAL_ZOOM_MODE,
    /// Digital zoom. Value 1.0 (x1) - 20.0 (x20).
    DIGITAL_ZOOM,
    /// Exposure compensation mode.
    EXPOSURE_COMPENSATION_MODE,
    /// Exposure compensation position. 
    EXPOSURE_COMPENSATION_POSITION,
    /// Defog mode.
    DEFOG_MODE,
    /// Dehaze mode.
    DEHAZE_MODE,
    /// Noise reduction mode.
    NOISE_REDUCTION_MODE,
    /// Black and white filter mode.
    BLACK_WHITE_FILTER_MODE,
    /// Filter mode.
    FILTER_MODE,
    /// NUC mode for thermal cameras.
    NUC_MODE,
    /// Auto NUC interval for thermal cameras. 
    AUTO_NUC_INTERVAL_MSEC,
    /// Image flip mode.
    IMAGE_FLIP,
    /// DDE mode.
    DDE_MODE,
    /// DDE level.
    DDE_LEVEL,
    /// ROI top-left horizontal position, pixels.
    ROI_X0,
    /// ROI top-left vertical position, pixels.
    ROI_Y0,
    /// ROI bottom-right horizontal position, pixels.
    ROI_X1,
    /// ROI bottom-right vertical position, pixels.
    ROI_Y1,
    /// Camera temperature, degree.
    TEMPERATURE,
    /// ALC gate.
    ALC_GATE,
    /// Sensor sensitivity.
    SENSITIVITY,
    /// Changing mode (day / night).
    CHANGING_MODE,
    /// Changing level (day / night).
    CHANGING_LEVEL,
    /// Chroma level. Values: 0 - 100%.
    CHROMA_LEVEL,
    /// Details, enhancement. Values: 0 - 100%.
    DETAIL,
    /// Camera settings profile.
    PROFILE,
    /// Connection status (read only). Shows if we have a response from camera.
    /// Value: 0 - not connected, 1 - connected.
    IS_CONNECTED,
    /// Open status (read only):
    /// 1 - camera control port open, 0 - not open.
    IS_OPEN,
    /// Camera type.
    TYPE,
    /// Camera custom param.
    CUSTOM_1,
    /// Camera custom param.
    CUSTOM_2,
    /// Camera custom param.
    CUSTOM_3
};
}
}

Table 3 - Camera params description.

Parameter	Access	Description
WIDTH	read / write	Not supported by OwlCamera library.
HEIGHT	read / write	Not supported by OwlCamera library.
DISPLAY_MODE	read / write	Not supported by OwlCamera library.
VIDEO_OUTPUT	read / write	Not supported by OwlCamera library.
LOG_MODE	read / write	Logging mode. Values: 0 - Disable, 1 - Only file, 2 - Only terminal (console), 3 - File and terminal.
EXPOSURE_MODE	read / write	Exposure mode (ALC). Values: 0 - Manual (ALC disabled), 1 - Auto (ALC enabled).
EXPOSURE_TIME	read / write	Exposure time raw value. OWL 640: 1 count = 25 ns (40 MHz), range [20:1073741823]. OWL 1280 low gain: 1 count = 1 µs. OWL 1280 high gain: 1 count = 10 µs.
WHITE_BALANCE_MODE	read / write	Not supported by OwlCamera library.
WHITE_BALANCE_AREA	read / write	Not supported by OwlCamera library.
WHITE_DINAMIC_RANGE_MODE	read / write	Not supported by OwlCamera library.
STABILIZATION_MODE	read / write	Not supported by OwlCamera library.
ISO_SENSITIVITY	read / write	Not supported by OwlCamera library.
SCENE_MODE	read / write	Not supported by OwlCamera library.
FPS	read / write	Frame rate in frames per second. Internally converted to period counts (OWL 640: 40 MHz, OWL 1280: 70 MHz). Value must be > 0.
BRIGHTNESS_MODE	read / write	Not supported by OwlCamera library.
BRIGHTNESS	read / write	ALC level (auto level set point). 14-bit value, range [0:16383]. 0x3FFF = White.
CONTRAST	read / write	Not supported by OwlCamera library.
GAIN_MODE	read / write	Gain mode. Values: 0 - Low Gain, 1 - High Gain. Note: gain mode cannot be set if ALC (OWL 1280) or AGMC (OWL 640) is enabled.
GAIN	read / write	Digital video gain. 16-bit value = gain × 256. Sent as two serial commands. Note: ALC must be disabled.
SHARPENING_MODE	read / write	Not supported by OwlCamera library.
SHARPENING	read / write	Not supported by OwlCamera library.
PALETTE	read / write	Not supported by OwlCamera library.
AGC_MODE	read / write	Automatic Gain Mode Control (OWL 640 only, AGMC). Values: 0 - Disabled, 1 - Enabled. Not supported on OWL 1280.
SHUTTER_MODE	read / write	Not supported by OwlCamera library.
SHUTTER_POSITION	read / write	Not supported by OwlCamera library.
SHUTTER_SPEED	read / write	Not supported by OwlCamera library.
DIGITAL_ZOOM_MODE	read / write	Not supported by OwlCamera library.
DIGITAL_ZOOM	read only	Not supported by OwlCamera library.
EXPOSURE_COMPENSATION_MODE	read only	Not supported by OwlCamera library.
EXPOSURE_COMPENSATION_POSITION	read / write	Not supported by OwlCamera library.
DEFOG_MODE	read / write	Not supported by OwlCamera library.
DEHAZE_MODE	read / write	Not supported by OwlCamera library.
NOISE_REDUCTION_MODE	read / write	Not supported by OwlCamera library.
BLACK_WHITE_FILTER_MODE	read only	Not supported by OwlCamera library.
FILTER_MODE	read / write	Not supported by OwlCamera library.
NUC_MODE	read / write	Automatic NUC mode: 0 - Off, 1 - Offset corrected, 2 - Offset + Gain corrected, 3 - Offset + Gain + Dark corrected.
AUTO_NUC_INTERVAL	read / write	Not supported by OwlCamera library.
IMAGE_FLIP	read / write	Image flip mode. Values: 0 - Off, 1 - Horizontal, 2 - Vertical, 3 - Horizontal and vertical.
DDE_MODE	read / write	Not supported by OwlCamera library.
DDE_LEVEL	read / write	Not supported by OwlCamera library.
ROI_X0	read / write	ROI X offset. OWL 640: 8-bit value = 1/4 of X pixel offset. OWL 1280: 8-bit value = 1/8 of X pixel offset.
ROI_Y0	read / write	ROI Y offset. OWL 640: 8-bit value = 1/4 of Y pixel offset. OWL 1280: 8-bit value = 1/8 of Y pixel offset.
ROI_X1	read / write	ROI X size. OWL 640: 8-bit value = 1/4 of X pixel size. OWL 1280: 8-bit value = 1/8 of X pixel size.
ROI_Y1	read / write	ROI Y size. OWL 640: 8-bit value = 1/4 of Y pixel size. OWL 1280: 8-bit value = 1/8 of Y pixel size.
TEMPERATURE	read only	Not supported by OwlCamera library.
ALC_GATE	read / write	Not supported by OwlCamera library.
SENSITIVITY	read / write	Not supported by OwlCamera library.
CHANGING_MODE	read / write	Not supported by OwlCamera library.
CHANGING_LEVEL	read / write	Not supported by OwlCamera library.
CHROMA_LEVEL	read / write	Not supported by OwlCamera library.
DETAIL	read / write	Not supported by OwlCamera library.
PROFILE	read / write	Not supported by OwlCamera library.
IS_CONNECTED	read only	Connection status. Shows if the controller has data exchange with the equipment. For example, if the serial port is open but the equipment is not active (no power), the connection status shows that the controller doesn’t have data exchange with the equipment (method will return 0). If the controller has data exchange with the equipment, the method will return 1. If the controller is not initialized, the connection status is always FALSE. Values: 0 - not connected, 1 - connected.
IS_OPEN	read only	Controller initialization status. Shows if the controller is initialized or not but doesn’t show if the controller has communication with the equipment. For example, if the serial port is open but the equipment is not active (no power), the open status just shows that the controller has opened the serial port. Values: 0 - not open (not initialized), 1 - open (initialized).
TYPE	read / write	Camera type. Values: 640 (OWL 640) or 1280 (OWL 1280, default).
CUSTOM_1	read / write	TEC set point. 12-bit DAC value. The value is sent as two serial commands.
CUSTOM_2	read / write	Peak/Average mode. 8-bit value: 0 = Full Peak, 255 = Full Average.
CUSTOM_3	read / write	AGC/ALC speed. Encoded as gainSpeed × 16 + expSpeed (both [0:15], default: 7). OWL 640 uses AGC speed, OWL 1280 uses ALC speed.

Example

The example below demonstrates how to use the OwlCamera library. The example shows how to initialize the camera controller, set camera parameters and execute camera commands.

#include <iostream>
#include "OwlCamera.h"

int main()
{
    // Init camera controller.
    OwlCamera camera;
    if (!camera.openCamera("/dev/ttyUSB0"))
    {
        std::cout << "Camera controller initialization failed." << std::endl;
        return -1;
    }

    // Set camera parameters.
    camera.setParam(CameraParam::LOG_MODE, 3); // Enable logging to file and terminal.

    // Execute camera command.
    camera.executeCommand(CameraCommand::RESTART); // Restart camera controller.

    return 1;
}

CameraParams class description

CameraParams class used for camera controller initialization or to get all actual params. Also CameraParams provide structure to write/read params from JSON files (JSON_READABLE macro) and provide method to encode and decode params.

CameraParams Class declaration

CameraParams interface class declared in Camera.h file. Class declaration:

namespace cr
{
namespace camera
{
class CameraParams
{
public:
    /// Initialization string.
    std::string initString{"/dev/ttyUSB0;9600"};
    /// Video frame width. Value from 0 to 16384.
    int width{0};
    /// Video frame height Value from 0 to 16384.
    int height{0};
    /// Display menu mode. 
    int displayMode{0};
    /// Video output type.
    int videoOutput{0};
    /// Logging mode.
    int logMode{0};
    /// Exposure mode. 
    int exposureMode{1};
    /// Exposure time of the camera sensor.
    int exposureTime{0};
    /// White balance mode. 
    int whiteBalanceMode{1};
    /// White balance area.
    int whiteBalanceArea{0};
    /// White dynamic range mode.
    int wideDynamicRangeMode{0};
    /// Image stabilization mode.
    int stabilisationMode{0};
    /// ISO sensitivity.
    int isoSensitivity{0};
    /// Scene mode.
    int sceneMode{0};
    /// FPS.
    float fps{0.0f};
    /// Brightness mode.
    int brightnessMode{1};
    /// Brightness. Value 0 - 100%.
    int brightness{0};
    /// Contrast. Value 1 - 100%.
    int contrast{0};
    /// Gain mode.
    int gainMode{1};
    /// Gain. Value 1 - 100%.
    int gain{0};
    /// Sharpening mode.
    int sharpeningMode{0};
    /// Sharpening. Value 1 - 100%.
    int sharpening{0};
    /// Palette.
    int palette{0};
    /// Analog gain control mode.
    int agcMode{1};
    /// Shutter mode.
    int shutterMode{1};
    /// Shutter position. 0 (full close) - 65535 (full open).
    int shutterPos{0};
    /// Shutter speed. Value: 0 - 100%.
    int shutterSpeed{0};
    /// Digital zoom mode.
    int digitalZoomMode{0};
    /// Digital zoom. Value 1.0 (x1) - 20.0 (x20).
    float digitalZoom{1.0f};
    /// Exposure compensation mode.
    int exposureCompensationMode{0};
    /// Exposure compensation position.
    int exposureCompensationPosition{0};
    /// Defog mode. 
    int defogMode{0};
    /// Dehaze mode.
    int dehazeMode{0};
    /// Noise reduction mode.
    int noiseReductionMode{0};
    /// Black and white filter mode.
    int blackAndWhiteFilterMode{0};
    /// Filter mode.
    int filterMode{0};
    /// NUC mode for thermal cameras.
    int nucMode{0};
    /// Auto NUC interval for thermal cameras.
    int autoNucIntervalMsec{0};
    /// Image flip mode. 
    int imageFlip{0};
    /// DDE mode.
    int ddeMode{0};
    /// DDE level.
    float ddeLevel{0};
    /// ROI top-left horizontal position, pixels.
    int roiX0{0};
    /// ROI top-left vertical position, pixels.
    int roiY0{0};
    /// ROI bottom-right horizontal position, pixels.
    int roiX1{0};
    /// ROI bottom-right vertical position, pixels.
    int roiY1{0};
    /// Camera temperature, degree.
    float temperature{0.0f};
    /// ALC gate.
    int alcGate{0};
    /// Sensor sensitivity.
    float sensitivity{0};
    /// Changing mode (day / night).
    int changingMode{0};
    /// Changing level (day / night).
    float changingLevel{0.0f};
    /// Chroma level. Values: 0 - 100%.
    int chromaLevel{0};
    /// Details, enhancement. Values: 0 - 100%.
    int detail{0};
    /// Camera settings profile.
    int profile{0};
    /// Connection status (read only).
    bool isConnected{false};
    /// Open status (read only).
    bool isOpen{false};
    /// Camera type.
    int type{0};
    /// Camera custom param.
    float custom1{0.0f};
    /// Camera custom param.
    float custom2{0.0f};
    /// Camera custom param.
    float custom3{0.0f};

    JSON_READABLE(CameraParams, initString, width, height, displayMode,
                  videoOutput, logMode, exposureMode, exposureTime,
                  whiteBalanceMode, whiteBalanceArea, wideDynamicRangeMode,
                  stabilisationMode, isoSensitivity, sceneMode, fps,
                  brightnessMode, brightness, contrast, gainMode, gain,
                  sharpeningMode, sharpening, palette, agcMode, shutterMode,
                  shutterPos, shutterSpeed, digitalZoomMode, digitalZoom,
                  exposureCompensationMode, exposureCompensationPosition,
                  defogMode, dehazeMode, noiseReductionMode,
                  blackAndWhiteFilterMode, filterMode, nucMode,
                  autoNucIntervalMsec, imageFlip, ddeMode, ddeLevel,
                  roiX0, roiY0, roiX1, roiY1, alcGate, sensitivity,
                  changingMode, changingLevel, chromaLevel, detail,
                  profile, type, custom1, custom2, custom3)

    /// operator =
    CameraParams& operator= (const CameraParams& src);

    /// Encode params. The method doesn't encode initString.
    bool encode(uint8_t* data, int bufferSize, int& size,
                CameraParamsMask* mask = nullptr);

    /// Decode params. The method doesn't decode initString.
    bool decode(uint8_t* data, int dataSize);
};
}
}

Table 4 - CameraParams class fields description is equivalent to CameraParam enum description.

Field	type	Description
initString	string	Initialization string. Uses first segment before ‘;’ as serial port name, or whole string if no ‘;’. Baudrate is 115200 by default.
width	int	Not supported by OwlCamera library.
height	int	Not supported by OwlCamera library.
displayMode	int	Not supported by OwlCamera library.
videoOutput	int	Not supported by OwlCamera library.
logMode	int	Logging mode. Values: 0 - Disable 1 - Only file 2 - Only terminal (console) 3 - File and terminal
exposureMode	int	Exposure mode (ALC). 0 - Manual (ALC disabled), 1 - Auto (ALC enabled).
exposureTime	int	Exposure time raw value. OWL 640: 1 count = 25 ns. OWL 1280 low gain: 1 count = 1 µs. OWL 1280 high gain: 1 count = 10 µs.
whiteBalanceMode	int	Not supported by OwlCamera library.
whiteBalanceArea	int	Not supported by OwlCamera library.
wideDynamicRangeMode	int	Not supported by OwlCamera library.
stabilisationMode	int	Not supported by OwlCamera library.
isoSensitivity	int	Not supported by OwlCamera library.
sceneMode	int	Not supported by OwlCamera library.
fps	float	Frame rate (frames per second). Converted to period counts internally.
brightnessMode	int	Not supported by OwlCamera library.
brightness	int	ALC level (auto level set point). 14-bit value, range [0:16383].
contrast	int	Not supported by OwlCamera library.
gainMode	int	Gain mode. 0 - Low Gain, 1 - High Gain.
gain	int	Digital video gain. 16-bit value = gain × 256.
sharpeningMode	int	Not supported by OwlCamera library.
sharpening	int	Not supported by OwlCamera library.
palette	int	Not supported by OwlCamera library.
agcMode	int	Automatic Gain Mode Control (OWL 640 only, AGMC). 0 - Disabled, 1 - Enabled.
shutterMode	int	Not supported by OwlCamera library.
shutterPos	int	Not supported by OwlCamera library.
shutterSpeed	int	Not supported by OwlCamera library.
digitalZoomMode	int	Not supported by OwlCamera library.
digitalZoom	float	Not supported by OwlCamera library.
exposureCompensationMode	int	Not supported by OwlCamera library.
exposureCompensationPosition	int	Not supported by OwlCamera library.
defogMode	int	Not supported by OwlCamera library.
dehazeMode	int	Not supported by OwlCamera library.
noiseReductionMode	int	Not supported by OwlCamera library.
blackAndWhiteFilterMode	int	Not supported by OwlCamera library.
filterMode	int	Not supported by OwlCamera library.
nucMode	int	NUC mode: 0 - Off, 1 - Offset corrected, 2 - Offset + Gain corrected, 3 - Offset + Gain + Dark corrected.
autoNucIntervalMsec	int	Not supported by OwlCamera library.
imageFlip	int	Image flip mode. 0 - Off, 1 - Horizontal, 2 - Vertical, 3 - Horizontal and vertical.
ddeMode	int	Not supported by OwlCamera library.
ddeLevel	float	Not supported by OwlCamera library.
roiX0	int	ROI X offset. OWL 640: 1/4 pixel. OWL 1280: 1/8 pixel.
roiY0	int	ROI Y offset. OWL 640: 1/4 pixel. OWL 1280: 1/8 pixel.
roiX1	int	ROI X size. OWL 640: 1/4 pixel. OWL 1280: 1/8 pixel.
roiY1	int	ROI Y size. OWL 640: 1/4 pixel. OWL 1280: 1/8 pixel.
temperature	float	Not supported by OwlCamera library.
alcGate	int	Not supported by OwlCamera library.
sensitivity	float	Not supported by OwlCamera library.
changingMode	int	Not supported by OwlCamera library.
changingLevel	float	Not supported by OwlCamera library.
chromaLevel	int	Not supported by OwlCamera library.
detail	int	Not supported by OwlCamera library.
profile	int	Not supported by OwlCamera library.
isConnected	bool	Connection status. Shows if the controller has data exchange with the equipment. Values: 0 - not connected, 1 - connected.
isOpen	bool	Controller initialization status. Shows if the controller is initialized. Values: 0 - not open, 1 - open.
type	int	Camera type. 640 (OWL 640) or 1280 (OWL 1280, default).
custom1	float	TEC set point. 12-bit DAC value.
custom2	float	Peak/Average mode. 8-bit value: 0 = Full Peak, 255 = Full Average.
custom3	float	AGC/ALC speed. Encoded as gainSpeed × 16 + expSpeed (both [0:15]).

Note: CameraParams class fields listed above reflect params set/get by methods setParam(…) and getParam(…).

Serialize camera params

CameraParams class provides the encode(…) method to serialize camera params (fields of CameraParams class, see Table 4). Serialization of camera params is necessary when you have to send camera params via communication channels. The method doesn’t encode the initString field. The method provides options to exclude particular parameters from serialization. To do this, the method inserts a binary mask (8 bytes) where each bit represents a particular parameter and the decode(…) method recognizes it. Method declaration:

bool encode(uint8_t* data, int bufferSize, int& size, CameraParamsMask* mask = nullptr);

Parameter	Value
data	Pointer to data buffer. Buffer size must be >= 237 bytes.
bufferSize	Data buffer size. Buffer size must be >= 237 bytes.
size	Size of encoded data.
mask	Parameters mask - pointer to CameraParamsMask structure. CameraParamsMask (declared in Camera.h file) determines flags for each field (parameter) declared in CameraParams class. If the user wants to exclude any parameters from serialization, he can put a pointer to the mask. If the user wants to exclude a particular parameter from serialization, he should set the corresponding flag in the CameraParamsMask structure.

Returns: TRUE if params encoded (serialized) or FALSE if not.

CameraParamsMask structure declaration:

typedef struct CameraParamsMask
{
    bool width{true};
    bool height{true};
    bool displayMode{true};
    bool videoOutput{true};
    bool logMode{true};
    bool exposureMode{true};
    bool exposureTime{true};
    bool whiteBalanceMode{true};
    bool whiteBalanceArea{true};
    bool wideDynamicRangeMode{true};
    bool stabilizationMode{true};
    bool isoSensitivity{true};
    bool sceneMode{true};
    bool fps{true};
    bool brightnessMode{true};
    bool brightness{true};
    bool contrast{true};
    bool gainMode{true};
    bool gain{true};
    bool sharpeningMode{true};
    bool sharpening{true};
    bool palette{true};
    bool agcMode{true};
    bool shutterMode{true};
    bool shutterPos{true};
    bool shutterSpeed{true};
    bool digitalZoomMode{true};
    bool digitalZoom{true};
    bool exposureCompensationMode{true};
    bool exposureCompensationPosition{true};
    bool defogMode{true};
    bool dehazeMode{true};
    bool noiseReductionMode{true};
    bool blackAndWhiteFilterMode{true};
    bool filterMode{true};
    bool nucMode{true};
    bool autoNucIntervalMsec{true};
    bool imageFlip{true};
    bool ddeMode{true};
    bool ddeLevel{true};
    bool roiX0{true};
    bool roiY0{true};
    bool roiX1{true};
    bool roiY1{true};
    bool temperature{true};
    bool alcGate{true};
    bool sensitivity{true};
    bool changingMode{true};
    bool changingLevel{true};
    bool chromaLevel{true};
    bool detail{true};
    bool profile{true};
    bool isConnected{true};
    bool isOpen{true};
    bool type{true};
    bool custom1{true};
    bool custom2{true};
    bool custom3{true};
} CameraParamsMask;

Example without parameters mask:

// Encode data.
CameraParams in;
in.profile = 10;
uint8_t data[1024];
int size = 0;
in.encode(data, 1024, size);
cout << "Encoded data size: " << size << " bytes" << endl;

Example with parameters mask:

// Prepare params.
CameraParams in;
in.profile = 3;

// Prepare mask.
CameraParamsMask mask;
mask.profile = false; // Exclude profile. Others by default.

// Encode.
uint8_t data[1024];
int size = 0;
in.encode(data, 1024, size, &mask);
cout << "Encoded data size: " << size << " bytes" << endl;

Deserialize camera params

CameraParams class provides the decode(…) method to deserialize camera params (fields of CameraParams class, see Table 4). Deserialization of camera params is necessary when you need to receive params via communication channels. The method automatically recognizes which parameters were serialized by the encode(…) method. The method doesn’t decode the initString field. Method declaration:

bool decode(uint8_t* data, int dataSize);

Parameter	Value
data	Pointer to data buffer with serialized camera params.
dataSize	Size of command data.

Returns: TRUE if params decoded (deserialized) or FALSE if not.

Example:

// Encode data.
CameraParams in;
uint8_t data[1024];
int size = 0;
in.encode(data, 1024, size);
cout << "Encoded data size: " << size << " bytes" << endl;

// Decode data.
CameraParams out;
if (!out.decode(data, size))
    cout << "Can't decode data" << endl;

Read and write camera params to JSON file

Camera library depends on ConfigReader library which provides methods to read params from JSON file and to write params to JSON file. Example of writing and reading params to JSON file:

// Write params to file.
cr::utils::ConfigReader inConfig;
inConfig.set(in, "cameraParams");
inConfig.writeToFile("TestCameraParams.json");

// Read params from file.
cr::utils::ConfigReader outConfig;
if(!outConfig.readFromFile("TestCameraParams.json"))
{
    cout << "Can't open config file" << endl;
    return false;
}

TestCameraParams.json will look like:

{
    "cameraParams": {
        "agcMode": 90,
        "alcGate": 6,
        "autoNucIntervalMsec": 71,
        "blackAndWhiteFilterMode": 238,
        "brightness": 62,
        "brightnessMode": 95,
        "changingLevel": 240.0,
        "changingMode": 138,
        "chromaLevel": 83,
        "contrast": 219,
        "custom1": 215.0,
        "custom2": 19.0,
        "custom3": 135.0,
        "ddeLevel": 13.0,
        "ddeMode": 229,
        "defogMode": 236,
        "dehazeMode": 109,
        "detail": 125,
        "digitalZoom": 201.0,
        "digitalZoomMode": 33,
        "displayMode": 2,
        "exposureCompensationMode": 138,
        "exposureCompensationPosition": 99,
        "exposureMode": 216,
        "exposureTime": 167,
        "filterMode": 188,
        "fps": 133.0,
        "gain": 248,
        "gainMode": 106,
        "height": 79,
        "imageFlip": 100,
        "initString": "dfhglsjirhuhjfb",
        "isoSensitivity": 26,
        "logMode": 168,
        "noiseReductionMode": 178,
        "nucMode": 218,
        "palette": 97,
        "profile": 194,
        "roiX0": 78,
        "roiX1": 39,
        "roiY0": 168,
        "roiY1": 27,
        "sceneMode": 77,
        "sensitivity": 89.0,
        "sharpening": 209,
        "sharpeningMode": 115,
        "shutterMode": 208,
        "shutterPos": 83,
        "shutterSpeed": 53,
        "stabilizationMode": 67,
        "type": 52,
        "videoOutput": 206,
        "whiteBalanceArea": 69,
        "whiteBalanceMode": 10,
        "wideDynamicRangeMode": 106,
        "width": 99
    }
}

Build and connect to your project

Typical commands to build OwlCamera library:

cd OwlCamera 
mkdir build
cd build
cmake ..
make

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

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

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

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

Create CMakeLists.txt file in OwlCamera 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}_SUBMODULE_OWL_CAMERA                      ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_OWL_CAMERA)
    SET(${PARENT}_OWL_CAMERA                            ON  CACHE BOOL "" FORCE)
endif()

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

File 3rdparty/CMakeLists.txt adds folder OwlCamera to your project. Your repository new structure will be:

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

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 OwlCamera library in your src/CMakeLists.txt file:

target_link_libraries(${PROJECT_NAME} OwlCamera)

Done!

Test application

The repository includes a test application (test/main.cpp) to interactively test all supported camera parameters and commands via a serial port. To build and run the test application:

cd OwlCamera
mkdir build
cd build
cmake ..
make
./bin/OwlCameraTest

On startup, the application asks for a serial port name and camera type:

OwlCamera version: 3.0.0
Enter serial port name: /dev/ttyUSB0
Chose camera type (640 or 1280): 1280
Camera opened successfully.

After initialization, the application presents an interactive menu:

-------------------------------------------
Chose command:
0 - Exit
1 - Restart camera
2 - NUC command (set NUC mode to 4)
3 - Set NUC mode
4 - Exposure mode
5 - Exposure time
6 - Gain mode
7 - Gain
8 - Image flip
9 - FPS
10 - AGC mode
11 - Brightness (ALC level)
12 - Custom 1 (TEC set point)
13 - Custom 2 (Peak/Average)
14 - Custom 3 (AGC/ALC speed)
Your option:

---

Table of contents