...
To trigger a switch to port 1, send text (ASCII):
CMD_ACTIVATE_PORT 1
PROTOCOL SPECIFICATION
OPC3 > RS232
Notification when active port changes
Notification when MTR-mode changes
Notification when there is an ERROR reported on a port
Notification when a laptop is connected or disconnected on a port
Notification when the system enter admin-mode on Port 4
RS232 > OPC3
Switch to selected port. None or 1-4
Change MTR Mode
RS232 Settings
...
RS232 TX: (from the Dongles POV)
COMMAND | PARAMETERS | COMMENT |
|---|---|---|
EVT_PORT_ACTIVE_CHANGE | 0 = No Port active 1-4 = New active port | Just send new bit pattern on active port. Same as HID data. |
EVT_PORT_ERROR <port> | 1-4 = Port no that reported an error |
|
EVT_PORT_CONNECT <port> <bitpattern> | 1-4 = Port that had a USB-C connected <bitpattern> = Value from HID | HID protocol provides bit-pattern on all changes. Need to deduce specific port changes from this. |
EVT_PORT_DISCONNECT <port> <bitpattern> | 1-4 = Port that had a USB-C disconnected <bitpattern> = Value from HID | HID protocol provides bit pattern on all changes. Need to deduce specific port changes from this. |
EVT_ADMIN_STATE_CHANGE | 0 = Left admin mode 1 = Entered admin mode |
|
EVT_MTR_STATE_CHANGE | 0 = MTR Mode Off 2 = MTR Mode On (Android-based) 3 = MTR Mode On (PC-Based) |
|
RS232 TX: (from the Dongles POV)
COMMAND | PARAMETERS | COMMENT |
|---|---|---|
CMD_ACTIVATE_PORT <port> | 0 = No Port active 1-4 = New active port |
|
CMD_SET_MTR_ON |
| Change device to MTR mode |
CMD_SET_MTR_OFF |
| Change device to BYOD mode |
Notification commands
Command format
Every status command is a series of ASCII characters and consist of a command name string, which is uppercase characters, followed by a space (hex 0x20) - separated the parameter of the command. A command may take multiple parameters. All command is terminated by a pair of termination characters: Carriage return (CR, hex 0x0D) and Line feed (LF, hex 0x0A) as almost Window applications support.
...
Command notifies port 1 is active:
EVT_PORT_ACTIVE_CHANGE 1<CRLF>
Parameter strings
Command parameters are expressed as string of ASCII digits. The string is interpreted as a decimal (base 10) value. For example:
Command notifies ports connected:
EVT_PORT_CONNECT 4 12<CRLF>, where the first parameter4indicates that port 4 is just connected (plugged), and the second parameter12(binary0b00001100) is bitpattern value indicates port 3 and 4 are connected.
Command list
Change active port
Command: EVT_PORT_ACTIVE_CHANGE <port_no>
...
Port 4 is active (all OPC3 LEDs is turn on): notify port active change by EVT_PORT_ACTIVE_CHANGE 4
Change MTR-mode
Command: EVT_MTR_STATE_CHANGE <mode_no>
...
Configure MTR on OMC by
Integrated MTR, notify mode change byEVT_MTR_STATE_CHANGE 1Configure MTR on OMC by
PC-base MTR, notify mode change byEVT_MTR_STATE_CHANGE 2Configure MTR on OMC by
Diabled, notify mode change byEVT_MTR_STATE_CHANGE 0
Error port
Command: EVT_PORT_ERROR <port_no>
...
port_no: 1-4 = ERROR reported on port
Connected port
Command: EVT_PORT_CONNECT <port_no> <bitpattern>
...
15, and send notify command: EVT_PORT_CONNECT 4 15.
Disconnected port
Command: EVT_PORT_DISCONNECT <port_no> <bitpattern>
...
15), then disconnect on port 1, so new decimal value is 14, and send notify command: EVT_PORT_DISCONNECT 1 14
Change Admin state
Only port 4 has Admin state.
...
For example: connect USB-C port 4 to computer, then hot the button on the back for 5 seconds, port 4 will enter the Admin mode. Notify Admin state change by EVT_ADMIN_STATE_CHANGE 1.
Control commands
Command format
Every control command is a series of ASCII characters and consist of a command name string, which is uppercase characters, followed by a space (hex 0x20) or horizontal tab (hex 0x09) - separated the parameter of the command. A command may take a single parameter or not. Currently only one command CMD_ACTIVATE_PORT takes a port number parameter. All command must be terminated by a special termination character.
...
Multiple spaces or horizontal tabs between command name and parameter are accepted. For example: CMD_ACTIVATE_PORT 4.
Parameter strings
Command parameters are expressed as string of ASCII digits. The string is interpreted as a decimal (base 10) value. The Command list section will describe detail about parameter of each command.
Termination character
Accept below different termination characters:
...
One of above termination characters must be the last character in ASCII command string.
Length of command strings
Currently, we limited length of control command string by maximum 64 ASCII characters. If the received command length is greater than 64, response error message: ERROR: the received command is too long and we must re-send the command. The received command will be discarded.
Command list
Activate a port
Command: CMD_ACTIVATE_PORT <port_no>
...
For a valid command, response
EVT_PORT_ACTIVE_CHANGEcommand to notify active port change.If a command is invalid, error is responded, and there is no effect in program.
Enter MTR mode
Command: CMD_SET_MTR_ON
Parameters: no parameter
...
For a valid command, response
EVT_MTR_STATE_CHANGEcommand to notify MTR mode change.If a command is invalid, error is responded, and there is no effect in program.
Leave MTR mode
Command: CMD_SET_MTR_OFF
Parameters: no parameter
...
For a valid command, response
EVT_MTR_STATE_CHANGEcommand to notify MTR mode change.If a command is invalid, error is responded, and there is no effect in program.
HDMI power on TV
Command: CMD_HDMI_CEC_ON
Parameters: no parameter
...
For a valid command, there is no response.
If a command is invalid, error is responded, and there is no effect in program.
HDMI power off TV
Command: CMD_HDMI_CEC_OFF
Parameters: no parameter
...
For a valid command, there is no response.
If a command is invalid, error is responded, and there is no effect in program.
Support ASCII control characters
On terminal app, normally there are two type of command line modes:
Line-editing: terminal applications (likes Putty, Hyper Terminal) allow to edit a whole line at a time locally, and the line will only be sent to OPC3 when pressing Return which will send the termination characters.
Non line-editing: every character we type into terminal applications (like Putty, Tera Term is sent immediately, OPC3 supports handling ASCII control characters, so we can edit likes Line-editing mode as below.
Start of line
ASCII control characters marks start of command line: Start of header (SOH, hex 0x01), Start of text (STX, hex 0x02).
End of line
ASCII control characters marks end of command line: Carriage Return (CR, hex 0x0A), Line Feed (LF, hex 0x0D), End of Transmission Block (ETB, hex 0x17). Those characters are termination characters also.
Backspace character
Backspace characters (BS hex 0x08; DEL hex 0x7F) enable move the cursor one space left and delete the character under it. It works similar as pressing Backspace button on the keyboard.
Cancel command line
ASCII control character End of Text (ETX, hex 0x03), End of Transmission (EOT, hex 0x04), Cancle (CAN, hex 0x18), and Substitute (SUB, hex 0x1A), allow to cancel/exit handling the sent characters. All sent character will be discarded, we can type new command.
...
Ctrl + Cto send ETX character.Ctrl + Dto send EOT character.Ctrl + Xto send CAN character.Ctrl + Zto send SUB character.
Arrow keys
Terminal application (likes Putty) can send a control sequence ASCII character by the arrow keys. The arrow keys send ESC [C as right arrow key (cursor forward), and ESC [D as left arrow key (cursor backward). So we can move cursor to edit command as in Line-editing mode.
For up/down arrow keys are not supported, so press them in terminal will have no effect.
Other ASCII control characters and function keys
For other ASCII control characters are not listing above, they are not supported, so if OPC3 receives them, then there is no effect.
...