Interacting_with_CASPER_Instruments - david-macmahon/wiki_convert_test GitHub Wiki

There are multiple ways to interact with CASPER instruments. This page aggregates descriptions of the different methods for each board type.

Hardware Interfaces

You can control all CASPER instruments over an Ethernet link or a Serial link.

For Ethernet control, connect a CAT-5 (or better) cable from a NIC on your control computer to the RJ-45 port on your instrument. Figure out the IP address and subnet mask of your instrument. Put your control computer on that subnet.

For Serial control, connect a serial cable from the DB9 connector your control computer to the serial header on the board.

Once you've established a physical link with an Ethernet or Serial cable, follow the control methods specific to your board (as described below).

Software Interfaces

TinySHell

TinySHell is a stripped-down remote shell providing a command prompt. There are several ways to connect to an IBOB, and all of them involve TinySHell. The shell itself is outside the scope of this page, but more info can be found on the TinySHell wiki page.

Supported platforms: IBOB

BORPH

BORPH is a full-featured Linux operating system. Among other things, it provides shell access via ssh, and it maps FPGA regions to the proc filesystem. The OS itself is outside the scope of this page, but more info can be found on the BORPH wiki page.

Supported platforms: BEE2, ROACH

Corr

Corr is a Python library that implements the Karoo Array Telescope Control Protocol (KATCP). It eliminates the need for everyone to write their own FPGA control code. The library itself is outside the scope of this page, but more info can be found on the Corr wiki page.

Supported platforms: BEE2, ROACH

Boards

IBOB

TinySHell with TCP

The easiest way to control your IBOB is over an Ethernet link. All you need to do is include an LWIP block in your Simulink design. By default, IBOBs have an address of the form 169.254.128.x, where the last one and a half octets (12 bits) are set by jumpers on the board at the time of power-on. The default subnet is 255.255.255.0.

IMPORTANT: The IBOB telnet interface supports only a single client at a time. The telnet interface implemented on the IBOB is very rudimentary, and as such should be used only for interactive access during the debugging phase of instrument design. For applications where the IBOB will be accessed programmatically, especially repeatedly, the UDP interface (see below) is preferable.

Telnet

For manual control of a design, you can telnet into an IBOB. When you connect, you'll be greeted with board info and a command prompt:

****************************
* TinySH lightweight shell *
****************************
Design name : your_design_name
Compiled on : 01-Jan-1970 00:00:00
DON'T PANIC ;-)
Type 'help' for help
Type '?' for a list of available commands
IBOB %

Netcat

For scripted control of a design, you can netcat to an IBOB (although this is only advised for debugging and prototyping). Strings sent to the telnet port (23) of the IBOB will be interpreted as TinySHell commands, and any text result will be returned across the same connection. So sending a command to an IBOB from a shell script might look something like this:

echo COMMAND | nc 169.254.128.1 23

C Code

If you're trying to control an IBOB from a C program, then you should establish a TCP connection to the IBOB on port 23 using standard UNIX socket techniques. Once you've got a connected socket, you can send() TinySHell commands as strings, and then recv() that command's result.

TinySHell with UDP

TinySHell commands can also be executed via UDP. This method is preferable for issuing commands programmatically. For information on setting this up, see the LWIP page.

Netcat

Netcat works differently in UDP mode than in TCP mode. It requires a flag (-u) telling it to operate in UDP mode. And since UDP is connectionless, netcat will never receive any signal from the board telling it to close the connection. So to prevent netcat from never terminating, you should also give it a flag to close the connection after waiting for a finite amount of time (say, 1 second: -w 1). The UDP server listens on the echo port (7), so the example shell script from above might now look something like this:

echo COMMAND | nc -u -w 1 169.254.128.1 7

C Code

Socket code will be almost exactly the same in UDP mode as in TCP mode. The only difference is a single argument when opening the socket. Instead of SOCK_STREAM, use SOCK_DGRAM in your socket() call. Strictly speaking, nothing else in your code needs to change. But you'll probably want to add code to make sure your command got through, since UDP is connectionless and thus offers no delivery guarantees.

You can download some example code here.

Matlab

You can also interact with IBOBs directly using Matlab. Some example code is available here.

TinySHell with RS-232

If your design is so big that you have no resources to spare for LWIP, you can still interact with TinySHell over RS-232.

Terminal Emulator

Proper terminal settings are: 115200 bps / 8N1 with no flow control.

Shell Commands

To be documented.

C Code

To be documented.

BEE2 and ROACH

There are two ways to interact with BEE2 and ROACH boards: BORPH or Corr.

BORPH

One of the key features of BORPH is that it maps FPGA resources (like Software Registers and Shared BRAMs) to entries in the proc filesystem. Since BORPH is a full-featured Linux operating system, you can interact with an FPGA as if you were interacting with a device on a normal computer running Linux.

FPGA resources correspond to yellow blocks in the Simulink BEE_XPS System Blockset. For a Simulink model, the names of all yellow blocks will show up as entries in /proc/PID/hw/ioreg/. To access these resources, you would just open any of these entries for normal binary I/O in any language. A common method of interaction is with custom C code.

Corr

Most users of CASPER hardware probably have similar (if not identical) board control needs, so it seemed wasteful to have everyone implement their own board interaction routines. So, we developed a general purpose protocol for board interaction called KATCP. Then, we implemented a standalone KATCP server that runs under BORPH. When this server is running on a board, a user can interact with the the board's FPGA resources by querying it over the network with the Corr library.

Since Corr is written in Python, you just need to import corr, instantiate an FpgaClient instance, and call methods on that instance. You can script this, or, for manual control of a design, you can start an iPython shell and do everything by hand. An example session would look like this:

import corr
roach = corr.katcp_wrapper.FpgaClient('HOSTNAME', 7147)
roach.listbof()
roach.progdev('BOF_FILENAME')
roach.listdev()

This example connects to a board, asks for a list of available bof files, loads one of them onto the FPGA, and then asks for a list of available resources for that design. For a more elaborate list of Corr commands, consult the Corr wiki page.