<markdown>
Protocol
========

## 基本仕様
命令を送信するにあたり、3文字で定義されたヘッダをまず送信し、
それに続いて各構成要素を定められたフォーマットのもと順次送信していきます。

クライアント側では全ての表現を文字列にしてから送信する必要があります。
(バイナリをそのまま送信した場合、意図しない動作をすることがあります。)

なお、コマンドラインが大文字か小文字かは区別されません。
ボーレートは**2,000,000**を使用してください。


## Controller関連のコマンド
### $AN (指示値の適用)

|タグ     |役割                |最小値(dec)|最大値(dec)|フォーマット            |
|:--------|:-------------------|:---------:|:---------:|:-----------------------|
|DEVICE_ID|デバイス番号の指定  |0          |23         |0埋め,16進数表現,2byte|
|VALUE    |デバイス出力値の指定|-2048      |2047       |0埋め,16進数表現,3byte|

*examples*  
デバイス**10**に**1000**を出力したい場合、送信するコマンドラインは以下の通りです。

```
$an0a3e8
```

### $AD (指示値差分の適用)

|タグ     |役割                |最小値(dec)|最大値(dec)|フォーマット            |
|:--------|:-------------------|:---------:|:---------:|:-----------------------|
|DEVICE_ID|デバイス番号の指定  |0          |23         |0埋め,16進数表現,2byte|
|VALUE    |デバイス出力値の指定|-2048      |2047       |0埋め,16進数表現,3byte|

*examples*  
デバイス**4**の初期値に**-100**した値を出力したい場合、送信するコマンドラインは以下の通りです。

```
$ad04f9c
```

### $PM (モーションの再生)

**Attention!**  
後方互換性のために**$MP**も利用可能ですが、**非推奨**扱いです。

|タグ|役割                  |最小値(dec)|最大値(dec)|フォーマット            |
|:---|:---------------------|:---------:|:---------:|:-----------------------|
|SLOT|読み出しスロットの指定|0          |89         |0埋め,16進数表現,2byte|

*examples*  
スロット**4**のモーションを再生したい場合、送信するコマンドラインは以下の通りです。

```
$pm04
```

### $SM (モーションの停止)

**Attention!**  
後方互換性のために**$MS**も利用可能ですが、**非推奨**扱いです。

*examples*  
モーションを停止したい場合、送信するコマンドラインは以下の通りです。

```
$sm
```

### $HP (初期姿勢への移行)

*examples*  
初期姿勢に移行したい場合、送信するコマンドラインは以下の通りです。

```
$hp
```


## Interpreter関連のコマンド
### #PU (関数のプッシュ)

|タグ      |役割                  |最小値(dec)|最大値(dec)|フォーマット            |
|:---------|:---------------------|:---------:|:---------:|:-----------------------|
|SLOT      |読出しスロットの指定  |0          |89         |0埋め,16進数表現,2byte|
|LOOP_COUNT|ループ回数の指定      |0          |255        |0埋め,16進数表現,2byte|

*examples*  
スロット**10**のモーションを**3**回再生する関数をプッシュしたい場合、送信するコマンドラインは以下の通りです。

```
#pu0a03
```

### #PO (関数のポップ)

*examples*  
関数をポップしたい場合、送信するコマンドラインは以下の通りです。

```
#po
```

### #RI (インタプリタの初期化)

*examples*  
インタプリタを初期化したい場合、送信するコマンドラインは以下の通りです。

```
#ri
```


## Setter関連のコマンド
### >IN (モーションのインストール)

**Attention!**  
**非推奨**扱いです。version 2.xでは廃止予定なので、基本的に後述の**>MH**,**>MF**を使用してください。

|タグ              |役割                     |最小値(dec)|最大値(dec)|フォーマット            |
|:-----------------|:------------------------|:---------:|:---------:|:-----------------------|
|SLOT              |書き込みスロットの指定   |0          |89         |0埋め,16進数表現,2byte|
|NAME              |モーション名の指定       |---        |---        |空白埋め,20byte        |
|FUNC              |関数の指定 (*1)          |0          |255        |0埋め,16進数表現,2byte|
|ARG0              |制御機能に渡す引数0 (*1) |0          |255        |0埋め,16進数表現,2byte|
|ARG1              |制御機能に渡す引数1 (*1) |0          |255        |0埋め,16進数表現,2byte|
|FRAME_LENGTH      |フレーム総数の指定       |1          |20         |0埋め,16進数表現,2byte|
|TRANSITION_TIME_MS|遷移時間の指定           |32         |65535      |0埋め,16進数表現,4byte|
|VALUE[DEVICE_ID]  |デバイス出力値の指定 (*2)|-32768     |32767      |0埋め,16進数表現,4byte|

**(*1) 関数の種類と引数の意味は下表の通りです。**

|"FUNC"の値|機能                                                          |
|:---------|:-------------------------------------------------------------|
|0         |---                                                           |
|1         |loop,"ARG0"から"ARG1"までのフレームを無限ループで再生します。|
|2         |jump,再生終了後、"ARG0"のモーションを再生します。            |

**(*2) デバイスの個数は現状24個で、全てサーボモータです。**

*example*:  
以下のようなモーションをインストールするとします。

|タグ              |値  |
|:-----------------|:---|
|SLOT              |0   |
|NAME              |Test|
|FUNC              |0   |
|ARG0              |0   |
|ARG1              |0   |
|FRAME_LENGTH      |2   |
|TRANSITION_TIME_MS|100 |
|OUTPUT[EVEN]      |0   |
|OUTPUT[ODD]       |-1  |

その際、送信するコマンドラインは以下の通りです。(改行は実際には必要ありません。)

```
>in
00Test                00000002
0064
0000ffff0000ffff0000ffff0000ffff
0000ffff0000ffff0000ffff0000ffff
0000ffff0000ffff0000ffff0000ffff
0064
0000ffff0000ffff0000ffff0000ffff
0000ffff0000ffff0000ffff0000ffff
0000ffff0000ffff0000ffff0000ffff
```

### >MH (モーションヘッダの設定)

|タグ        |役割                  |最小値(dec)|最大値(dec)|フォーマット            |
|:-----------|:---------------------|:---------:|:---------:|:-----------------------|
|SLOT        |書き込みスロットの指定|0          |89         |0埋め,16進数表現,2byte|
|NAME        |モーション名の指定    |---        |---        |空白埋め,20byte        |
|FUNC        |関数の指定 (*1)       |0          |255        |0埋め,16進数表現,2byte|
|ARG0        |制御機能に渡す引数0   |0          |255        |0埋め,16進数表現,2byte|
|ARG1        |制御機能に渡す引数1   |0          |255        |0埋め,16進数表現,2byte|
|FRAME_LENGTH|フレーム総数の指定    |1          |20         |0埋め,16進数表現,2byte|

細かい仕様については、">IN"と同様です。

### >MF (モーションフレームの設定)

|タグ              |役割                     |最小値(dec)|最大値(dec)|フォーマット            |
|:-----------------|:------------------------|:---------:|:---------:|:-----------------------|
|SLOT              |書き込みスロットの指定   |0          |89         |0埋め,16進数表現,2byte|
|FRAME_ID          |書き込みフレームの指定   |0          |19         |0埋め,16進数表現,2byte|
|TRANSITION_TIME_MS|遷移時間の指定           |32         |65535      |0埋め,16進数表現,4byte|
|VALUE[DEVICE_ID]  |デバイス出力値の指定     |-32768     |32767      |0埋め,16進数表現,4byte|

細かい仕様については、">IN"と同様です。

### >JS (関節設定の初期化)

*example*:  
関節設定を初期化したい場合に、送信するコマンドラインは以下の通りです。

```
>js
```

### >HO (初期値の設定)

|タグ     |役割              |最小値(dec)|最大値(dec)|フォーマット            |
|:--------|:-----------------|:---------:|:---------:|:-----------------------|
|DEVICE_ID|デバイス番号の指定|0          |23         |0埋め,16進数表現,2byte|
|VALUE    |初期値の指定      |-2048      |2047       |0埋め,16進数表現,3byte|

*example*  
デバイス**0**の初期値を**100**に設定したい場合、送信するコマンドラインは以下の通りです。

```
>ho00064
```

### >MA (最大値の設定)

|タグ     |役割              |最小値(dec)|最大値(dec)|フォーマット            |
|:--------|:-----------------|:---------:|:---------:|:-----------------------|
|DEVICE_ID|デバイス番号の指定|0          |23         |0埋め,16進数表現,2byte|
|VALUE    |最大値の指定      |-2048      |2047       |0埋め,16進数表現,3byte|

*example*  
デバイス**0**の最大値を**100**に設定したい場合、送信するコマンドラインは以下の通りです。

```
>ma00064
```

### >MI (最小値の設定)

|タグ     |役割              |最小値(dec)|最大値(dec)|フォーマット            |
|:--------|:-----------------|:---------:|:---------:|:-----------------------|
|DEVICE_ID|デバイス番号の指定|0          |23         |0埋め,16進数表現,2byte|
|VALUE    |最小値の指定      |-2048      |2047       |0埋め,16進数表現,3byte|

*example*  
デバイス**10**の最小値を**-1**に設定したい場合、送信するコマンドラインは以下の通りです。

```
>mi0afff
```

## Getter関連のコマンド
### <JS (関節設定のダンプ)

*examples*  
関節設定をダンプしたい場合、送信するコマンドラインは以下の通りです。

```
<js
```

その際、以下のような書式のJSONが出力されます。

```
[
	{
		"max": <integer>,
		"min": <integer>,
		"home": <integer>
	},
	...
]
```

### <MO (モーションのダンプ)

|タグ|役割                |最小値(dec)|最大値(dec)|フォーマット            |
|:---|:-------------------|:---------:|:---------:|:-----------------------|
|SLOT|読出しスロットの指定|0          |89         |0埋め,16進数表現,2byte|

*example*  
スロット**0**のモーションをダンプしたい場合、送信するコマンドラインは以下の通りです。

```
<mo00
```

その際、motion.jsonと同様な形式のJSONが出力されます。([詳細](https://github.com/plenprojectcompany/PLEN2/tree/master/motions))
ただし、"device"に対応する値は**string**ではなく、
[device_map.json](https://github.com/plenprojectcompany/plen-ControlServer/blob/master/control_server/device_map.json)で定義されているようなIDの**ineteger**です。

### <VI (バージョン情報のダンプ)

*examples*  
バージョン情報をダンプしたい場合、送信するコマンドラインは以下の通りです。

```
<vi
```

その際、以下のような書式のJSONが出力されます。

```
{
	"device": <string>,
	"codename": <string>,
	"version": <string>
}
```
</markdown>