Command Custom Functions

Command Custom Functions

AlertNote: The Command Custom Function feature is currently in its beta stage with further enhancements planned in the product roadmap. Contact support@zohoiot.com 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


 










      Create. Review. Publish.

      Write, edit, collaborate on, and publish documents to different content management platforms.

      Get Started Now


        Access your files securely from anywhere

          Zoho CRM Training Programs

          Learn how to use the best tools for sales force automation and better customer engagement from Zoho's implementation specialists.

          Zoho CRM Training
            Redefine the way you work
            with Zoho Workplace

              Zoho DataPrep Personalized Demo

              If you'd like a personalized walk-through of our data preparation tool, please request a demo and we'll be happy to show you how to get the best out of Zoho DataPrep.

              Zoho CRM Training

                Create, share, and deliver

                beautiful slides from anywhere.

                Get Started Now


                  Zoho Sign now offers specialized one-on-one training for both administrators and developers.

                  BOOK A SESSION







                              Quick LinksWorkflow AutomationData Collection
                              Web FormsEnterpriseOnline Data Collection Tool
                              Embeddable FormsBankingBegin Data Collection
                              Interactive FormsWorkplaceData Collection App
                              CRM FormsCustomer ServiceAccessible Forms
                              Digital FormsMarketingForms for Small Business
                              HTML FormsEducationForms for Enterprise
                              Contact FormsE-commerceForms for any business
                              Lead Generation FormsHealthcareForms for Startups
                              Wordpress FormsCustomer onboardingForms for Small Business
                              No Code FormsConstructionRSVP tool for holidays
                              Free FormsTravelFeatures for Order Forms
                              Prefill FormsNon-Profit

                              Intake FormsLegal
                              Mobile App
                              Form DesignerHR
                              Mobile Forms
                              Card FormsFoodOffline Forms
                              Assign FormsPhotographyMobile Forms Features
                              Translate FormsReal EstateKiosk in Mobile Forms
                              Electronic Forms
                              Drag & drop form builder

                              Notification Emails for FormsAlternativesSecurity & Compliance
                              Holiday FormsGoogle Forms alternative GDPR
                              Form to PDFJotform alternativeHIPAA Forms
                              Email FormsFormstack alternativeEncrypted Forms

                              Wufoo alternativeSecure Forms

                              WCAG

                                      Create. Review. Publish.

                                      Write, edit, collaborate on, and publish documents to different content management platforms.

                                      Get Started Now







                                                        You are currently viewing the help pages of Qntrl’s earlier version. Click here to view our latest version—Qntrl 3.0's help articles.




                                                            Manage your brands on social media


                                                              • Desk Community Learning Series


                                                              • Digest


                                                              • Functions


                                                              • Meetups


                                                              • Kbase


                                                              • Resources


                                                              • Glossary


                                                              • Desk Marketplace


                                                              • MVP Corner


                                                              • Word of the Day


                                                              • Ask the Experts


                                                                Zoho Sheet Resources

                                                                 

                                                                    Zoho Forms Resources


                                                                      Secure your business
                                                                      communication with Zoho Mail


                                                                      Mail on the move with
                                                                      Zoho Mail mobile application

                                                                        Stay on top of your schedule
                                                                        at all times


                                                                        Carry your calendar with you
                                                                        Anytime, anywhere




                                                                              Zoho Sign Resources

                                                                                Sign, Paperless!

                                                                                Sign and send business documents on the go!

                                                                                Get Started Now




                                                                                        Zoho TeamInbox Resources





                                                                                                  Zoho DataPrep Demo

                                                                                                  Get a personalized demo or POC

                                                                                                  REGISTER NOW


                                                                                                    Design. Discuss. Deliver.

                                                                                                    Create visually engaging stories with Zoho Show.

                                                                                                    Get Started Now








                                                                                                                        • Related Articles

                                                                                                                        • Understanding Custom Functions

                                                                                                                          Custom functions in Zoho IOT allow you to extend the platform's capabilities. These functions are written using various programming languages and are easy to construct. With custom functions, users can move beyond a rigid platform to a highly ...
                                                                                                                        • Adding and managing custom functions

                                                                                                                          This guide will help you add, edit, delete, and manage custom functions in the Zoho IOT application. Adding a Custom Function You can add a custom function in the developer application as well as in the end application. Adding a custom function in ...
                                                                                                                        • Command - FAQs

                                                                                                                          Is it mandatory for an edge device to send an acknowledgment after executing a command? In some cases, acknowledgements are not required. We can assist you in configuring commands on your device to work without mandatory acknowledgements, please ...
                                                                                                                        • Understanding Command Widgets

                                                                                                                          Command type widgets are used to perform actions such as On/Off, control brightness or volume, etc., on managed entities. You can choose from a list of commands created in the application and associate it with the corresponding widget. These widgets ...
                                                                                                                        • Understanding Custom Modules

                                                                                                                          Custom modules in Zoho IOT allow you to store and manage additional information specific to your business needs. You can configure these modules with various fields to capture both manual and automated information from users and the application. For ...
                                                                                                                          Wherever you are is as good as
                                                                                                                          your workplace

                                                                                                                            Resources

                                                                                                                            Videos

                                                                                                                            Watch comprehensive videos on features and other important topics that will help you master Zoho CRM.



                                                                                                                            eBooks

                                                                                                                            Download free eBooks and access a range of topics to get deeper insight on successfully using Zoho CRM.



                                                                                                                            Webinars

                                                                                                                            Sign up for our webinars and learn the Zoho CRM basics, from customization to sales force automation and more.



                                                                                                                            CRM Tips

                                                                                                                            Make the most of Zoho CRM with these useful tips.



                                                                                                                              Zoho Show Resources