Digi Remote Manager allows users to send requests to their connected devices to do certain actions remotely, like turning on a light, reading the temperature, or returning diagnostics data, among other things. These are all custom processes, and final users program their devices to behave in a certain way when they receive these requests. Simulated devices can also be set up to do similar tasks.

1. Include device requests support

To include device requests support in a simulation you must:

  1. Add the user_app object to the simulation.json file. See Simulation configuration.

  2. Include the device_requests_id value in the corresponding profile file inside the profiles directory of your simulation. See Device profiles definition.

  3. Create a *.json file named as the value of the device_requests_id property inside device_requests directory of your simulation.

  4. Include the supported requests targets. See Device request configuration.

  5. Create the required Python custom code to process your configured requests.

2. Implement device requests custom code

The last step requires the customization of Python method process_request() to manage the requests:

  1. Create a Python file called simulation.py in the root of your simulation directory if it does not exist yet.

  2. Implement the method process_requests() inside simulation.py.

    def process_request(device_id, profile_id, target, request_data)

A device request follows this structure:

<sci_request version="1.0">
  <data_service>
    <targets>
      <device id="XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX" />
    </targets>
    <requests>
      <device_request target_name="custom_target">custom data</device_request>
    </requests>
  </data_service>
</sci_request>

The implemented process_request() method:

  • Receives as parameters:

    • device_id, the device identifier in the value of the id attribute of the device element in the request from Remote Manager. In the example above XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX.

    • profile_id, the profile identifier the simulated device is using.

    • target, the value of the target_name attribute in the request from Remote Manager. In the example above custom_target.

    • request_data, text data of the device_request element in the request from Remote Manager.

  • Returns a tuple with:

    • An integer value for the result after processing the request. Usually 0 for success, any other value for failure.

    • A string with the response for the request, or None if it is not required.

    • Returning the tuple (None, None) means the request is not supported for the provided parameters.

For example, find below the code to respond a received ping request target with:

  • pong from devices using pingpong profile

  • pang from devices using pingpang profile

def process_request(device_id, profile_id, target, request_data):
    """
    Process the provided request.

    Args:
        device_id (String): Device identifier.
        profile_id (String): Identifier of the profile the device is using.
        target (String): Request target.
        request_data (String): Request data.

    Returns:
        Tuple: Tuple with response to send to Remote Manager:
                - status (Integer): Status value after processing the request included in
                                    the 'status' attribute of the response.
                                    Usually 0 for success, any other value is an error code.
                                    Not implemented yet, reserved for future use.
                - data (String): Response data for the request included as text content.
                                 `None` for empty response.

                Returns `(None, None)` if not supported target.
    """
    if target == "ping":
        if profile_id == "pingpong":
            return 0, "pong from %s" % device_id
        elif profile == "pingpang":
            return 0, "pang from %s" % device_id

    return None, None

You can also review the example at 6. Implement custom code.