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.

Send binary data
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.

Send binary data
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.