Table of contents:

Overview

Document purpose

This document is meant to be a documentation of the ProTouch API that gives our users the possibility to connect with ProTouch, interact, display texts on video and control vendor’s device using our application’s user interface. ProTouch API is a network API to control device that do not certainly needs to be available on the same machine. There is a possibility to control devices in the same network that our application is connected to. 

Current version

Version: 2022.2.0 

Data format 

Line-delimited JSON 

Protocol

Standard TCP will be used as a communication protocol over configurable port (available on ProTouch settings – Device Control tab). 

API Versioning 

To maintain backward compatibility there is included API versioning. By default, version 1 is used and if you want to use newer features, you need to change api version by SETUP: CHOOSE_API_VERSION before using its features. 

API Documentation 

Messages struct 

A standard message should have a following structure: 

type MessageName = "OBJECT_STATUS_IND" |    
                   "METER_COUNTER_STATUS_IND" |  
                   “INCLINATION_VALUE_STATUS_IND” | //since V2 
                   "DYNAMIC_UI_VISIBILITY_IND" |
                   "SHOW_NOTIFICATION_IND" |
                   "CHANGE_OBJECT_VALUE_REQ" |  
                   "CHANGE_OBJECT_VALUE_RESP" |  
                   "MOVE_OBJECT_REQ" |  
                   "MOVE_OBJECT_RESP" |  
                   "ACTION_OBJECT_TRIGGER_REQ" |  
                   "ACTION_OBJECT_TRIGGER_RESP" |  
                   "CREATE_FREE_TEXT" | 
                   “CHOOSE_API_VERSION” |
                   "FORCE_CHOOSING_UNIT" |
                   "PING" |
                   "PONG" |
                   "SETTING_INFO_REQ" |
                   "SETTING_INFO_RESP" |
                   "SETTING_INFO_IND" |
                   "REMOTE_INFO_IND" |
                   "APPLICATION_CLOSED"

type MessageType = "CONTROL" | "MONITORING" | "OSD" | "VIDEO" | “SETUP” | "SETTING" | "STATUS"

type Message = { 
    header: { 
        messageId: uint // unique id for message 
        messageName: MessageName // one of supported message names 
        messageType: MessageType // one of supported message types   
    }, 
    payload: { 
        // specific for concrete message 
    } 
} 

Message names 

Every single message has its name. This name informs ProTouch about the reason for it being sent. Available message names are:  

...

• REMOTE_INFO_IND (Message type: Setting) - once this message will be received, there will be new tab available in Settings/Help with System Status label, which will contain content of last REMOTE_INFO_IND

  • Payload:

    • text - <string> can be multiline according to escape rules in standard JSON

• APPLICATION_CLOSED (Message type: Status) - this message is sent from ProTouch when application is about to close, e.g. User presses X (closing button) and accepts the prompt.

  • Payload: none

Message types

There are several types of messages that can be sent. Those can be:  

...

Every type is being used for a different purpose.  

Control

Control message is the one that is being used for device parameters manipulation. The user can use those messages to change values of the previously registered parameters. In the initialization phase of communication application should inform ProTouch about the parameters that should be controlled via our predefined control panel. In this moment ProTouch waits for all the elements on that panel to be initialized. Panel elements that correspond to the given parameter will only be enabled if they are previously registered.  

Monitoring

Monitoring message is the one that is being used for device parameters display. The connected device should inform ProTouch about every value change of the given parameters for e.g.: 

...

Warning! Value placeholders will display “n/a” label until the device provides the initial value. 

OSD

OSD message is the one that is being used for displaying overlay texts on live video. With a help of that message the device is able to add and manage the overlay texts content, position, color and display duration.  

type Color = "Black" | "DarkBlue" | "DarkGreen" | "DarkCyan" |
 "DarkRed" | "DarkMagenta" | "Brown" | "Gray" | "DarkGray" | "Blue" 
 | "Green" | "Cyan" | "Red" | "Magenta" | "Yellow" | "White 

type CreateFreeText = { 
    header: { 
        messageName: "CREATE_FREE_TEXT" 
        messagetType: "OSD" 
    }, 
    payload: { 
        text: string, 
        x: number, //integer 
        y: number, 
        visible: number //range [1;100] 
        textColor: Color 
        backColor: Color 
    } 

Video

Video message is the one that is being used for configuration and management of video streaming in ProTouch.  

Setup

Setup message is usually used at the beginning of connection with server, right now it allows to upgrade api version by CHOOSE_API_VERSION. 

Settings

Setting message is usually used to query or being reported about some change in configuration, like camera resolution of application language.

Status

Status message informs about changing status of an application which isn’t related to domain data nor device configuration.

Dynamic UI API

Dynamic UI is orthogonal to ProTouch API, however it is required to define controls for CONTROL part of ProTouch API. It uses two ZMQ sockets: 

...

To reduce message size, there some abbreviations can be used, like “pr” for “properties”. Full list of available abbreviations can be found in in config/DynamicUiShortcutAliases.json.default located where ProTouch is installed, usually C:\Program Files\WinCan\ProTouch or /opt/WinCan/ProTouch. You can change list if abbreviations, but to apply changes, you have to remove .default from extension.

Simulator

To integrate your application with ProTouch there is a possibility to use our open-source simulator available at: 

...