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 |
---|---|
|
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 |
|
Pointer to the data buffer. |
|
Length of the data buffer (in bytes). |
|
Number of seconds to wait for response from the daemon. |
|
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.
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 |
---|---|
|
Absolute path of the file to be uploaded. |
|
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. |
|
Number of seconds to wait for response from the daemon. |
|
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.
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:
-
Go to the Insights > Data Streams tab.
-
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
, where00000000-00000000-00XXXXXX-XXXXXXXX
is the device ID.If you have several streams on the list, you can filter using the stream identifier:
-
Click on the filter text box and select Stream ID.
-
Type the stream identifier, for example
photo_stream
, and press Enter.
-
-
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 |
---|---|
|
Operation completed successfully. No error found. |
|
In most cases this refers to empty strings or NULL pointers in structures. |
|
CCCS encountered problems allocating memory to perform receive operations. Your system may have run out of resources. |
|
CCCS encountered problems using synchronization mechanisms. Your system may have run out of resources. |
|
Unable to connect to CCCS daemon. It is probably not running. |
|
Received bad response from CCCS daemon. |
|
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.