All Products
Search
Document Center

IoT Platform:Device Modelling Programming

Last Updated:Sep 01, 2023

The SDK provides the option to receive a reply from the cloud when a device reports properties or events. We can use IOT_Ioctl to set the IOTX_IOCTL_RECV_EVENT_REPLY option.

Device Modelling means to define a product by properties, services and events, a device that supports device modelling is also referred to as the “Pro Edition.”
  • Property report description

The following example code describes property reports. /examples/linkkit/linkkit_example_solo.c

You can call the IOT_Linkkit_Report() function to report the properties. When you report the properties, use the JSON encoding according to the property format defined by the cloud. In the example, the user_post_property function shows how to use IOT_Linkkit_Report for property reporting (for reporting exceptions, see the example):

void user_post_property(void)
{
static int example_index = 0;
int res = 0;
user_example_ctx_t *user_example_ctx = user_example_get_ctx();
char *property_payload = "NULL";

...
... 
/* Normal Example */
property_payload = "{\"LightSwitch\":1}";
example_index++;
...
...

res = IOT_Linkkit_Report(user_example_ctx->master_devid, ITM_MSG_POST_PROPERTY,
(unsigned char *)property_payload, strlen(property_payload));

EXAMPLE_TRACE("Post Property Message ID: %d", res);
}
Note: property_payload = “{\”LightSwitch\”:1}” encodes the property as a JSON object.
  • Property setting description

In the example, the device obtains the property value set in the cloud using the callback function user_property_set_event_handler, and reports the data to the cloud as it is. This updates the device property value saved in the device shadow on the cloud, and allows you to process the property value that is received.

Note: This callback function corresponds to the ITE_SERVICE_REQUEST event registered using IOT_RegisterCallback when the example is initialized:

static int user_property_set_event_handler(const int devid, const char *request, const int request_len)
{
int res = 0;
user_example_ctx_t *user_example_ctx = user_example_get_ctx();
EXAMPLE_TRACE("Property Set Received, Devid: %d, Request: %s", devid, request);

res = IOT_Linkkit_Report(user_example_ctx->master_devid, ITM_MSG_POST_PROPERTY,
(unsigned char *)request, request_len);
EXAMPLE_TRACE("Post Property Message ID: %d", res);

return 0;
}

Device services

In the device-side example program, when a service call request is received, the following callback function will be invoked:

static int user_service_request_event_handler(const int devid, const char *serviceid, const int serviceid_len,
const char *request, const int request_len,
char **response, int *response_len)
{
int contrastratio = 0, to_cloud = 0;
cJSON *root = NULL, *item_transparency = NULL, *item_from_cloud = NULL;
EXAMPLE_TRACE("Service Request Received, Devid: %d, Service ID: %.*s, Payload: %s", devid, serviceid_len,
serviceid,
request);

/* Parse Root */
root = cJSON_Parse(request);
if (root == NULL || ! cJSON_IsObject(root)) {
EXAMPLE_TRACE("JSON Parse Error");
return -1;
}

Process the received service with the Custom Service ID, assign the value of the service input parameter +1 to the output parameter, and return it to the cloud:

if (strlen("Custom") == serviceid_len && memcmp("Custom", serviceid, serviceid_len) == 0) {
/* Parse Item */
const char *response_fmt = "{\"Contrastratio\":%d}";
item_transparency = cJSON_GetObjectItem(root, "transparency");
if (item_transparency == NULL || ! cJSON_IsNumber(item_transparency)) {
cJSON_Delete(root);
return -1;
}
EXAMPLE_TRACE("transparency: %d", item_transparency->valueint);
contrastratio = item_transparency->valueint + 1;

/* Send Service Response To Cloud */
*response_len = strlen(response_fmt) + 10 + 1;
*response = HAL_Malloc(*response_len);
if (*response == NULL) {
EXAMPLE_TRACE("Memory Not Enough");
return -1;
}
memset(*response, 0, *response_len);
HAL_Snprintf(*response, *response_len, response_fmt, contrastratio);
*response_len = strlen(*response);
} else if (strlen("SyncService") == serviceid_len && memcmp("SyncService", serviceid, serviceid_len) == 0) {
...
...
}
cJSON_Delete(root);

return 0;
}

Device events

The example uses IOT_Linkkit_TriggerEvent to report events. It demonstrates how to use IOT_Linkkit_Report to report events (for reporting exceptions, see the example).

void user_post_event(void)
{
static int example_index = 0;
int res = 0;
user_example_ctx_t *user_example_ctx = user_example_get_ctx();
char *event_id = "Error";
char *event_payload = "NULL";

...
... 
/* Normal Example */
event_payload = "{\"ErrorCode\":0}";
example_index++;
...
...

res = IOT_Linkkit_TriggerEvent(user_example_ctx->master_devid, event_id, strlen(event_id),
event_payload, strlen(event_payload));
EXAMPLE_TRACE("Post Event Message ID: %d", res);
}

Format descriptions and examples of the report message

When reporting the properties, the property ID and value are placed in the IOT_Linkkit_Report()payload in JSON format. Format examples for different data types and properties are as follows:

/* Integer data */
char *payload = "{\"Brightness\":50}";

/* Floating-point data reporting */
char *payload = "{\"Temperature\":11.11}";

/* Enumeration data reporting */
char *payload = "{\"WorkMode\":2}";

/* Boolean data reporting. In the TSL definition, the Boolean type is an integer and the value is 0 or 1, which is different from the JSON format integer */
char *payload = "{\"LightSwitch\":1}";

/* String data reporting */
char *payload = "{\"Description\":\"Amazing Example\"}";

/* Time-type data reporting. In the TSL definition, the time type is a string */
char *payload = "{\"Timestamp\":\"1252512000\"}";

/* Composite property reporting. In the TSL definition, the composite property is a JSON object */
char *payload = "{\"RGBColor:{\"Red\":11,\"Green\":22,\"Blue\":33}\"}";

/* Multi-property reporting. If you need to report all the properties and data types mentioned above, simply put them in one JSON object */
char *payload = "{\"Brightness\":50,\"Temperature\":11.11,\"WorkMode\":2,\"LightSwitch\":1,\"Description\":\"Amazing Example\",\"Timestamp\":\"1252512000\",\"RGBColor:{\"Red\":11,\"Green\":22,\"Blue\":33}\"}";

/* After the property payload is ready, use the following API to report it */
IOT_Linkkit_Report(devid, ITM_MSG_POST_PROPERTY, payload, strlen(payload));

The difference between reporting events and properties is that the event ID needs to be extracted and placed in the eventid of IOT_Linkkit_TriggerEvent(). The event report content, namely the output parameters of the event according to the TSL definition, is reported in the same format required for property reporting. The example is as follows:

/* If the Event ID is Error, its output parameter ID is ErrorCode and the data type is enumeration */
char *eventid = "Error";
char *payload = "{\"ErrorCode\":0}";

/* If the Event ID is HeartbeatNotification, it has two output parameters. The first is the Boolean parameter ParkingState, and the second is the floating-point parameter VoltageValue */
char *eventid = "HeartbeatNotification";
char *payload = "{\"ParkingState\":1,\"VoltageValue\":3.0}";

/* After the event payload is ready, use the following API to report it */
IOT_Linkkit_TriggerEvent(devid, event_id, strlen(event_id), payload, strlen(payload));

/* As seen in the above example, when an event has multiple output parameters, the payload format is the same as that of a multi-property report */