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 is always set by Remote Manager when the value is received.

  • Remote Manager is not 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 any of the following functions to send it to Remote Manager:

cccs_comm_error_t cccs_send_binary_dp(char const * const stream_id,
                                      void const * const data,
                                      size_t const bytes,
                                      cccs_resp_t *resp);
cccs_comm_error_t cccs_send_binary_dp_tout(char const * const stream_id,
                                           void const * const data,
                                           size_t const bytes,
                                           unsigned long const timeout,
                                           cccs_resp_t *resp);
Parameter Description

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).

timeout[1]

Number of seconds to wait for response from the daemon.

resp

Received response from CCCS daemon.

1. only for cccs_send_binary_dp_tout() function.

This functions return a cccs_comm_error_t error code indicating whether any failure occurs during the process, CCCS_SEND_ERROR_NONE if success. See Description of errors for more information.

Send binary data
cccs_comm_error_t ret;
cccs_resp_t resp;
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 }

/* [...] */

ret = cccs_send_binary_dp(stream_id, buffer, sizeof(buffer), &resp);
if (ret != CCCS_SEND_ERROR_NONE) {
	log_error("%s: error sending binary data point: CCCSD error %d", __func__, ret);
}

If data cannot be uploaded and data backlog service is enabled, data is stored locally in the configured data_backlog_path directory.

This service is enabled and configured in the ConnectCore Cloud Services (CCCS) configuration file, /etc/cccs.conf. For more information about the configuration file, see Configure ConnectCore Cloud Services and Include ConnectCore Cloud Services applications in Digi Embedded Yocto.

Send file contents as a binary data point

CCCS also provides a function to upload a file content as a binary data point, cccs_send_dp_binary_file(). It works like cccs_send_binary_dp_tout().

cccs_comm_error_t cccs_send_dp_binary_file(char const * const path,
                                           char const * const stream_id,
                                           unsigned long const timeout,
                                           cccs_resp_t *resp);
Parameter Description

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.

timeout

Number of seconds to wait for response from the daemon.

resp

Received response from CCCS daemon.

Function cccs_send_dp_binary_file() returns a cccs_comm_error_t error code indicating whether any failure occurs during the process, CCCS_SEND_ERROR_NONE if success. See Description of errors for more information.

Send file content as binary data
int send_image(const char *path)
{
	cccs_comm_error_t ret;
	cccs_resp_t resp;

	log_info("Sending image '%s'!", path);

	ret = cccs_send_dp_binary_file(path, "photo_stream", 5, &resp);
	if (ret != CCCS_SEND_ERROR_NONE) {
		log_error(
			"%s: error sending file '%s' as binary data point: CCCSD error %d",
			__func__, path, ret);
	} else if (resp.code != 0) {
		if (resp.hint)
			log_error(
				"%s: error sending file '%s' as binary data point: CCCSD error %s (%d)",
				__func__, path, resp.hint, resp.code);
		else
			log_error(
				"%s: error sending file '%s' as binary data point: CCCSD error %d",
				__func__, path, resp.code);
	}

	free(resp.hint);

	return ret;
}

If data cannot be uploaded and data backlog service is enabled, data is stored locally in the configured data_backlog_path directory.

This service is enabled and configured in the ConnectCore Cloud Services (CCCS) configuration file, /etc/cccs.conf. For more information about the configuration file, see Configure ConnectCore Cloud Services and Include ConnectCore Cloud Services applications in Digi Embedded Yocto.

View data stream series in Remote Manager

You can view the data points stored in the cloud (in charts and in text format) from the Remote Manager platform. To do so follow these steps:

  1. Go to the Insights > Data Streams tab.

  2. Click on the Stream ID item of the stream in the table you want to analyze.

    It is similar to 00000000-00000000-00XXXXXX-XXXXXXXX/photo_stream, where 00000000-00000000-00XXXXXX-XXXXXXXX is the device ID.

    If you have several streams on the list, you can filter using the stream identifier:

    1. Click on the filter text box and select Stream ID.

    2. Type the stream identifier, for example photo_stream, and press Enter.

  3. On the right, select the format to represent the values (Tabular, Line Chart, Area Chart, etc.), for example, Tabular. A table with the values in the selected stream is displayed.

See Monitor device data for more information on how to retrieve stored data in Remote Manager or listen to new data events using Remote Manager web service APIs.

Description of errors

cccs_comm_error_t error Description

CCCS_SEND_ERROR_NONE

Operation completed successfully. No error found.

CCCS_SEND_ERROR_INVALID_ARGUMENT

In most cases this refers to empty strings or NULL pointers in structures.

CCCS_SEND_ERROR_OUT_OF_MEMORY

CCCS encountered problems allocating memory to perform receive operations.

Your system may have run out of resources.

CCCS_SEND_ERROR_LOCK

CCCS encountered problems using synchronization mechanisms.

Your system may have run out of resources.

CCCS_SEND_UNABLE_TO_CONNECT_TO_DAEMON

Unable to connect to CCCS daemon.

It is probably not running.

CCCS_SEND_ERROR_BAD_RESPONSE

Received bad response from CCCS daemon.

CCCS_SEND_ERROR_FROM_CLOUD

Error received from Digi Remote Manager.

Upload binary file example

The Upload binary 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.