# (內部版) ASI-KVM -- TCP Protocol Reference Guide

* Protocol version: 6
* Document update: May 24 ,2023

:::danger
-- 關於版號與版本管理：目前並沒有正式的 Protocol 版號編碼機制，故 "Protocol version" 僅供內部溝通、參考使用。
:::

:::success
-- 後續文件擴展工作：待 ASI-KVM "SDK" 計畫啟動後 (目前無此產品線與客戶)，再協助整理 ASI-KVM 權限真值表，或是狀態轉換表文件。
:::

---

## 概觀

### 目的

ASI-KVM，為 "權控" 專案推出的硬體解決方案。其內建乙太網路介面並提供 TCP based protocol，供 guest Apps (TCP client) 操作 host machine 之鍵盤與滑鼠。Protocol Reference Guide 則提供 TCP protoocl規格說明。

### 其他工程文件

工程文件可能並未全部公開，請洽硬體開發部，或是生產部取得讀取權限。

* [ASI-KVM and NAT Transport User Manual](https://docs.google.com/document/d/1e1ZdLTCRkzIKtJjdoKxA1KyRRI3TTJe3k2RdLQQy8Xo/edit?usp=sharing)
* [ASI-KVM Service Manual](https://docs.google.com/document/d/1K6RgKonCGopvEPvl_Uzqca9VqCpnSL3Oh_sA33ZhFKo/edit?usp=sharing)
* [(內部版) ASI-KVM – C# SDK User Manual](https://hackmd.io/o-EYK9LpRDauq1dvrzGaDw?view)

### 維運資訊暨出廠預設值說明

#### 乙太網孔使用說明

ASI-KVM 內附一個有 NAT 功能的乙太網路 router，並對外開放兩個乙太網路孔，分別標示為 Device 和 ETH。

Device 網孔位於 NAT 之下，可用於直接由內部連線至 ASI-KVM (建議開發、工程人員使用)，或是進行 router 設定等。ETH 網孔即為 NAT 之上的 WLAN port，提供 user、其他設備連線使用。

相關出廠預設值如下。若有外觀貼紙，或是出貨說明文件，則以貼紙、文件文準。

##### ASI-KVM 出廠預設值

ASI-KVM / TCP API port: 2049

##### ETH 網孔出廠預設值

* Static IP: 172.16.168.42
* Subnet mask: 255.255.0.0
* Gateway: 172.16.168.42
* DNS: 8.8.8.8, 1.1.1.1
* NAT traversal
* ipeps_DA -- 192.168.1.42:5900
* ASI_KVM -- 192.168.1.202:2049

##### Device 網孔出廠預設值

* IP: 192.168.1.1
* Subnet: 255.255.0.0
* DHCP server: yes, IP range: 192.168.1.101 ~ 192.168.1.150

#### 乙太網孔出廠標示建議

##### ETH 網孔

建議標示目前是原廠設定，或是已配合 user 環境變更 (static IP, DHCP client, ...)。

##### Device 網孔

建議標示 "DHCP client"，也可以加上 DHCP IP 範圍，NAT traversal ports 等資訊。不建議貼上網孔本身的 IP "192.168.1.1"，因為這個 IP 對設備連接，或是程式控制都沒有作用。

### 通訊協定格式設計

#### 編碼

Plaintext/fixed, ASCII.

#### 行為

Client / server，"大致上" 為一問一答通訊方式。

#### Payload

採用 fixed 欄位設計，"大致上" 由 header、data、EOL 三個部組成，沒有 checksum、signature 的設計。

:::warning
#### 關於 "大致上"

目前並未採用結構化的定義文件，與進行對應的程式建置、驗證機制。因此規格仍以最終實作結果為準。
:::

---

## "Protocol 相關" ASI-KVM 產品設計摘要

### "Channels"

ASI-KVM 共有三組鍵盤滑鼠輸出控制，用於 "權控" 之切換與應用。其中包含兩個實體輸出 console A, B，與遠端、透過網路的 A1 channel。

| Channel | Device |
| ------------| ------------- |
| Console_A | Local K/M |
| Console_B | Remote K/M |
| S1 | TCP/IP K/M |

### Push button

ASI-KVM 近端權控的可移除實體按鈕，擁有關閉遠端 channel 與否的最高權限。

---

## 已知議題 / 共用設定

### ASI-KVM TCP client 連線限制

* 上限 10 個 clients
* 超過後，新加入的會被踢掉 (拒絕連線)

### EOL of TCP commands

使用 CR, LF 跳脫字元皆可 -- 可選用 ``\r``, ``\n``，或是兩者都使用 (``\r\n``)。

但是在 PuTTY 以 enter 送出 command 時，會有誤動作，導致 ASI-KVM 沒有回應，需要另外設定。或者可改用 [TCP test tool](http://www.simplecomtools.com/) 等工具。

### 無法辨識的指令，不會得到 error return

只有 ASK-KVM 認得、但是 "參數給錯" 指令，才會得到 error return 回應。如果是在 ASI-KVM *pattern matching* 以外的指令錯誤，則不會得到任何回應。

也就是說，如果是合法的指令，但是 "多加" 了一些參數、錯誤的字元在後面，ASI-KVM 還是會接受合法的部分，並給予回應。例如：

* 正確指令：Asi=readST
* 仍可以得到正確回應的錯誤指令：Asi=readST<font color=red>I_ADDED_SOMETHING_WRONG</font>
* 完全沒有回應的錯誤指令：<font color=red>si=readST</font>

---

## *Protocol* -- 連線初始化

ASI-KVM 設計有連線後的應用層交握機制，說明如下。

### First connected return

U  n  l  o  c  k  .  \r \n
0  1  2  3  4  5  6  7  8  
Fixed chars  9 byte

### Confirm connected return

L  o  g  i  n  .  \r \n
0  1  2  3  4  5  6  7    
Fixed chars  8 byte

---

## *Protocol* -- 回應類型與格式

在 ASI-KVM 中，**除了 "Status" command 外**，其餘 command 皆會以 "normal" 或是 "error" packet 回應。

### "normal" return

Normal return   (ASCII) 
A  n  s  :  0  0  
0  1  2  3  4  5   
D  B  B  B  C  C 

Data code
D. Block or Normal mode   A:Normal mode  /  B:Block mode(Console_A only)   1 byte
B. Fixed char  3 byte
C. 00~99   2 byte
CR/LF   2 byte

### "error" return

Error return    (ASCII)
E  r  r  :  1
E  E  E  E  D

E. Error status   4 byte
D. Error type   1:command error  /  2:parameter error   1 byte
CR/LF   2 byte

### "status" return

請見 "Protocol – Status commands" 章節。

---

## *Protocol* -- Channel commands

### Request

# Channel select action (ASCII)
Leader code

A  s  i  =  s  a  C  M  D  G  0
0  1  2  3  4  5  6  7  8  9 10
A  A  A  A  A  A  A  A  A  B  D

A. Fixed chars  9 byte
B. Function code  E:Channel mode  /   F:Switch Channel  /  G:Move Channel  /  S:ASI200 command   1 byte
D. @B='E' Channel mode  0:Release  /  1:Lock  1 byte
D. @B='F' Channel select  0:Console_A  /  1:Console_B  /  2:S1  /  3:S1 with abs mode 1 byte
D. @B='G' Channel move  0:Console_A  /  1:Console_B  /  2:S1   1 byte
D. @B='S' ASI200 command  0:Local only  /  1:Normal use   1 byte
CR/LF     2 byte             

---

## *Protocol* -- Mouse commands

### Data encoding and limits

* Mouse moving: value under text/decimal
* S1 with abs mode :Maximun 1280 x 1024 resolution. If value less then the maximum, use proportional scaling.

### Request

# Mouse action (ASCII)
Leader code
"MoS："   20 byte + CR/LF
0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 20
M  o  S  :  R  0  1  0  0  U  0  1  0  0  Z  0  0  1  p  0  1
A  A  A  A  B  C  C  C  C  D  E  E  E  E  F  G  G  G  H  I  1

A(0) . Leader code  4 byte
B(4) . X:idle  /  R: move right  /  L:move left   1 byte  
C(5) . value:0000~9999   4 byte
D(9) . Y:idle  /  D:move down    /  U: move up    1 byte
E(10). value:0000~9999   4 byte
F(14). Z  id  reserve  1 byte  
G(15). 000~127  move range  3 byte 
H(18). mouse left button  W:normal  /  p:press   1 byte
I(19). mouse wheel  0:stop  / 1:up / 2:down   1 byte
J(20): ASI200 status of the Dout 0:Local only / 1:Normal use 1 byte
CR/LF     2 byte

# Mouse left button click               
M  o  s  :  b  t  n  L  0
0  1  2  3  4  5  6  7  8

# Mouse right button click                   
M  o  s  :  b  t  n  R  0
0  1  2  3  4  5  6  7  8            

---

## *Protocol* -- Keyboard commands

### Data encoding and limits

* Special key: bitwise flag under text/BCD
* HID keyboard (scan) code (K1 ~ K6): value under text/BCD
* HID keyboard [(scan) code](https://www.toomanyatoms.com/computer/usb_keyboard_codes.html)

### Request

＃ Keyboard special key bit define:
Low    (Left side)              High (Right side)
Win / Alt / Shift / Ctrl  /  Win / Alt / Shift / Ctrl  (8bit)        
                 
# Keyboard action   (ASCII)
Leader code
"KoS:"   4 byte + CR/LF

K  o  S  :  S1 S2 K1 K1 K2 K2 K3 K3 K4 K4 K5 K5 K6 K6
0  1  2  3  4  5  6  7  8  9  10 11 12 13 14 15 16 17
A  A  A  A  B  B  C  C  D  D  E  E  F  F  G  G  H  H  

Data code
A. Leader code   4 byte
B. 00~FF   2 byte
C. 00~FF   2 byte
D. 00~FF   2 byte
E. 00~FF   2 byte
F. 00~FF   2 byte
G. 00~FF   2 byte
H. 00~FF   2 byte
CR/LF   2 byte

K1~K6
Reference USB hid keyboard codes.
Eg. 'A' = 04
Usually use K1.

---

## *Protocol* -- Status commands

### Request

Check status code   (ASCII)
A  s  i  =  r  e  a  d  S  T
0  1  2  3  4  5  6  7  8  9
E  E  E  E  E  E  E  E  E  E

E. Read ASI_KVM status.   10 byte
CR/LF   2 byte

### Status response

Status return   (ASCII)
Z  N  S  :  0  0  0  0  0  0
0  1  2  3  4  5  6  7  8  9
A  B  C  D  E  F  G  H  I  J

A. Fixed char   1 byte
B. S1 set channel mode  N:Release  /  n:Lock    1 byte   
C. mouse action status  S:Not Tcpip channel /  R:run  /  P:idle    1 byte
D. keyboard action status  ':':Not Tcpip channel  /  r:run  /  p:idle    1 byte 
E. 0:Console_A  /  1:Console_B /   2:Ethernet    1 byte
F. 0:Block mode(Console_A only)  /  1:Normal mode    1 byte
G. 0: idle  /  1: Console_A is using  /  2: Console_B is using    1 byte
H: Absolutely mode  0:None  /  1:Console_A  /  2:Console_B    1 byte
I: Absolute model of the S1  0:Disable  /  1:Enable   1 byte  
J: ASI200 status of the Dout  0:Local only  /  1:Normal use   1 byte  
CR/LF   2 byte

---

## 附件

* [Designing a Protocol](http://labs.cs.upt.ro/labs/sprc/html/res/Designing%20a%20Protocol.pdf)
* [Protocol Design Principles](https://www.ncsc.gov.uk/whitepaper/protocol-design-principles)

***

abc
123

xyz
000

mmm
999