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: 

Message names 

Messages in grey are not released yet and work on them is in progress.

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

• CHOOSE_API_VERSION (Message type: Setup) - this message is sent to upgrade api version used (V1 is used by default).

  • Payload: 

    • value – <int> [1;2] 

• FORCE_CHOOSING_UNIT (Message type: Setup) - this message can alter default unit displayed on OSD and Dynamic UI panels.

  • Payload:

    • measure - <string>, right now only “distance” is supported

    • unit - <string>, for “distance” there can be set “meters” or “feet” - use null to reset to default

• PING (Message type: Setup) - this is lightweight message that can be used to calculate round-trip time on ProTouch API or simply check if connection is still alive.

  • Payload: none

• PONG (Message type: Setup) - this is response on PING message to ProTouch.

  • Payload: none

• OBJECT_STATUS_IND (Message type: Monitoring) – this message is sent from client to server to update object status when some object’s value on client side has changed.  

  • Payload:  

    • object – <string> id of object, which is to be updated, should be one of supported object, others will be ignored  

    • value – value for updated object, negative will be ignored, server is not responsible for a validation, only displays what receives.  

  • Supported objects:  

    • LevelIndicator – <int> you can change value on indicator in percent (range 0 – 100%)  

    • Spinbox – <int> you can change value on spinbox in percent (range 0 – 100%)  

    • SwitchButton – <bool> you can change value on switch in boolean (true or false)  

    • Label – <text> you can write text on label  

    • Text – <text> you can write text on text element  

  • Example message (json): 

    • {\"header\":{\"messageId\":102,\"messageName\":\"OBJECT_STATUS_IND\",\"messageType\":\"MONITORING\"},\"payload\":{\"object\":\"levelIndicator1\",\"value\":57}} 

• METER_COUNTER_STATUS_IND (Message type: Monitoring) – this message is sent from client to server to update meter counter value when meter counter’s value on client side has changed.  

  • Payload:  

    • value – <float> meter counter value in specified unit – meter or feet 

    • unit – <text> unit of value - "meter" or "feet" 

    • isLateral - <bool> is meter counter lateral (Since Api: V2) 

  • Example message (json):  

    • {\"header\":{\"messageId\":102,\"messageName\":\"METER_COUNTER_STATUS_IND\",\"messageType\":\"MONITORING\"},\"payload\":{\"value\":320, \"unit\":\"meter\"}}  

• TOTAL_METER_COUNTER_STATUS_IND (Message type: Monitoring) - same purpose as METER_COUNTER_STATUS_IND, but for total meter counter.

  • Payload:

    • value – <float> meter counter value in specified unit – meter or feet 

    • unit – <text> unit of value - "meter" or "feet" 

• INCLINATION_VALUE_STATUS_IND (Message type: Monitoring) (Required Api: V2) - this message is sent to update value of inclination in ProTouch. 

  • Payload: 

    • value - <float> 

    • unit - <string> possible units: “rad”, “deg”, “percent” 

• DYNAMIC_UI_VISIBILITY_IND (Message type: Monitoring) - this message can be used to hide Dynamic UI panels. Behavior is same as clicking on button in top left corner:

  Open

  

  • Payload:

    • visible - <bool>

• SHOW_NOTIFICATION_IND (Message type: Monitoring) - this message can be used to show notification to user.

  • Payload:

    • type - <string> possible types: “success”, “info”, “warning”, “error”, “errorWithConfirm”

    • text - <string>

• CHANGE_OBJECT_VALUE_REQ (Message type: Control) – this message is sent from server to client to update object value, when user click on spinbox buttons (“+” or “-“) the value is changed and a new value is sent to client.

  • Payload:  

    • value – <int> new value of object  

    • object - <string> object id which value has changed  

  • Example message (json):  

    • {\"header\":{\"messageId\":3,\"messageName\":\"CHANGE_OBJECT_VALUE_REQ\",\"messageType\":\"CONTROL\"},\"payload\":{\"object\":\"spinBox2\",\"value\":6}}  

• CHANGE_OBJECT_VALUE_RESP (Message type: Control) – this message is sent from client to server to response on message CHANGE_OBJECT_VALUE_REQ. If request is accepted by client response should have status ok. If not, response should contain error.  

  • Payload:  

    • status – <bool> if message was accepted by client it should be true, if error status should be false  

    • errorCode - <int> if message was accepted by client it should be 0, if error occurred, errorCode should be on of available error codes  

    • error - <string> if message was accepted by client it should be empty, if error occurred, error should contain error description.  

  • Example message (json):  

    • {\"header\":{\"messageId\":3,\"messageName\":\"CHANGE_OBJECT_VALUE_RESP\",\"messageType\":\"CONTROL\"},\"payload\":{\"error\":\"errorDescription2\",\"errorCode\":2,\"status\":false}}  

• MOVE_OBJECT_REQ (Message type: Control) – this message is sent from server to client to update object angle, when user click on a joystick the value is changed and new angle is sent to client.

  • Payload:  

    • angle – <int> angle in degrees.  

    • power - <double> power in range 0.0 – 1.0   

    • object - <string> object id which angle has changed  

  • Example message (json):  

    • {\"messageId\":36,\"messageName\":\"MOVE_OBJECT_REQ\",\"messageType\":\"CONTROL\"},\"payload\":{\"angle\":97,\"object\":\"joystick1\",\"power\":0.4729}}  

• MOVE_OBJECT_RESP (Message type: Control) – this message is sent from client to server to response on message MOVE_OBJECT_REQ. If request is accepted by client response should have status ok. If not, response should contain error.  

  • Payload:  

    • status – <bool> if message was accepted by client it should be true, if error status should be false  

    • errorCode - <int> if message was accepted by client it should be 0, if error occurred, errorCode should be on of available error codes  

    • error - <string> if message was accepted by client it should be empty, if error occurred, error should contain error description.  

  • Example message (json):  

    • {\"header\":{\"messageId\":1,\"messageName\":\"MOVE_OBJECT_RESP\",\"messageType\":\"CONTROL\"},\"payload\":{\"error\":\"\",\"errorCode\":0,\"status\":true}}  

• ACTION_OBJECT_TRIGGER_REQ (Message type: Control) – this message is sent from server to client to trigger action on object, when user click on a button the message is sent to client.

  • Payload:  

    • object - <string> object id which button was clicked  

  • Example message (json):  

    • {\"header\":{\"messageId\":2,\"messageName\":\"ACTION_OBJECT_TRIGGER_REQ\",\"messageType\":\"CONTROL\"},\"payload\":{\"object\":\"button1\"}}  

• ACTION_OBJECT_TRIGGER_RESP (Message type: Control) – this message is sent from client to server to response on message ACTION_OBJECT_TRIGGER_REQ. If request is accepted by client response should have status ok. If not, response should contain error.  

  • Payload:  

    • status – <bool> if message was accepted by client it should be true, if error status should be false  

    • Error code - <int> if message was accepted by client it should be 0, if error occurred, error code should be on of available error codes  

    • error - <string> if message was accepted by client it should be empty, if error occurred, error should contain error description.  

  • Example message (json):  

    • {\"header\":{\"messageId\":2,\"messageName\":\"ACTION_OBJECT_TRIGGER_RESP\",\"messageType\":\"CONTROL\"},\"payload\":{\"error\":\"errorDescription2\",\"errorCode\":2,\"status\":false}}  

• CHANGE_METER_COUNTER_VALUE_REQ (Message type: Control) – this message is sent from server to client everytime when meter counter value in ProTouch is changed.   

  • Payload:   

    • value – <double> new meter counter value   

    • unit – <string> unit of meter counter can be “ft” or “m”   

    • isLateral - <bool> is meter counter lateral (Since Api: V2) 

  • Example message (json)(V1):   

    • {\"header\":{\"messageId\":20,\"messageName\":\"CHANGE_METER_COUNTER_VALUE_REQ\",\"messageType\":\"CONTROL\"},\"payload\":{\"unit\":\"ft\",\"value\":24}}  

• CHANGE_METER_COUNTER_VALUE_RESP (Message type: Control) – this message is sent from client to server to response on message CHANGE_METER_COUNTER_VALUE_REQ. If request is accepted by client response should have status ok. If not, response should contain error.   

  • Payload:   

    • status – <bool> if message was accepted by client it should be true, if error status should be false   

    • Error code - <int> if message was accepted by client it should be 0, if error occurred, error code should be on of available error codes   

    • error - <string> if message was accepted by client it should be empty, if error occurred, error should contain error description.   

  • Example message (json):   

    • {\"header\":{\"messageId\":20,\"messageName\":\"CHANGE_METER_COUNTER_VALUE_RESP\",\"messageType\":\"CONTROL\"},\"payload\":{\"error\":\"\",\"errorCode\":0,\"status\":true}}  

• CHANGE_TOTAL_METER_COUNTER_VALUE_REQ (Message type: Control) – same as CHANGE_METER_COUNTER_VALUE_REQ, but for total meter counter

  • Payload:   

    • value – <double> new meter counter value   

    • unit – <string> unit of meter counter can be “ft” or “m”   

• CREATE_FREE_TEXT (Message type: OSD) – this message is sent from client to server to display free text using software OSD on the live video stream in ProTouch.  

  • Payload:  

    • text: <string> content of the message, 

    • x: <number> integer informing about the column in which the text should appear, 

    • y: <number> integer informing about the row in which the text should appear, 

    • visible: <number> range [1;100] informing about the time that value should display for, 

    • textColor: <Color> color of text, 

    • backColor: <Color> color of background.  

  • Example message (json):  

    • {\"header\":{\"messageId\":2,\"messageName\":\"CREATE_FREE_TEXT \",\"messageType\":\"OSD\"},\"payload\":{\"text\":\"messageText76\",\"x\":2,\"y\":4,\”visible\":6,\"textColor\":\"black\",\"backColor\":\"white\"}} 

• SET_LINES_PER_SCREEN (Message type: OSD) - this message is sent from client to server to change the size of text displayed by software OSD, measured by (approximate) number of lines that should fit in entire screen height.

  • Payload:

    • value – <int> number of OSD text lines to fit in total screen height (valid values range from 20 to 60 and exceeding values are clamped to that range; NOTE, that the lower value of linesPerScreen, the larger size of the text).

  • Example message (json):

    • { "header": { "messageName": "SET_LINES_PER_SCREEN", "messageType": "OSD" }, "payload": { "value": 50 } }

• TEXT_OBJECT_SET_TEXT (Message type: OSD) - Used for setting text for one of Text Objects. See OSD:Text Object paragraph for more information.

  • Payload:

    • id: <int>

    • text: <string>

• TEXT_OBJECT_SET_POSITION (Message type: OSD) - Used for setting position in pixels for one of Text Objects. See OSD:Text Object paragraph for more information.

  • Payload:

    • id: <int>

    • position: <object>:

      • x: <int>

      • y: <int>

• TEXT_OBJECT_SET_VISIBILITY (Message type: OSD) - Used for setting visibility for one of Text Objects. See OSD:Text Object paragraph for more information.

  • Payload:

    • id: <int>

    • visible: <bool>

• TEXT_OBJECT_SET_TEXT_COLOR (Message type: OSD) - Used for setting text color for one of Text Objects. See OSD:Text Object paragraph for more information.

  • Payload:

    • id: <int>

    • color: <string> in format “#RRGGBB”

• TEXT_OBJECT_SET_BACK_COLOR (Message type: OSD) - Used for setting background color for one of Text Objects. See OSD:Text Object paragraph for more information.

  • Payload:

    • id: <int>

    • color: <string> in format “#RRGGBB”

• START_VIDEO_STREAMING_REQ (Message type: Video) – this message is sent from client to server when client wants to start UDP video streaming on ProTouch.   

  • Payload:   

    • port – <int> port for video streaming    

  • Example message (json):   

    • {{\"header\":{\"messageName\":\"START_VIDEO_STREAMING_REQ\",\"messageType\":\"VIDEO\"},\"payload\":{\"port\":5000}}    

• START_VIDEO_STREAMING_RESP (Message type: Video) – this message is sent from server to client to response on message START_VIDEO_STREAMING_REQ with IP on which streaming can be started.   

  • Payload:   

    • ip – <string> IP of ProTouch on which video can be streamed by UDP  

  • Example message (json):   

    • {\"header\":{\"messageId\":102,\"messageName\":\"START_VIDEO_STREAMING_RESP\",\"messageType\":\"VIDEO\"},\"payload\":{\"ip\":\"127.0.0.1\"}}  

• SETTING_INFO_IND (Message type: Setting) - this message is sent from ProTouch when particular application setting has been changed.

  • Payload:

    • setting - <string> what setting has been changed, supported now: “cameraResolution”, “language”, “linesPerScreen”

    • width - <optional int> camera resolution’s width

    • height - <optional int> camera resolution’s height

    • value - depending on setting:

      • for language: <optional string> language_country string (lowercase two-letter ISO 639 language, underscore, uppercase two- or three-letter ISO 3166 country code)

      • for applicationVersion: <optional string> version string

      • for linesPerScreen: <optional int> parameter determining size of OSD text (see SET_LINES_PER_SCREEN message for more info)

• SETTING_INFO_REQ (Message type: Setting) - this message is sent to ProTouch to query setting, ex. because application has started and there was no change to being indicate via SETTING_INFO_IND

  • Payload:

    • setting - <string> supported now: “cameraResolution”, “language”, “applicationVersion” or “linesPerScreen”

• SETTING_INFO_RESP (Message type: Setting) - this is response on SETTING_INFO_REQ

  • Payload - exactly the same as SETTING_INFO_IND

• 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

• ARRAY (Message type: BULK) - this message is used for send multiple messages at once.

  • Payload:

    • messages - <array> array of messages

  • Example message:

    { "header": { "messageType": "BULK", "messageName": "ARRAY" }, "payload": { "messages": [ { "header": { "messageType": "OSD", "messageName": "TEXT_OBJECT_SET_POSITION" }, "payload": { "id": 7, position: { "x": 10, "y": 20 } } }, { "header": { "messageType": "OSD", "messageName": "TEXT_OBJECT_SET_TEXT" }, "payload": { "id": 7, "text": "sample text" } }, { "header": { "messageType": "OSD", "messageName": "TEXT_OBJECT_SET_VISIBILITY" }, "payload": { "id": 7, "visible": true } }, { "header": { "messageType": "OSD", "messageName": "TEXT_OBJECT_SET_TEXT_COLOR" }, "payload": { "id": 7, "color": "#00FF00" } }, { "header": { "messageType": "OSD", "messageName": "TEXT_OBJECT_SET_BACK_COLOR" }, "payload": { "id": 7, "color": "#FFFFFF" } } ] } }

Message types

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

• Control, 

• Monitoring, 

• OSD, 

• Video,

• Setup,

• Setting,

• Status.

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.: 

• Meter counter value,  

• Light’s state and value,  

• Sonde value. 

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.  

Ad hoc free texts with timeout:

OSD:Text Objects

Additionally there are 20 text objects that can be freely edited in terms of content, position, visibility and colors. By default they are not visible in unspecified state, so make sure to initialize every property on first use of given identifier. You can use identifiers from 0 to 19. Colors can be any from #000000 to #FFFFFF.

Configuration is not saved between ProTouch restarts, so you need to reinitialize it on every start.

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: 

1. Configuration, ROUTER, TCP, port 52943.

It is used to define controls, using the following JSON shape:

1. Events (from controls) PUB, TCP, port 52944.

Events from that socket are also forwarded in ProTouch API in CONTROL messages.

Reference implementation of this API can also be found in Simulator. 

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: 

This is a very simple application that allows you to connect with ProTouch and control it with a help of ProTouch API. Windows executable and the entire source code is available on our GitHub. The application contains 4 main parts: 

1. First one which is: “Connection box”. In there you can connect to server. By default, the connection parameters are: localhost (127.0.0.1) on port 8095 (if they are not changed there is no need to provide them).  After a click on the “Connect to server” button the application will attempt to connect into ProTouch and the status on status information bar will update. 

2. The second box is for MONITORING messages.

3. The third box is for CONTROL, SETTING and SETUP messages.

   1. “Control message’s response” is responsible for simulating response messages such as:  

      1. CHANGE_OBJECT_VALUE_RESP,   

      2. MOVE_OBJECT_RESP,  

      3. ACTION_OBJECT_TRIGGER_RESP, 

      4. CHANGE_METER_COUNTER_VALUE_RESP.

         You can create payload for these messages by providing status, errorCode and error. You can also ignore messages by clicking “Ignore messages” for example to test error handling timeout, etc.

   2. “Setting” is responsible for SETTING_INFO_REQ. Response can be found in “Messages received” box

   3. “Setup” is for  PING and FORCE_CHOOSING_UNIT.

4. The fourth box is "Video Message" for simulating START_VIDEO_STREAMING_REQ with port as parameter.  

5. There is a box "Create free text" where you can send CREATE_FREE_TEXT message to OSD on server.  

6. On the bottom there is text area where client can see messages, which are sent from server.

To test if video streaming by UDP is correct you can use ProTouch’s GStreamer libraries via UDP Video tab in simulator or call gstreamer command (below), where IP should be the same as in START_VIDEO_STREAMING_RESP and port from START_VIDEO_STREAMING_REQ: 

gst-launch-1.0 autovideosrc is-live=true do-timestamp=true ! autovideoconvert ! queue leaky=downstream ! x264enc tune=zerolatency ! h264parse ! rtph264pay pt=96 ! udpsink host=127.0.0.1 port=5000 

Open