Service invocation

Service list

Service definitions

1. Log on to the IoT Platform console.

2. In the upper-left corner of the console, select the China (Shanghai) region.

3. On the Instance Overview tab, under All Environments, find and click your instance.

4. In the left-side navigation pane, choose Device Management > Products.

5. In the product list, find the product for your broadcast device and click View in the Actions column.

6. On the Product Details page, click the Function Definition tab.

7. Click View in the Actions column for a service to see its function definition, including the identifier, input parameters, and output parameters.

   The dialog box also lets you set the Invocation Method to either asynchronous or synchronous.

Service definitions

Speech push

When you use the Speech Broadcasting Service to push speech to a device, IoT Platform invokes its speech push service on the device. You must use event reporting to report the push result to IoT Platform.

Definition

Feature	Description
Identifier	SpeechPost.
Invocation mode	Asynchronous. IoT Platform returns a result immediately after the service is invoked, without waiting for a response message from the device.
Input parameter	Speech content download URL: IoT Platform compiles the speech file URLs into a JSON file and sends the URL of this file to the device. The device then parses the JSON file, downloads the speech files, and stores them locally for future composite broadcasts. Note To ensure the Speech Broadcasting Service functions correctly, the downloaded speech files must be named using their speech identifiers, or a mapping between speech identifiers and local filenames must be implemented on the broadcast device. Task ID: The ID of the speech push task. This corresponds to the jobcode parameter in the example payload. When the task is complete or an error occurs, you must use this ID to report the push result to the IoT Platform cloud.

Speech push result

The speech push result must be reported to IoT Platform through event reporting. For details, see event reporting.

Note

The status on the Speech Push Task Board in the Speech Broadcasting Service console updates only after the device reports the execution result. Otherwise, the task status changes to timed out, even if the speech was pushed successfully.

Example

• Example of data received by the device

  {
      "method":"thing.service.SpeechPost",
      "id":"6835*",
      "params":{
          "jobcode":"LJSdmPCIcG9js83R3IHc3GD6cbN*_16086091*",    // task ID
          "url":"http://speech-solution.oss-cn-shanghai.aliyuncs.com/speech_post_content/hL7****gu7Auup1TQUMy4gEcFyQ/LJSdmPCIcG9js8****Hc3GD6cbN.json?Expires=16086&OSSAccessKeyId=LTAI****************&Signature=ivvUslTdFHqeUCsa0yBv%2FD****"  // URL for the JSON file containing speech content
      },
      "version":"1.0.0"
  }

• Example of content in the downloaded file

  {
      "audios":[
          {
              "format":"wav",   // Audio format of this speech
              "id":"100wan",    // Identifier of this speech
              "size":69960,     // Size of this speech in bytes
              "type":"custom",
              "url":"http://speech-solution.oss-cn-shanghai.aliyuncs.com/speech_model_audio/A96R0NcWiYoAXPSAuyfoLTG12nn*****/100wan.wav?Expires=1628949824&OSSAccessKeyId=LTAI****************S6P47&Signature=%2Bqk2bs********SfyoXU1Ugjxeg%3D"    // Speech download URL
          }
      ],
      "format":"wav",
      "size":69960    // Total size of all speech in this push, in bytes
  }

Composite broadcast

When a user application sends a broadcast command via the Speech Broadcasting Service, IoT Platform invokes the composite broadcast service on the device. The device receives this same invocation whether you call the composite broadcast API or the shared composite broadcast API, so no separate integration is required.

Definition

• Identifier: SpeechBroadcast.

• Invocation mode: Asynchronous. IoT Platform returns a result immediately after the service is invoked, without waiting for a response message from the device.

  If you use the Overview, refer to the asynchronous callback function in the data_model_basic_demo.c file of the SDK to implement asynchronous calls. For details, see Step 4: Set properties.

  static void demo_dm_recv_async_service_invoke(void *dm_handle, const aiot_dm_recv_t *recv, void *userdata)
  {
      printf("demo_dm_recv_async_service_invoke msg_id = %ld, service_id = %s, params = %.*s\r\n",
              (unsigned long)recv->data.async_service_invoke.msg_id,
              recv->data.async_service_invoke.service_id,
              recv->data.async_service_invoke.params_len,
              recv->data.async_service_invoke.params);
      /* TODO: The following code demonstrates how to respond to an asynchronous service invocation from the cloud. You can uncomment the code to see the demonstration.
          *
          * Note: If you respond outside the callback function, you must save the msg_id yourself. The input parameters of the callback function are destroyed after the function exits and can no longer be accessed.
          */
      /*
      {
          aiot_dm_msg_t msg;
          memset(&msg, 0, sizeof(aiot_dm_msg_t));
          msg.type = AIOT_DMMSG_ASYNC_SERVICE_REPLY;
          msg.data.async_service_reply.msg_id = recv->data.async_service_invoke.msg_id;
          msg.data.async_service_reply.code = 200;
          msg.data.async_service_reply.service_id = "ToggleLightSwitch";
          msg.data.async_service_reply.data = "{\"dataA\": 20}";
          int32_t res = aiot_dm_send(dm_handle, &msg);
          if (res < 0) {
              printf("aiot_dm_send failed\r\n");
          }
      }
      */
  }

• Input parameter:

  Parameter	Description
  Composite broadcast parameters	Content broadcast: Pass a JSON array of speech identifiers. These identifiers correspond to speech segments stored locally. The device plays the speech segments sequentially according to their order in the array. Numeric broadcast: Unlike content broadcasts, a special identifier {} is sent to instruct the device to perform a numeric broadcast instead of sending individual identifiers for each digit. Broadcast amount: Use the format {$***}. For example, {$123.4} plays "one hundred twenty-three point four yuan". Broadcast number: Use the format {N***}. For example, {N123.4} plays "one two three point four".
  Broadcast command issuance timestamp	The UTC timestamp from IoT Platform when the broadcast command was issued.
  Broadcast ID	A unique message ID for the broadcast command. The device plays a command with a given ID only once to prevent duplicates.
  Audio format	The audio format of the speech to be broadcast. Use this parameter when speech has the same broadcast ID but a different format. Supported formats: wav, mp3, and amr.

• Return parameter:

  Parameter	Description
  Broadcast result	The actual broadcast result from the device. The valid values are: 0: The speech was successfully broadcast. 1: The speech was already broadcast (duplicate broadcast). 2: The speech does not exist.
  Error message	Returns the specific reason for an error. You can customize this message.
  Broadcast ID	This ID must match the broadcast ID from the input parameter. It is used to correlate the response with the original invocation.
  Start processing timestamp	The UTC timestamp when the device started processing the broadcast request. This is used by the cloud to collect broadcast metrics.
  Processing completion timestamp	The UTC timestamp when the device finished processing the broadcast request. This is used by the cloud to collect broadcast metrics.

Example

Example: Received data

• Topic: /sys/${productKey}/${deviceName}/thing/service/SpeechBroadcast.

• Payload:

  {
      "method":"thing.service.SpeechBroadcast",
      "id":"4532*",
      "params":{
          "format":"wav",                         // Audio format
          "speechs":[
              "ZFBDZ",                            // composite broadcast parameter for content broadcast
              "{$123}"                            // composite broadcast parameter for broadcasting an amount
          ],
          "id":"zGlLLH9GMhrWTwYWXppcvvM3****",    // Broadcast ID
          "timestamp":"1608523503634"             // Broadcast command issuance timestamp
      },
      "version":"1.0.0"
  }

Example: Returned data

• Topic: /sys/${productKey}/${deviceName}/thing/service/SpeechBroadcast_reply.

• Payload:

  {
      "code":200,
      "data":{
          "result":2,
          "error_message":"speech model not found",
          "task_id":"LH9GMhrWTwYWXppcvvM3****",
          "start_time":"1638179978545",
          "end_time":"1638179978545"
      },
      "id":"4532*"
  }

• Return parameter:

  Parameter	Description
  code	A fixed value of 200 indicates that the broadcast request has been processed.
  id	The message ID. It must be the same as the payload.id in the received request.
  data	The returned result. For details, see the Return parameter section under Definition.

Synchronous composite broadcast

Unlike the asynchronous service, the synchronous composite broadcast service requires the device to return an execution result. If IoT Platform does not receive a response, it retries the broadcast command.

Definition

• Identifier: SyncSpeechBroadcast.

• Invocation mode: Synchronous. IoT Platform waits for a response from the device. If the device does not respond, the invocation times out.

  For synchronous services, you need to respond by using RRPC. If you use the Overview, refer to the implementation of the synchronous call callback function in the data_model_basic_demo.c file in the SDK. For specific operations, see Step 4: Set properties.

  static void demo_dm_recv_sync_service_invoke(void *dm_handle, const aiot_dm_recv_t *recv, void *userdata)
  {
      printf("demo_dm_recv_sync_service_invoke msg_id = %ld, rrpc_id = %s, service_id = %s, params = %.*s\r\n",
              (unsigned long)recv->data.sync_service_invoke.msg_id,
              recv->data.sync_service_invoke.rrpc_id,
              recv->data.sync_service_invoke.service_id,
              recv->data.sync_service_invoke.params_len,
              recv->data.sync_service_invoke.params);
      /* TODO: The following code demonstrates how to respond to a synchronous service invocation from the cloud. You can uncomment the code to see the demonstration.
          *
          * Note: If you respond outside the callback function, you must save the msg_id and the rrpc_id string yourself. The input parameters of the callback function are destroyed after the function exits and can no longer be accessed.
          */
      /*
      {
          aiot_dm_msg_t msg;
          memset(&msg, 0, sizeof(aiot_dm_msg_t));
          msg.type = AIOT_DMMSG_SYNC_SERVICE_REPLY;
          msg.data.sync_service_reply.rrpc_id = recv->data.sync_service_invoke.rrpc_id;
          msg.data.sync_service_reply.msg_id = recv->data.sync_service_invoke.msg_id;
          msg.data.sync_service_reply.code = 200;
          msg.data.sync_service_reply.service_id = "SetLightSwitchTimer";
          msg.data.sync_service_reply.data = "{}";
          int32_t res = aiot_dm_send(dm_handle, &msg);
          if (res < 0) {
              printf("aiot_dm_send failed\r\n");
          }
      }
      */
  }

• Input parameter:

  The input parameters are the same as those for the composite broadcast service. For details, see the Input parameter section under the Definition for that service.

• Return parameter:

  Parameter	Description
  Broadcast result	The actual broadcast result from the device. The valid values are: 0: The speech was successfully broadcast. 1: The speech was already broadcast (duplicate broadcast). 2: The speech does not exist.
  Error message	Returns the specific reason for an error. You can customize this message.
  Broadcast ID	This ID must match the broadcast ID from the input parameter. It is used to correlate the response with the original invocation.
  Broadcast result details	Returns information such as the device's signal strength and battery level at the time of broadcast. You can customize this information.
  Start processing timestamp	The UTC timestamp when the device started processing the broadcast request. This is used by the cloud to collect broadcast metrics.
  Processing completion timestamp	The UTC timestamp when the device finished processing the broadcast request. This is used by the cloud to collect broadcast metrics.

Example

Example: Received data

• Topic: /ext/rrpc/${rrpcId}/sys/${productKey}/${deviceName}/thing/service/SyncSpeechBroadcast.

• Payload:

  {
      "method":"thing.service.SyncSpeechBroadcast",
      "id":"4532*",
      "params":{
          "format":"wav",                         // Audio format
          "speechs":[
              "ZFBDZ",                            // composite broadcast parameter for content broadcast
              "{$123}"                            // composite broadcast parameter for broadcasting an amount
          ],
          "id":"zGlLLH9GMhrWTwYWXppcvvM3****",    // Broadcast ID
          "timestamp":"1608523503634"             // Broadcast command issuance timestamp
      },
      "version":"1.0.0"
  }

Example: Returned data

• Topic: /ext/rrpc/${rrpcId}/sys/${productKey}/${deviceName}/thing/service/SyncSpeechBroadcast.

• Payload:

  {
      "code":200,
      "data":{
          "result":2,
          "error_message":"speech model not found",
          "task_id":"LH9GMhrWTwYWXppcvvM3****",
          "start_time":"1638179978545",
          "end_time":"1638179978545"
      },
      "id":"4532*"
  }

• Return parameter:

  Parameter	Description
  code	A fixed value of 200 indicates that the broadcast request has been processed.
  id	The message ID. It must be the same as the payload.id in the received request.
  data	The returned result. For details, see the Return parameter section under Definition.

Replay last message

When you use the Speech Broadcasting Service to command a device to replay the last composite broadcast, IoT Platform invokes the replay last message service on the device.

Feature	Description
Identifier	ReSpeechBroadcastLastOne.
Invocation mode	Asynchronous. IoT Platform returns a result immediately after the service is invoked, without waiting for a response message from the device.
Input parameter	None.

Start loop broadcast

When you use the Speech Broadcasting Service to start a loop broadcast of a fixed speech combination on a device, IoT Platform invokes the start loop broadcast service on the device.

Feature	Description
Identifier	StartSpeechBroadcastLoop.
Invocation mode	Asynchronous. IoT Platform returns a result immediately after the service is invoked, without waiting for a response message from the device.
Input parameter	List of speech identifiers: A JSON array that contains the identifiers of the speech files to be included in the loop broadcast. Audio format: The audio format of the speech files to be included in the loop broadcast. Supported formats: wav, mp3, and amr.

Stop loop broadcast

When you use the Speech Broadcasting Service to stop a loop broadcast of a fixed speech combination on a device, IoT Platform invokes the stop loop broadcast service on the device.

Feature	Description
Identifier	StopSpeechBroadcastLoop.
Invocation mode	Asynchronous. IoT Platform returns a result immediately after the service is invoked, without waiting for a response message from the device.
Input parameter	List of speech identifiers: A JSON array that contains the identifiers of the speech files whose loop broadcast you want to stop. Audio format: The audio format of the specified speech files. Supported formats: wav, mp3, and amr.

Batch delete speech

When you use the Speech Broadcasting Service to delete specified speech files from a device, IoT Platform invokes the batch delete speech service on the device. After the call succeeds, you can manage the speech files on the device in the Speech Broadcasting Service console.

Definition

Feature	Description
Identifier	DeleteSpeech.
Invocation mode	Asynchronous. IoT Platform returns a result immediately after the service is invoked, without waiting for a response message from the device.
Input parameter	List of speech files: A JSON array that specifies the list of speech files to be deleted. Speech identifier: The identifier of the speech file to be deleted. Audio format: The audio format of the speech file to be deleted. Supported formats: wav, mp3, and amr.

Example

Example of data received by the device:

{
    "method":"thing.service.DeleteSpeech",
    "id":"189604****",
    "params":{
        "speechs":[
            {
                "format":"wav",     // Audio format
                "id":"SYS_T**E_0"   // Speech identifier
            },
            {
                "format":"wav",
                "id":"SYS_T**E_TIME_ri"
            }
        ]
    },
    "version":"1.0.0"
}

Delete all pushed speech

Deletes all speech files pushed from the IoT Platform cloud to free up local storage. After you integrate this service, you can manage device storage in the Speech Broadcasting Service console.

When you need to delete all speech files pushed to a device via the Speech Broadcasting Service, IoT Platform invokes the delete all pushed speech service on the device.

Feature	Description
Identifier	ClearAllSpeechModelByPost.
Invocation mode	Asynchronous. IoT Platform returns a result immediately after the service is invoked, without waiting for a response message from the device.
Input parameter	Audio format: The audio format of the speech files to be deleted. Supported formats: wav, mp3, and amr. Example: If you pass mp3, the service deletes all mp3-format speech files from the device.

Topics

• Cloud-to-device service call:

  /sys/${productkey}/${deviceName}/thing/service/${tsl.service.identifier}

• Service call response:

  To monitor the execution status of asynchronous service calls, the device must publish a response to the corresponding reply topic.

  /sys/${productkey}/${deviceName}/thing/service/${tsl.service.identifier}_reply

Where:

• ${productkey} and ${deviceName}: Replace with your device's ProductKey and DeviceName.

• ${tsl.service.identifier}: The service identifier. For example, SpeechBroadcast is the identifier for the composite broadcast service.

Usage

The Alibaba Cloud OpenAPI developer portal features an API online debugging tool. Use this tool to simulate cloud-to-device service calls and verify that your device responds correctly to service calls from IoT Platform.

For details on using the IoT Platform OpenAPI, see integration overview and OpenAPI examples.