Table of contents:

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:

Code Block

type MessageName = "OBJECT_STATUS_IND" |    
                   "METER_COUNTER_STATUS_IND" |  
                   "TOTAL_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:

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

...

Table of contents:

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:

Code Block

type MessageName = "OBJECT_STATUS_IND" |    
                   "METER_COUNTER_STATUS_IND" |  
                   "TOTAL_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" | 
                   "SET_LINES_PER_SCREEN" |
                   “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

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:
Image Added
- 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\":1022,\"messageName\":\"ACTION_OBJECT_STATUSTRIGGER_INDREQ\",\"messageType\":\"MONITORINGCONTROL\"},\"payload\":{\"object\":\"levelIndicator1\",\"valuebutton1\":57}}

METERACTION_COUNTEROBJECT_STATUSTRIGGER_INDRESP (Message type: Monitoring Control) – 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)

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\":1022,\"messageName\":\"METERACTION_COUNTEROBJECT_STATUSTRIGGER_INDRESP\",\"messageType\":\"MONITORINGCONTROL\"},\"payload\":{\"valueerror\":320\"errorDescription2\",\"uniterrorCode\":2,\"meterstatus\":false}}

TOTALCHANGE_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 _COUNTER_VALUE_REQ (Message type: Monitoring) (Required Api: V2) -  Control) – this message is sent to update value of inclination in ProTouch. from server to client everytime when meter counter value in ProTouch is changed.  
CHANGE_OBJECT_VALUE_REQ (Message type:
- 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:
Image Removed
- 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>

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

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\":320,\"messageName\":\"CHANGE_METER_OBJECTCOUNTER_VALUE_REQRESP\",\"messageType\":\"CONTROL\"},\"payload\":{\"objecterror\":\"\",\"spinBox2errorCode\":0,\"value\":6}}

CHANGE_OBJECT_VALUE_RESP

(Message type:

Control

- \"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 response on message CHANGE_OBJECT_VALUE_REQ. If request is accepted by client response should have status ok. If not, response should contain errordisplay free text using software OSD on the live video stream in ProTouch.
- 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 descriptiontext: <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\":32,\"messageName\":\"CHANGECREATE_OBJECTFREE_VALUE_RESPTEXT \",\"messageType\":\"CONTROLOSD\"},\"payload\":{\"errortext\":\"errorDescription2messageText76\",\"errorCodex\":2,\"y\":4,\”visible\":6,\"textColor\"status:\"black\",\"backColor\":false\"white\"}}
MOVESET_LINES_OBJECTPER_REQSCREEN (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 clientOSD) - 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:
  - angle value – <int> angle in degrees.
  - power - <double> power in range 0.0 – 1.0
  - object - <string> object id which angle has changed 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):
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):
  - Code Block
    language 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\"}}


    "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\":{\"messageId\":2,\"messageName\":\"ACTIONSTART_OBJECTVIDEO_TRIGGERSTREAMING_RESPREQ\",\"messageType\":\"CONTROLVIDEO\"},\"payload\":{\"errorport\":\"errorDescription2\",\"errorCode\":2,\"status\":false5000}}

CHANGESTART_METER_COUNTERVIDEO_VALUESTREAMING_REQ RESP (Message type:  Control Video) – this message is sent from server to client everytime when meter counter value in ProTouch is changedfrom server to client to response on message START_VIDEO_STREAMING_REQ with IP on which streaming can be started.  
- 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) ip – <string> IP of ProTouch on which video can be streamed by UDP 
- Example message (json)(V1):  
  - {\"header\":{\"messageId\":20102,\"messageName\":\"CHANGESTART_METERVIDEO_COUNTERSTREAMING_VALUE_REQRESP\",\"messageType\":\"CONTROLVIDEO\"},\"payload\":{\"unit\":\"ftip\",:\"value127.0.0.1\":24}}

CHANGESETTING_METER_COUNTER_VALUE_RESP INFO_IND (Message type:  Control Setting) – - 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\"}}

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\":{\"messageId\":102,\"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”
  - width - <optional int> camera resolution’s width
  - height - <optional int> camera resolution’s height
  - value - <optional string> for language: `language_country` string(lowercase two-letter ISO 639 language, underscore, uppercase two- or three-letter ISO 3166 country code)
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”
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
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:

Code Block

language	json

{
	"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:

...

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

Ad hoc free texts with timeout:

Code Block

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 
    }

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. 

...

Versions Compared

Old Version 8

New Version Current

Key

Overview

Document purpose

Current version

Data format

Protocol

API Versioning

API Documentation

Messages struct

Message names

Overview

Document purpose

Current version

Data format

Protocol

API Versioning

API Documentation

Messages struct

Message names

Message types

Video

Page Comparison

Versions Compared

Old Version 8

New Version Current

Key

Overview

Document purpose

Current version

Data format

Protocol

API Versioning

API Documentation

Messages struct

Message names

Overview

Document purpose

Current version

Data format

Protocol

API Versioning

API Documentation

Messages struct

Message names

Message types

Video