You can use Cloud Connector to receive data from Remote Manager, also known as receiving Device Requests. Transfers are initiated from a Web Services client connected to Remote Manager, which hosts the device. This transfer is used to send data to the device or trigger actions in the device. The device may also return a response.
Device Requests are composed of:
-
Target: A unique name which specifies which part of the application is in charge of attending this request.
-
Data: Arbitrary data sent to the device.
On the device, when Cloud Connector receives the request, it looks into the user-registered targets. If a match is found, then it is automatically accepted and the appropriate handlers called. If no match is found, Cloud Connector returns a standard error response to Remote Manager.
Digi Embedded Yocto includes a Device Request example demonstrating how to receive device requests from Remote Manager.
For a list of possible errors receiving device request from Remote Manager, see Description of errors. |
1. Register a target
In order to make your application aware of Device Requests sent to the device, you must register a handler for each new target.
The ccapi_receive_add_target()
function allows you to register specific targets.
ccapi_receive_error_t ccapi_receive_add_target(char const * const target, ccapi_receive_data_cb_t const data_cb,
ccapi_receive_status_cb_t const status_cb, size_t const max_request_size)
Parameter | Description |
---|---|
|
Name of the target to register. It must be unique. |
|
Callback called when new data for target is received. This function performs the request and optionally returns a response to Remote Manager. |
|
Callback called when the receive process has completed. This function checks status and free resources. This may be |
|
Maximum length of the data to be received in a request from Remote Manager for this target. If the data received exceeds this value, |
The following subset of ccapi_receive_error_t
errors can be returned by ccapi_receive_add_target()
:
-
CCAPI_RECEIVE_ERROR_NONE
-
CCAPI_RECEIVE_ERROR_CCAPI_NOT_RUNNING
-
CCAPI_RECEIVE_ERROR_NO_RECEIVE_SUPPORT
-
CCAPI_RECEIVE_ERROR_INSUFFICIENT_MEMORY
-
CCAPI_RECEIVE_ERROR_INVALID_TARGET
-
CCAPI_RECEIVE_ERROR_TARGET_ALREADY_ADDED
-
CCAPI_RECEIVE_ERROR_INVALID_DATA_CB
-
CCAPI_RECEIVE_ERROR_LOCK_FAILED
See Description of errors for more information.
If you want to stop listening for any specific Device Request, you can remove the target with ccapi_receive_remove_target()
function.
ccapi_receive_error_t ccapi_receive_remove_target(char const * const target);
Parameter | Description |
---|---|
|
Name of the target to remove. It must be unique. |
int main (void)
{
[...]
init_error = init_cloud_connection(NULL);
[...]
receive_error = ccapi_receive_add_target("increment_counter", increment_counter_cb,
increment_counter_status_cb, DESIRED_MAX_REQUEST_SIZE);
if (receive_error != CCAPI_RECEIVE_ERROR_NONE) {
log_error("Cannot register target 'increment_counter', error %d", receive_error);
}
[...]
start_error = start_cloud_connection();
[...]
}
The following subset of ccapi_receive_error_t
errors can be returned by ccapi_receive_remove_target()
:
-
CCAPI_RECEIVE_ERROR_NONE
-
CCAPI_RECEIVE_ERROR_CCAPI_NOT_RUNNING
-
CCAPI_RECEIVE_ERROR_NO_RECEIVE_SUPPORT
-
CCAPI_RECEIVE_ERROR_INSUFFICIENT_MEMORY
-
CCAPI_RECEIVE_ERROR_INVALID_TARGET
-
CCAPI_RECEIVE_ERROR_TARGET_NOT_ADDED
-
CCAPI_RECEIVE_ERROR_LOCK_FAILED
See Description of errors for more information.
2. Define receive callbacks
Custom receive callbacks are required when registering a new target with ccapi_receive_add_target()
: a data callback to perform the requested operation, and an optional status callback to check the status of the process.
In the example above, increment_counter_cb and increment_counter_status_cb callbacks are those custom callbacks:
Data callback
Input and output callback where the application performs the necessary operations to attend the request and optionally creates and returns a response to Remote Manager.
The callback typically follows this scheme:
-
Analyze the input data from the request.
-
Perform any necessary operations on the device.
-
Provide a response to Remote Manager. The callback cannot return a response if Remote Manager made the request without requesting a response.
typedef ccapi_receive_error_t (*ccapi_receive_data_cb_t)(char const * const target,
ccapi_transport_t const transport,
ccapi_buffer_info_t const * const request_buffer_info,
ccapi_buffer_info_t * const response_buffer_info)
Parameter | Description |
---|---|
|
Name of the received target. |
transport |
The transport used to received the request. Always |
|
Data sent from Remote Manager to the device. It may be empty if no data is required to process the target. |
|
Device response to Remote Manager after processing the request. |
Status callback
Cloud Connector calls status user callback (if provided) when the receive process is complete.
This callback provides overall error status. Users should check status and free all possible resources allocated during the receive process, including the memory allocated to provide a response within the data callback.
typedef void (*ccapi_receive_status_cb_t)(char const * const target, ccapi_transport_t const transport,
ccapi_buffer_info_t * const response_buffer_info, ccapi_receive_error_t receive_error)
Parameter | Description |
---|---|
|
Name of the received target. |
|
The transport used to received the request. Always |
|
Device response to Remote Manager after processing the request. |
|
Error code after completing the response process to Remote Manager. |
This callback has a receive_error argument indicating the final error status. Following subset of ccapi_receive_error_t errors can arrive to this callback:
-
CCAPI_RECEIVE_ERROR_NONE
-
CCAPI_RECEIVE_ERROR_INSUFFICIENT_MEMORY>
-
CCAPI_RECEIVE_ERROR_INVALID_DATA_CB
-
CCAPI_RECEIVE_ERROR_USER_REFUSED_TARGET
-
CCAPI_RECEIVE_ERROR_REQUEST_TOO_BIG
-
CCAPI_RECEIVE_ERROR_STATUS_CANCEL
-
CCAPI_RECEIVE_ERROR_STATUS_TIMEOUT
-
CCAPI_RECEIVE_ERROR_STATUS_SESSION_ERROR
See Description of errors for more information.
int counter = 0;
void increment_counter_cb(char const *const target, ccapi_transport_t const transport,
ccapi_buffer_info_t const *const request_buffer_info, ccapi_buffer_info_t *const response_buffer_info)
{
char *request = NULL;
int increment = 0;
log_info("Increment counter request!");
/*
* Request info is available at request_buffer_info->buffer
* and is request_buffer_info->length bytes long.
*
* Handle the request here. Write response to response_buffer_info
*/
request = calloc(1, sizeof (char) * (request_buffer_info->length + 1));
strncpy(request, request_buffer_info->buffer, request_buffer_info->length + 1);
increment = atoi(request);
counter = counter + increment;
response_buffer_info->buffer = calloc(1, sizeof (char) * DESIRED_MAX_RESPONSE_SIZE);
response_buffer_info->length = sprintf(response_buffer_info->buffer, "Current value: %d", counter);
}
void increment_counter_status_cb(char const *const target, ccapi_transport_t const transport,
ccapi_buffer_info_t *const response_buffer_info, ccapi_receive_error_t receive_error)
{
log_info("increment_counter_status_cb(): error code='%d'", receive_error);
/* Free the response buffer */
free(response_buffer_info->buffer);
}
You can register different targets using the same callback. Use the target parameter in the callback function to distinguish between them. |
3. Use the API Explorer to send device requests
A Device Request can be sent via Web Services within the Remote Manager platform. If you have implemented a Device Request listener and you want to test it, follow these steps:
-
Go to Documentation > API Explorer.
-
Select Examples > SCI > Data Service > Send Request. Remote Manager automatically creates the necessary code.
-
Replace the "device id" value with the ID of your device.
-
Enter your target name and data for the device request.
Remote Manager - API Explorer<sci_request version="1.0"> <data_service> <targets> <device id="XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX"/> </targets> <requests> <device_request target_name="increment_counter">5</device_request> </requests> </data_service> </sci_request>
-
Click Send.
Description of errors
Error | Description |
---|---|
|
Operation completed successfully. No error found. |
|
You missed calling
|
|
Receive service is not available. It probably has not been started. |
|
Cloud Connector encountered problems allocating memory to perform receive operations. Your system may have run out of resources. |
|
The target argument in
|
|
The |
|
The |
|
The |
|
Cloud Connector encountered problems using synchronization mechanisms. Your system may have run out of resources. |
|
Received request is bigger that
the limit established by the user through the |
|
Session timed out. |
|
Error from lower communication layer. You can check the specific error on the logging output. |
Device Request example
The Device Request listener example demonstrates the usage of the Cloud Connector receive data API. In this example, a target to retrieve the system time is registered.
This example is included in Digi Embedded Yocto. Go to GitHub to look at the application source code.