XGRIDSDocs

Quick Start

This page walks you through C++: prepare the environment → build → integrate into your project → send your first request. The C++ client is Linux only.

Requirements

ItemVersionNote
OSLinuxverified on Ubuntu 22.04
CMake3.16 or newertested with 3.22.1
C++ compilerC++14tested with GCC 11.4
git, network—needed at configure time to fetch the pinned dependencies
OpenSSL dev files—libssl-dev
lz4 dev files1.9 or newerliblz4-dev, found through pkg-config

CMake fetches and pins two dependencies at build time; no manual install needed:

DependencyVersionWhy
protobufv21.12 (3.21.12)generated code and runtime must be the same release
paho.mqtt.cv1.3.13the release the device side builds against

Install the system dependencies (Ubuntu):

sudo apt-get update
sudo apt-get install -y build-essential cmake git libssl-dev liblz4-dev pkg-config

Build and test

From the repository root:

cmake -S cpp -B cpp/build
cmake --build cpp/build -j
ctest --test-dir cpp/build --output-on-failure

The first configure builds protobuf from source. A clean build took about 47 s with 20 parallel jobs on the verified machine (Ubuntu 22.04).

Note: Ubuntu 22.04 ships protobuf 3.12.4, below this project's requirement. The default option AUTO automatically builds the pinned release (3.21.12) instead, with no action needed from you.

The build output includes 18 examples in cpp/build/examples/:

./cpp/build/examples/heartbeat --seconds 5                 # no key needed
./cpp/build/examples/device_info --key <provided by XGRIDS>
./cpp/build/examples/modeling --key <provided by XGRIDS> --project demo --watch 8

Integrate into your project

There is no install or CMake package export yet; add cpp/ to your project with add_subdirectory (protobuf and paho are fetched by it):

set(LIXEL_OPENAPI_BUILD_TESTS OFF)
set(LIXEL_OPENAPI_BUILD_EXAMPLES OFF)
add_subdirectory(path/to/Lixel_OpenAPI/cpp lixel)
target_link_libraries(my_app PRIVATE LixelOpenApi::lixel_openapi)

Your first request

Connect to the device and query device info:

#include "lixel/openapi/client.h"
#include "openapi/aiot_msgs.pb.h"

lixel::openapi::ClientOptions options;
options.transport.host = "192.168.55.1";
options.openapi_key = "<provided by XGRIDS>";

lixel::openapi::Client client(options);
if (!client.Connect().ok()) return 1;

openapi::aiot_msgs::DeviceInfoRequest request;
openapi::aiot_msgs::DeviceInfoResponse response;
lixel::openapi::Result r = client.Request(
    "lixel/application/request/device_info", request,
    "lixel/application/response/device_info", &response);
// r.ok(): the device answered with a success code.
// r.code == Errc::DeviceError: the device answered with an error code (see r.device_code, r.desc), response is filled.
// r.code == Errc::RequestTimeout: no response arrived.

Request fills header.seq, header.openapi_key, and header.device_id into the request automatically. A response is matched by header.seq, which the device copies back.

Next steps