View source for VSP-G1 Remote control guide

== Introduction ==
The VSP-G1 supports remote control using the RS232 serial communication protocol. This enables you to remotely and/or programmatically set and retrieve the operational parameters of the system, e.g. to implement logging or implement controlled operational routines. This guide discusses setting up the connection as well as the command and control structure and possible errors. <mark>Additionally, libraries implementing the API for various languages are available upon request.</mark>

== Connecting to the VSP G1 ==
The VSP-G1 can be controlled remotely via a female 9 pin D-SUB connector on the back panel of the device. It implements the RS232 communication protocol for serial communication. Use a straight through serial cable or a RS232-to-USB dongle for connecting the system. Only pins 2,3 (RX,TX) and 5 (ground) need to be connected for successful communication between two systems.
{{Warning|Be careful with custom connections:|The VSP-G1  communicates using voltage swings between ±12V as is common for RS232. This is not compatible with TTL serial implementations, which commonly use ±3.3V or ±5V signals for communication. Ensure the equipment connected to the VSP-G1 explicitly supports RS232!}}
=== Settings ===
{| class="table table-bordered table-striped"
|-
! Parameter !! Setting
|-
| Baud rate || 19200 bps
|-
| Data bits || 8
|-
| Stop bits || 1
|-
| Parity || None
|-
| Flow control || Off
|-
| Control character || Carriage return (\r)
|}

== API reference ==
=== Scope ===
The VSP-G1 accepts the commands described in the table below. Not all commands are available during the various states of operation of the machine. E.g. during calibration of the electrodes, remote control is unavailable and when the system encounters an interlock error, the remote control is limited. All commands are terminated using the carriage return as control character (<code>\r</code>). The VSP-G1 echoes the command in response and optionally the requested set point or status terminated by <code>\r</code>. 

=== Resolving errors ===
If an error is encountered, the system will reply <code>?</code>. This indicates a specific error code is available. Before any new commands can be executed, the error needs to be cleared using the <code>E</code> command. 

=== Command reference ===
{| class="table table-bordered table-striped"
|-
! Command !! Description !! Input !! Return !! Example
|-
| <code>V</code> || Retrieves or sets (if input was provided) the spark voltage in kV. || Optional: a floating point number with 2 decimal precision between 0.00 and the maximum value determined by the carrier gas setting (e.g. 1.36kV when using Argon) . || The command and the (new) value of the spark voltage setpoint. 
| '''To set a new value'''<br>Input: <code>V1.05</code>
Answer: <code>V1.05</code><br>
'''To retrieve setpoint'''<br> Input: <code>V</code><br>Answer: <code>V1.05</code>
|-
| <code>I</code> || Retrieves or sets (if input was provided) the spark current in mA. || Optional: a floating point number with 1 decimal precision between 0 and 10.4. || The command and the (new) value of the spark current setpoint.
|'''To set a new value'''<br>Input: <code>I1.05</code>
Answer: <code>I1.05</code><br>
'''To retrieve setpoint'''<br> Input: <code>I</code><br>Answer: <code>I1.05</code>
|-
| <code>G</code> || Starts sparking when in idle mode. || N.A. || <code>G</code> 
| Input: <code>G</code> <br> Answer: <code>G</code>
|-
| <code>A</code> || Aborts sparking when in spark mode. || N.A. || <code>A</code> 
| Input: <code>A</code> <br> Answer: <code>A</code>
|-
| <code>S</code> || Returns the current status. || N.A. || A JSON formatted string indicating the spark status, spark current and voltage setpoints and the current reading of the spark voltage and current. The '''S''' element has values 0 and 1, indicating whether the system is sparking (1) or not (0). The '''SET''' element contains the spark voltage ('''V''') and spark current ('''I''') set points and, when sparking, the '''MON''' element contains the current monitor values of the spark voltage ('''V''') and current ('''I'''). All monitor values are refreshed approximately every 10ms.
| Input: <code>S</code> <br> Answer when sparking:<code> {"S":1,"SET":{"I":6.5,"V":1.05},"MON":{"I":6.4,"V":1.04}}</code>
Answer when idle: <code>{"S":0,"SET":{"I":6.5,"V":1.05}}</code>
|-
| <code>!</code> || Returns the version number of the software. || N.A. || A string containing the command followed by the version description of the software. 
| Input: <code>!</code> <br> Answer: <code>!1.0-10HV</code>
|-
| <code>E</code> || If an error was encountered, this retrieves the error code. || N.A. || An integer as error code. Refer to [[VSP-G1 Remote control guide#Error codes| Error codes]] for details on the possible error codes. 
| Input: <code>E</code> <br> Answer: <code>E2</code>
|}

== Error codes ==
The table below lists the possible error codes returned by the <code>E</code> command. 
{| class="table table-striped table-bordered"
|-
! Error code !! Reason
|-
| 0 || No error. This is returned when you send <code>E</code>, but no error was present.
|-
| 1 || The last command is not a valid command or it was improperly formatted.
|-
| 2 ||  The last command exceeded the maximum length for a valid command and is not valid.
|-
| 3 || Invalid input provided with the command. E.g. only numeric input is allowed for the <code>I</code> and <code>V</code> commands, but alphanumeric input was encountered.
|-
| 4 || The command is not valid in the current mode. E.g. a command to start sparking was issued while the device was already in spark mode.
|-
| 3x || The system is in interlock mode and is not functional. In interlock mode, only the <code>E</code> command can be used. The interlock error encountered is given by x. Refer to the [[VSP-G1 User Manual#Interlock errors | table of interlock error codes in the troubleshooting section]] to identify the precise interlock error. Any interlock error can only be cleared by pressing both dials on the front panel of the VSP G1.
|}