Command Custom Function

Command Custom Function

AlertNote: The Command Custom Function feature is currently in its beta stage with further enhancements planned in the product roadmap. Contact support@zohoiot.com to enable it and for more details.
When a command is executed in the Zoho IoT application, it sends a standard command payload to the connected device and expects an acknowledgement.

You can use the command custom function when:
  1. Your device cannot process the standard command payload used by Zoho IoT.
  2. You want to define and send a customised payload format that matches your device requirements.
  3. You need to control whether an acknowledgement is required from the device.
In this command custom function, you must write a custom function using the Deluge scripting language. The custom function must be manually associated to the specific device model of the device instance through the browser console.   

This document explains the steps involved in creating a command custom function, linking it manually to a device in the application, a sample code, and executing the command.

Command Payload

When a command is executed, the Zoho IoT application sends a JSON payload containing key details. The command key inside this payload helps the edge device identify which command was triggered and perform the right action.

Here is a sample command payload:

Prerequisites

Before adding and executing a command custom function, ensure the following prerequisites are met:
  1. The gateway or smart device is added and connected to the Zoho IoT application.
  2. For peripheral devices, assets, or locations, ensure they are correctly associated with the gateway device.
  3. The required command is configured for the relevant device, asset, or location.

Creating a command custom function

NotesNote: The command custom function is not available by default and will be enabled on request to support@zohoiot.com
The first step is to add a command custom function in the Zoho IoT application. 

To create a command custom function,
  1. Access the End Application.



  2. Click the Settings icon in the top right corner.



  3. Click Action in the Automation section.



  4. Select the Custom Functions tab.



  5. Click Add Custom Function.



  6. Select Commands in the Category field.



  7. Provide the required values in the appropriate fields.
    Example -
    Language : Deluge
    Model/Module: Gateway (Select the model on which the device, asset, or location is based on)
    Display Name: example command custom function (Provide a name of your choice)
    Function Name: ex_comm_cus_func (Provide a name of your choice)
    Description:  A custom command function that sends a custom payload on execution.



  8. Click Save. This will open the Code Editor.
Now you can now proceed to write the code for the command custom function. 

Command Custom Function Code

The following section describes in detail the code components needed to write a command custom function.

payload_map

When a command is executed in the Zoho IoT application, the command payload is passed to your Deluge function in a variable called payload_map.

payload_map contains information about the command that was triggered. Here is the basic payload stored in payload_map when a command is triggered.
 
{
  "device_id": 6102000000346431,
  "hub_ipaddress": "10.44.3.249",
  "zsoid": "884225516",
  "commands": [
    {
      "payload": [
        {
          "edge_command_key": "power_status",
          "value": "on"
        }
      ],
      "command_name": "Power",
      "correlation_id": "965a23b0-b4b7-11f0-bb09-53540001bbcd",
      "user_input_value": "on"
    }
  ]
}
You can add additional information to this payload by enabling fields in the command's configuration and selecting the required fields.



Sample of command payload when the fields: Model and Last Status Update are selected.

{
  "device_id": 6102000000346431,
  "hub_ipaddress": "10.44.3.249",
  "zsoid": "884225516",
  "commands": [
    {
      "payload": [
        {
          "edge_command_key": "power_status",
          "attributes": [
            {
              "field": "layout",
              "value": {
                "settings": {
                  "show_instance_dashboard": false,
                  "default_location_preference": "field"
                },
                "name": "Home Gateway",
                "icon": "device",
                "id": "6102000000346003"
              }
            },
            {
              "field": "status_update_time",
              "value": {
                "millis_in_gmt": 1761735856000,
                "formatted": [
                  "10 minutes ago"
                ],
                "value": "2025-10-29T16:34:16"
              }
            }
          ],
          "value": "on"
        }
      ],
      "command_name": "Power",
      "correlation_id": "74d6ed30-b4b8-11f0-bb09-53540001bbcd",
      "user_input_value": "on"
    }
  ]
}
From the payload_map variable, you can extract the required values and use them in your Deluge script. The following example shows how to read values from payload_map and assign them to variables.
command_key = payload_map.get("commands").get(0).get("payload").get(0).get(" edge_command_key");
command_value = payload_map.get("commands").get(0).get("payload").get(0).get("value");
With these lines of code, the values for command, power_status, and on are extracted from the payload_map variable and stored in their respective variables. You can then use these values as inputs or conditions in your Deluge script.

Return value

The command custom function must end with a return variable that is a map object. This map should contain specific keys and values that define how the command behaves. The returned map can include details such as:
  1. the command payload
  2. whether the payload should be sent to the device
  3. whether a post-acknowledgement message is required from the device
  4. the acknowledgement code to be sent
Here’s a simple, working example of a Deluge custom command function that returns the required map variable with all the key parameters:
response = map();
response.put("send_to_device", true);
response.put("post_function_ack", true);
response.put("ack_status", 1001);
response.put("command_payload", {'power_status':'on'});
return response;
In this script, response is the variable that must be returned. It is first declared as a map, after which the required parameters and their corresponding values are added using the put method.

Keys to be returned

While writing a command custom function, the following keys and their corresponding values must be returned.

command_payload 

Holds the command payload that will be dispatched as the output. The value must be a JSON object containing its own set of key-value pairs.
The value for the command_payload key must be of the JSON object data type.
Info
Refer to the examples section for different types of payloads that can be sent.

send_to_device 

Determines whether the output payload should be sent to the connected device over MQTT.
  1. false, is used for LoRa devices, where the actual payloads are not sent.
  2. For MQTT devices, set this key to true so that the command payload is delivered to the connected device.
The value for the send_to_device key must be of the Boolean data type. The default value is false.

post_function_ack  

Defines whether the acknowledgement for a command should be sent by the device or handled within the custom function. 
  1. When false, the Zoho IoT application expects the device to send an acknowledgement. If none is received, the command fails.
  2. When true, the custom function sends an acknowledgement status directly to the application.
  3. If post_function_ack is set to true, the ack_status key and its corresponding value must also be included.
The value for the post_function_ack key must be of the Boolean data type. The default value is false.
NotesNote: If post_function_ack is set to true, the actual execution result of the command on the device will not be known, since the acknowledgement originates from the custom function rather than the device.

ack_status  

Represents the acknowledgement status. This key is used only when post_function_ack is set to true.
The value for the post_function_ack key must be of the Integer data type.

Possible values:
1001 : Success
1002 : Pushed to Network Server (for LoRa cases only, used when send_to_device is false)
1004 : Success (Published to Device)
4000 : Failure
4009 : Failure (Customization Response Limit Exceeded)

Examples of command custom functions

Below are a few examples of command custom functions for different use cases.

Modified payload

In this example, the command custom function modifies the payload before it is sent.

Static Payload

In the following example, the command payload remains the same regardless of the option selected during command execution or the command key configured for the command.

If you need to change the payload value, it must be manually updated within the custom function itself.
response = map();
response.put("send_to_device", true);
response.put("command_payload", {'value': 'on', 'status':1});
return response;
Payload output for static value code:


Dynamic Payload

In the following example, the command payload value changes dynamically based on the command, its command key, and the selected value during execution. The command_key and its corresponding command_value are retrieved from the payload_map variable.
response = map();
response.put("send_to_device", true);
command_key = payload_map.get("commands").get(0).get("payload").get(0).get(" edge_command_key");
command_value = payload_map.get("commands").get(0).get("payload").get(0).get("value");
response.put("command_payload", {command_key, command_value});
return response;
Payload output for dynamic value code:



(or)


Removing acknowledgement requirement

In the modified payload example, the payload value is sent to the device with the assumption that it can return an acknowledgement indicating the command’s status. If the device in unable to do so, the command will be marked as failed. In such cases, the acknowledgement can be managed within the custom function itself.

The following example demonstrates how a custom function can send an success acknowledgement once the command is executed.

Example 1:
response = map();
response.put("send_to_device",true);
response.put("post_function_ack",true); //handles acknowledgement internally
response.put("ack_status",1001); //acknowledgement set to success
response.put("command_payload",{"value":"on","status":1});
return response;
Example 2:
response.put("send_to_device",true);
response.put("post_function_ack",true);  //handles acknowledgement internally
response.put("ack_status",1001);  //acknowledgement set to success
command_key = payload_map.get("commands").get(0).get("payload").get(0).get("edge_command_key");
command_value = payload_map.get("commands").get(0).get("payload").get(0).get("value")
response.put("command_payload",{command_key:command_value});
return response;

Linking with the required Device 

Once you’ve written and saved the command custom function, you can link it to the required device. Since the command custom function isn’t a publicly available feature, it must be associated manually. Before proceeding, make sure you have both the Device ID and the Command Custom Function ID, as these are needed to complete the linking process.

Obtain the Device ID

Notes
Note: The same steps are applicable for assetID and locationID.
To obtain the deviceID,

  1. Select Devices > Device in the left navigation page.



  2. Click on the device for which the command custom function needs to be associated. For this illustration, Arduino Home GM is selected. 



  3. From the address bar of your browser, copy the 16 digit device ID.


Obtain the Command Custom Function ID

To obtain the command custom function ID,

  1. Click the Settings icon in the top right corner.



  2. Click Actions in the Automation section.



  3. Select the Custom Functions tab.



  4. In the custom functions list view, right click on the page and select Inspect in the context menu.



  5. Select the Network tab.



  6. Select Fetch/XHR.



  7. Now, click the required command custom function.



  8. Click the value that appears in the Name Section of the inspect panel. 



  9. Select the Response tab.



  10. From there, scroll up or down to get the 16 digit custom function ID.


Executing Association code

With the Device ID and custom function ID obtained we can now run the association code in console to associate the command custom function with the required devices.
NotesNote: Before proceeding with this step, make sure you have added the required Command Template to the selected model. 
To execute association code,
  1. Select Console in the Inspect window. 



  2. Paste the following lines of code, with <device_ID > and <custom_function_ID> replaced with the actual values obtained. 

    Code without DeviceID and CustomFunctionID

    ((recordId, functionId)=>
    {
        ZIOT.ajax.put("/iot/v1/devices/"+recordId, JSON.stringify({
            "devices": {
                "id": ""+recordId,
                "command_handler": {
                    "id": ""+functionId
                }
            }
            }))
    })('<device_id>', '<custom_function_id>')
    Code with DeviceID and CustomFunctionID

    ((recordId, functionId)=>
    {
        ZIOT.ajax.put("/iot/v1/devices/"+recordId, JSON.stringify({
            "devices": {
                "id": ""+recordId,
                "command_handler": {
                    "id": ""+functionId
                }
            }
            }))
    })('6102000000346431', '6102000000353047')


  3. Press Enter.
The command custom function will now be associated to the selected model and all its instances. 

Executing the Command

With the command custom function now associated, you can now execute the command from the device and send the command payload defined in the custom function.
Alert
The device (connected device, in the case of assets and locations) must be connected with the Zoho IoT application before executing the command.
NotesNote: The below steps are applicable to both assets and locations.
To execute the command,
  1. Navigate to Device > Device in the navigation pane.



  2. Click the device for which you want to execute the command. For this illustration, Arduino Home GW is selected.



  3. In the device information page, select Actions > Command Configuration.



  4. Check the box near the required command and click Execute.



  5. Select the required value and click Execute.



  6. In the command execution confirmation dialog box, click Execute.



  7. The command will be successfully executed.



If you used the dynamic custom function shown in the previous section, the application would send the following payloads when each type of the commands below is executed.






See Also