Acqgen DataAcquisition: Difference between revisions

From Control Systems Technology Group
Jump to navigation Jump to search
(added more install details)
(Nicer name for the download link)
 
(10 intermediate revisions by the same user not shown)
Line 4: Line 4:
To use Acqgen, you need
To use Acqgen, you need


# 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 Windows 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.
# 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.
# 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.
# 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.
# An experiment to measure or control.
# An '''experiment to measure or control'''.
# Cables, power, etc to hook the EtherCaT measurement device(s) to the experiment, and to connect the EtherCaT devices to the computer.
# '''Cables, power, etc''' to hook the EtherCaT measurement device(s) to the experiment, and to connect the EtherCaT devices to the computer.
# A Matlab (tested with R2015a, newer should also work) installed at the Linux system. The software generates a C module that must be compiled, which means the Linux system must have a working C compiler compatible with Matlab Mex (that is, the normal gcc program).
# A '''Matlab''' (tested with R2015a, newer should also work) installed at the Linux system.
# Python3 (Likely already installed at the Linux system, try running <code>python3 --version</code>, which should output some lines of text with the version number of the Python interpreter. If you get an error that <code>python3</code> does not exist, it must be installed in the Linux system first.)
# '''Python3''' (Likely already installed at the Linux system, try running <code>python3 --version</code>, which should output some lines of text with the version number of the Python interpreter. If you get an error that <code>python3</code> does not exist, it must be installed in the Linux system first.)
# The Soem software installed at the Linux computer (for details, see below). Installing this software needs the same C compiler as above.
# Build software for CMake and C source code (<code>cmake</code>, <code>make</code>, and <code>gcc</code> packages).
# The Acqgen software distribution at the Linux computer (for details see below).
# The '''Soem''' software installed at the Linux computer (for details, see below). Installing this software needs the same C compiler as above.
# The '''Acqgen''' software installed at the Linux computer (for details see below).


== Installing the Soem software ==
== Installing the software ==
# Soem is available from Github, at https://github.com/OpenEtherCATsociety/SOEM Clone or download a copy (acqgen was tested with revision <code>fb975cbc70bde723a178936ddb8c3b1c8c192c39</code>, committed at March 31, 2017).
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.
# Unpack the archive.
# Install the software.


Installing it can be done anywhere, for simplicity, it is assumed that it should be installed in directory <code>installed_soem</code>, right next to the unpacked archive directory named <code>SOEM</code>.
== Using Acqgen ==
The software uses CMake, which works best if it has a directory by itself for building. That means you need the following directory structure.
The user manual also explains the Acqgen software in full detail, but a brief explanation and illustration is likely useful.


  ...  / SOEM            # the unpacked archive, a file .../SOEM/CMakeLists.txt should exist
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.
      / installed_soem  # empty directory, will contain the installed result
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.
      / build_dir      # empty directory, used for building and installing SOEM, should be deleted afterwards


Building and installing is then
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).


   mkdir installed_soem   # Create 'installed_soem' (use <code>rm -rf installed_soem</code> if the directory already exists,
   Input signals:
                        #    this removes the directory and everything inside it)
    ebox[0]:ain0
  mkdir build_dir        # Make some room for CMake too
    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


  gcc --version          # Verify that the C compiler is installed. If it is, this command should output a version number,
The <code>ebox[0]</code> here is the device name, a second E-Box will get <code>ebox[1]</code> 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 <code>el5002[0]</code> is always the first EL5002 device, no matter where it is connected in the EtherCaT chain, or which other device types are connected.
                        #    else you get an error that the command cannot be found. In the latter case, install gcc in the Linux system first.
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 <code>din[0].1</code> 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:


   cd build_dir          # Enter Cmake build directory
   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();


  # Tell CMake where to install the result, which C compiler to use, which additional compiler flags to use, and where to find the source.
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 <code>aout[0], aout[1] = from_matlab()</code> statement, and it returns a column matrix with values obtained from the signals in <code>to_matlab(ain[0], din[1].2)</code>. 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.)
  cmake -DCMAKE_INSTALL_PREFIX=../installed_soem -DCMAKE_C_COMPILER:FILEPATH=gcc -DCMAKE_C_FLAGS:STRING=-fPIC ../SOEM


  # CMake should find everything it needs, else additional software needs to be install at the Linux system first.
The <code>config( ... )</code> at the top defines the various system parameters. The <code>buffered = false</code> means no buffering of Matlab matrices happens, your matrix data is directly passed on to the signals (or rather to the EtherCaT connection). The <code>nic = "eth5"</code> defines which ethernet port to use ("eth5" likely does not exist at your computer, so change it!). The <code>frequency</code> 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.


  make          # Compile the SOEM source code, and put the results into build_dir (the current directory)
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 <code>'report'</code>.
  make install  # Install the compiled results ready for use in ../installed_soem.


Afterwards, the <code>installed_soem</code> directory should have a <code>bin</code>, <code>include</code>, and <code>lib</code> directories, each containing some files.
=== Advanced measurement scenario ===
By setting <code>buffered = true</code>, 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.)


== Installing the Acqgen software ==
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.
Installing Acqgen is pretty much the same procedure, except it doesn't have a nifty CMake script, it uses a simple Python script
1. Download the software archive (see Releases below for a link.
2. Unpack the archive.
3. Install it somewhere
2. If your archive is named <code>acqgen-release-v1-RC2.tar.gz</code>, run a command like


  tar xzf acqgen-release-v1-RC2.tar.gz
That may lead to a specification like


(extract while decompressing, the file <code>acqgen-release-v1-RC2.tar.gz</code>)
  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);


Extracting gives you a directory named like the archive but without extensions, that is, something like <code>acqgen-release-v1-RC2</code>.
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 <code>myconfiguration.txt</code> 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 <code>buffered = false</code>, <code>input</code> and <code>result</code> are simple 1 column matrices.
 
With <code>buffered = true</code>, the <code>input</code> and <code>result</code> are cell matrices where the indices match the <code>index</code> parameter of the <code>to_matlab</code> and <code>from_matlab</code> 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 <code>to_matlab</code> block. This trivially holds when you deliver the first output matrix, but it may also happen if you control output with the <code>enable</code>  parameter.
 
== Other configurations ==
The above configuration files are just two examples, where <code>from_matlab</code> data was coupled directly to output, and measurements where coupled to <code>to_matlab</code> 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 <code>from_matlab</code> or <code>to_matlab</code> if that is useful, or use the same signal at several places. For the <code>buffered = false</code> case has some more restrictions, you can at most have one <code>from_matlab</code> and one <code>to_matlab</code> block, and you cannot use the <code>enable=</code> parameter, since Matlab does not support empty matrices.
 
== Releases ==
* [[Media:Acqgen-release-V1.zip | Acqgen-release-V1]] March 2018

Latest revision as of 10:14, 8 March 2018

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