C++ Example

Table of Contents

• Build and rund the C++ example
  • Windows
    • Prerequisites
    • Building the example program
    • Runing the example program
  • Linux
    • Prerequisites
    • Building the example program
    • Running the example program
• Examine the source code
  • Error handling
  • Opening the factory
  • Opening a device
    • Open device by using the factory
    • Open device by using Open()
  • Using the device
  • Closing devices and the factory

How to build and run the first example program

Build and rund the C++ example

Windows

Prerequisites

IMAGO delivers the VisionBox with a pre-installed Windows OS including the IMAGO SDK and the required drivers. The SDK provides the DLLs, import libraries and header files for building the example program.

The example program FirstTest demonstrates the use of the library. The source code is available in the following SDK directory:

<SDK installation folder>\examples\C++\FirstTest

Note that the SDK installation folder is also stored in the Windows system environment variable IMAGO_AGEX_BASEPATH.

Building the example program

The example folder contains a solution file for Microsoft Visual Studio: FirstTest.sln
The Visual Studio project already contains the correct compiler options.

Using other compilers is also possible. The following compiler and linker settings are required to build the program:

• Compiler:
  Add include path for header files: <SDK installation folder>\include
• Linker:
  Add the VIB Interface DLL import library to the linker input
  • for 32 bit applications: <SDK installation folder>\lib\VIB_Interface.lib
  • for 64 bit applications: <SDK installation folder>\lib\VIB_Interface_amd64.lib

Runing the example program

Depending on the hardware, the console output of the program should look similar to this:

Version numbers ==>
<-- API -->
Version Number (major.minor.patchlevel.buildnumber):
1.6.9.1
Compile Date:
...
 
Serial number: 'AGEX1903400122'
 
Found 1 Digital Output device(s)
    Setting output signals...
 
Closing devices...

Linux

Prerequisites

This document requires the user to have successfully walked through the "Getting Started Guide" for logging into the command line of the device. A basic understanding of using the Linux command line is also required.

IMAGO delivers the VisionBox, VisionCam and VisionSensor with a pre-installed Debian Linux root filesystem including development tools like the GNU GCC compiler and the Make utility. Additionally, the IMAGO SDK package provides the required kernel modules and libraries. In order to build and run the example program, there is no need to install or configure anything else.

The example program FirstTest demonstrates the use of the library. It can be executed on all supported platforms. The source code is located at the following SDK directory:

/opt/ImagoTechnologies/SDK/examples/FirstTest_Linux

Building the example program

The example directory contains a Makefile which uses the required library and compiler settings for building the program:

• GCC compiler options (header search path):
  -I/opt/ImagoTechnologies/SDK/include
• GCC linker options (library search path and shared library name):
  -L/opt/ImagoTechnologies/SDK/lib/ -lVIBInterface

In order to build the program, login to the device and copy the source code to your home directory. Then, build the project by executing 'make':

> cp -r /opt/ImagoTechnologies/SDK/examples/FirstTest_Linux ~/
> cd ~/FirstTest_Linux
> make

Running the example program

After successful build, the program can be started:

> ./FirstTest_Linux

Depending on the hardware, the console output should look similar to this:

Version numbers ==>
<-- API -->
Version Number (major.minor.patchlevel.buildnumber):
1.6.9.1
Compile Date:
...
 
Serial number: 'VCXM1811000833'
 
Found 1 Digital Output device(s)
    Setting output signals...
 
Closing devices...

Examine the source code

The FirstTest example source code is the same for the Linux and Windows SDK: FirstTest.cpp

Error handling

All library functions return a Boolean result which indicates the success of the function call. To keep the example clear, we add a little helper function to test the result of every library call. In case of an error, the helper function reads out the error message of the library and throws an exception:

void TestRes(bool result)
{
    char ErrText[512];
 
    // was the function call successful?
    if (result)
        return;
 
    // read error string
    VIB::VIBSystem::GetLastErrorString(*ErrText, sizeof(ErrText));
 
    throw std::runtime_error(ErrText);
}

Now, we can put all library function calls in a try / catch block and use the helper function as follows:

...
try
{
    // open the factory
    TestRes(VIB::VIBSystem::CreateInstance(&pVIBSystem));
    ...
}
catch (std::runtime_error &err)
{
    printf("Error:\n %s\n", err.what());
}
catch (...)
{
    printf("Error: Unknown exception\n");
}
...

Opening the factory

The first step in the main() function is to create a VIB::VIBSystem factory object for the mainboard hardware entity. This allows us to acquire and print version information about the libraries and the firmware:

    VIB::VIBSystem      *pVIBSystem     = NULL;
    VIB::Service        *pService       = NULL;
 
    try
    {
        // open the factory for the mainboard
        TestRes(VIB::VIBSystem::CreateInstance(&pVIBSystem));
        // -> is the same as:
        // VIB::VIBSystem::CreateInstance(&pVIBSystem, VIB::SYST_BASEBOARD, 0);
 
        // read out version string
        std::vector<char>pstText(4096);
        TestRes(pVIBSystem->GetVersionString(&pstText[0], 4096));
        printf("Version numbers ==>\n%s\n", &pstText[0]);

Opening a device

The example opens two devices using different methods:

Open device by using the factory

The VIB::Service device is opened by using the factory function VIBSystem::OpenDevice(), see page Device Factory for a description:

        // open the Service device by using the factory
        TestRes(pVIBSystem->OpenDevice(pService));

Depending on the device class, the overloaded OpenDevice() function has an Index parameter which selects the component on the hardware entity if multiple of the same type are present.

Open device by using Open()

The VIB::DigitalOutput device is opened by using the device object's member function Open(), see page Open devices using the Open() method for a description:

        // === try to open the first DigitalOutput device ===
        VIB::DigitalOutput digitalOutput;
        if (digitalOutput.Open(0))
        {
            printf("\nFound Digital Output device\n");

This method doesn't require a factory for opening the device. The Index parameter specifies the component for the given device type across all hardware entities. Depending on the actual hardware configuration of the system, the DigitalOutput device may not be available and the function returns an error.

Using the device

After a device is opened, we can start using the device.

Each device class has its own set of member functions. Refer to the device class documentation for a detailed description. See also Devices for a list of supported devices.

            printf("    Setting output signals...\n");
 
            // turn all outputs on (up to 16)
            TestRes(digitalOutput.Set(0xffff));
 
            // turn output signals off one after another
            unsigned int outputSignals;
            TestRes(digitalOutput.GetNumberOfOutputs(outputSignals));
            for (unsigned int signal = 0; signal < outputSignals; signal++)
            {
                usleep(100*1000);
                TestRes(digitalOutput.SetBit(signal, false));
            }

Closing devices and the factory

All device objects have to be closed before they can be used again.

In the example, the DigitalOutput device automatically gets closed when the object is destructed, but it could also be closed manually by using the function Close().

        // the device 'digitalOutput' is automatically closed by the destructor
    }

The Service device is closed by using the factory again. Then, the factory itself is also closed:

    if (pVIBSystem != NULL)
    {
        printf("\nClosing devices...\n");
 
        if (pService != NULL)
            pVIBSystem->CloseDevice(pService);
 
        VIB::VIBSystem::DeleteInstance(pVIBSystem);
    }