For some use cases, regular data points are not the best format for holding data. If you need to minimize the data traffic or if you are using an internal structure, a binary array, a stream, a photo, or any other binary blob of data, use the binary concise alternative format to send data points to Remote Manager.
Binary data points allow you to keep arbitrary time-series data in Remote Manager. Data can be anything from 1 byte status indicators to 10 kilobytes images.
They also have some limitations:
-
Only single values can be uploaded per data service message.
-
Data must be smaller than 64 kilobytes.
-
Binary data do not have other attributes such as quality or location.
-
The timestamp will be always set by Remote Manager when the value is received.
-
Remote Manager will not be able to provide roll-ups on items that do not use the specified formats.
The following section includes a description of different methods of sending binary data points, information about possible errors, and an example.
Send binary data points from a buffer
If the data is directly available in a buffer, you can use function ccapi_dp_binary_send_data() to send it to Remote Manager.
ccapi_dp_b_error_t ccapi_dp_binary_send_data(ccapi_transport_t const transport, char const * const stream_id, void const * const data, size_t const bytes);
Parameter | Description |
---|---|
transport |
Must always be CCAPI_TRANSPORT_TCP. |
stream_id |
Name of the data stream destination in Remote Manager. It must be unique. For example, name "temperature" creates a stream in Remote Manager with the path <DeviceID>/temperature, where <DeviceID> is the ID of your device. |
data |
Pointer to the data buffer. |
bytes |
Length of the data buffer (in bytes). |
Function ccapi_dp_binary_send_data() returns a ccapi_dp_b_error_t error code indicating whether any failure occurs during the process. See Description of errors for more information.
ccapi_dp_b_error_t error; char const stream_id[] = "buffer_stream"; char const buffer[] = { 0x00, 0x01, 0x02, 0x03, \ 0x04, 0x05, 0x06, 0x07, \ 0x08, 0x09, 0x0a, 0x0b, \ 0x0c, 0x0d, 0x0e, 0x0f, \ 0x10, 0x11, 0x12, 0x13, \ 0x14, 0x15, 0x16, 0x17, \ 0x18, 0x19, 0x1a, 0x1b, \ 0x1c, 0x1d, 0x1e, 0x1f } [...] error = ccapi_dp_binary_send_data(CCAPI_TRANSPORT_TCP, stream_id, buffer, sizeof buffer); if (error != CCAPI_DP_B_ERROR_NONE) { log_error("Cannot send binary data points, error %d", error); } [...]
Send binary data points from a file
Cloud Connector also provides a function to easily send binary data from a file, ccapi_dp_binary_send_file(). It works like ccapi_dp_binary_send_data().
ccapi_dp_b_error_t ccapi_dp_binary_send_file(ccapi_transport_t const transport, char const * const local_path, char const * const stream_id)
Parameter | Description |
---|---|
transport |
Must always be CCAPI_TRANSPORT_TCP. |
local_path |
Absolute path of the file to be uploaded. |
stream_id |
Name of the data stream destination in Remote Manager. It must be unique. For example, name "temperature" creates a stream in Remote Manager with the path <DeviceID>/temperature, where <DeviceID> is the ID of your device. |
Function ccapi_dp_binary_send_file() returns a ccapi_dp_b_error_t error code indicating whether any failure occurs during the process. See Description of errors for more information.
ccapi_dp_b_error_t error;
char const local_path[] = "/home/root/photo.jpg";
char const stream_id[] = "photo_stream";
[...]
error = ccapi_dp_binary_send_file(CCAPI_TRANSPORT_TCP, local_path, stream_id);
if (error != CCAPI_DP_B_ERROR_NONE) {
log_error("Cannot send binary data points, error %d", error);
}
[...]
Description of errors
Error | Description |
---|---|
CCAPI_DP_ERROR_NONE |
Operation finished successfully. |
CCAPI_DP_B_ERROR_CCAPI_NOT_RUNNING |
Cloud Connector is not running. You missed calling start_cloud_connector() function or it failed. |
CCAPI_DP_B_ERROR_TRANSPORT_NOT_STARTED |
The requested transport is not available. Either it is not generally available for your operating system/hardware or it has not been started. |
CCAPI_DP_B_ERROR_FILESYSTEM_NOT_SUPPORTED |
File system service is not available for your operating system/hardware. Only applies to function variants that use a file in the local filesystem as source. |
CCAPI_DP_B_ERROR_INVALID_STREAM_ID |
stream_id argument is NULL or empty. |
CCAPI_DP_B_ERROR_INVALID_DATA |
data argument is NULL or bytes argument is 0. Only applies to function variants that use a buffer as source. |
CCAPI_DP_B_ERROR_INVALID_LOCAL_PATH |
local_path argument is NULL or empty. Only applies to function variants that use a file in the local file system as source. |
CCAPI_DP_B_ERROR_NOT_A_FILE |
The local_path is not available in your file system or it’s not a file. Only applies to function variants that use a file in the local file system as source. |
CCAPI_DP_B_ERROR_ACCESSING_FILE |
Error while opening or reading from the file specified in the local_path argument. Can indicate missing permissions for opening/reading the file. Only applies to function variants that use a file in the local file system as source. |
CCAPI_DP_B_ERROR_INSUFFICIENT_MEMORY |
Cloud Connector encountered problems allocating memory to perform send operations. Your system may have run out of resources. |
CCAPI_DP_B_ERROR_LOCK_FAILED |
Cloud Connector encountered problems using synchronization mechanisms. Your system may have run out of resources. |
CCAPI_DP_B_ERROR_INITIATE_ACTION_FAILED |
An unexpected failure on lower communication layers occurred. You can check the specific error on the logging output. |
CCAPI_DP_B_ERROR_STATUS_CANCEL |
Session was canceled by the user. Only applies to SM transports |
CCAPI_DP_B_ERROR_STATUS_SESSION_ERROR |
Error from lower communication layer. You can check the specific error on the logging output. |
CCAPI_DP_B_ERROR_RESPONSE_BAD_REQUEST |
At least some portion of the request is not valid. |
CCAPI_DP_B_ERROR_RESPONSE_UNAVAILABLE |
Service not available, may retry later. |
CCAPI_DP_B_ERROR_RESPONSE_CLOUD_ERROR |
Remote Manager encountered an error while handling the request. |
Upload file example
The Upload file example demonstrates how to send a file as a binary data point to Remote Manager.
This example is included in Digi Embedded Yocto. Go to GitHub to look at the application source code.