API Reference

This document provides a complete API reference for the CPP StreamDock SDK.

DeviceManager Class

The device manager for enumerating and managing StreamDock devices.

Static Methods

instance()

static DeviceManager& instance();

Get the singleton instance of DeviceManager.

Returns: DeviceManager reference

Instance Methods

enumerator()

void enumerator();

Enumerate currently connected StreamDock devices.

listen()

void listen(std::function<void(std::shared_ptr<StreamDock>)> connect_and_run = nullptr);

Start background thread to listen for device plug/unplug events.

Parameters:

  • connect_and_run: Optional callback function to execute when new device connects

stopListen()

void stopListen();

Stop device listening thread.

getStreamDocks()

std::unordered_map<std::string, std::shared_ptr<StreamDock>>& getStreamDocks();

Get all currently connected StreamDock devices.

Returns: Device map with key as device path and value as device object

StreamDock Class

Base class for StreamDock devices, providing basic device control functionality.

Initialization Methods

init()

void init();

Initialize StreamDock device and all internal components.

initImgHelper()

void initImgHelper();

Initialize internal image helpers (background, keys, second screen, etc.).

Device Information Methods

getFirmwareVersion()

std::string getFirmwareVersion();

Get device firmware version.

Returns: Firmware version string

info()

StreamDockInfo* info();

Get device metadata.

Returns: StreamDockInfo pointer

feature()

FeatureOption* feature();

Get supported feature options.

Returns: FeatureOption pointer

Screen Control Methods

wakeupScreen()

virtual void wakeupScreen();

Wake up device screen.

setKeyBrightness()

virtual void setKeyBrightness(uint8_t brightness);

Set device key brightness.

Parameters:

  • brightness: Brightness level (usually 0-100)

sleep()

virtual void sleep();

Put device into sleep mode.

refresh()

virtual void refresh();

Refresh display.

Key Control Methods

clearAllKeys()

virtual void clearAllKeys();

Clear all key images.

clearKey()

virtual void clearKey(uint8_t keyValue);

Clear specified key image.

Parameters:

  • keyValue: Key index

Image Setting Methods

setKeyImgFile()

virtual void setKeyImgFile(const std::string& filePath, uint8_t keyValue);

Set key image from file.

Parameters:

  • filePath: Image file path
  • keyValue: Target key index

setKeyImgFileStream()

virtual void setKeyImgFileStream(const std::string& stream, uint8_t keyValue);

Set key image from data stream.

Parameters:

  • stream: Image data stream
  • keyValue: Target key index

setBackgroundImgFile()

virtual void setBackgroundImgFile(const std::string& filePath, uint32_t timeoutMs = 3000);

Set background image from file.

Parameters:

  • filePath: Image file path
  • timeoutMs: Timeout in milliseconds

setBackgroundImgStream()

virtual void setBackgroundImgStream(const std::string& stream, uint32_t timeoutMs = 3000);

Set background image from data stream.

Parameters:

  • stream: Image data stream
  • timeoutMs: Timeout in milliseconds

Connection Management Methods

disconnected()

virtual void disconnected();

Disconnect device.

heartbeat()

virtual void heartbeat();

Send heartbeat signal.

Function Controller Methods

reader()

IReadController* reader();

Get input read controller.

Returns: IReadController pointer

rgber()

IRGBController* rgber();

Get RGB controller.

Returns: IRGBController pointer

gifer()

IGifController* gifer();

Get GIF animation controller.

Returns: IGifController pointer

configer()

IConfiger* configer();

Get configuration controller.

Returns: IConfiger pointer

heartbeater()

IHeartBeat* heartbeater();

Get heartbeat controller.

Returns: IHeartBeat pointer

Image Processing Methods

setEncoder()

void setEncoder(std::shared_ptr<IImageEncoder> encoder);

Set image encoder.

Parameters:

  • encoder: Shared pointer to image encoder

getBgImgHelper()

std::shared_ptr<ImgHelper> getBgImgHelper() const;

Get background image helper.

Returns: ImgHelper shared pointer

getKyImgHelper()

std::shared_ptr<ImgHelper> getKyImgHelper(uint16_t keyValue = 0) const;

Get key image helper.

Parameters:

  • keyValue: Key index

Returns: ImgHelper shared pointer

Static Utility Methods

readImgToString()

static std::string readImgToString(const std::string& jpgPath);

Read image file and return as byte stream.

Parameters:

  • jpgPath: JPEG image path

Returns: Byte string of image data

isStreamDockHidDevice()

static bool isStreamDockHidDevice(const hid_device_info& device);

Check if device is a valid StreamDock HID device.

Parameters:

  • device: HID device info

Returns: true if it's a StreamDock device

isJpegData()

static bool isJpegData(const std::string& originData);

Check if given data is JPEG encoded.

Parameters:

  • originData: Original data

Returns: true if it's JPEG data

isPngData()

static bool isPngData(const std::string& originData);

Check if given data is PNG encoded.

Parameters:

  • originData: Original data

Returns: true if it's PNG data

readGifToStream()

static std::vector<std::vector<uint8_t>> readGifToStream(const std::string& filePath,
                                                        std::shared_ptr<IImageEncoder> encoder,
                                                        const ImgHelper& helper);

Read GIF file and split into encoded image frames.

Parameters:

  • filePath: GIF file path
  • encoder: Image encoder
  • helper: Image helper

Returns: Vector of byte arrays of image frames

IReadController Interface

Input read controller for handling device input events.

Methods

read()

virtual std::vector<uint8_t> read(int32_t timeoutMs = -1) = 0;

Read data from device.

Parameters:

  • timeoutMs: Timeout in milliseconds, -1 means blocking read

Returns: Vector of read data

registerReadCallback()

virtual void registerReadCallback(uint8_t realValue, ReadCallback callback,
                               RegisterEvent event = RegisterEvent::EveryThing,
                               bool callbackAsync = false) = 0;

Register key event callback.

Parameters:

  • realValue: Actual key value
  • callback: Callback function
  • event: Event type
  • callbackAsync: Whether to execute callback asynchronously

unregisterReadCallback()

virtual void unregisterReadCallback(uint8_t realValue, RegisterEvent event) = 0;

Unregister key event callback.

Parameters:

  • realValue: Actual key value
  • event: Event type

registerRawReadCallback()

virtual void registerRawReadCallback(RawReadCallback callback, bool callbackAsync = false) = 0;

Register raw read callback.

Parameters:

  • callback: Callback function
  • callbackAsync: Whether to execute callback asynchronously

unregisterRawReadCallback()

virtual void unregisterRawReadCallback() = 0;

Unregister raw read callback.

startReadLoop()

virtual void startReadLoop() = 0;

Start read loop.

stopReadLoop()

virtual void stopReadLoop() = 0;

Stop read loop.

IRGBController Interface

RGB controller for controlling device LED lights.

Methods

setLedBrightness()

virtual void setLedBrightness(uint8_t brightness) = 0;

Set LED brightness.

Parameters:

  • brightness: Brightness level (usually 0-100)

setLedColor()

virtual void setLedColor(uint8_t red, uint8_t green, uint8_t blue) = 0;

Set LED color.

Parameters:

  • red: Red component (0-255)
  • green: Green component (0-255)
  • blue: Blue component (0-255)

resetLedColor()

virtual void resetLedColor() = 0;

Reset LED color.

IGifController Interface

GIF animation controller for handling GIF animations.

Methods

setKeyGifFile()

virtual void setKeyGifFile(const std::string& gifPath, uint8_t keyValue, uint16_t gifDelay = 100) = 0;

Set key GIF file.

Parameters:

  • gifPath: GIF file path
  • keyValue: Target key index
  • gifDelay: GIF delay in milliseconds

setKeyGifStream()

virtual void setKeyGifStream(const std::vector<std::string>& gifStream, uint8_t keyValue, uint16_t gifDelay = 100) = 0;
virtual void setKeyGifStream(const std::vector<std::vector<uint8_t>>& gifStream, uint8_t keyValue, uint16_t gifDelay = 100) = 0;

Set key GIF data stream.

Parameters:

  • gifStream: GIF data stream
  • keyValue: Target key index
  • gifDelay: GIF delay in milliseconds

setBackgroundGifFile()

virtual void setBackgroundGifFile(const std::string& gifPath, int16_t background_place_x = 0,
                                int16_t background_place_y = 0, uint16_t gifDelay = 100,
                                uint8_t FBlayer = 0x00) = 0;

Set background GIF file.

Parameters:

  • gifPath: GIF file path
  • background_place_x: Background X position
  • background_place_y: Background Y position
  • gifDelay: GIF delay in milliseconds
  • FBlayer: Frame buffer layer

startGifLoop()

virtual void startGifLoop() = 0;

Start GIF loop.

stopGifLoop()

virtual void stopGifLoop() = 0;

Stop GIF loop.

TransportCWrapper Class

Transport layer C++ wrapper providing C++ interface for HID device operations.

Constructor and Destructor

TransportCWrapper()

explicit TransportCWrapper(const hid_device_info& device_info);

Initialize connection using device information.

Parameters:

  • device_info: HID device information

~TransportCWrapper()

~TransportCWrapper();

Destructor, automatically releases resources.

Basic Communication Methods

canWrite()

bool canWrite() const;

Check if device is writable.

Returns: true if writable

read()

void read(uint8_t* response, size_t* length, int32_t timeoutMs = -1) const;

Read data from device.

Parameters:

  • response: Output buffer
  • length: Buffer size on input, actual bytes read on output
  • timeoutMs: Timeout in milliseconds

getFirmwareVesion()

std::string getFirmwareVesion() const;

Get firmware version.

Returns: Firmware version string

Screen Control Methods

wakeupScreen()

void wakeupScreen() const;

Wake up screen.

setKeyBrightness()

void setKeyBrightness(uint8_t brightness) const;

Set key brightness.

Parameters:

  • brightness: Brightness level

refresh()

void refresh() const;

Refresh display.

sleep()

void sleep() const;

Put device into sleep mode.

Key Control Methods

clearAllKeys()

void clearAllKeys() const;

Clear all keys.

clearKey()

void clearKey(uint8_t key_value) const;

Clear specified key.

Parameters:

  • key_value: Key value

Image Transfer Methods

setKeyImgFileStream()

void setKeyImgFileStream(const std::string& jpegData, uint8_t keyValue) const;

Set key image stream.

Parameters:

  • jpegData: JPEG image data
  • keyValue: Target key index

setBackgroundImgStream()

void setBackgroundImgStream(const std::string& jpegData, int32_t timeoutMs = 3000) const;

Set background image stream.

Parameters:

  • jpegData: JPEG image data
  • timeoutMs: Timeout in milliseconds

setBackgroundBitmap()

void setBackgroundBitmap(const std::string& bitmapStream, int32_t timeoutMs = 5000) const;

Set background bitmap.

Parameters:

  • bitmapStream: Bitmap data stream
  • timeoutMs: Timeout in milliseconds

LED Control Methods

setLedBrightness()

void setLedBrightness(uint8_t brightness) const;

Set LED brightness.

Parameters:

  • brightness: Brightness level

setLedColor()

void setLedColor(uint16_t count, uint8_t r, uint8_t g, uint8_t b) const;

Set LED color.

Parameters:

  • count: LED count
  • r: Red component
  • g: Green component
  • b: Blue component

resetLedColor()

void resetLedColor() const;

Reset LED color.

K1 Pro Keyboard Control Methods

The following methods are specific to K1 Pro device keyboard control functionality:

setKeyboardBacklightBrightness()

void setKeyboardBacklightBrightness(uint8_t brightness) const;

Set keyboard backlight brightness.

Parameters:

  • brightness: Brightness value (0-6)

setKeyboardLightingEffects()

void setKeyboardLightingEffects(uint8_t effect) const;

Set keyboard lighting effects.

Parameters:

  • effect: Effect mode identifier (0-9), 0 for static lighting

setKeyboardLightingSpeed()

void setKeyboardLightingSpeed(uint8_t speed) const;

Set keyboard lighting effect speed.

Parameters:

  • speed: Lighting effect speed value (0-7)

setKeyboardRgbBacklight()

void setKeyboardRgbBacklight(uint8_t r, uint8_t g, uint8_t b) const;

Set keyboard RGB backlight color.

Parameters:

  • r: Red component (0-255)
  • g: Green component (0-255)
  • b: Blue component (0-255)

keyboardOsModeSwitch()

void keyboardOsModeSwitch(uint8_t osMode) const;

Set keyboard OS mode.

Parameters:

  • osMode: OS mode identifier (Windows/Mac)

Connection Management Methods

disconnected()

void disconnected() const;

Disconnect.

heartbeat()

void heartbeat() const;

Send heartbeat packet.

Static Methods

disableOutput()

static void disableOutput(bool isDisable = true);

Disable underlying output.

Parameters:

  • isDisable: Whether to disable output

Enum Types

RegisterEvent

Registration event types for specifying callback trigger events.

enum class RegisterEvent {
    EveryThing,    // All events
    KeyPress,      // Key press
    KeyRelease,    // Key release
    KnobLeft,      // Knob turn left
    KnobRight,     // Knob turn right
    KnobPress,     // Knob press
    KnobRelease,   // Knob release
    SwipeLeft,     // Swipe left
    SwipeRight,    // Swipe right
    ToggleUp,      // Toggle up
    ToggleDown     // Toggle down
};

DeviceOriginType

Device original type for identifying different StreamDock device models.

enum class DeviceOriginType {
    SD293,         // StreamDock 293
    SD293s,        // StreamDock 293s
    SDN1,          // StreamDock N1
    SDN3,          // StreamDock N3
    SDN4,          // StreamDock N4
    SDN4Pro,       // StreamDock N4Pro
    SDM3,          // StreamDock M3
    SDM18,         // StreamDock M18
    SDXL,          // StreamDock XL
    SDK1Pro        // K1 Pro
};

Callback Function Types

ReadCallback

Key event callback function type.

using ReadCallback = std::function<void()>;

RawReadCallback

Raw read callback function type.

using RawReadCallback = std::function<void(const std::vector<uint8_t>&)>;
Last Updated:
Contributors: JKWTCN