Low Level Software API

Low-Level Software API

The low-level software API is in the lib directory. In the original implementation (prior to Version 1.3.0), there were two main classes:

• FirewirePort: this defines a "port manager" for a particular Firewire port
• AmpIO: this defines the data layout for an amplifier board (e.g., the QLA); it is derived from an abstract base class BoardIO

Starting with Version 1.3.0, a BasePort class was added to enable support for other communication interfaces, such as Ethernet. Versions 1.3.0, 1.4.0 and 1.5.0 included a file Eth1394Port, which contained a prototype implementation of a raw Ethernet interface that was never fully supported. Starting with Version 1.6.0, this was revised to introduce EthBasePort, which is derived from BasePort and serves as a base class for EthUdpPort and EthRawPort

The basic idea is that all I/O should be performed via the BasePort object (FirewirePort, EthUdpPort or EthRawPort). This avoids issues due to multi-threading. Up to 16 amplifier boards can be created, as instances of AmpIO, and then added to the BasePort object.

For maximum efficiency (lowest latency), it is best to combine all information into a single read or write command over the port (for Firewire, each transaction requires about 30 microseconds). These block read and block write commands are issued by the BasePort object, via the ReadAllBoards and WriteAllBoards methods, or the ReadAllBoardsBroadcast and WriteAllBoardsBroadcast methods, respectively.

The FirewirePort API depends on the Linux libraw1394 library. For real-time performance, RT-Firewire was an option, but is no longer supported. The EthRawPort API depends on a PCAP library (libpcap) and the EthUdpPort API depends on a standard socket library. On Ubuntu, libpcap can be installed using apt install libpcap-dev. Note that libpcap requires root capabilities; one option is to use the Linux setcap (set capabilities) command: sudo setcap cap_net_raw=eip <filename>, where <filename> is the executable (e.g., qladisp).

A typical use of the library (using FirewirePort) is as follows (see also the qladisp test program (qladisp.cpp)):

FirewirePort Port(0);
AmpIO Board(5);
Port.AddBoard(&Board);
while (1) {
  Port.ReadAllBoards();
  std::cout << "Encoder0 = " << Board.GetEncoderPosition(0) << std::endl;
  // ...
}

Go to the NEXT section (Example Program) or return to the INDEX