Table of contents:

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. 

Version: 2022.2.0 

Line-delimited JSON 

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

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. 

A standard message should have a following structure: 

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

• FORCE_CUSTOM_SETTING (Message type: Setup) - this message can be used for manual changes for subset of values from SETTING_INFO_IND

  • Payload:

    • setting - <string>, supported right now: “connectionStatus”, “powerStatus”, “batteryLevel”

    • value: <string or int or null>, <string> - status suffix, int - level suffix, null - give control back to PT

      • for connectionStatus and powerStatus: <string> - “On”, “Off” or “Hidden” denoting state of status icon

      • for batteryLevel: <int> - from 0 to 100 to set battery level, ‘-1’ to hide battery level status icon

• 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” , “connectionStatus”, “batteryLevel”, “powerStatus”

    • 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)

      • for connectionStatus and powerStatus: <bool> indicating current status

      • for batteryLevel: <int> indicating current battery level

• 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”, “linesPerScreen”, “connectionStatus”, “batteryLevel”, “powerStatus”

• 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" } } ] } }

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