GoPxL SDK and REST API

The GoPxL Software Development Kit (GoPxL SDK) includes open-source software libraries and documentation that you can use to programmatically access and control GoPxL devices.

The GoPxL SDK and REST API use the term "scanner" instead of "sensor group." The two are interchangeable.

The following sections describe the Software Development Kit (GoPxL SDK).

The GoPxL Development Kit (GDK) will be available in a later release.

Setup and Location of GoPxL SDK and REST API References

The GoPxL SDK, and the SDK and REST API references, are available in the 14630-1.0.x.x_SOFTWARE_GoPxL_SDK.zip package.

The SDK zip file contains both a C++ and a .NET SDK. They are organized as follows:

• x.x.x.x_SOFTWARE_DEV_GoPxL_SDK\GoPxL_SDK_Cpp\
• x.x.x.x_SOFTWARE_DEV_GoPxL_SDK\GoPxL_SDK_dotNet\

Please choose the type of SDK (C++ or .NET) that you will be working with. The directory paths in the documentation below will be relative to either x.x.x.x_SOFTWARE_DEV_GoPxL_SDK\GoPxL_SDK_Cpp\ (for C++ SDK) or x.x.x.x_SOFTWARE_DEV_GoPxL_SDK\GoPxL_SDK_dotNet\ (for the .NET SDK), if the full path is not fully specified. The following references are availab;e:

• The full GoPxL SDK class reference is available in the following file: x.x.x.x_SOFTWARE_DEV_GoPxL_SDK\GoPxL_SDK_Cpp\doc\GoPxLSdk\GoPxLSdk.html.

• The full REST API reference is available in the following file: x.x.x.x_SOFTWARE_DEV_GoPxL_SDK\GoPxL_SDK_Cpp\doc\rest-api-doc.html.

Visual Studio Solution Files and Linux Makefile

Visual Studio solution files are included for both the C++ and .NET SDKs.

• x.x.x.xx_SOFTWARE_DEV_GoPxL_SDK\GoPxL_SDK_Cpp\Gocator
• x.x.x.xx_SOFTWARE_DEV_GoPxL_SDK\GoPxL_SDK_dotNet\Gocator

In Linux, first ensure that you have the g++ compiler package and then run the following command from GoPxL_SDK_Cpp\Gocator\GoPxLSdk directory:

> make -f GoPxL_SDK_Cpp/Gocator/GoPxLSdk/GoPxLSdk-Linux_X64.mk

Note that only the C++ SDK is supported on Linux.

Building the SDK

To compile in Visual Studio, you may need to retarget the solution to the installed Windows SDK version. To retarget a solution, open the solution in Visual Studio, right-click the solution in the Solution Explorer, choose Retarget solution in the context menu, and click OK.

The compiled Linux output libraries can be found in the GoPxL_SDK/lib/linux_x64 directory.

The GoPxL SDK can be compiled using the following environment requirements:

• Visual Studio 2017; with more recent versions, you must retarget the solution

• GCC X64 compiler, version: 7.5.0 (GccX64_7.5.0-p3)

The GoPxL SDK uses mm, mm², mm³, hertz, microseconds, and degrees as standard units unless otherwise mentioned.

Header Files

Header files are referenced with GoPxLSDK as the source directory, for example: #include <GoPxLSdk/GoRestClient.h>.

The SDK header files also reference files from the kApi directory, for example, #include <kApi/kApiDef.h>.

Sample Projects

Sample projects showing how to perform various operations are provided, each one demonstrating a specific area. A makefile for Linux systems is also provided after running generate.py. Examples are located in the following folders:

• C++: x.x.x.xx_SOFTWARE_DEV_GoPxL_SDK\GoPxL_SDK_Cpp\Gocator\GoPxLSdk\samples
• .NET: x.x.x.xx_SOFTWARE_DEV_GoPxL_SDK\GoPxL_SDK_dotNet\Gocator\GoPxLSdkNet\samples

Functional Hierarchy of Classes

GoPxL offers a simple programming API interface for connecting, configuring, and acquiring data from sensors and the GoMax vision accelerator.

Example code shown below as examples are for C++ SDK programs.

All C++ GoPxL SDK programs should have the sequence described below, at the minimum. The .NET SDK programs may require less.

The following sequence assumes you know the IP address of the device. If you do not know the IP address or it's not static, an application can discover the devices that are available on the network using the GoPxL SDK discovery capability. For more information, see Discover Devices.

1
2
// Constructs GoPxL API core framework.
                GoApiLib_Construct(&goApiLib)

1
2
3
4
5
#define SENSOR_IP       "192.168.1.10"
                    kIpAddress ipAddress;
                    kIpAddress_Parse(&ipAddress, SENSOR_IP);
                    system = GoSystem(ipAddress);
                system.Connect();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
gdpClient = std::make_unique<GoGdpClient>();
                    gdpClient->Connect(ipAddress)

                    // Callback function for ReceiveDataAsync()
                    void onData(const GoDataSet &receivedDataSet)
                    {
                    for (size_t i = 0; i < receivedDataSet.Count(); i++)
                    {
                    case GoPxLSdk::MessageType::MEASUREMENT:
                    {
                    const GoGdpMeasurement &MeasurementMsg = (const GoGdpMeasurement &)receivedDataSet.GdpMsgAt(i);
                    std::cout << "Array count: " << std::endl;
                    std::cout << "Value: " << MeasurementMsg.Value() << std::endl;
                    break;
                    }
                    }
                    }

                    // Establish an asynchronous data transfer.
                    std::function<kStatus(GoDataSet* pDataSet)> func = onData;
                gdpClient->ReceiveDataAsync(func)

1
2
3
4
5
6
7
8
// Start sensor
                    system.RunningState() != GoSystem::State::Running)
                    {
                    system.Start();
                    }

                    // Stop the sensor.
                system.Stop();

After the device starts running, data will be streamed to the onData function handler as it becomes available. For more information, see Receive Device Data.

If required, you can configure the device settings, such as changing exposure value, using system.Client(). For more information, see Configure Device Settings.

Discover Devices

If a device IP address is not known (for example, because it is assigned through DHCP), you can discover the devices available on the network using the GoPxL SDK discovery function by instantiating a GoDiscoveryClient class and calling the BlockingDiscover function.

1
2
3
// Discover GoPxL instances on the network.
                std::unique_ptr<GoDiscoveryClient> discovery = std::make_unique<GoDiscoveryClient>();
            discovery->BlockingDiscover(10000);

After the discover function is completed, you can loop through the instances vector to get device information and IP addresses:

1
2
3
4
5
6
7
8
instances = discovery->InstanceList();
                for (size_t i = 0; i < instances.size(); i++)
                {
                const GoInstance& instance = discovery->InstanceList().at(i);
                kIpAddress_Format(instance.GetIpAddress(), ipAddress, 
                std::cout << "IP Address: " << ipAddress << std::endl;
                ++instanceCount;
            }

For more information, see the Discover sample.

Configure Device Settings

You configure GoPxL device settings, which are represented as JSON resources, through JSON-based REST API commands. GoSystem includes a client class instance you can use to read and write settings.

You use the system.Client().read and system.Client().write functions, among others, to access and modify a wide variety of parameters using the following format:

"command /path/to/callable/resource {'argument':'value'}"

For the full list of resources available, please see the REST API Resources and User Guide (x.x.x.xx_SOFTWARE_DEV_GoPxL_SDK\GoPxL_SDK_Cpp\doc\rest-api-doc.html).

The following sections describe the more common use cases.

It's important to understand that GoPxL device settings are divided into two general types:

• sensor-level: These settings only apply to individual sensors

• scanner-level: These settings apply to all of the sensors in a group of sensors (a "scanner")

To help explain the functions, some sections below include definitions of the API resources.

Accessing Sensor Resources

The most common use case is modifying settings that apply to individual sensors, such as exposure or active area.

If you know a device's serial number, you can access the corresponding resource using the SensorPath function.

1
std::string sensorPath = system.SensorPath(sensorSerialNumber);

You can then access the settings under the sensor resources.

1
2
3
4
5
// Update Single Exposure:
SENSOR_PATH = "/scan/engines/g2xxx/scanners/scanner-0/sensors/sensor-0";
system = GoSystem(ipAddress);
payload = GoJson("{\"parameters\" : {\"exposureSettings\" : {\"exposureMode\" : 0, \"singleExposure\" : 400} }}");
system.Client().Update(SENSOR_PATH, payload)

Accessing Scanner Resources

You access system-level settings (those that apply to a group of sensors) through the scanner resources.

If you know the engine ID and scanner ID (available in the REST API reference documentation), you can use the following to access the scanner and modify the trigger setting:

1
2
3
4
SCANNER_PATH = "/scan/engines/g2xxx/scanners/scanner-0";
system = GoSystem(ipAddress);
payload = GoJson("{\"parameters\" : {\"triggerSettings\" : {\"source\" : 0} }}");
system.Client().Update(SCANNER_PATH, payload).

Configuring scanner resources through the SDK is less common. These resources are related to physical setup. Normally, you configure these settings through the user interface during the initial system installation and setup, and the settings don’t need to change for different production runs.

Accessing an Array Element

Some resources are returned as an array. One example is the visibleSensors resource, which can have multiple elements .

The following returns an array of sensors under the /scan/visibleSensors resource path.

1
sensors = system.Client().Read(VISIBLE_SENSORS_PATH).GetResponse().Content().At("sensors");

You can then access elements of the returned array:

1
2
sensor = sensors.Begin();
std::string sensorSerialNumber = sensor.Value().At("/serialNumber").Get<std::string>();

Instantiate a GoPxL Data Protocol Client (GoGdpClient) and connect it to the discovered device.

1
2
gdpClient = std::make_unique<GoGdpClient>();
gdpClient->Connect(instance.GetIpAddress())

Receive Device Data

GoPxL streams out acquired data (such as Profile and Surface data, and measurements) using the GoPxL Data Protocol (GDP). To receive the data, you use a GoGdpClient instance, first connecting it to the device. You can use GoPxLSdk::MessageType to identify the type of received data and the associated stamp information. Stamps contain encoder, trigger timing information, current time, and the frame index, and are grouped into a dataset with their corresponding data.

1
2
3
4
5
6
7
auto gdpClient = std::make_unique<GoGdpClient>();
                auto ipAddress = instance.GetIpAddress();
                if ((status = gdpClient->Connect(ipAddress)) != kOK)
                {
                std::cout << "Error: " << status << " - Failed to connect to the GDP server. Make sure Ethernet output is available." << std::endl;
                return -1;
            }

Data can be received on the same thread used for controlling the sensors (that is, synchronously) or on a different thread (that is, asynchronously).

For synchronous data retrieval:

1
2
3
// Surfaces take longer to generate, so need to wait longer.
// Set to 3 seconds here.
gdpClient->ReceiveDataSync(3000000)) pDataSet = gdpClient->DataSet();

For more information, see the ReceiveProfile and ReceiveSurface samples.

For asynchronous data retrieval:

1
2
std::function<kStatus(GoDataSet* pDataSet)> func = onData;
dpClient->ReceiveDataAsync(callbackFunction)

Data is received in the onData function call:

1
2
3
4
5
kStatus onData(GoDataSet* pDataSet)
{
    std::cout << "Total number of messages in this data set: " << pDataSet->Count() << std::endl;
    …
}

For details, see the ReceiveAsync sample.

Note that data is received as the GoDataSet type. For more information on GoDataSet, see GDP Data Types.

Receive Health and Metrics Information

Health information is sent out using the REST client interface.

1
2
3
4
5
6
7
8
9
10
11
12
13
// Callback function for SetStreamHandler().
static void onMetrics(const std::shared_ptr<GoStreamResponse> &notification)
{
    GoJson content = notification->Payload();
    cout << "\nApplication Uptime: " << content.Get<int>("/appUpTime") << endl;
    cout << "CPU Cores Usage Average: " << content.Get<int>("/cpuCoresUsedAvg") << endl;
    cout << "Memory Capacity: " << content.Get<double>("/memCapacity") << endl;
}

// Running callback function to receive metrics
system.Client().SetStreamHandler(onMetrics);
system.Client().StartStream("/system/metrics");
system.Client().StopStream("/system/metrics");

For more information, see the ReceiveHealth sample.

Accelerated Devices

Control of devices accelerated by GoMax NX or a PC instance of GoPxL uses the same function API. The only difference is that you must use the IP address of the GoMax NX device or the PC running GoPxL when connecting to the device (that is, in system->Connect()).

GDP Data Types

Value Types

The GoPxL SDK is built on a set of basic data structures, utilities, and functions, which are contained in the kApi library.

The following basic value types are used by the kApi library.

Output Types

Data outputs are encapsulated as data messages in the GoPxL SDK. The following message types are available in the SDK.

*Not commonly used in a production system.

All of the messages above are extended from GoGdpMsg. For more information, see GoDataSet.

GoDataSet

Data is passed to the data handler in a GoDataSet object. The GoDataSet object is a container that can hold any type of data, including scan data (sections or surfaces), measurements, or results from various operations. Data inside the GoDataSet object is represented as messages. The following illustrates the content of a GoDataSet object of a Surface mode setup with two measurements.

Measurement Values and Decisions

There are two outputs for each measurement; value and decision. A measurement value is returned as a 64-bit number.

The measurement decision specifies the state of the measurement value as follows: