Updated on 2024-11-06 GMT+08:00

Device Reporting a Message

Function

If a device cannot report data in the format defined in the product model, the device can use this API to report data in a custom format to the platform. The platform does not parse the message but forwards it to an application or other Huawei Cloud services for storage and processing.

For differences between message reporting and property reporting, see Message Communications Overview.

It is not suitable to report data in JSON format for devices with low configuration and limited resources or with limits on bandwidth usage. In this case, devices can transparently transmit the original binary data to the platform, but a codec is required to convert binary data to JSON format. For details about how to develop codecs, see Developing a Codec.

Topic

Upstream: $oc/devices/{device_id}/sys/messages/up

  • In addition to the preset system topics, the device can also use a custom topic that is not declared by the platform, for example, $oc/devices/{device_id}/user/{customized}.
  • You can add ?request_id to the end of the topic to specify the request ID for the data reporting. Message reporting example: $oc/devices/{device_id}/sys/messages/up?request_id={request_id}. If this parameter is not specified, the platform automatically generates a request ID to identify the request.

Parameters

Message reporting has no fixed requirements on the data content. The following table lists the parameters involved when the system format is used for delivery.

Parameter

Mandatory or Optional

Type

Description

object_device_id

Optional

String

Explanation:

  • Mandatory when the child device reports data during the gateway device data reporting. Specify object_device_id as the child device ID of the device in the topic. Otherwise, the request fails.
  • When a directly connected device reports data, the value of object_device_id must be the same as that of device_id in the topic.
  • If this parameter is left blank, the value of this parameter is the same as that of device_id in the topic by default.

name

Optional

String

Explanation:

Message name, which is optional and is used for description.

id

Optional

String

Explanation:

Unique ID of a message, which is used to distinguish and search for messages. If you do not enter a value, the system automatically generates a message ID. The message ID must be unique.

content

Mandatory

Object, String

Explanation:

Message content, which can be encoded in Base64 format.

IoTDA does not verify the format of the message reported by a device. The parameter description and example are for reference only. Devices can customize the data format as required.

Example

Assume that the data reported by the device is "hello!". The request examples are as follows:

  • Sending only the message content:
    Topic: $oc/devices/{device_id}/sys/messages/up  
    Data format:
        hello!
  • Reporting data in the system format:
    Topic: $oc/devices/{device_id}/sys/messages/up  
    Data format:
    {
        "object_device_id": "{object_device_id}",
        "name":null,
        "id":"aca6a906-c74c-4302-a2ce-b17ba2ce630c",
        "content":"hello!"
    }