Host Interface#

This document explains the interfaces available for interaction between the AMDC and the host.

Physical Layer#

The AMDC has two available host interface physical layers:

  1. USB-UART

  2. Ethernet

Both options support almost identical features, however, Ethernet has higher performance and is the preferred option. USB-UART is supported for simple use cases and debugging.

Tip

Invest the time to get Ethernet working between the AMDC and your test environment host PC. It will save countless hours over the long term and make the AMDC much easier and more enjoyable to use.

USB-UART#

USB-UART refers to the typical character-based “serial” interface common to most embedded platforms. On the host side, USB-UART appears as a USB device which emulates the classic serial (COM) port. On the AMDC side, USB-UART appears as standard UART RX/TX data lines which go to the UART peripheral of the processor. Hence, most of the firmware and docs refer to the USB-UART interface as simply UART.

The UART interface is fairly slow and not very robust. However, it is easy to set up and use.

Setting Up UART on Host PC#

The only required set-up is the drivers for converting the USB device into a serial port:

  • On REV D hardware, follow the instructions outlined near the end of this document.

  • On REV E and beyond, the host should already have the drivers installed.

Ethernet#

The AMDC also supports Gigabit Ethernet. Compared to the UART interface, Ethernet is much faster and very robust. It is the preferred host interface.

Setting up Ethernet from the host side is a bit harder than UART.

Gigabit Ethernet Adapter#

First, you will need a dedicated Gigabit Ethernet jack. Using a USB-to-Ethernet adapter is recommended for portability, but make sure it supports the link speeds you want to use (e.g., try this USB 3.0 to Ethernet adapter which supports 10/100/1000 Mbps).

Adapter Name#

For ease-of-use, consider renaming the network exposed from the dedicated network adapter as “AMDC” so it is clear on your PC what is what.

In Windows 10, update the name of the network connection to the AMDC:

  1. Plug in the Ethernet adapter and ensure its drivers are installed (most likely this will be automatic)

  2. Open Control Panel > Network and Internet > Network and Sharing Center

  3. Find the network in the list of “Active Networks” – it will probably be labeled “Unidentified network” and will say it is connected via “Ethernet X”

  4. On the left side bar, go to Change adapter settings

  5. Click once on the “Ethernet X” entry which you found in step 3

  6. In the top tool bar, select “Rename this connection”

  7. Type in “AMDC” – if you already did this for another Ethernet adapter on your PC, you will have to pick a new name

Adapter IP Settings#

When using the Ethernet interface to the AMDC, the AMDC acts as the server and the host PC is the client. The AMDC server does not use DHCP, meaning you must give a static IP address to your host PC on the dedicated network adapter. The AMDC server is hard-coded to IP address 192.168.1.10. You must statically define your client PC IP address to an address which is not the AMDC address, e.g., 192.168.1.8.

In Windows 10, set the Ethernet network settings for the AMDC:

  1. Open Network status

  2. The AMDC network should appear under your Wi-Fi and will be labeled “AMDC” if you renamed it per the above section

  3. Select Properties for the AMDC network

  4. Under IP settings, it will default to IP assignment: Automatic (DHCP)

  5. Click Edit under IP settings

  6. Change to Manual

  7. Turn on IPv4

  8. Set the following settings:

    • IP address: 192.168.1.8

    • Subnet prefix length: 24

    • Gateway: 192.168.1.1

  9. Click Save

Usage#

There are also two ways to use the interface between the host and AMDC:

  1. Manual interface via serial terminal software (UART only)

  2. Programmatic interface via Python, typically via Jupyter notebook (UART or Ethernet)

The following table summarizes the acceptable combinations:

Usage

UART

Ethernet

Manual Terminal

✔

❌

Programmatic via Python

✔

✔

Manual Interface With Terminal Software#

This is the easiest way to get started with the AMDC. This simply involves plugging in a single cable for USB-UART and opening a serial terminal program on your host PC. Note that this usage does not support Ethernet.

Some possible host terminal software includes:

  • Xilinx SDK integrated terminal

  • Tera Term

  • PuTTY

There are many other host software options available.

Follow the Blink tutorial for more detailed instructions on using the manual terminal interface via UART.

Programmatic Interface With Python#

For complex experiments and systems (i.e., most users), the programmatic interface method is preferred and should be used. This can be done via either UART or Ethernet, and is typically done using a Jupyter Notebook environment. The AMDC-Firmware repo contains Python classes which encapsulate the functionality of AMDC-host interfacing.

The Python wrapper class for the AMDC is documented here.

The most basic way to think about the programmatic method is simply automating typing commands on the serial terminal. For example, typing hw pwm on and [ENTER] into the terminal program is the same as running amdc.cmd("hw pwm on") in Python.

At the simplest level, the benefits of using Python already start to appear, such as dynamically changing command arguments.

Consider an experiment where a levitated object is moved by 10 um every second and data is collected from an oscilloscope. This is trivial to implement in Python:

# Specifiy set point in microns
xx_ref = [0, 10, 20, 30, 40]

# Send command to AMDC with the set point in meters
for x_ref in xx_ref:
    amdc.cmd("ctrl set {}".format(x_ref * 1e-6))
    time.sleep(1)

This simple automated experiment would be very tedious to type in by hand via the serial console, while ensuring consistent timing. However, Python scripting makes it easy.