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

...

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

...

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

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) (Required Api: V2) - this message is sent to update value of inclination in ProTouch. can be used to show notification to user.
- Payload:
  - value type - <float> unit - <string> possible units: “rad”, “deg”, “percent”
DYNAMIC_UI_VISIBILITY_IND
- - types: “success”, “info”, “warning”, “error”, “errorWithConfirm”
  - text - <string>

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

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_REQRESP (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.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:
  - value – <int> new value of object
  - object - <string> object id which value has changed 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_REQRESP\",\"messageType\":\"CONTROL\"},\"payload\":{\"objecterror\":\"errorDescription2\"spinBox2,\"errorCode\":2,\"valuestatus\":6false}}

CHANGEMOVE_OBJECT_VALUE_RESPREQ (Message type: Control) – this message is sent from server to 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. update object angle, when user click on a joystick the value is changed and new angle is sent to client.
- 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. 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):
  - {\"header\":{\"messageId\":336,\"messageName\":\"CHANGEMOVE_OBJECT_VALUE_RESPREQ\",\"messageType\":\"CONTROL\"},\"payload\":{\"errorangle\":97,\"errorDescription2object\",:\"errorCodejoystick1\":2,\"statuspower\":false0.4729}}

MOVE_OBJECT_REQRESP (Message type: Control) – this message is sent from client to server to client to update object angle, when user click on a joystick the value is changed and new angle is sent to client.response on message MOVE_OBJECT_REQ. If request is accepted by client response should have status ok. If not, response should contain error.
- Payload:
  - angle – <int> angle in degrees.
  - power - <double> power in range 0.0 – 1.0
  - object - <string> object id which angle has changed 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.
- 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\":361,\"messageName\":\"MOVE_OBJECT_REQRESP\",\"messageType\":\"CONTROL\"},\"payload\":{\"angleerror\":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.
- - \",\"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\":12,\"messageName\":\"MOVEACTION_OBJECT_TRIGGER_RESPREQ\",\"messageType\":\"CONTROL\"},\"payload\":{\"errorobject\":\"button1\",\"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 }}

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_REQRESP\",\"messageType\":\"CONTROL\"},\"payload\":{\"objecterror\":\"errorDescription2\"button1,\"errorCode\":2,\"status\":false}}

ACTIONCHANGE_METER_OBJECTCOUNTER_TRIGGERVALUE_RESPREQ (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):

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\":220,\"messageName\":\"ACTIONCHANGE_METER_OBJECTCOUNTER_TRIGGERVALUE_RESPREQ\",\"messageType\":\"CONTROL\"},\"payload\":{\"errorunit\":\"errorDescription2ft\",\"errorCodevalue\":2,\"status\":false24}}

CHANGE_METER_COUNTER_VALUE_REQ RESP (Message type: Control) – this message is sent from server to client everytime when meter counter value in ProTouch is changedfrom 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:  
  - 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) 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)(V1):  
  - {\"header\":{\"messageId\":20,\"messageName\":\"CHANGE_METER_COUNTER_VALUE_REQRESP\",\"messageType\":\"CONTROL\"},\"payload\":{\"uniterror\":\"ft\",\"errorCode\":0,\"valuestatus\":24true}}

CHANGE_TOTAL_METER_COUNTER_VALUE_REQ (Message type: Control) – same as CHANGE_METER_COUNTER_VALUE_RESP 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:  Control OSD) – 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.  

display free text using software OSD on the live video stream in ProTouch.

CREATE_FREE_TEXT

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\":202,\"messageName\":\"CHANGECREATE_METER_COUNTER_VALUE_RESPFREE_TEXT \",\"messageType\":\"CONTROLOSD\"},\"payload\":{\"errortext\":\"messageText76\",\"errorCodex\":02,\"y\"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”

- - :4,\”visible\":6,\"textColor\":\"black\",\"backColor\":\"white\"}}
backColor: <Color> color of background.
SET_LINES_PER_SCREEN (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,

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):
- Code Block
  language json
  {
  \
  "header
  \
  ":
  {\"messageId\":2,\"messageName\":\"CREATE_FREE_TEXT \",\"messageType\":\"OSD\"},\"payload\":{\"text\":\"messageText76\",\"x\":2,\"y\":4,\”visible\":6,\"textColor\":\"black\",\"backColor\":\"white\"}}
  { "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>
  - 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\":102,\"messageName\":\"START_VIDEO_STREAMING_REQ\",\"messageType\":\"VIDEO\"},\"payload\":{\"port\":5000}}

...

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>
    for
    - language
    : `language
    - _
    country`
    - country string (lowercase two-letter ISO 639 language, underscore, uppercase two- or three-letter ISO 3166 country code)
    or version string
    - 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 “applicationVersion”“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,
					"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"
				}
			}
		]
	}
}

...

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 11

New Version 12

Key

Overview

Document purpose

Overview

Document purpose

Message names

Video

Page Comparison

Versions Compared

Old Version 11

New Version 12

Key

Overview

Document purpose

Overview

Document purpose

Message names

Video