MATRIX VISION - mvBlueLYNX-M7 Technical Documentation
Programming local applications

Table of Contents

Introduction

The "Programming local applications" book gives you a short overview, how you can program local applications for the mvBlueLYNX-M7 the easiest way. It is arranged successively that means if you read the sections one after another you will get the information you need to start programming without any difficulty.

Let's start with

Device local software architecture

As described System architecture section in the How to get started? chapter, it is possible to run local applications based on mvIMPACT Acquire on the mvBlueLYNX-M7 , given that it runs an embedded Linux OS.

The applications can perform image analysis and decide whether the data is transmitted or not and what additional data will be send, if this is needed. In the latter case, you can either send the image or the processed image or only the processed data like a decoded barcode.

Note
Given that local applications allocates CPU time, it could be possible, that the performance in terms of max. frame rate decreases.

A short introduction to both local application scenarios:

Scenario 1: Local processing without GigE compliant streaming

In this scenario you can use the mvBlueLYNX-M7 without any connection to a client PC, except for loading the local driver files. Additionally, a serial connection to start and stop the application could be necessary.

Figure 1: Local application on mvBlueLYNX-M7 without GigE Vision compliant streaming

Scenario 2: Local processing with GigE compliant streaming

In this scenario the mvBlueLYNX-M7 transfers the data via GigE compliant streaming to a host PC using the vl_transmit library (gevss = GigE Vision streaming server, gevcs = GigE Vision control server).

Figure 2: Local application on mvBlueLYNX-M7 with GigE Vision compliant streaming

The application properties can be set up via GenICam.

Location for local applications

The directory structure of mvBlueLYNX-M7 , where you can (only) save or change data looks like this:

/--|
|- flash
|
|- bin
|- lib
|- MatrixVision
|
|-bin
|-lib

Programs written by the user are saved in /flash/MatrixVision/bin while MATRIX VISION libraries (mvIMPACT Acquire and mvIMPACT SDK) are located in /flash/MatrixVision/lib. Given that the library path is set to /flash/MatrixVision/lib by default, you do not have to set it manually.

Note
In /flash you can also find the autostart script.

Copying files to the camera via secure copy (scp)

If you want to save files on the camera, you can use secure copy and will need write access. The following sample shows, how this will work via Linux:

  1. Please click on the desktop icon "Command Shell" to open a Shell window.
  2. Connect to the device (IP address of the sample: 192.168.1.166) via ssh and make the device writable.

    ssh root@192.168.1.166
    remount rw
  3. Copy the wanted file to the flash of the device.

    scp testfile root@192.168.1.166:/flash
  4. Now, you have to type in the root password which is "root". Afterwards the copy procedure will start.

    MATRIX Vision mvBC-P
    root@192.168.1.166's password:
    testfile 100% 0 0.0KB/s 00:00

On Windows PCs you can use WinSCP. With WinSCP it is possible to start ssh with PuTTY. PuTTY has to be in the same directory.

Attention
After you've copied/changed the files, you have to change the access to read-only ("remount ro"). Otherwise the garbage collector of the file system will work permanently, which could decrease the lifetime of the Flash memory.

Programming environment

Normally for a development environment, you need and have to install

  1. an API for the mvBlueLYNX-M7 (mvIMPACT Acquire),
  2. (optionally) a SDK, an image processing software library (like mvIMPACT SDK),
  3. (optionally) an IDE (like Eclipse).

With mvBlueLYNX-M7 , MATRIX VISION ships a Virtual Machine (VMware) image based on Kubuntu including all these listed things for mvBlueLYNX-M7 development. The image can be run on Windows® systems with VMware server. Please continue with the next section.

Virtual Machine (VMware)

Introduction

The mvBlueLYNX-M7 has an Embedded Linux as its operating system. To develop software applications for the mvBlueLYNX-M7 you would need a suitable development environment based on Linux with all needed software like mvIMPACT Acquire.

So that you have to pay no attention to this, MATRIX VISION created an VMware image, a virtual machine with Linux as operating system and all needed software and installation to start developing immediately.

This section will explain,

For system requirements, please have a look at Requirements.

VMware image description

The base system for our VMware image is the latest Kubuntu distribution "8.04". This Kubuntu image is already optimized for the VMware software like automatic mouse release, VMware grahics card etc.

We do not recommend to use the distribution based update utility like "adept_manager", "synaptic" or any command line version like "apt-get update". We will extend the image with improvements and new software packages which are necessary in developing applications in the near future.

Kubuntu login data

  • Username: mvbc
  • Password: mvbc

VMware settings

  • "HDD (SCSI 0:0)":
    • 8GB (~7 GB / and ~1 GB SWAP)
    • Currently available HDD space : ~3.8GB
  • "Memory":
    • 512 MB RAM
  • "CD-ROM (IDE 0:0)":
    • Physical device connected on the host (Auto Detect)
  • "Floppy":
    • Physical device A:
  • "Network Interfaces":
    • Ethernet - Specific Virtual Network VMNet 0 - bridged.
    • Ethernet 2 - Specific Virtual Network VMNet 2 - bridged.
  • VMNet 0 is bridged to the first physical Ethernet card in the system.
  • VMNet 2 is bridged to the second physical Ethernet card in the system.
    • Inside the Linux image you will have two network interfaces: eth0 and eth1. One of them is bound to the first physical network card, e.g. to you own company network. The second interface can be used to connect the mvBlueLYNX-M7
      Note
      The DHCP server is only listening to eth1 interface!
      For further information about assignment of the network interfaces, please have a look at How to differentiate eth0 and eth1 concerning the bridged physical interfaces.
  • "TFTP": (tftp-hpa)
    • To be able to boot up the mvBlueLYNX-M7over the network, the tftp-hpa package is already installed.
      The latest mvBlueLYNX-M7network boot file systems are here:
      /var/lib/tftpboot

VMware user guide

Download and installation

To start the VMware image, please follow these steps:

  1. Download the VMware server from http://www.vmware.com/download/server/ .
    Note
    You have to use VMware server Version 1.0.x instead of the VMware server 2.x. The current tested version is 1.0.7.
  2. Install the server and
  3. Register your version to get a key here: http://register.vmware.com/content/registration.html
  4. After registration, copy the image Ubuntu.vmx from the DVD (directory "...\sdk\") onto your PC. Preferably, please use the standard directory of the VMware server ("C:\Virtual Machines").
  5. Now, please go on with Initial operation.

Initial operation

Note
If you are not familiar with network settings, it will be better to adapt no settings which have to do with the IP address (e.g. using DHCP server or a static IP address). As described in chapter Connecting the camera, the mvBlueLYNXgets an IP address without configuring the network (so-called zero configuration) and VMware will work with this.
  1. Now, please start the VMware server.
    Note
    With Vista you have to start VMware as admin.
  2. Connect to the "Local Host".
  3. Click on "Host" -> "Virtual Network Settings" to set them.
  4. Choose the tab "Automatic Bridging" and deactivate "Automatic bridging".
    Figure 3: Deactivated "Automatic bridging"

  5. Choose the tab "Host Virtual Network Mapping" and choose to which physical network device the virtual ones are mapped.

    Figure 4: Mapped physical and virtual network devices
    Note
    On systems with two network devices, you have to test which one is connected to the network and to which one the mvBlueLYNX-M7is connected.
  6. The settings of all other tabs will remain unchanged.
  7. Confirm the changes with "Ok".
  8. Click on "File" -> "Open" -> "Browse..." and select the Ubuntu.vmx image on your local hard disk.
    On the right window you will see the VMware settings of the image.
  9. Start the VMware image with "Start this virtual machine".

    Figure 5: VMware server console
    The VMware image logs on to Kubuntu automatically with following settings Kubuntu login data.
Note
  • American keyboard is set by default. Change this with "KDE Keyboard Tool":
    1. Right-Click on the flag icon on the status line.
      "KDE Keyboard Tool" will be opened.

      Figure 6: KDE Keyboard Tool.

    2. Choose the keyboard setting you need.

  • Berlin is set by default as the current time zone. Change this in a Shell window with the command:
    tzselect

  • Sometimes it could be possible, that the time runs faster or slower in VMware. Please have a look at http://www.vmware.com/pdf/vmware_timekeeping.pdf how to correct this behavior.

  • If you want to be root user, please enter following command in a Shell :
    sudo -s

Attention
If you want to use this VMware several times in the same network, you have to change the MAC addresses in the Ubuntu.vmx VMware image file and set the "70-persistent-net.rules" file in the VMware image. Otherwise you have same MAC addresses in the same network and this will lead to network problems. Please change the MAC addresses as described in the glossary and then edit "70-persistent-net.rules".

It is also possible to access the VMware image via VNC. Please follow the link for further information.

Communication with camera

A direct communication (without GigE Vision) with the camera is necessary to copy files and set up the camera. For this, it is important to know the IP address of the camera. You can get the IP address with the programs wxPropView (property: "Device > DeviceIPAddress") or mvIPConfigure.

Now, please open a Shell in the VMware:

  1. Please click on the desktop icon "Command Shell".

    Figure 7: VMware desktop



    A Shell window will be opened:

    Figure 8: Shell window


    For security reasons, the camera supports only Secure Shell (ssh). Only one user is set up on the camera: root For this reason, the access to the camera will look like this:

    ssh root@<IP address of the camera>

    For example:

    mvbc@mvSDK:~$ ssh root@192.168.1.10

    You will be asked for the password. Please insert root.

    Now, you are logged on the camera and with the commands cd you can change the directory and with ls it is possible to list all files in the directory.

Shared usage of a directory

With NFS

Although it is possible to copy files to the camera via secure copy (scp), it is much easier to share a directory (with read and write permissions) which can be used by the development environment and the camera. This can be done by mounting the directory. A directory for shared usage is prepared in the development environment: /home/mvbc/. This directory includes all libraries as well as the examples.

To mount this directory in the directory structure of the camera, please use the following command in the Shell :

mount -n -o nolock <IP address virtual machine PC>:/home/mvbc/ /mnt/user/work

For example:

mvbc@mvSDK:~$ mount -n -o nolock 192.168.1.150:/home/mvbc/ /mnt/user/work

It is important to use the IP address of the virtual machine instead of the IP address of the host PC, given that both have different addresses. To get the address of the virtual machine, please open a new Shell and enter the command:

ifconfig eth0

You will receive result like the following:

eth0 Link encap:Ethernet Hardware Adresse 00:1d:60:5a:f4:2e
inet Adresse:192.168.1.150 Bcast:192.168.1.255 Maske:255.255.255.0

The second line shows the IP address of the virtual machine (here: inet Adresse:192.168.1.150).

Note
The IP addresses are also displayed on the VMware desktop (
See also
Figure 7).

Now you can change to the directory /mnt/user/work on the camera and with the command ls the same files are shown which you can find on the virtual machine in /home/mvbc/.

With CIFS

If you want to mount the folder by hand, with CIFS you can do this in the following way (from mvBlueLYNX-M7 to Virtual Machine (VMware) share (public)):

xxx.xxx.xxx.xxx is the IP address of the Virtual Machine (VMware).

mvBC-P> mount.cifs //xxx.xxx.xxx.xxx/public /mnt -o username=mvbc,password=mvbc,rw

Or alternatively, if you do not want to show the username and password:

mvBC-P> mount.cifs //xxx.xxx.xxx.xxx/public /mnt -o credentials=/flash/home/credentials,rw

The content of credentials would be in this example:

username=mvbc
password=mvbc
See also
http://gertranssmb3.berlios.de/output/mount.cifs.8.html

Afterwards, you can create the local sample applications as described in Running an example.

Exchange files between host PC without network connection and VMware

If you have a single PC without network connection and want to exchange files from the VMware image to this host PC, you have to do following:

  1. Share a folder of the host PC by using the standard functionality of Windows.
  2. Switch off the Firewall at least for the VMware server.
  3. In the VMware, open a file explorer using the icon "My Network Places".
    There, you will see all available Windows workgroups.

    Figure 9: My Network Places

  4. Change to the wanted workgroup and in that change to the host PC.
    You will see the shared folder and you will be able to work with these files.

Software on VMware image

All needed software can be found in the /home/mvbc/workspace/ directory.

Note
For further details of the directory structure, please have a look at Directory structure of VMware.

mvIMPACT Acquire

mvIMPACT Acquire is the API for all MATRIX VISION products excluding standard mvBlueLYNX. To control the camera and handle the images, you will have a good introduction by reading the main pages of the mvIMPACT Acquire interface references. Additionally, please have a look at the example programs. Several basic examples are available. The separate mvIMPACT Acquire manuals are

  • "mvIMPACT_Acquire_API_CPP_manual.chm",
  • "mvIMPACT_Acquire_API_C_manual.chm", and
  • "mvIMPACT_Acquire_API_NET_manual.chm"
    Due to the fact that all MATRIX VISION devices use mvIMPACT Acquire, you can program applications once and use them for all MATRIX VISION devices.

Installing mvIMPACT Acquire

mvIMPACT Acquire development environment is pre-installed and can be found in the directory /home/mvbc/workspace/mvimpact-acquire of the VMware. mvimpact-acquire is a symbolic link to the mvIMPACT Acquire development directory whose name is composed like this: mvimpact_acquire-[Version]. E.g. "mvimpact_acquire-1.10.3.81".

If you want to (re-)install mvIMPACT Acquire or mvIMPACT SDK in the VMware, please have a look at Installing driver - Linux® Updating mvIMPACT Acquire

For updating mvIMPACT Acquire API, MATRIX VISION offers two files:

  1. mvIMPACT Acquire API as ".tgz" file (e.g. mvimpact_acquire-ppc_6xx-1.10.3.84.tgz)
  2. Install file (e.g. install-ppc_6xx-1.10.4.84)
Note
This install file can only be used with the corresponding mvIMPACT Acquire API.

Briefly, to install a new mvIMPACT Acquire API in the VMware, you have to

  • copy the files to the directory /home/mvbc/workspace (please have a look at SMB) and
  • run the install script.

If you want to (re-)install mvIMPACT Acquire or mvIMPACT SDK in the VMware, please have a look at Installing driver - Linux®

Note
The existing mvIMPACT Acquire API (e.g. mvimpact_acquire-ppc_6xx-1.10.3.81) are neither overwritten nor deleted!

Make mvIMPACT Acquire samples

The mvIMPACT Acquire API can be found in the directory /home/mvbc/workspace/mvimpact-acquire. mvimpact-acquire is a symbolic link to the mvIMPACT Acquire development directory with the name:

mvimpact_acquire-[Version]

E.g.:

mvimpact_acquire-1.10.3.81

In this folder, you can find libraries and samples for a remote application (native Linux, TARGET = x86) as well as for a local application (PowerPC Linux (mvBlueCOUGAR/mvBlueLYNX-M7), TARGET = ppc_6xx)

Please follow these steps to build the existing mvIMPACT Acquire applications for mvBlueCOUGAR:

  1. Open a Shell window by clicking the desktop icon and "Shell" (
    See also
    Communication with camera).
  2. Change into directory apps:
    mvbc@mvSDK:~/$ cd workspace/mvimpact-acquire/apps
  3. Build all samples:
    mvbc@mvSDK:~/workspace/mvimpact-acquire/apps$ make ppc_6xx

To build a single sample, you have to change in to the corresponding sample directory and execute:

make ppc_6xx

in the corresponding directory or by making all samples in the root directory of mvimpact-acquire with the same command.

mvIMPACT SDK

mvIMPACT SDK is a comprehensive library with high performance algorithms for fast image processing. The library offers a software architecture with an object oriented design. With MATRIX VISION hardware, the mvIMPACT Base module, a comprehensive library with about 120 useful functions for e.g. image processing, is free of charge.

Other advanced modules like Blob, Data Matrix, etc. are available on the Virtual Machine (VMware) image as test versions.

The complete mvIMPACT manual is available as a CHM file on the MATRIX VISION website: http://www.matrixvision.de/support/manuals.php

Differences between Windows and mvBlueLYNX-M7 version of mvIMPACT SDK

The following modules are not available for the PPC - Linux mvIMPACT version of mvBlueLYNX-M7 :

vl_display Display module of mvIMPACT
vl_3ddisp mvIMPACT 3D Display
vl_device Device module of mvIMPACT
vl_driver part of mvIMPACT Base responsible for general frame grabber integration

Additionally, there is the module vl_transmit, a library for transferring images, result data like texts or overlay elements (like rectangles, points, etc.) via GigE Vision.

Make mvIMPACT SDK samples

The mvIMPACT SDK can be found in the directory /home/mvbc/workspace/mvimpact.

Please follow these steps to build the existing mvIMPACT SDK applications:

  1. Open a Shell window by clicking the desktop icon and "Shell" (see: Communication with camera).
  2. Change into directory apps:
    mvbc@mvSDK:~/$ cd workspace/mvimpact/samples
  3. Build all samples:
    mvbc@mvSDK:~/workspace/mvimpact/samples$ make ppc_6xx

To build a single sample, you have to change in to the corresponding sample directory and execute:

make ppc_6xx
See also
http://www.matrix-vision.com/image-processing-software-mvimpact-summary.html for a list of all available mvIMPACT SDK modules.

Eclipse

Eclipse is an IDE, which is available on the Virtual Machine (VMware) image. Naturally, you can use your own preferred IDE, but this section will describe the usage of Eclipse.

See also
http://www.eclipse.org for more information about Eclipse.

Starting Eclipse

For the start of Eclipse, you have to indicate the workspace:

  1. Open a Shell window by clicking the monitor icon and "Shell".
  2. Enter:
    eclipse
  3. Choose in the dialog via "Browse..." the path to the workspace.
    e.g. /home/mvbc/workspace/mvimpact-acquire/apps
    -> Eclipse starts.

Loading an existing Eclipse project

If an Eclipse applications already exists, you can load it to the IDE as following:

  1. Start Eclipse.
  2. Start import dialog via "File | Import...".
  3. After the choice "General | Existing projects into Workspace" continue with "Next>".
  4. Select via "Browse..." the path of the application's root directory
    e.g. /home/mvbc/workspace/mvimpact-acquire/apps/SingleCapture.
  5. In the box "Projects" appears a list with all projects, which are available in the chosen directory. Activate the checkbox of the corresponding project and accept the choice with "Finish".

Create a Eclipse project with an existing Makefile application

Please follow these steps:

  1. Start Eclipse.
  2. Start dialog for new C projects via "File | New | C Project...".
  3. Enter name of directory in "Project name", where the application sources with Makefile are located. If the path of the entered directory is not conform to the gray marked entry under "Location", you have to deactivate the checkbox "Use default location" and choose the corresponding directory via "Browse".
  4. Choose "Makefile project" in "Project type".
  5. Continue with "Next>".
  6. Start the advanced mode via "Advanced settings..." in the next dialog "Select Configuration".
  7. Click tab "Behaviour" in "C/C++ Build".
  8. Change entry "all" to "ppc_6xx" in "Build (Incremental build)".
  9. Accept the choice with "Ok".
  10. Finish "Select Configuration" with "Finish".

The new project is displayed in the Project Explorer. Via "Project | Build All" you can start the build (compiling and linking).

Release and debug configuration in Makefile project

Attention
Following description can only be used with MATRIX VISION applications and whose Makefile structure.

After creating an Eclipse Makefile project you can create different configurations. Please follow the next steps to create a Release and a Debug configuration.

Configuration management

To create a new configuration for a project, you have to open the dialog with the project properties:

  1. Click in the "Project Explorer" with the right mouse button on the project name and choose the menu "Properties".
    You can see in the section "C/C++ Build" the current "Configuration".
  2. Click on "Manage configurations".
  3. Create a new configuration via "New...".
  4. Enter the name of the new configuration in "Name" (Release or Debug).
  5. Optionally enter description in "Description".
  6. Confirm with "OK".
    The new configuration appears in the configuration manager.
  7. During the creation of a Makefile project, a Default configuration is created. You can remove this one via "Remove".
  8. Confirm changes with "OK".

After creation of Debug and/or Release configuration you can adapt the "Builder settings" and "Behaviour" of the Makefile make command.

Attention
The entry "Configuration" has to be Debug or Release.

You have to adapt following entries in the Debug configuration:

  1. "Builder settings"
    • Inactivate checkbox "Use default build command".
    • Set "Build command" to "make OPT=-g".
  2. "Behaviour"
    • Set "Build (Incremental build)" to "ppc_6xx".
    • Set "Clean" to "clean".
  3. Confirm these entries with "Apply".

You have to adapt following entries in the Release configuration:

  1. "Builder settings"
    • Activate checkbox "Use default build command".
    • Set "Build command" to "make".
  2. "Behaviour"
    • Set "Build (Incremental build)" to "ppc_6xx strip".
    • Set "Clean" to "clean".
  3. Confirm these entries with "Apply".

Others

Alternatively, "Denx - an embedded Linux development kit (ELDK)", is available on the VMware image (http://www.denx.de/wiki/DULG/ELDK). It includes the GNU cross development tools, such as the compilers, binutils, gdb, etc. Please have a look at the website of Denx to get an instruction how to use the ELDK.

Installation of Denx

  1. Download the ELDK from http://www.denx.de or ftp://ftp.denx.de/pub/eldk/4.2/ppc-linux-x86/iso/ppc-2008-04-01_freescale.iso
  2. Install the according to the ELDK README. Target: ppc_6xx
    ./install -d /opt/eldk42 ppc_6xx
  3. Create a symbolic link to the eldk42 in /opt/:
    ln -s eldk42 eldk

Cross-Compiling in Visual Studio

If you are working with Microsoft's Visual Studio, you can use the virtual machine as cross-compiler.

For this purpose, you can use PuTTY (plink), which can activate a make in the virtual machine via SSH. For example (using the login data of the virtual machine):

c:\Tools\PuTTY\plink -ssh -P 22 -l mvbc -pw mvbc -batch HOST cd /mnt/PROJECT_DIR; make ppc_6xx

In the virtual machine, /mnt/PROJECT_DIR can be a mounted SMB or NFS share of an existing server and has not to be inside of the virtual machine. Default directory would be /home/mvbc/workspace. Before, the share has to be mounted manually of entered in /etc/fstab.

Figure 12: Using the virtual machine as cross-compiler in Visual Studio



Directory structure of VMware

This chapter will give you a short overview about the directory structure of the VMware. This chapter will dwell on important content.

First, please have a look at following figure. This shows the complete directory structure.

Figure 17: Directory structure of VMware

mvimpact

|- samples

" |- mvbcdemos"

The samples in this folder can be compiled for mvBlueCOUGAR(ppc_6xx).

  • transmitData is described in Running an example.
  • loadTransmitData can be used to load an image from flash or hard disk and transfer the image to wxPropView on the PC.
  • patmatch, ocr, colordemo,closedCheck are mvIMPACT SDK samples, which can be complied for ppc_6xx directly.
  • mkNewmvBCLAppl.sh can be used to create a new local application, which can be compiled with ppc_6xx.

" |- linux"

In this folder you can find mvIMPACT SDK samples, which do not need a display. Display is not available on the mvBlueCOUGAR-P. These samples can be compiled with ppc_6xx and run on the mvBlueCOUGARdirectly.

" |- images"

The folder contains images needed by the samples.

" |- cpp / c"

This folder contains samples, which uses display. These samples are Windows samples and to some extent they cannot be compiled for Linux. Ergo they are not intended for mvBlueCOUGAR

|- lib

The libraries are built for the mvBlueCOUGAR/mvBlueLYNX-M7 with the "ppc_6xx-gcc" compiler and are placed in the subfolder ppc_6xx.

See also
Others for the ELDK, an embedded Linux development kit (ELDK) including GNU cross development tools, such as the compilers, binutils, gdb, etc.
Note
If you copy this folder on Windows® by using Windows® Explorer or similar Windows® programs the symbolic link will turn into a real folder and it might not work any more.

|- include

The Windows® and Linux® common and system specific header files are contained in the include folder.

mvimpact-acquire

All samples in this folder are mvIMPACT Acquire samples and do not use mvIMPACT SDK .

Figure 18: mvimpact-acquire folder

|- apps

  • SingleCapture und LiveSnap are available as Eclipse project and Eclipse can create ppc_6xx applications (see: local application)
  • wxPropView, mvIPConfigure, LiveSnapFLTK use display and for this reason they can only be used as host programs.



How to differentiate eth0 and eth1 concerning the bridged physical interfaces

There are several ways to check how the physical interfaces are assigned:

Assignment of VMNet0 and VMNet1

To check the assignment of VMNet0 and VMNet1, please start the VMware server console and open the virtual machine as described in Download and installation. Next, please follow these steps:

Step1

The select the menu item Host -> Virtual Network Settings and the tab Host Virtual Network Mapping.

Figure 19: Host Virtual Network Mapping

There, you have an overview about the assignment of the network devices.

Step2

In the VMware server console you have a list of all devices of the virtual machine.

Figure 20: VMware server console: Devices overview

Double click on the corresponding Ethernet device to check the assigned VMNet.

Figure 21: VMware server console: Network adapter

Checking the MAC addresses of the virtual machine

Open the virtual machine "Ubuntu.vmx" with an editor.

Figure 22: Virtual machine Ubuntu.vmx

Please check the Ethernet0 und Ethernet1 MAC addresses.

Figure 23: Virtual machine: MAC addresses of the Ethernet interface 0
Figure 24: Virtual machine: MAC addresses of the Ethernet interface 1

Edit config files in the virtual machine

  1. Start the virtual machine as described in Initial operation.
  2. Open the "70-persistent-net.rule" within the virtual machine.
  3. Please check, which MAC address is assigned to which eth(X) interface.

    Figure 7: 70-persistent-net.rule: assigned eth interfaces



Running an example

With the help of the transmitData sample, this section will explain

The transmitData sample uses

  • mvIMPACT Acquire to acquire images from the mvBlueCOUGAR- a mvIMPACT SDK image functions to create an rectangle and
  • vl_transmit, a library for transferring images, result data like texts or overlay elements (like rectangles, points, etc.) via GigE Vision.

The next section Programming will go into detail. But first try to start the example.

Starting a local application

Following instruction shows, how to start the mvIMPACT sample transmitData for mvBlueCOUGAR
In the example the PC with the VMware image has the IP address 169.254.4.93 and mvBlueCOUGARthe IP address 169.254.67.186.

  1. Open a Shell window by clicking the monitor icon and "Shell".
  2. Make the examples if not already done.
    (Please have a look at Make mvIMPACT Acquire samples or Make mvIMPACT SDK samples.)
  3. Connecting via ssh (user: root using "root" as password), if not already done:
    mvbc@mvSDK:~$ ssh root@169.254.67.186
  4. Mount PC directory via NFS, if not already done:
    mvBC-P> mount -o nolock -n 169.254.4.93:/home/mvbc/ /mnt/user/
    Note
    In order to be able to mount the VMware folder /home/mvbc to the mvBlueCOUGARyou need to check if the folder /mnt/user/work already exists. If there is no mnt/user/work/ directory and /mnt/user/ is empty, please use /mnt/user/ instead.
  5. Change the directory:
    mvBC-P> cd workspace/mvimpact/samples/mvbcdemos/transmitData/
    mvBC-P> pwd
    /mnt/user/workspace/mvimpact/samples/mvbcdemos/transmitData
  6. Set the system variable LD_LIBRARY_PATH to mvIMPACT SDK and mvIMPACT Acquire libraries (given that not all necessary libraries are installed on the camera by default):
    mvBC-P> export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/mnt/user/workspace/mvimpact/lib/ppc_6xx
    mvBC-P> export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/mnt/user/workspace/mvimpact-acquire/lib/ppc_6xx
    Note
    The library path is already set, if program runs in /flash/MatrixVision/bin.
  7. Start the application:
    mvBC-P> ./ppc_6xx/transmitData

Connecting to local application via wxPropView

After starting the local application, please follow this steps:

Note
At the moment changing the properties like Gain or Exposure in wxPropView will not affect the settings in the local application. These properties need to be set in the local application.
  1. Start wxPropView on your PC.
  2. Select the mvBlueCOUGARin the DropDown menu "Serial No" and click on "Use".
  3. Activate "Request info overlay" in the menu "Settings | Image display..." to make the received data visible.
    It is also possible to see the image data in the list "Requests" und "Info/UserData".
  4. Click on "Live" to start the live mode.
    The data are displayed, which were activated via the "Properties" of "Image Setting | RequestInfo"
  5. To make own data visible, you have to set "UserDate" to "On".
Figure 25: Overlay of user data and image properties on the live image.
Note
Given that the wxPropView is running in the virtual machine, it is normal that the error count increases.

Explaining the example code

Change into the directory /home/mvbc/workspace/mvimpact/samples/mvbcdemos/transmitData/ an open transmitData.cpp with your preferred editor.

  1. Please open e.g. Konqueror and change in to the directory /home/mvbc/workspace/mvimpact/samples/mvbcdemos/transmitData/
  2. Right click on transmitData.cpp and choose your preferred program in the "Open with" dialog (e.g. Kate).

Now we will have a look at the source code:

Includes

As already mentioned the transmitData.cpp sample is a little example, which uses

In the following lines the required libraries are included:

#include <mvIMPACT.h>
#include <mvIMPACT_transmit.h>
#include <mvIMPACT_CPP/mvIMPACT_acquire.h>

Main

In the main function a device handle is obtained:

DeviceManager devMgr;

Then an interface to the first MATRIX VISION device with the serial number sDevSerial is created:

Device* pDev = devMgr.getDeviceBySerial( sDevSerial );

Afterwards the Liveloop function is called, which starts live acquisition loop:

liveLoop( pDev );
cout << " == Will exit...." << endl;
pDev->close();

Liveloop

As the first action in this loop, the device is opened:

pDev->open();

Then a function interface to the device is created:

FunctionInterface fi( pDev );

Afterwards some image request buffers will be allocated. For more information about image requests, please have a look at the "How the capture process works" chapter in the respective mvIMPACT Acquire SDK manual:

  • "mvIMPACT_Acquire_API_CPP_manual.chm",
  • "mvIMPACT_Acquire_API_C_manual.chm", or
  • "mvIMPACT_Acquire_API_NET_manual.chm".
SystemSettings ss( pDev );
ss.requestCount.write( MAX_REQUESTS );

Next, an interface to send the data to the host is created (vl_transmit class):

Transmitter tr;

Then the next available result queue entry will be returned:

requestNr = fi.imageRequestWaitFor( timeout_ms );

Next, the image is added to the transmitter (vl_transmit function):

tr.AddItem( pRequest->getIMPACTImage( ));

Afterwards a blue rectangle is generated (mvIMPACT SDK function) and added to the transmitter (vl_transmit function). The parameters are the coordinates in the order left, top, right, bottom:

Rectangle rect( 100, 100, 200, 200 );
tr.AddItem( rect, 0xff );

Here a magenta text overlay to the image is created. The text shows the serial number of the mvBlueCOUGARand the amount of captured images. Then the text is added to the transmitter and finally all information are send (vl_transmit function):

char pInfo[128];
sprintf( pInfo, "Local message from: %s - ImageCnt: %06d,%d,%d", pDev->serial.read().c_str(), cnt, ib.iWidth/2, ib.iHeight/2 );
tr.AddItem( string( pInfo ), 0xff00ff );
tr.Send();

The request buffer is unlocked and a new image request is send into the capture queue:

fi.imageRequestUnlock( requestNr );
fi.imageRequestSingle( );

By pressing any key, the application will be stopped.

vl_transmit library

With the help of vl_transmit library you can transfer images, result data like texts or overlay elements (like rectangles, points, etc.) from a local application on the mvBlueCOUGAR
On a PC these data are interpreted and displayed on wxPropView.

The section Running an example shows how functions of vl_transmit can be used.

See also
vl_transmit

Possible errors when running a mvIMPACT SDK sample

Error
error while loading shared libraries:
libxxx.so: cannot open shared object file: No such file or directory
Description
This means that mvBlueCOUGARdoes not know the mvIMPACT SDK libraries.
Solution

You can set the library path to the mounted folder of your PC in which you have the libraries (see: Starting a local application). You can add the new library path to the environment variable LD_LIBRARY_PATH by exporting the variable with the system tool export and add the new path manually:

mvBC-P> export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/mnt/user/work/workspace/mvimpact/lib/ppc_6xx
Note
If you have problems with the Linux symbolic links, you can make them again like:
mvBC-P> cd /usr/lib/ppc_6xx
mvBC-P> ln -sf libvl_base.so.4.2.3 libvl_base.so.4
mvBC-P> ln -sf libvl_base.so.4.2.3 libvl_base.so
Error
error while loading shared libraries: libvl_[name].so.5:
cannot open shared object file: No such file or directory
Description
The application was linked with the mvIMPACT libraries version 5 and on the VMware image are libraries of version 6 or newer installed.
Solution

There are two solutions:

  1. Install the new mvIMPACT SDK Linux development packages and compile/link the application with this.
  2. Change into the folder /usr/lib and make a symbolic link for the version 5 library.


mvBC-P> cd /usr/lib
mvBC-P> ln -sf libvl_[name].so.X.X.X libvl_[name].so.5

Please note that X.X.X is the version of the library which should be greater as 6.0.0.

Error example:

error while loading shared libraries: libvl_display.so.5: \n
cannot open shared object file: No such file or directory
mvBC-P> cd /usr/lib
mvBC-P> ln -sf libvl_base.so.6.1.3 libvl_base.so.5
Note
After an update of the development packages and build of the applications with mvIMPACT SDK versions upon 6 this won't be needed any more.
Error
main (../blob.cpp: 14): "IPL_FlImport(&image, __null, FL_DONT_CARE, "money.tif")"
� � "Invalid file" (code: -800)
Description
This mvIMPACT SDK sample works with loaded images from the memory. The images for the samples are placed in the folder mvimpact/samples/images. This folder has to be specified for the sample.
Solution
You have to export VL_FILE_DIR
mvBC-P> cd work/workspace/mvimpact/samples/c/aoi
export VL_FILE_DIR=/data/[..]/mvimpact/samples/images/

The next section shows, how you can start your own application and how programming with mvBlueCOUGARwill work.

Programming

In the previous sections you've already seen, how you can make the samples of the Virtual Machine (VMware) image an how you can run this example locally. This section will show you

The scripts create a dummy sample source file and the needed makefiles for the build ("make") under Linux depending on the mvIMPACT and mvIMPACT Acquire directory structure. Because of this you can simply execute "make" in the new generated sample directory without needing to manually generate the makefiles.

The dummy sample contents also the needed source for the image capturing. The settings of the sample are kept global so that an image with the default camera settings will be captured. This way you could only add the individual needed camera settings (e.g. change the default expose value, change the trigger mode, etc.) and/or add the needed image processing.

Programming process

  1. Decide what application you want to write:
    1. An application to capture images and control the camera. -> Create a new mvIMPACT Acquire application
    2. An application to make image processing on images. -> Create a new mvIMPACT SDK application
  2. Write new application (optionally with an IDE like Eclipse).
    1. Note
      If you want to transfer the images, result data, etc. you will need the vl_transmit library.
    2. Note
      If you need some examples, how to program applications, you can look at the examples for:
      • mvIMPACT Acquire
        • See the example applications in the respective mvIMPACT Acquire SDK manual ("mvIMPACT_Acquire_API_CPP_manual.chm", "mvIMPACT_Acquire_API_C_manual.chm", or "mvIMPACT_Acquire_API_NET_manual.chm")
      • mvIMPACT SDK
    3. Note
      Interface documentations are available for:
      • mvIMPACT Acquire (included in this manual)
        • See the reference in the respective mvIMPACT Acquire SDK manual ("mvIMPACT_Acquire_API_CPP_manual.chm", "mvIMPACT_Acquire_API_C_manual.chm", or "mvIMPACT_Acquire_API_NET_manual.chm")
      • mvIMPACT SDK (external links)
  3. Start the local application as described here including the steps:
    1. Connecting to the mvBlueCOUGARvia ssh.
    2. Mounting the path to the example.
    3. Setting the library path.
    4. Starting the application.

Create a new mvIMPACT Acquire application

To create a new Linux application based on mvIMPACT Acquire, you can use the Shell script mknewappl.sh, which can be found in the directory apps.

Note
Some embedded systems like e.g. mvBlueLYNX and mvBlueCOUGAR have no display module.
  1. Open a Shell window.
  2. Change into directory apps:
    mvbc@mvSDK:~/$ cd workspace/mvimpact-acquire/apps
  3. Execute the script mknewappl.sh as follows:
    ./mknewappl.sh myDemo

A new directory with the name "myDemo" will be created. In this directory there are

The code in myDemo.cpp shows the acquisition of one image. You can modify this code to your own needs.

Adapt the application's Makefiles

Based on the work folder e.g. [..]/workFolder/ mvIMPACT Acquire applications like myDemo have following Makefile structure:

  • apps/myDemo/Makefile -
    contains the TARGETS (e.g. x86, arm, ppc_6xx, etc.) depending on the used toolchain. It also includes all make rules (e.g. all, clean, new, build, etc.), see also: Makefile (mvIMPACT Acquire).
  • apps/myDemo/Makefile.inc -
    contains the specific part for the application. These settings can be made (see also Makefile.inc (mvIMPACT Acquire)):
    • OOBJ - here you can add the names of further source files, which the application needs: e.g.
      OOBJ = myAdditionalSource.o
      Attention
      The generated source file (myDemo.o) is integrated in apps/Makefile.samp.inc automatically, so it should not be named in OOBJ.
    • vpath - shows the type of the used source files. As additional parameter you have name the path to the source file. You can use ":" or a free space as seperator. e.g.
      vpath %.cpp .. ../../myAdditionalSourceFolder
      or
      vpath %.cpp ..:../../myAdditionalSourceFolder
      • C Source - "%.c"
      • C++ Source - "%.cpp"
      • C and C++ Source - "%"
    • USR_INCLS - additional include directories; e.g.
      USR_INCLS = -I../../myAdditionalIncludeFolder
    • USR_LIBS - additional libraries, e.g.
      USR_LIBS = -lNeededLib -L../../myAdditionalLibFolder -lmyAdditionalLib
    • CPPFLAGS_1 - additional compilers or pre-processors options, e.g.
      CPPFLAGS_1 = -D__DEBUG -W
  • apps/Makefile.samp.inc -
    global Makefile. It contains the most settings to build an application. In this file, the settings are identically with all created applications in apps. To minimize all redundant information for all applications, this file was created.
  • common/System/linux/Makefile.all.inc -
    contains specific settings for used toolchain. Makefile.all.inc needs toolchain path settings from the file common/System/linux/config.inc.

Create a new mvIMPACT SDK application

To create a new Linux application based on mvIMPACT SDK, you can use the Shell script mkNewmvBCLAppl, which can be found in the directory mvimpact/samples/mvbcdemos/.

Note
Some embedded systems like e.g. mvBlueLYNX and mvBlueCOUGAR have no display module.
  1. Open a Shell window.
  2. Change into directory apps:
    mvbc@mvSDK:~/$ cd workspace/mvimpact/samples/mvbcdemos
  3. Execute the script mkNewmvBCLAppl.sh as follows:
    ./mkNewmvBCLAppl myDemo

A new directory with the name "myDemo" will be created. In this directory there are

The generated file myDemo.cpp file contains by default the source code for the "Hello, world" sample. You can modify this code to your own needs.

Adapt the application's Makefiles

Based on the work folder e.g. [..]/workFolder/ mvIMPACT SDK applications like myDemo have following Makefile structure:

  • samples/linux/cpp/myDemo/Makefile -
    contains the TARGETS (e.g. x86, arm, ppc_6xx, etc.) depending on the used toolchain. It also includes all make rules (e.g. all, clean, new, build, etc.), see also: Makefile (mvIMPACT SDK).
  • samples/linux/cpp/myDemo/Makefile.inc -
    contains the specific part for the application. These settings can be made (see also Makefile.inc (mvIMPACT SDK)):
    • MODULE_NAME - Under MODULE_NAME you will find the name of your demo or sample. The generated binary will have the same name and will be placed in the subfolder (ppc_6xx) generated by Makefile.demotarg.inc.
    • OOBJ - here you can add the names of further source files, which the application needs: e.g.
      OOBJ = mynewfile1.o mynewfile2.o
      Attention
      The generated source file (myDemo.o) is integrated in apps/Makefile.samp.inc automatically, so it should not be named in OOBJ.
    • vpath - shows the type of the used source files. As additional parameter you have name the path to the source file. You can use ":" or a free space as seperator. e.g.
      vpath %.cpp .. ../../myAdditionalSourceFolder
      or
      vpath %.cpp ..:../../myAdditionalSourceFolder
      • C Source - "%.c"
      • C++ Source - "%.cpp"
      • C and C++ Source - "%"
    • IMPACT_LIBS - here you have to specify the mvIMPACT libraries that you wish to be linked to the sample; e.g.
      IMPACT_LIBS = -lvl_device \
      -l[name] \
      -lvl_blob \
      -lvl_base
    • USR_INCLS - additional include directories; e.g.
      USR_INCLS = -I../../myAdditionalIncludeFolder
    • USR_LIBS - additional libraries, e.g.
      USR_LIBS = -lNeededLib -L../../myAdditionalLibFolder -lmyAdditionalLib
    • CPPFLAGS_1 - additional compilers or pre-processors options, e.g.
      CPPFLAGS_1 = -D__DEBUG -W
  • mvimpact/Makefile.samp.inc -
    global Makefile. Is needed by all samples, demos and libraries.
  • mvimpact/Makefile.demotarg.inc -
    target Makefile. Will create the target subfolders (x86, arm, ppc_6xx, etc.).
  • mvimpact/samples/Makefile.samp.inc -
    build Makefile. Contains the build rules. Will be included by Makefile.inc (mvIMPACT SDK) placed in the sample/linux/demo folder (e.g. in samples/linux/c/aoi).

Masking memory as a mvIMPACT SDK image buffer handle

To mask a user allocated memory for the image buffer as an mvIMPACT image buffer handle (IPL_BUFHANDLE), you need to implement dev_AllocUsrBuf().

Note
Please note that the memory must be freed after it is no longer needed by the user and it will not be freed by mvIMPACT.
IPL_BOOL dev_AllocUsrBuf( IPL_BUFHANDLE* pImageHandle, BYTE* pImagePtr, const int iWidth, const int iHeight )
{
IPL_DEVICEINFO info;
info.DevId = -1;
info.IdentStr = (char*) pImagePtr;
info.Flags = IPL_USER_MEM;
IPL_BUFFER_ATTRIBUTE Attribute = IPL_IMAGEBUF;
return IPL_BufAlloc2D( pImageHandle, iWidth, iHeight, IPL_DTUCHAR, Attribute, &info );
}
Parameters
pImageHandleOutput buffer handle
pImagePtrInput pointer to the user memory
iWidthwidth of the user memory
iHeightheight of the user memory

Notes about debugging

For debugging you can use every tool, which can address GDB - this debugger works also remotely. However, GDB is not available locally, but you can mount it via NFS or SMB.

Unlike PCI(e) devices cannot disappear during runtime and USB devices, where the system informs you about appearing and disappearing, network devices haven't got such a behavior.

Thus the GigE Vision standard defines a procedure, which will check, if a device or the connected application to the device still exists. A device, which was opened by a primary application (it has the write access to the register), will closed automatically, if the application does not access (read or write) the device within a predefined timeout (default 3000ms).

This behavior has influence over the debug behavior of an application: If you jump to a breakpoint of the application, the cyclic reading will be stopped, but not the device. During debugging, it could be possible that the device is closed, although the user did not initiate it.

To change this behavior during debugging, it is possible to set the timeout on a high value. But if you finish the application without signing off the device correctly (reset CCP register), you will have no access to the device until the timeout is elapsed or you disconnect the device.