Acqgen DataAcquisition

Acqgen is a piece of software for generating real-time measurement or control software for plain Matlab for EtherCaT devices, such as the E-Box.

Required equipment

To use Acqgen, you need

1. A Linux computer (tested with Ubuntu 16.04 LTS), with an Ethernet port compatible with the Soem EtherCaT master software (that is, a normal TU/e laptop). Since these laptops usually have the Windows operating system that you want to keep, you can use an USB stick to boot and run a Linux operating system from it, rather than install Linux at the hard disk.
2. One or more EtherCaT compatible measurement devices, like an E-Box. The software supports several devices, the full list is in the manual, which is included in the software distribution.
3. An experiment to measure or control.
4. Cables, power, etc to hook the EtherCaT measurement device(s) to the experiment, and to connect the EtherCaT devices to the computer.
5. A Matlab (tested with R2015a, newer should also work) installed at the Linux system.
6. Python3 (Likely already installed at the Linux system, try running python3 --version, which should output some lines of text with the version number of the Python interpreter. If you get an error that python3 does not exist, it must be installed in the Linux system first.)
7. Build software for CMake and C source code (cmake, make, and gcc packages).
8. The Soem software installed at the Linux computer (for details, see below). Installing this software needs the same C compiler as above.
9. The Acqgen software installed at the Linux computer (for details see below).

Installing the software

You need to download and install both Soem and Acqgen. The simplest starting point is to download the latter first (see #Releases below for the available versions), and unpack the archive. In it you will find a user manual that explains where to get Soem, and how to build and install everything.

Using Acqgen

The user manual also explains the Acqgen software in full detail, but a brief explanation and illustration is likely useful.

Acqgen generates software that talks with measurement and control devices (for example, an E-box) in real time through EtherCat at one side, and exchanges rows of data in matrices in a Matlab function at the other side. There is no pre-defined connection between both sides, although the normal practice is to send data from Matlab to the actuators of the devices, and to send data from sensors of the devices up to Matlab.

The concept used by Acqgen to define the connection between sides is signals. A signal is a sampled continuously changing data value with a name. Each measurement or control device introduces a number of signals, so you can make connection to it. A single E-Box device gives you 10 signals, 5 input signals (2 analoge inputs, 1 digital input, and two encoder inputs) and 5 output signals (2 analoge outputs, 1 digital output, and 2 pulse with modulator outputs).

 Input signals:
    ebox[0]:ain0
    ebox[0]:ain1
    ebox[0]:din0
    ebox[0]:enc0
    ebox[0]:enc1
 
 Output signals:
    ebox[0]:aout0
    ebox[0]:aout1
    ebox[0]:dout0
    ebox[0]:pwm0
    ebox[0]:pwm1

The ebox[0] here is the device name, a second E-Box will get ebox[1] as device name, etc. If a different type of device is also added, a new device name expressing its type is used (and index numbering starts again at 0 for that type. This means that el5002[0] is always the first EL5002 device, no matter where it is connected in the EtherCaT chain, or which other device types are connected. For digital input and outputs you can address single bits by appending a bit number, and you can drop the device name entirely if you don't care about the connected devices. For example din[0].1 would be the second bit (bit 1) of the first digital input signal that exists.

Control scenario

In the simplest case, you connect the device signals directly to Matlab, leading to a real-time control scenario:

 config(memsize = 32000,
     nic = "eth5", # Modify to the ethernet device connected to EtherCaT
     frequency = 1000, # hz
     buffered = false
 );
 
 # Matlab gets samples from ain[0] and din[1].2, the first analogue input, and
 # bit 2 (3rd bit) of the second digital input.
 to_matlab(ain[0], din[1].2);
 
 # Matab provides analogue control data to aout[0] and aout[1].
 aout[0], aout[1] = from_matlab();

Acqgen generates a Matlab mex function that takes a column matrix with values that are forwarded to the signals at the left hand side of the aout[0], aout[1] = from_matlab() statement, and it returns a column matrix with values obtained from the signals in to_matlab(ain[0], din[1].2). In this example, there are 2 output signals, so the matrix passed into the Matlab function has 1 column and 2 rows. The configuration also reads two signal values, so the returned matrix is also a 2 row, 1 column matrix. (The simplest way to think about this is that a row represents a signal, while a column represents a point in time.)

The config( ... ) at the top defines the various system parameters. The buffered = false means no buffering of Matlab matrices happens, your matrix data is directly passed on to the signals (or rather to the EtherCaT connection). The nic = "eth5" defines which ethernet port to use ("eth5" likely does not exist at your computer, so change it!). The frequency gives the data rate. Obviously, this means that you must call the generated Matlab function at least 1000 times each second, exchanging one column of output and one column of new input from the sensors on each call.

During the experiment, errors are not reported, since reporting them might take enough additional time to miss the deadline, and destroy the experiment. Instead, they are collected, and printed when you close down the experiment by calling the generated Matlab function with the single argument 'report'.

Advanced measurement scenario

By setting buffered = true, Acqgen generates a Matlab function that buffers Matlab matrices. If you give enough buffers, data acquisition and Matlab calls run independently of each other. While the requirements of the data rate must still be met for continuous operation, since you exchange many data values at the same time, there is time to process results or to create new data while the experiment runs, if you so desire. (A simpler and probably more common scenario is that Matlab simply stores all data while the experiment runs, and afterwards performs post-processing on it.)

A second extension is that Acqgen also knows about other `blocks', additional pieces of functionality that take and/or produce signals. There are blocks to generate common signals, filter blocks to apply a filter on a signal with a custom filter, and trigger blocks to construct a on/off signal. A common use of the latter is to control storage of measured signals into Matlab matrices, for example if you are interested in only a part of the periodic behavior.

That may lead to a specification like

 config(memsize = 32000,
     nic = "eth5", # Modify to the ethernet device connected to EtherCaT
     frequency = 1000, # Frequency in Hz
     buffered = true,
     default_input_buffersize = 100,
     default_input_buffercount = 2,
     default_prewrite = 0.2
 );
 
 # aout[0] provides 100Hz sine wave at sample frequency 1000Hz, between -4 and 4.
 aout[0] = function(shape=sine, frequency=100, base=0.0, amplitude=4.0);
 
 # Filter ain[0] by averaging the last 3 samples.
 fout = filter(ain[0], weights=[0.33, 0.33, 0.33]);
 
 # Trigger on upgoing flank of filter output, passing 1.3. Trigger output is
 # high for 100 samples (= 100/1000 = 0.1 seconds).
 tout = trigger(fout, policy=up, value=1.3, count=100);
 
 # Save and return raw ain[0] when triggered by tout, with 20% prewriting (due to the "default_prewrite=0.2" configuration).
 to_matlab(ain[0], index = 1, enable=tout);

The user manual contains many more details than can be explained at this page.

Generating the Matlab function

Generating a Mex-compiled function is as simple as

 acqgen myconfiguration.txt

where myconfiguration.txt is a specification file like above. This call also compiles the code to a Mex function file, that you can immediately use in the Matlab program.

Using the Matlab function

The common usage pattern of a generated Matlab function is something like

  % prepare data that should be sent away, if needed.
  for i = 1:20
     result = mymex(input);
     % store result
  end
  mymex('report'); % Report any errors that may have occurred.

With buffered = false, input and result are simple 1 column matrices.

With buffered = true, the input and result are cell matrices where the indices match the index parameter of the to_matlab and from_matlab blocks. In this way you can have several independent input or output streams. Be prepared for the case that there is no data to return from a to_matlab block. This trivially holds when you deliver the first output matrix, but it may also happen if you control output with the enable parameter.

Other configurations

The above configuration files are just two examples, where from_matlab data was coupled directly to output, and measurements where coupled to to_matlab blocks. However, you can make any configuration with blocks that you like, and connect them with signals, as long as a signal does not use itself to derive its value. If you do not use a signal, it is removed automatically (no point in wasting time to compute a value that is never used). It is also perfectly fine to have a configuration without from_matlab or to_matlab if that is useful, or use the same signal at several places. For the buffered = false case has some more restrictions, you can at most have one from_matlab and one to_matlab block, and you cannot use the enable= parameter, since Matlab does not support empty matrices.

Releases

*  Acqgen-release-V1 March 2018