API reference Introduction HubClient is a class containing the main functions you will use in applications to communicate between your device and the cloud. HubClient is a singleton meaning that you don’t have to create an HubClient object, there is a unique instance of the class that will be used by the static functions. CallbackParameters CallbackParameters class CallbackParameters Creates a callback "package" (function name, parameters, ...) that can be registered using HubClient::registerFunction. Usage // Setup a callback function in case of a device parameter change CallbackParameters callback_param; // Use "|" if you want your callback to be set on several parameters callback_param.setParameterCallback("onParamChange", "camera_resolution|camera_fps|camera_image_flip", CALLBACK_TYPE::ON_PARAMETER_UPDATE); // Register your function HubClient::registerFunction(onInitParamUpdate, callback_param); CallbackParameters static function setConfigurationCallback ( std::string function_name , std::string setting_key , callback_type callback_type , std::vector<FunctionParameterDescription> parameters ) Generates configuration callback parameters (for device twin update). function_name std::string The name of the function callback. setting_key std::string The device twin key that will activates the callback on update. callback_type callback_type optional allowed callback_type for this function is CALLBACK_TYPE::ON_CONFIGURATION_UPDATE parameters std::vector<FunctionParameterDescription> optional Vector of function parameters. Usage // Setup a callback function in case of a device twin configuration change CallbackParameters callback_param; callback_param.setConfigurationCallback("onHostSoftwareUpdate", "host.software", CALLBACK_TYPE::ON_CONFIGURATION_UPDATE); // Register your function HubClient::registerFunction(onHostSoftwareUpdate, callback_param); CallbackParameters static function setRemoteCallback ( std::string function_name , callback_type callback_type , std::vector<FunctionParameterDescription> parameters ) Generates remote function callback parameters (for remote function calls). function_name std::string The name of the function callback. callback_type callback_type optional allowed callback_type for this function is CALLBACK_TYPE::ON_REMOTE_CALL parameters std::vector<FunctionParameterDescription> optional Vector of function parameters. Usage // Set a remote callback for the function "functionCall" CallbackParameters callback_param; HubClient::setRemoteCallback("functionCall", CALLBACK_TYPE::ON_REMOTE_CALL); // Register your function HubClient::registerFunction(onFunctionCall, callback_param); CallbackParameters static function setParameterCallback ( std::string function_name , callback_type callback_type , parameter_type parameter_type , std::vector<FunctionParameterDescription> parameters ) Generates parameter callback parameters (for device or application requested parameters update). function_name std::string The name of the function callback. callback_type callback_type optional allowed callback_type for this function is CALLBACK_TYPE::ON_PARAMETER_UPDATE parameter_type parameter_type optional The requested parameter type that can be PARAMETER_TYPE::APPLICATION or PARAMETER_TYPE::DEVICE (default: DEVICE). parameters std::vector<FunctionParameterDescription> optional Vector of function parameters. Usage // Setup a callback function in case of an application parameter change CallbackParameters callback_param; // Use "|" if you want your callback to be set on several parameters callback_param.setParameterCallback("onParamChange", "first_param|second_param", CALLBACK_TYPE::ON_PARAMETER_UPDATE, PARAMETER_TYPE::APPLICATION); // Register your function HubClient::registerFunction(onParamUpdate, callback_param); CallbackParameters static function reset ( ) Resets the CallbackParameters structure to reuse it. Usage // Setup a callback function in case of an application parameter change CallbackParameters callback_param; callback_param.setParameterCallback("onFirstParamChange", "first_param", CALLBACK_TYPE::ON_PARAMETER_UPDATE, PARAMETER_TYPE::APPLICATION); // Register your function HubClient::registerFunction(onFirstParamUpdate, callback_param); // Reset the CallbackParameters structure callback_param.reset(); callback_param.setParameterCallback("onSecondParamChange", "second_param", CALLBACK_TYPE::ON_PARAMETER_UPDATE, PARAMETER_TYPE::APPLICATION); // Register your function HubClient::registerFunction(onSecondParamUpdate, callback_param); DataParameters DataParameters struct UpdateParameters A structure that defines parameters used in the HubClient::update function. enable_recording bool Enable the recordings (default: true). enable_zed_sdk_streaming bool Enable the SDK streaming (default: false). enable_rtsp_streaming bool Enable the RTSP streaming (default: false). recording_bitrate int Bitrate of the recordings in Kbit/s (default: 2200). streaming_width int With of the streaming in pixel (default: 1280). streaming_height int Height of the streaming in pixel (default: 720). Usage UpdateParameters update_params; update_params.enable_rtsp_streaming = true; HubClient::update(update_params); HubClient::register(p_zed, update_params); DataParameters struct LogParameters A structure that defines parameters for logs that can be used in the HubClient::sendLog function. timestamp unsigned long long Defines the timestamp of the log in milliseconds. 0 gives the current timestamp when the log is sent. retention int Retention of the log in days. 0 gives the default retention for logs. reference std::string Gives a specific id to the log to be used to send data to this log. reference_to std::string The log will be incremented to the log that was sent with this value as reference. Usage LogParameters log_params; log_params.retention = 2; // 2 days HubClient::sendLog("Info log sent, will be deleted in 6 hours", LOG_LEVEL::INFO, "label", log_params); DataParameters struct TelemetryParameters A structure that defines parameters for telemetry that can be used in the HubClient::sendTelemetry function. timestamp unsigned long long Defines the timestamp of the telemetry in milliseconds. 0 gives the current timestamp when the telemetry is sent. retention int Retention for telemetry in days. 0 gives the default retention for telemetry. tags std::string optional Tags to add to the telemetry. Usage ts_start = getCurrentTimestamp(); sl_iot::json telemetry_data; // Do some stuff with telemetry_data during a certain amount of time TelemetryParameters telemetry_params; telemetry_params.timestamp = ts_start; // Send the telemetry with the right timestamp HubClient::sendTelemetry("telem", telemetry_data, telemetry_params); DataParameters struct EventParameters A structure that defines parameters for events that can be used in the HubClient::startVideoEvent function. timestamp unsigned long long Defines the timestamp of the event in milliseconds. 0 gives the current timestamp when the event is sent. reference std::string Gives a specific id to the event to be used to send data to this event and update it. reference_to std::string The data of this event will be incremented to the event that was sent with this value as reference. The duration attribute will be added by the cloud to the event data calculated from the new timestamp. retention int Retention of the event in days. 0 gives the default retention for events. Usage // Create a ZED Object std::shared_ptr p_zed; p_zed.reset(new sl::Camera()); // Init sl_iot STATUS_CODE status_iot = HubClient::connect(app_name); if (status_iot != STATUS_CODE::SUCCESS) { std::cout << "Status: " << status_iot << std::endl; exit(1); } // Open the ZED Camera sl::ERROR_CODE errZed = p_zed->open(); if (errZed != ERROR_CODE::SUCCESS) { HubClient::sendLog("Camera initialization error: " + std::string(toString(errZed)), LOG_LEVEL::ERROR); exit(1); } // Register the ZED Camera status_iot = HubClient::registerCamera(p_zed); if (status_iot != STATUS_CODE::SUCCESS) { std::cout << "Registration: " << status_iot << std::endl; exit(1); } // Enable Object Detection p_zed->enableObjectDetection(); // Main Loop sl::Mat depth_image; sl::Objects objects; bool same_event = false; std::string curr_event = ""; unsigned long long curr_ts = 0; unsigned long long last_ts = 0; while(true) { if (p_zed->grab() == sl::ERROR_CODE::SUCCESS) { // Use zed results curr_ts = getCurrentTimestamp(); p_zed->retrieveObjects(objects); // If object list size is >= 5 send an event if (!same_event && objects.object_list.size() >= 5) { sl_iot::json value; value["nb_persons"] = objects.object_list.size(); EventParameters event_params; // Give a unique id to the event curr_event = random_string(); event_params.reference = curr_event; HubClient::startVideoEvent("crowd", value, event_params); same_event = true; last_ts = getCurrentTimestamp(); } // If object list size is still >= 5 after the event, update the event if (same_event && curr_ts > last_ts + 5000 && objects.object_list.size() >= 5) { sl_iot::json value["nb_persons"] = objects.object_list.size(); // Give the current event id EventParameters event_params; event_params.reference_to = curr_event HubClient::startVideoEvent("crowd", value, event_params); same_event = true; last_ts = getCurrentTimestamp(); } // If object list size is not >= 5 anymore after 5 seconds, finish the event if (same_event && curr_ts > last_ts + 5000 && objects.object_list.size() < 5) { same_event = false; curr_event = ""; } HubClient::update(); // Live/Playback view will be the depth image. } } DataParameters struct WebRTCConfigurationParameters A structure that defines parameters to establish a WebRTC connection, used in the HubClient::setWebRTCConfig function. signaling_host std::string Defines the host name of a signaling server. signaling_port int Defines the port of a signaling server. stun_host std::string Defines the host name of a STUN/TURN server. stun_port int Defines the port of a STUN/TURN server. stun_username std::string Defines a username used to connect to the STUN/TURN server. stun_credential std::string Defines credentials used to connect to the STUN/TURN server. data_provider_id std::string Defines the id of the device for the signaling server. Usage // Create a ZED Object std::shared_ptr p_zed; p_zed.reset(new sl::Camera()); // Init sl_iot STATUS_CODE status_iot = HubClient::connect(app_name); if (status_iot != STATUS_CODE::SUCCESS) { std::cout << "Status: " << status_iot << std::endl; exit(1); } // Set a custom WebRTC Configuration sl_iot::WebRTCConfigurationParameters config_params; config_params.signaling_host = "localhost"; config_params.signaling_port = 8000; config_params.stun_host = "localhost" config_params.stun_port = 9000; config_params.stun_username = "username"; config_params.stun_credential = "pwd"; config_params.data_provider_id = "sender"; status_iot = HubClient::setWebRTCConfig(config_params); if (status_iot != STATUS_CODE::SUCCESS) { std::cout << "Status: " << status_iot << std::endl; exit(1); } Enumerates Enumerates enum LOG_LEVEL Represents the available level of logs. DEBUG log level for debugging INFO log level for an info STATUS log level for a status WARNING log level for a warning ERROR log level for an error SUCCESS log level for a success DISABLED level where no log will be sent Usage HubClient::sendLog("Sample log", LOG_LEVEL::INFO); Enumerates function std::string toString ( LOG_LEVEL log_level ) Converts the given enumerated value into readable text. log_level LOG_LEVEL The log level to convert to string On Success std::string String that reflects the enumerated value. On Error std::string String containing "Unknown" value. Usage std::cout << toString(LOG_LEVEL::INFO) << std::endl; std::cout << LOG_LEVEL::INFO << std::endl; Enumerates enum STATUS_CODE Represent the status code that can be returned by functions. A successful function will return SUCCESS. INVALID_SYSTEM_CLOCK The device has an invalid clock, which can mess with SSL certificates. INVALID_TARGET A publish or a subscribe was called with an invalid \ref TARGET NO_RECORDINGS_FOUND No recordings were found on the device. CANNOT_LOAD_CONFIGURATION Cannot get the local device configuration. CANNOT_CONNECT Cannot connect to ZED Hub. FAILURE A function has failed. INVALID_FUNCTION_CALL A function was called with invalid parameters. INVALID_TOPIC A publish on an invalid topic was requested. REST_REQUESTS_DISABLED A REST Request was called but the feature is disabled. REQUEST_FAILED A REST Request has failed. EMPTY_KEY A device configuration read or write was called with an empty key. EMPTY_JSON A publish on a topic with an empty json is called. NOT_INITIALIZED A function was used before HubClient::connect has been successfully called. UNEXPECTED_INIT_TOKEN HubClient was initialized with a wrong token (application token for applications or device token for Edge Agent) CANNOT_OPEN_FILE Error while opening a file. SUCCESS No Error, Success. Usage STATUS_CODE status = HubClient::isInitialized(); std::cout << status << std::endl; Enumerates function std::string toString ( STATUS_CODE status ) Converts the given enumerated value into readable text. status STATUS_CODE The log level to convert to string On Success std::string String that reflects the enumerated value. On Error std::string String containing "Unknown" value. Usage std::cout << toString(STATUS_CODE::SUCCESS) << std::endl; std::cout << STATUS_CODE::SUCCESS << std::endl; Enumerates enum REST_REQUEST_TYPE Specify the REST request to perform. GET Defines a GET request. POST Defines a POST request. PUT Defines a PUT request. DELETE Defines a DELETE request. Usage // Get the device information through a REST request std::string workspace_url; std::string device_id; getWorkspaceUrl(workspace_url); getDeviceId(device_id); std::string endpoint = workspace_url + "/devices/" + device_id; json result; if (HubClient::performRESTRequest(result, REST_REQUEST_TYPE::GET, endpoint) == STATUS_CODE::SUCCESS) std::cout << "Device Information as REST response: " << result.dump(1) << std::endl; Enumerates function std::string toString ( REST_REQUEST_TYPE type ) Converts the given enumerated value into readable text. type REST_REQUEST_TYPE The rest request type to convert to string. On Success std::string String that reflects the enumerated value. On Error std::string String containing "Unknown" value. Usage std::cout << toString(REST_REQUEST_TYPE::GET) << std::endl; std::cout << REST_REQUEST_TYPE::GET << std::endl; Enumerates enum TARGET Specify the communication target. This is used in the methods publishOnTopic and subscribeToTopic to specify the target recipient of the messages. TARGET::LOCAL_DEVICE refers to localhost, TARGET::WORKSPACE refers to any device on the same local network. LOCAL_DEVICE Target recipients are all applications that run on the current device. WORKSPACE Target recipients are all devices in the current workspace. Usage // Subscribe to the "myLocalData" topic on local device only HubClient::subscribeToTopic("myLocalData", onNewMessage, TARGET::LOCAL_DEVICE); Enumerates enum CALLBACK_TYPE Defines the callback type for CallbackParameters. ON_CONFIGURATION_UPDATE Callback type for a configuration setting update. ON_REMOTE_CALL Callback type for a remote function call. ON_RESTART_CALL Callback type for a restart request. ON_PARAMETER_UPDATE Callback type for a parameter update. Usage // Set a remote callback HubClient::setRemoteCallback("functionCall", CALLBACK_TYPE::ON_REMOTE_CALL); Enumerates enum PARAMETER_TYPE Defines the parameter type for CALLBACK_TYPE::ON_PARAMETER_UPDATE CallbackParameters. DEVICE The parameters is a device parameter (in device twin). ON_REMOTE_CALL The parameter is an application parameter (in application twin). Usage // Set a remote callback for the application parameter "alarm" HubClient::setParameterCallback("alarmUpdate", "alarm", CALLBACK_TYPE::ON_PARAMETER_UPDATE, PARAMETER_TYPE::APPLICATION); Enumerates function std::string toString ( CALLBACK_TYPE type ) Converts the given enumerated value into readable text. type CALLBACK_TYPE The rest request type to convert to string. On Success std::string String that reflects the enumerated value. On Error std::string String containing "Unknown" value. Usage std::cout << toString(CALLBACK_TYPE::ON_REMOTE_CALL) << std::endl; std::cout << CALLBACK_TYPE::ON_REMOTE_CALL << std::endl; FunctionEvent FunctionEvent class FunctionEvent This is used in the callback function as parameter. status int Status of the event. result json Result sent from the cloud. Can be emtpy. Usage // Define a callback with a FunctionEvent as parameter void remoteCallback(FunctionEvent& event) { // Perform action on event ... } FunctionEvent function std::string getFunctionName ( ) Get function name registered. On Success std::string Function name as std::string. Usage // Define a callback with a FunctionEvent as parameter void remoteCallback(FunctionEvent& event) { auto function_name = event.getFunctionName(); } FunctionEvent function json getEventParameters ( ) Get event parameters as json of the function event. On Success json Event parameters as json. Usage // Define a callback with a FunctionEvent as parameter void remoteCallback(FunctionEvent& event) { auto event_params = event.getEventParameters(); } FunctionEvent function int getEventParameterValue ( std::string parameter_key , T& parameter_value ) Parse the event parameters and extract value for parameter_key. parameter_key std::string The name of the target parameter. parameter_value T& A reference to a variable to store the value in. On Success int An int set as 0. On Error int An non-zero value. Usage // Define a callback with a FunctionEvent as parameter void remoteCallback(FunctionEvent& event) { int value; auto status_code = event.getEventParameterValue("key", &value); } FunctionEvent struct FunctionParameterDescription Defines a function parameter as a name and a default value. name std::string Name of the parameter. default_value std::string Default value of the parameter as std::string. Usage FunctionParameterDescription param("unit", "meters"); FunctionEvent static function json generateParametersDescription ( std::vector<FunctionParameterDescription> parameters ) Generate a parameter description parameters std::vector<FunctionParameterDescription> Vector of function parameters On Success json A json description of provided parameters Usage std::vector parameters; parameters.push_back(FunctionParameterDescription("unit", "meters")); json result = generateParametersDescription(parameters); std::cout << result.dump() << std::endl; HubClient HubClient class HubClient Provides the main interface to connect your program to the cloud. This class can be used program-wide with the static functions it provides. An initial configuration is required using the connect function. This initialization is available in two ways: Without a previously defined sl::Camera object: No video-related functions will be available, but Telemetry/Logs/Callbacks will still be available. With a previously defined sl::Camera object: All video-related functions will be available. This class is implemented as a singleton, it means that the constructor isn't available and only the static functions should be used. HubClient static function STATUS_CODE connect ( std::string app_id , bool verbose ) Init function for an application that doesn't use the ZED Camera. This function does not require a sl::Camera object. Some functions (related to video) will not be available if this function is used without registering a camera with registerCamera. app_id std::string An identifier for your application verbose bool optional Set to false by default, whether the HubClient object will print verbose info in the console On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage // Init sl_iot STATUS_CODE status_iot = HubClient::connect(app_name); if (status_iot != STATUS_CODE::SUCCESS) { std::cout << "Status: " << status_iot << std::endl; } HubClient static function STATUS_CODE isInitialized ( ) Returns the status of HubClient's initialization. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage // Init sl_iot STATUS_CODE status_iot = HubClient::connect(app_name); if (HubClient::isInitialized() != STATUS_CODE::SUCCESS) { exit(1); } HubClient static function STATUS_CODE disconnect ( ) Disconnect function that properly closes HubClient threads and connection. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage // Init sl_iot STATUS_CODE status_iot = HubClient::connect(app_name); if (status_iot != STATUS_CODE::SUCCESS) { std::cout << "Status: " << status_iot << std::endl; } status_iot = HubClient::disconnect(); HubClient static function STATUS_CODE registerCamera ( std::shared_ptr<sl::Camera> camera , UpdateParameters parameters ) ZED camera registration function for an application. The ZED camera must be opened before being registered. camera std::shared_ptr<sl::Camera> Shared pointer of an opened ZED camera object. ZED SDK feature. parameters UpdateParameters Defines streaming and recording parameters. See UpdateParameters for more details. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage // Create a ZED Object std::shared_ptr p_zed; p_zed.reset(new sl::Camera()); // Init sl_iot STATUS_CODE status_iot = HubClient::connect(app_name); if (status_iot != STATUS_CODE::SUCCESS) { std::cout << "Status: " << status_iot << std::endl; exit(1); } // Open the ZED Camera sl::ERROR_CODE errZed = p_zed->open(); if (errZed != ERROR_CODE::SUCCESS) { HubClient::sendLog("Camera initialization error: " + std::string(toString(errZed)), LOG_LEVEL::ERROR); exit(1); } // Register the ZED Camera UpdateParameters update_params; status_iot = HubClient::registerCamera(p_zed, update_params); if (status_iot != STATUS_CODE::SUCCESS) { std::cout << "Registration: " << status_iot << std::endl; exit(1); } HubClient static function STATUS_CODE update ( std::shared_ptr<sl::Camera> camera , sl::Mat image ) Function called in the main loop that updates the video features, live stream and recording, of the sl_iot library. Commonly called after each p_zed->grab. This function is mandatory for the video module: if it is not called, the live stream and SVO/MP4 recording won't be available. HubClient::connect must be called before using this function. camera std::shared_ptr<sl::Camera> optional Shared pointer of the ZED camera to update features from. ZED SDK feature. If not filled, the update will loop on all registered ZED camera and use the left RGB image. image sl::Mat optional Image from the SDK to update features. If not filled, the update will use the left RGB image. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage // Create a ZED Object std::shared_ptr p_zed; p_zed.reset(new sl::Camera()); // Init sl_iot STATUS_CODE status_iot = HubClient::connect(app_name); if (status_iot != STATUS_CODE::SUCCESS) { std::cout << "Status: " << status_iot << std::endl; exit(1); } // Open the ZED Camera sl::ERROR_CODE errZed = p_zed->open(); if (errZed != ERROR_CODE::SUCCESS) { HubClient::sendLog("Camera initialization error: " + std::string(toString(errZed)), LOG_LEVEL::ERROR); exit(1); } // Register the ZED Camera status_iot = HubClient::registerCamera(p_zed); if (status_iot != STATUS_CODE::SUCCESS) { std::cout << "Registration: " << status_iot << std::endl; exit(1); } // Main Loop while(true) { if (p_zed->grab() == sl::ERROR_CODE::SUCCESS) { // Use ZED results // An empty update will use the left image of the registered ZED camera // HubClient::update(); // Otherwise, you can retrieve a matrix, play with it, and send it to Hub Client p_zed->retrieveImage(depth, VIEW::DEPTH); HubClient::update(p_zed, depth); } } HubClient static function STATUS_CODE setWebRTCConfig ( WebRTCConfigurationParameters parameters ) Function that sets specific configuration for the WebRTC video streaming and data communication feature of sl_iot. This function can be useful if you want to use a specific signaling or stun server parameters WebRTCConfigurationParameters structure with servers URLs and other informations. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage // Create a ZED Object std::shared_ptr p_zed; p_zed.reset(new sl::Camera()); // Init sl_iot STATUS_CODE status_iot = HubClient::connect(app_name); if (status_iot != STATUS_CODE::SUCCESS) { std::cout << "Status: " << status_iot << std::endl; exit(1); } // Set a custom WebRTC Configuration sl_iot::WebRTCConfigurationParameters config_params; config_params.signaling_host = "localhost"; config_params.signaling_port = 8000; config_params.stun_host = "localhost" config_params.stun_port = 9000; config_params.stun_username = "username"; config_params.stun_credential = "pwd"; config_params.data_provider_id = "sender"; status_iot = HubClient::setWebRTCConfig(config_params); if (status_iot != STATUS_CODE::SUCCESS) { std::cout << "Status: " << status_iot << std::endl; exit(1); } HubClient static function STATUS_CODE setPeerName ( std::string peer_name ) Function that sets the name of the peer client that will use WebRTC video streaming, data communication features of sl_iot. This name will be used by the connectToPeer and sendDataToPeer functions to send data to your application. peer_name std::string string containing the name of your peer client. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage // TODO HubClient static function STATUS_CODE connectToPeer ( std::string peer_name ) Function that connects to another peer to exchange data This name will be used by the connectToPeer and sendDataToPeer functions to send data to your application. peer_name std::string string containing the name of your peer client. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage // TODO HubClient static function STATUS_CODE addPeerDataCallback ( std::string data_label , std::function<void> callback ) Function that adds a callback when receiving a data with a certain label from another peer The callback is an std::function with a int& status argument for the status code number, a std::string& answer argument with the message answer and std::string data argument with the content of the data in itself. data_label std::string string containing the label of the data that triggers the callback. callback std::function<void> with the function that will be called. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage // TODO HubClient static function STATUS_CODE sendDataToPeer ( std::string peer_name , std::string data_label , std::string message ) Function that sends data to a peer client. This function can only be used with peer clients available in the workspace your device was registered on, using names set with the setPeerName function. peer_name std::string string containing the name of the peer client that will receive the data. data_label std::string string containing the label of the data that will be sent. message std::string string with the content of the data sent. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage // TODO HubClient static function STATUS_CODE sendDataToPeers ( std::string data_label , std::string message ) Function that sends data to all peer clients connected to the application's peer client. This function should be used when you want to stream data to many users. data_label std::string string containing the label of the data that will be sent. message std::string string with the content of the data sent. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage // TODO HubClient static function STATUS_CODE getWorkspacePeers ( ) Function that returns an array of all the peer clients available in the workspace. On Success STATUS_CODE an array of peer clients. On Error std::vector[DataProvider] Empty array. Usage // TODO HubClient static function STATUS_CODE sendLog ( std::string or json message , LOG_LEVEL lvl , std::string label , LogParameters log_parameters ) Sends a log message (cloud and terminal, depending on LOG_LEVEL chosen). HubClient::connect must be called before using this function. message std::string or json Message to be sent in a string or json format. lvl LOG_LEVEL LOG_LEVEL of the message. Will be filtered (displayed or not) according to Log level threshold set by setLogLevelThreshold. label std::string optional Label of the message (can be filtered). log_parameters LogParameters optional Defines a log parameter for this message. See LogParameters for more details. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage HubClient::sendLog("An error happened", LOG_LEVEL::ERROR); HubClient static function setLogLevelThreshold ( LOG_LEVEL local_terminal_log_level , LOG_LEVEL cloud_log_level ) Sets the log level limit to be displayed. Every log with LOG_LEVEL below the limit will not be printed. HubClient::connect must be called before using this function. local_terminal_log_level LOG_LEVEL Log limit for terminal display. cloud_log_level LOG_LEVEL Log limit for cloud display. Usage // set threshold to error for terminal and info for cloud HubClient::setLogLevelThreshold(LOG_LEVEL::ERROR, LOG_LEVEL::INFO); // this log will be printed in terminal but not sent to the cloud HubClient::sendLog(log_msg, LOG_LEVEL::ERROR); HubClient static function getLogLevelThreshold ( LOG_LEVEL& local_terminal_log_level , LOG_LEVEL& cloud_log_level ) Gets the current log level limit. HubClient::connect must be called before using this function. local_terminal_log_level LOG_LEVEL& Log limit for terminal display is returned in this variable. cloud_log_level LOG_LEVEL& Log limit for cloud display is returned in this variable. Usage // get threshold LOG_LEVEL terminal_log, cloud_log; HubClient::getLogLevelThreshold(terminal_log, cloud_log); std::cout << "Terminal Log: " << terminal_log << std::endl; std::cout << "Cloud Log: " << cloud_log << std::endl; HubClient static function STATUS_CODE sendTelemetry ( std::string label , json value , TelemetryParameters telemetry_parameters ) Sends a telemetry to the cloud. The telemetry will be stored on the cloud and can then be queried. Telemetry are data produced or calculated that meant to be reported to the cloud for further process. Combination of a label (i.e. a key), a format-free json value and internal metadata. HubClient::connect must be called before using this function. label std::string Label that defines the telemetry. This label can later be queried on the cloud for data filtering for example. value json Format-free json that contains the telemetry metadata values. telemetry_parameters TelemetryParameters optional Parameters for events. See TelemetryParameters for more details. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage // Create a ZED Object std::shared_ptr p_zed; p_zed.reset(new sl::Camera()); // Init sl_iot STATUS_CODE status_iot = HubClient::connect(app_name); if (status_iot != STATUS_CODE::SUCCESS) { std::cout << "Status: " << status_iot << std::endl; exit(1); } // Open the ZED Camera sl::ERROR_CODE errZed = p_zed->open(); if (errZed != ERROR_CODE::SUCCESS) { HubClient::sendLog("Camera initialization error: " + std::string(toString(errZed)), LOG_LEVEL::ERROR); exit(1); } // Register the ZED Camera status_iot = HubClient::registerCamera(p_zed); if (status_iot != STATUS_CODE::SUCCESS) { std::cout << "Registration: " << status_iot << std::endl; exit(1); } std::string label= "environment"; json value; value["temperature"] = 21.0; // °C value["humidity"] = 91; // % HubClient::sendTelemetry(label, value); HubClient static function STATUS_CODE publishOnTopic ( std::string topic , json value , TARGET target ) Publishes a message (json format) on the specified topic. HubClient::connect must be called before using this function. topic std::string Defines the topic name. value json Message to be sent in a json format. target TARGET optional Defines the recipient of the message. If TARGET::LOCAL_DEVICE is used, only the applications on the device that subscribed to this topic will receive the message. If TARGET::WORKSPACE is used, all the applications on the devices of the workspace that are running and that subscribed to this topic will receive the message. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage // Init sl_iot STATUS_CODE status_iot = HubClient::connect(app_name); if (status_iot != STATUS_CODE::SUCCESS) { std::cout << "Status: " << status_iot << std::endl; } // To only my device json val_device; val_device["message"] = "Hello myself"; HubClient::publishOnTopic("myLocalData", val_device, TARGET::LOCAL_DEVICE); // To all devices in the workspace json val_lan; val_lan["message"] = "Hello all"; HubClient::publishOnTopic("myWorkspaceData", val_lan, TARGET::WORKSPACE); HubClient static function STATUS_CODE subscribeToTopic ( std::string topic , std::function<void> callback , TARGET target ) Subscribes to a specified topic with a callback function. HubClient::connect must be called before using this function. topic std::string Defines the topic name. callback std::function<void> Pointer to a function callback that will be called when a message is received on the subscribed topic. The function must have the following signature: void callback(const std::string& topic, const std::string& message, TARGET target) const std::string& topic that defines the topic name. const std::string& message that defines the message (generally json but to be parsed). TARGET target that defines the recipient of the message. target TARGET optional Defines the recipient of the message. If TARGET::LOCAL_DEVICE is used, will receive messages only from applications on the device that send to this topic. If TARGET::WORKSPACE is used, will receive messages only from applications on devices of the workspace that send to this topic. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage void onNewMessage(std::string topic, std::string message, TARGET target, void *args) { std::cout << "Message Received: " << message << std:::endl; }; int main() { // Init sl_iot STATUS_CODE status_iot = HubClient::connect(app_name); if (status_iot != STATUS_CODE::SUCCESS) { std::cout << "Status: " << status_iot << std::endl; } HubClient::subscribeToTopic("myLocalData", onNewMessage, TARGET::LOCAL_DEVICE); } HubClient static function STATUS_CODE unsubscribeToTopic ( std::string topic , TARGET target ) Unsubscribes to a specified topic with a callback function. HubClient::connect must be called before using this function. topic std::string Defines the topic name. target TARGET optional Defines the recipient of the message. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage void onNewMessage(const std::string& topic, const std::string& message, TARGET target) { std::cout << "Message Received: " << message << std:::endl; }; int main() { // Init sl_iot STATUS_CODE status_iot = HubClient::connect(app_name); if (status_iot != STATUS_CODE::SUCCESS) { std::cout << "Status: " << status_iot << std::endl; } HubClient::subscribeToTopic("myLocalData", onNewMessage, TARGET::LOCAL_DEVICE); //Do stuff HubClient::unsubscribeToTopic("myLocalData", TARGET::LOCAL_DEVICE); } HubClient static function STATUS_CODE startVideoEvent ( std::shared_ptr<sl::Camera> target_camera , std::string label , json value , EventParameters event_params ) Starts a video event. The video event data will be stored on the cloud and can then be queried alongside the associated video if it's available on the device. Video events are data produced or calculated, associated with a recorded video on a device, that need to be reported on the cloud for further process. It's a combination of a label (i.e. a key), a format-free json value, a recorded video and internal metadata. HubClient::connect must be called before using this function. target_camera std::shared_ptr<sl::Camera> Shared pointer of the target ZED camera. ZED SDK feature. label std::string Label that defines the event. This label can later be queried on the cloud for data filtering for example. value json Format-free json that contains the event metadata value. event_params EventParameters optional Parameters for events. See EventParameters for more details. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage // Create a ZED Object std::shared_ptr p_zed; p_zed.reset(new sl::Camera()); // Init sl_iot STATUS_CODE status_iot = HubClient::connect(app_name); if (status_iot != STATUS_CODE::SUCCESS) { std::cout << "Status: " << status_iot << std::endl; exit(1); } // Open the ZED Camera sl::ERROR_CODE errZed = p_zed->open(); if (errZed != ERROR_CODE::SUCCESS) { HubClient::sendLog("Camera initialization error: " + std::string(toString(errZed)), LOG_LEVEL::ERROR); exit(1); } // Register the ZED Camera status_iot = HubClient::registerCamera(p_zed); if (status_iot != STATUS_CODE::SUCCESS) { std::cout << "Registration: " << status_iot << std::endl; exit(1); } // Enable Object Detection p_zed->enableObjectDetection(); // Main Loop sl::Mat depth_image; sl::Objects objects; while(true) { if (p_zed->grab() == sl::ERROR_CODE::SUCCESS) { // Use zed results p_zed->retrieveObjects(objects); if (objects.object_list.size() >= 5) { sl_iot::json value; value["nb_persons"] = objects.object_list.size(); HubClient::startVideoEvent(p_zed, "crowd", value); } HubClient::update(); } } HubClient static function STATUS_CODE updateVideoEvent ( std::shared_ptr<sl::Camera> target_camera , std::string label , json value , EventParameters event_params ) Update a video event. HubClient::startVideoEvent must be called before using this function. target_camera std::shared_ptr<sl::Camera> Shared pointer of the target ZED camera. ZED SDK feature. label std::string Label that defines the event. This label can later be queried on the cloud for data filtering for example. value json Format-free json that contains the event metadata value. event_params EventParameters optional Parameters for events. See EventParameters for more details. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage // Create a ZED Object std::shared_ptr p_zed; p_zed.reset(new sl::Camera()); // Init sl_iot STATUS_CODE status_iot = HubClient::connect(app_name); if (status_iot != STATUS_CODE::SUCCESS) { std::cout << "Status: " << status_iot << std::endl; exit(1); } // Open the ZED Camera sl::ERROR_CODE errZed = p_zed->open(); if (errZed != ERROR_CODE::SUCCESS) { HubClient::sendLog("Camera initialization error: " + std::string(toString(errZed)), LOG_LEVEL::ERROR); exit(1); } // Register the ZED Camera status_iot = HubClient::registerCamera(p_zed); if (status_iot != STATUS_CODE::SUCCESS) { std::cout << "Registration: " << status_iot << std::endl; exit(1); } // Enable Object Detection p_zed->enableObjectDetection(); // Main Loop sl::Mat depth_image; sl::Objects objects; bool event_started = false; while(true) { if (p_zed->grab() == sl::ERROR_CODE::SUCCESS) { // Use zed results p_zed->retrieveObjects(objects); if (objects.object_list.size() >= 5) { sl_iot::json value; value["nb_persons"] = objects.object_list.size(); if (event_started) { HubClient::updateVideoEvent(p_zed, "crowd", value); } else { HubClient::startVideoEvent(p_zed, "crowd", value); event_started = true; } } else { event_started = false; } HubClient::update(); } } HubClient static function STATUS_CODE purgeVideoStream ( ) Purge the HLS (streaming protocol) live playlist and remove any remaining segment. This can be used when changing camera settings of ZED camera (brightness, contrast, ...). HubClient::connect must be called before using this function. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage HubClient::purgeVideoStream(); HubClient::update(); HubClient static function STATUS_CODE registerFunction ( std::function<void(FunctionEvent event)> callback , CallbackParameters callback_parameters ) Registers a function callback associated with a function name. HubClient::connect must be called before using this function. callback std::function<void(FunctionEvent event)> Function callback that will be called. The function must have these arguments: FunctionEvent# event: A FunctionEvent containing data to be used in the callback. See FunctionEvent for more infos. callback_parameters CallbackParameters Parameters containing information about the callback function, name, type etc. See CallbackParameters for more infos. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage // Callback function void onInitParamUpdate(FunctionEvent &event) { event.status = 0; HubClient::sendLog("Init Parameters Update. Re-opening the camera.",LOG_LEVEL::INFO); p_zed.close(); sl::InitParameters initParameters; initParameters.camera_resolution = (sl::RESOLUTION) HubClient::getParameter("camera_resolution", (int) RESOLUTION::HD2K); initParameters.camera_image_flip = HubClient::getParameter("camera_image_flip", false); initParameters.camera_fps = HubClient::getParameter("camera_fps", 15); p_zed.open(initParameters); } int main(int argc, char **argv) { // Create camera object std::shared_ptr p_zed; p_zed.reset(new sl::Camera()); // Init sl_iot STATUS_CODE status_iot = HubClient::connect(); if (status_iot != STATUS_CODE::SUCCESS) { std::cout << "HubClient " << status_iot << std::endl; exit(1); } status_iot = HubClient::registerCamera(p_zed); if (status_iot != STATUS_CODE::SUCCESS) { std::cout << "Registration " << status_iot << std::endl; exit(1); } // Setup a callback function in case of an application parameter change CallbackParameters callback_param; // Use "|" if you want your callback to be set on several parameters callback_param.setParameterCallback("onParamChange", "camera_resolution|camera_fps|camera_image_flip", CALLBACK_TYPE::ON_PARAMETER_UPDATE); // Register your function HubClient::registerFunction(onInitParamUpdate, callback_param); } HubClient static function STATUS_CODE unregisterFunction ( std::string function_name ) Unregisters callback associated with the function name. HubClient::connect must be called before using this function. function_name std::string The function name of the function to be unregistered. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage // Setup a callback function in case of an application parameter change CallbackParameters callback_param; // Use "|" if you want your callback to be set on several parameters callback_param.setParameterCallback("onParamChange", "camera_resolution|camera_fps|camera_image_flip", CALLBACK_TYPE::ON_PARAMETER_UPDATE); // Register your function HubClient::registerFunction(onInitParamUpdate, callback_param); // Unregister your function HubClient::unregisterFunction("onParamChange"); HubClient static function STATUS_CODE getDeviceId ( std::string result ) Gets the device unique id that is stored on the cloud. This is the device id parameter that needs to be used in a REST request. See the REST API doc for more details. HubClient::connect must be called before using this function. result std::string Device id stored in a std::string. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage std::string device_id; HubClient::getDeviceId(device_id); std::cout << "Device Id: " << device_id << std::endl; HubClient static function STATUS_CODE getDeviceType ( std::string& result ) Gets the device type from the device twin. HubClient::connect must be called before using this function. result std::string& Device type stored in a std::string. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage std::string device_type; HubClient::getDeviceType(device_type); std::cout << "Device Type: " << device_type << std::endl; HubClient static function STATUS_CODE getDeviceName ( std::string& result ) Gets the device name from the device twin. HubClient::connect must be called before using this function. result std::string& Device name stored in a std::string. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage std::string device_name; HubClient::getDeviceName(device_name); std::cout << "Device Name: " << device_name << std::endl; HubClient static function STATUS_CODE getWorkspaceId ( std::string& result ) Gets the workspace unique id that is stored on the cloud. This is the workspace id parameter that needs to be used in a REST request. See the REST API doc for more details. HubClient::connect must be called before using this function. result std::string& Workspace id stored in a std::string. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage std::string workspace_id; HubClient::getWorkspaceId(workspace_id); std::cout << "Workspace Id: " << workspace_id << std::endl; HubClient static function STATUS_CODE getWorkspaceUrl ( std::string& result ) Gets the workspace URL of the current workspace. This is the region URL parameter that needs to be used in a REST request. See the REST API doc for more details. HubClient::connect must be called before using this function. result std::string& Workspace URL stored in a std::string. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS.0 Usage std::string workspace_url; HubClient::getWorkspaceUrl(workspace_url); std::cout << "Workspace URL: " << workspace_url << std::endl; HubClient static function STATUS_CODE getCloudUrl ( std::string& result ) Gets the cloud URL. This is the workspace URL parameter that needs to be used in a REST request. See the REST API doc for more details. HubClient::connect must be called before using this function. result std::string& Cloud URL stored in a std::string. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage std::string cloud_url; HubClient::getCloudUrl(cloud_url); std::cout << "Cloud URL: " << cloud_url << std::endl; HubClient static function vector<string> getHeaders ( ) Returns base headers for REST Request to the cloud with "Authorization" containing an access token. HubClient::connect must be called before using this function. On Success vector[string] Vector containing the base "Authorization" header containing an access token. On Error vector[string] Empty vector. Usage std::vector headers = HubClient::getHeaders(); HubClient static function STATUS_CODE performRESTRequest ( json& result , REST_REQUEST_TYPE type , std::string url , json payload , std::vector<string> headers ) Generic function to perform a REST request. See the REST API doc for more details. HubClient::connect must be called before using this function. result json& JSON response of the request. type REST_REQUEST_TYPE Defines the request type: GET, PUT, POST or DELETE as an enum for simplicity. url std::string URL that defines the end point of the request. payload json optional JSON payload to add to the request. Not used in GET request. headers std::vector<string> optional Headers to add to the REST Request, default is the result of HubClient::getHeader containing "Authorization" header with access token. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage // Init sl_iot STATUS_CODE status_iot = HubClient::connect(app_name); if (status_iot != STATUS_CODE::SUCCESS) { std::cout << "Status: " << status_iot << std::endl; } // Get the device information through a REST request std::string workspace_url; std::string device_id; getWorkspaceUrl(workspace_url); getDeviceId(device_id); std::string endpoint = workspace_url + "/devices/" + device_id; json result; if (HubClient::performRESTRequest(result,REST_REQUEST_TYPE::GET,endpoint) == STATUS_CODE::SUCCESS) std::cout << "Device Information as REST response: " << result.dump(1) << std::endl; HubClient static function STATUS_CODE getConfiguration ( std::string key , json& result ) Gets the content of a section of the device twin. HubClient::connect must be called before using this function. key std::string The name of the section of the device twin, subsections are separated by dots. result json& The content of the device twin section stored in a json. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage sl_iot::json content; // Get host software description from the device twin. HubClient::getConfiguration("host.software", content); std::cout << content.dump(2) << std::endl; HubClient static function STATUS_CODE updateConfiguration ( std::string key , json& new_conf ) Updates the content of a section of the device twin. HubClient::connect must be called before using this function. key std::string The key of the section of the device twin, subsection are separated by dots. new_conf json& The new value of the device twin section to update. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage sl_iot::json content; // Get user_data from the device twin. HubClient::getConfiguration("user_data", content); std::cout << "Before: " << content.dump(2) << std::endl; content["data"] = 3 // Update user_data HubClient::updateConfiguration("user_data", content); HubClient::getConfiguration("user_data", content); std::cout << "After: " << content.dump(2) << std::endl; HubClient static function T& getParameter ( std::string parameter_name , PARAMETER_TYPE parameter_type , T default_value ) Gets the requested device/application parameter defined by its name (parameters.requested in device/application twin). HubClient::connect must be called before using this function. parameter_name std::string Defines the parameter name that is stored on the cloud. parameter_type PARAMETER_TYPE The type of the parameter PARAMETER_TYPE::DEVICE for device parameters PARAMETER_TYPE::APPLICATION for application parameters. default_value T The default value to return if no parameter is found. On Success T# The value of the parameter. Usage std::string param_str = HubClient::getParameter("first_param", PARAMETER_TYPE::APPLICATION, "default_value"); HubClient static function STATUS_CODE setParameter ( std::string parameter_name , PARAMETER_TYPE parameter_type , T& value ) Sets the requested device/application parameter defined by its name (parameters.requested in device/application twin). HubClient::connect must be called before using this function. parameter_name std::string Defines the parameter name that is stored on the cloud. parameter_type PARAMETER_TYPE The type of the parameter PARAMETER_TYPE::DEVICE for device parameters PARAMETER_TYPE::APPLICATION for application parameters. value T& The value to to set. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage HubClient::setParameter("first_param", PARAMETER_TYPE::APPLICATION, "value"); HubClient static function STATUS_CODE reportParameter ( std::string parameter_name , PARAMETER_TYPE parameter_type , T value ) Reports the device/application parameter defined by its name (parameters.reported in device/application twin). HubClient::connect must be called before using this function. parameter_name std::string Defines the parameter name that is stored on the cloud.` parameter_type PARAMETER_TYPE The type of the parameter PARAMETER_TYPE::DEVICE for device parameters PARAMETER_TYPE::APPLICATION for application parameters. value T The value to to set. On Success STATUS_CODE The SUCCESS status code. On Error STATUS_CODE Any other status code != SUCCESS. Usage HubClient::reportParameter("first_param", PARAMETER_TYPE::APPLICATION, "value");