.. _Remote_Interface:

=========================
:index:`Remote Interface`
=========================

.. |pyB12MPS| raw:: html

   <a href="http://pyb12mps.bridge12.com/" target="_blank"> pyB12MPS</a>


The Bridge12 MPS is equipped with a :index:`Serial Interface` to allow control of the system remotely from a computer. Communication is enabled using standard serial communication (RS232) over USB.

.. warning::

    The remote interface should only be used by users familiar with the operation of the MPS. Please contact Bridge12 at support@bridge12.com if you have any questions about the serial interface.

-------------------------
Serial Port Configuration
-------------------------

The Serial Interface is configured with the following operation parameters:

.. _RI_SerialPortConfiguration:
.. list-table:: Serial Port Configuration
   :widths: 2 1
   :header-rows: 1
   :align: center

   * - Parameter
     - Value
   * - Baud Rate
     - 115200
   * - Data Bits
     - 8
   * - Parity Bit
     - No
   * - Stop Bit
     - 1

It is possible to communicate with the MPS through any serial terminal. Make sure the baud rate, number of data bits, number of parity bits, and the number of stop bits are set to the correct values (see :numref:`RI_SerialPortConfiguration`).

--------------------------
Communicating with the MPS
--------------------------

Most likely, the Bridge12 MPS will perform a reset at the time the serial connection (socket) is established. This is very normal behavior of the interface. When developing customer applications to control the MPS through the serial interface, the serial socket should only be opened once when the customer program goes through its initialization routine. The serial socket is kept open until the customer application closes. Closing the serial socket is important, otherwise the remote computer may report an error.

When opening the serial socket the system will respond with the following message:

.. code-block:: console

    Bridge12 MPS Started

Once the system is initialized and ready the system will respond with the following message:

.. code-block:: console

    System Ready
    Synthesizer detected

The user needs to wait for the System Ready statement before issuing any command. All commands that are issued before the System Ready message will be ignored.

---------------
Command Syntax
---------------

Commands are not case sensitive. When opening a serial socket to the MPS, the microcontroller will reset. Therefore, the serial socket should only be opened once and closed only after the last command is sent to the unit.

The general structure for sending a command is:

.. code-block:: console

    COMMAND VALUE <CR>

The general structure to query a value is:

.. code-block:: console

    COMMAND? <CR>

---------------------------------
Python Package to Control the MPS
---------------------------------

Bridge12 has developed a python package to control the MPS. The python package can be installed as a python module and its functionality can be integrated into user specific applications.

For more information about the package please visit |pyB12MPS|.

---------------------------------
Description of Available Commands
---------------------------------

Currently the following commands are implemented. If a special command is required, please contact Bridge12 at support@bridge12.com.


General Remote Commands
-----------------------


.. _RI_SerialCommands:
.. list-table:: Serial Port Configuration
   :widths: 10 80 10
   :header-rows: 1
   :align: center

   * - Command
     - Description
     - Firmware
   * - :index:`ampstatus`
     - Set/Query amplifier power.
     - 1.0.0
   * - :index:`amptemp`
     - Query amplifier temperature
     - 1.3.1
   * - :index:`firmware`
     - Query firmware version
     - 1.1.0
   * - :index:`freq`
     - Set/query microwave frequency in kHz
     - 1.0.0
   * - :index:`help`
     - Get help instructions on serial port
     - 1.0.0
   * - :index:`id`
     - Query MPS ID number
     - 1.1.0
   * - :index:`lockdelay`
     - Set/Query frequency lock delay in ms
     - 1.4.0
   * - :index:`lockstatus`
     - Set/Query frequency lock
     - 1.4.0
   * - :index:`lockstep`
     - Set/Query frequency lock step in kHz
     - 1.4.0
   * - :index:`power`
     - Set/query microwave power in dBm times 10
     - 1.0.0
   * - :index:`rfstatus`
     - Set/Query RF status
     - 1.1.0
   * - :index:`rfsweepsw`
     - Set/query the sweep width for cavity tune sweeps. The system has 4 predefined sweep widths, corresponding to integers between 0 and 3. The following arguments are allowed: 0 to set a sweep widht of 250 MHz, 1 to set a sweep widht of 100 MHz, 2 to set a sweep widht of 50 MHz, and 3 to set a sweep widht of 10 MHz.
     - 1.5.4
   * - :index:`rfsweepdosweep`
     - Trigger a single cavity tune sweep through the serial interface. The values of the reflected power are stored internally in an array, which can be accessed using the rfsweepdata command. IMPORTANT: Any character sent to the serial interface will abort the current sweep. This functionality can be used to abort an active sweep.
     - 1.5.4
   * - :index:`rfsweepnpts`
     - Set/query number of points of cavity tune sweep. The default is 50 points. The maximum number of points is 1024.
     - 1.5.4
   * - :index:`rxpowerdbm`
     - Query Rx diode power in dBm times 10
     - 1.0.0
   * - :index:`rxpowermv`
     - Query Rx diode reading in mV times 10
     - 1.0.0
   * - :index:`screen`
     - Set/Query the current screen on the front panel. A value of 0 corresponds to the Main Screen. A value of 1 corresponds to the Tune Screen. A value of 2 corresponds to the Operate Screen.
     - 1.4.0
   * - :index:`serial`
     - Query serial number
     - 1.1.0
   * - :index:`systemstatus`
     - Query a selection of system variables. The command returns a list of comma separated values of system variables. The format is human readable: systemvariable1:value,systemvariable2:value ....
     - 1.1.0
   * - :index:`txpowerdbm`
     - Query Tx diode power in dBm times 10
     - 1.0.0
   * - :index:`txpowermv`
     - Query Tx diode reading in mV times 10
     - 1.0.0
   * - :index:`wgstatus`
     - Set/Query Waveguide status
     - 1.1.0


Specialized Remote Commands
---------------------------

The following list of serial commands is for reference only, and are typically not used in a day-to-day operation. Extreme caution should be used when using any of these commands since permanent damage can occur to the system if commands are used incorrectly.

.. _RI_SpecialSerialCommands:
.. list-table:: Special Serial Port Configuration
   :widths: 10 80 10
   :header-rows: 1
   :align: center

   * - Command
     - Description
     - Firmware
   * - :index:`ampgain`
     - Set/query the amplifier gain on the fly. This parameter is used only for small adjustments during the calibration process. Users should not attempt to change this since it can cause permanent damage to the system.
     - 1.5.5
   * - :index:`debug`
     - Enable debug mode. The following arguments are allowed: 0 - Debug mode disabled, 1 - Debug mode enabled, 2 - Verbose mode enabled
     - 1.3.0
   * - :index:`rfsweepdwelltime`
     - Set/query the dwell time in microseconds between points when performing a cavity tune sweep. The default value is 110 us ms between each step.
     - 1.5.5
   * - :index:`rfsweepinitialdwelltime`
     - Set/query the initial dwell time in milliseconds for the first point of the frequency sweep when performing a cavity tune sweep. The default value is 100 ms between each step.
     - 1.5.5
   * - :index:`rfsweeppower`
     - Set/query the microwave power level used during a RF sweep. The default is 10 dBm. The maximum power available for a RF sweep is 20 dBm.
     - 1.5.4
   * - :index:`rxdiodesn`
     - Query Rx diode serial number
     - 1.1.0
   * - :index:`txdiodesn`
     - Query Tx diode serial number
     - 1.1.0


-----------------------------
Example using PuTTY (Windows)
-----------------------------

Below is an example using PuTTY to communicate with the MPS. PuTTY can be downloaded from https://www.putty.org/. Please follow the instructions for installation.

To communicate with the MPS you first have to determine the COM port. This can be done using the Windows Device Manager. To open the Device Manager type 

::

  devmgm

into the search box and hit return. The Device Manager opens. Navigate to **Ports (COM & LPT)** and expand this section. Here, you will see MPS listed as **Arduino Due Programming Port**. Note down the COM port number.

To start communication using PuTTY follow these instructions:

#. Start PuTTY

#. In the PuTTY configuration window, click on **Serial** tab (all the way at the bottom)

#. Enter the COM port number (from Windows Device Manager)

#. Enter a **Speed (baud)** of 115200

#. Return to the **Session** tab (all the way to the top right)

#. Choose **Serial** as connection type. In *Serial Line* the correct COM port should be displayed and under *Speed* a speed of 115200 should be displayed

#. Click the **Open** Button to start communication

Once you click the open button a new window will open. You will hear clicks from the MPS and the system will reboot and initialize. This will take a few seconds. In the new window you will see a few messages similar to this:

::

  ====================
  Bridge12 MPS Started
  ====================
  System Ready
  Synthesizer detected

You are now ready to send commands to the MPS. For example to set a frequency of 9.543210 GHz type

::

  freq 9543210

Depending on your settings and the type of serial terminal application you are using, you may not see the command that your typing and there will be no response for a correct command unless it is a query, in which case the value of the variable will be returned. If the syntax is not correct the MPS will answer with an error:

::

  freq 954321
  ERROR

(Note: this command creates an error since the frequency has to be entered in kHz.)

To close the COM port, simply close the PuTTY window.

---------------------
Example with pySerial
---------------------

Below is an example about how to use the MPS serial interface using pySerial. A MPS specific python package (|pyb12mps|) is available for more convenient remote control of the MPS.

::
    
    import serial
    import time

    # MPS Serial Port
    serialPort = 'COM5'

    # Start Serial Connection
    ser = serial.Serial(serialPort,115200,timeout = 1.)
    time.sleep(0.1)

    system_ready_string = 'Synthesizer detected'

    # Initialize MPS
    while not is_system_ready:
        time.sleep(0.1)
        bytes_in_waiting = ser.in_waiting
        if bytes_in_waiting > 0:
            read_bytes = ser.readline()
            read_string = read_bytes.decode('utf-8').rstrip()
            print(read_string)
            if read_string == system_ready_string:
                is_system_ready = True

    # Command to send to MPS
    command = 'freq 9400000\n'

    # Encode MPS command (convert to bytes)
    command_bytes = command.encode('utf-8')

    # Send command to MPS
    ser.write(command_bytes)


-----------
Error Codes
-----------

If the system does not recognize a command that was sent through the serial interface, it will return an error code. In :numref:`RI_ErrorCodes` the system error codes are listed together with a description. If neither the *debug* nor the *verbose* mode is enabled, no acknowledgement will be returned if the command has the correct syntax. Enabling the *debug* 


.. _RI_ErrorCodes:
.. list-table:: Special Serial Port Configuration
   :widths: 10 90
   :header-rows: 1
   :align: center

   * - Error Code
     - Description
   * - E001
     - Value out of range.
   * - E100
     - USB shield error. Please contact Bridge12 at support@bridge12.com.
   * - E101
     - USB shield error. USB shield failed to send data. Please contact Bridge12 at support@bridge12.com.
   * - E102
     - Temperature sensor not recognized.
   * - E999
     - The command was not recognized, either because the command does not exist or because of a typo. The same error code is returned if the command was sent without a question mark (query).