Acqgen DataAcquisition: Difference between revisions

From Control Systems Technology Group
Jump to navigation Jump to search
(Typo fix)
(row and column are different things)
(2 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
  gcc --version          # Verify that the C compiler is installed. If it is, this command should output a version number,
    ebox[0]:enc0
                        #    else you get an error that the command cannot be found. In the latter case, install gcc in the Linux system first.
    ebox[0]:enc1
                        #
    
                        #
   Output signals:
   cd build_dir          # Enter Cmake build directory
    ebox[0]:aout0
                        #
    ebox[0]:aout1
                        # Tell CMake where to install the result, which C compiler to use, which additional compiler flags to use,
    ebox[0]:dout0
                        #    and where to find the source.
    ebox[0]:pwm0
   cmake -DCMAKE_INSTALL_PREFIX=../installed_soem -DCMAKE_C_COMPILER:FILEPATH=gcc -DCMAKE_C_FLAGS:STRING=-fPIC ../SOEM
    ebox[0]:pwm1
                        #
  # CMake should find everything it needs, else additional software needs to be installed at the Linux system first.
                        #
  make                  # Compile the SOEM source code, and put the results into build_dir (the current directory)
  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.
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.
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.


== Installing the Acqgen software ==
=== Control scenario ===
Installing Acqgen is pretty much the same procedure, except it doesn't have a nifty CMake script, it uses a simple Python script
In the simplest case, you connect the device signals directly to Matlab, leading to a real-time control scenario:
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
   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.
  input(ain[0], din[1].2);
 
  # Matab provides analogue control data to aout[0] and aout[1].
  aout[0], aout[1] = output();


(extract while decompressing, the file <code>acqgen-release-v1-RC2.tar.gz</code>)
Starting at the bottom of the specification, Acqgen generates a Matlab function that takes a matrix of 2 columns with two output values to be assigned to analogue outputs <code>aout[0]</code> respectively <code>aout[1]</code> (The <code>output()</code> represents a row in the matrix, the statement <code>aout[0], aout[1] = output();</code> `assigns' the column values to the signals.)


Extracting gives you a directory named like the archive but without extensions, that is, something like <code>acqgen-release-v1-RC2</code>.
The <code>input(ain[0], din[1].2);</code> statement is the other direction, back to Matlab. It `takes' the value of the first analoge input, and the 3rd bit of the 2nd digital input, and combines them as a row in the matrix to return from the function in Matlab.
 
The <code>config( ... )</code> at the top defines the various system parameters. The <code>buffered = false</code> means no buffering of Matlab matrices happens. 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 row of output with one row of new input from the sensors on each call.
 
=== 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, you can process results or create new data to send to the actuators 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 `blocks', 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, and trigger blocks to construct a on/off signal, which can be used to control storage of signals into Matlab matrices.
 
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.
  input(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 <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.
 
== Releases ==
* [[Media:Acqgen-release-v1-RC2.zip]] April 2017

Revision as of 13:18, 12 July 2017

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.
 input(ain[0], din[1].2);
 
 # Matab provides analogue control data to aout[0] and aout[1].
 aout[0], aout[1] = output();

Starting at the bottom of the specification, Acqgen generates a Matlab function that takes a matrix of 2 columns with two output values to be assigned to analogue outputs aout[0] respectively aout[1] (The output() represents a row in the matrix, the statement aout[0], aout[1] = output(); `assigns' the column values to the signals.)

The input(ain[0], din[1].2); statement is the other direction, back to Matlab. It `takes' the value of the first analoge input, and the 3rd bit of the 2nd digital input, and combines them as a row in the matrix to return from the function in Matlab.

The config( ... ) at the top defines the various system parameters. The buffered = false means no buffering of Matlab matrices happens. 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 row of output with one row of new input from the sensors on each call.

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, you can process results or create new data to send to the actuators 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 `blocks', 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, and trigger blocks to construct a on/off signal, which can be used to control storage of signals into Matlab matrices.

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.
 input(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.

Releases

* Media:Acqgen-release-v1-RC2.zip April 2017