====== Serial Communication Specification ======

===== How to use this topic =====

This topic describes in Desktop Station's serial communication specification. DSGatewayLib's example (e.g. DSgateway, DSmainRx) supports this specification to communicate with Desktop Station.

このページでは、Windows上で動作するDesktop Station Softwareと、DSmainR5や、DCC/MM2シールド装着済みArduinoUNOにDSGatewayを書き込んだものと、シリアル通信で指令を送る際のコマンド体系を解説しています。この解説を元に、WindowsやMacでオリジナルのソフトを作って、DSmainなどを自由に制御できます。

===== How to communicate =====

The following table describes serial communication configuration. \\ 
シリアル通信設定は以下のとおりです。

|Parity | None | |
|Data Bits | 8 | |
|Stop Bit | 1 | |
|Bit rate | 115200bps (Default) | It depends on the configuration of Arduino's sketch |

Command structure is "CommandName(Parameter1,Parameter2)\n".\\
The parameter numeric must use decimal number. Do not use hexadecimal at command message.\\
Desktop Station sends to Arduino with DSmain or DCC/MM2 shield  that the end of command text is as line feed code "\n (0x0A)".

コマンドの構造は、「コマンド名(引数1,引数2,・・・)\n」となっています。命令の最後はLF(改行コード)を必ず付けてください。大文字小文字を考慮します。

コマンドを送る場合、200 Okの応答からウェイトを最低100ms以上置いてください。内部で処理を行ってDCCパルス生成器を確実に動作させるために必要です。
===== Command list =====

^Commands ^ Parameters ^ examples ^
|setPing| none | setPing()\n|
|setPower| Power on/off | setPower(1)\n|
|setLocoSpeed| Locomotive address, Speed, (Speed Step)| setLocoSpeed(5,100,2)\n |
|setLocoDirection| Locomotive address, Locomotive Direction | setLocoDirection(5,1)\n |
|setLocoFunction| Locomotive address, Function No, Function On/Off| setLocoFunction(5,1,1)\n |
|setTurnout| Accessory address, Turnout Direction | setTurnout(5,1)\n |
|getS88| S88 decoder count | getS88(2)\n |
|setLocoConfig| CV Address, CV No, CV Value | setLocoConfig(49152,1,3)\n |
|getLocoConfig| CV Address, CV No | getLocoConfig(49152,1)\n |

===== Parameter meaning =====

^Parameter ^ Value range ^ meanings ^
|Power on/off | 0-1 | 0: Power Off, 1: Power On |
|Locomotive address | 0-65535 | See the following address description. |
|Speed | 0-1023 | 1023 means max speed. 0 means stop locomotive. |
|Speed step | 0-2 | 0: DCC28 or MM2 14, 1:DCC14, 2:DCC128 |
|Function No | 0-28 | Locomotive's function number |
|Function Value | 0-1| Locomotive's function ON(1) or OFF(0) |
|Locomotive Direction | 1-2 | 1:FWD, 2:REV |
|Accessory address | 0-65535 | See the following address description.|
|Turnout/Signal Direction | 0-1 | 1:Straight(Green), 0: diverging(Red)|
|S88 decoder count | 0-32 | Set connected S88 decoder count.|
|CV Address| 0 or 49152 | Set 0 (MM2, under developing) or 49152 (DCC).|
|CV No | 0-1023| Locomotive's CV number |
|CV Value | 0-255 | Locomotive's CV Value |

以下のテーブルは、ロコとポイントのアドレス(1-65535)の意味をあらわしてます。\\ 
The following table describes Locomotive's and Accessory's address meaning.

^Address type ^Address range ^Address means ^Notes
|Marklin Motorola 2 locomotive | 0x0000-0x07FF | 0(0x0000) - 255(0x00FF) | |
|DCC locomotive | 0xC000-0x1FFF | 0(0xC000) - 9999(0xE70F) | |
|Marklin Motorola 2 accessory | 0x3000-0x37FF | 1(0x3000) - 320(0x3140) | |
|DCC accessory | 0x3800-0x3FFF | 1(0x3800) - 2044(0x3FFC) | |

===== Reply message =====

^Reply message ^ meanings ^
|100 Ready | Waiting for commands. |
|200 Ok | Completely processed. Received correctly. |
|300 Command error | Command or Parameter is not correct. |
|301 Syntax error | Command is not parsed correctly. Command syntax is not correct. |
|302 receive timeout | Command is not received fully in the enough time. |
|303 Unknown error | Unknown issue happens. |
|@PWR,SWITCH,| 電源操作されて発生する状態変化通知|
|@DIR,XX,YY,DIR,| 進行方向操作されて発生する状態変化通知 |
|@FNC,XX,YY,NO,SWITCH,| ファンクション操作されて発生する状態変化通知|
|@ACC,AA,BB,DIR,|ポイント操作されて発生する状態変化通知|
|@SPD,XX,YY,SPD_H,SPD_L,|速度操作されて発生する状態変化通知|

===== Communication procedure =====

  - Initialization of serial port.
  - Set baudrate 115200bps and FIFO configuration(if needed).
  - Open serial port
  - Reset serial port(Use DTR).
  - Wait for receiving a message "100 Ready".
  - After received "100 ready", you can send commands.
  - Firstly you need to send "setPower(1)".
  - The output of track is available. Send commands which you want.


===== Example of communication log =====

以下は、通信ログの例です。setPing()を投げて生存確認をしてから、setPower(1)で線路電源のON、そのあとはコマンドを打てばその通りにDCC信号が出力されます。

<code>
[RECV]100 Ready
[SEND] setPing()
[RECV]200 Ok
[SEND] setPower(1)
[RECV]200 Ok
[SEND] setLocoSpeed(3,63,0)
[RECV]200 Ok
[SEND] setLocoSpeed(3,200,0)
[RECV]200 Ok
[SEND] setLocoSpeed(3,89,0)
[RECV]200 Ok
[SEND] setLocoSpeed(3,0,0)
[RECV]200 Ok
[SEND] setLocoFunction(3,0,1)
[RECV]200 Ok
[SEND] getS88(1)
[RECV]200 Ok
[SEND] setLocoFunction(3,0,0)
[RECV]200 Ok
[SEND] getS88(1)
[RECV]200 Ok
[SEND] setLocoDirection(3,2)
[RECV]200 Ok
[SEND] setLocoSpeed(3,29,0)
[RECV]200 Ok
[SEND] setLocoSpeed(3,98,0)
[RECV]200 Ok
[SEND] setLocoSpeed(3,230,0)
[RECV]200 Ok
[SEND] setLocoSpeed(3,0,0)
[RECV]200 Ok
[SEND] setTurnout(12288,0)
[RECV]200 Ok
[SEND] setTurnout(12290,1)
[RECV]200 Ok
</code>

===== 外部操作の注意点 =====

  * 本体でDCC電源のON/OFFを操作された場合、本体側の操作が優先されます。@PWRで操作状態が応答されますので、その値を見て制御を行ってください。
  * 本仕様書は随時更新されます。また、予告なしに仕様が変更される場合があります。
  * 本仕様書に記載の事項で、自動運転装置をビジネス・業務としてインテグレーションすることは自由ですが、当社は一切の動作保証、環境に起因するサポートをいたしません。ビジネス・業務用途での個別サポートを要求される場合には、サポート契約を申し込みください。サポート契約外のサポートについては一切お断りいたします。