Use Python to respond to Digi Remote Manager SCI requests

The device_request Python module allows you to interact with Digi Remote Manager by using Remote Manager's Server Command Interface (SCI), a web service that allows users to access information and perform commands that relate to their devices.

Use Remote Manager's SCI interface to create SCI requests that are sent to your EX15 device, and use the device_request module to send responses to those requests to Remote Manager.

See the Digi Remote Manager Programmers Guide for more information on SCI.

Task one: Use the device_request module on your EX15 device to create a response

Select a device in Remote Manager that is configured to allow shell access to the admin user, and click Actions > Open Console. Alternatively, log into the EX15 local command line as a user with shell access.
Depending on your device configuration, you may be presented with an Access selection menu. Type shell to access the device shell.

At the shell prompt, use the python command with no parameters to enter an interactive Python session:

# python
Python 3.10.1 (main, Mar 30 2023, 23:47:13) [GCC 11.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>

Import the device_request module:

>>> from digidevice import device_request
>>>

Create a function to handle the request from Remote Manager:

>>> def handler(target, request):
     print ("received request %s for target %s" % (request, target))
     return "OK"
>>>

Register a callbackup function that will be called when the device receives a SCI request from Remote Manager:
```
>>> device_request.register("myTarget", handler)
>>>
```

Note Leave the interactive Python session active while completing task two, below. Once you have completed task two, exit the interactive session by using Ctrl-D. You can also exit the session using exit() or quit().

Task two: Create and send an SCI request from Digi Remote Manager

The second step in using the device_request module is to create an SCI request that Remote Manager will forward to the device. For example, you can create in SCI request a the Remote Manager API explorer:

In Remote Manager, click Documentation > API Explorer.
Select the device to use as the SCI target:
1. Click SCI Targets.
2. Click Add Targets.
3. Enter or select the device ID of the device.
4. Click Add.
5. Click OK.
Click Examples > SCI > Data Service > Send Request.
Code similar to the following will be displayed in the HTTP message body text box:
```
<sci_request version="1.0">
  <data_service>
  <targets>
    <device id="00000000-00000000-0000FFFF-A83CF6A3"/>
  </targets>
    <requests>
      <device_request target_name="myTarget">
        my payload string
      </device_request>
    </requests>
  </data_service>
</sci_request>
```
Note The value of the target_name parameter in the device_request element must correspond to the target parameter of the device_request.register function in the Python script. In this example, the two are the same.

Click Send.

Once that the request has been sent to the device, the handler on the device is executed.

On the device, you will receive the following output:

>>> received request
       my payload string
      for target myTarget
>>>

In Remote Manager, you will receive a response similar to the following:

<sci_reply version="1.0">
  <data_service>
    <device id="00000000-00000000-0000FFFF-A83CF6A3"/>
      <requests>
        <device_request target_name="myTarget" status="0">OK</device_request>
      </requests>
    </device>
  </data_service>
</sci_request>

Example: Use digidevice.cli with digidevice.device_request

In this example, we will use the digidevice.cli module in conjunction with the digidevice.device_request module to return information about multiple devices to Remote Manager.

Create a Python application, called showsystem.py, that uses the digidevice.cli module to create a response containing information about device and the device_request module to respond with this information to a request from Remote Manager:

from digidevice import device_request
from digidevice import cli
import time

def handler(target, request):
    return cli.execute("show system verbose")

def status_cb(error_code, error_description):
    if error_code != 0:
        print("error handling showSystem device request: %s" % error_description)

device_request.register("showSystem", handler, status_callback = status_cb)

# Do not let the process finish so that it handles device requests
while True:
    time.sleep(10)

Upload the showsystem.py application to the /etc/config/scripts directory on two or more Digi devices. In this example, we will upload it to two devices, and use the same request in Remote Manager to query both devices.
See Configure scripts to run automatically for information about uploading Python applications to your device. You can also create the script on the device by using the vi command when logged in with shell access.
For both devices:
1. Configure the device to automatically run the showsystem.py application on reboot, and to restart the application if it crashes. This can be done from either the WebUI or the command line:
   Web
  1. Log into Digi Remote Manager, or log into the local Web UI as a user with full Admin access rights.
  2. Access the device configuration:
    
    Remote Manager:
    Locate your device as described in Use Digi Remote Manager to view and manage your device.
    Click the Device ID.
    Click Settings.
    Click to expand Config.
    
    Local Web UI:
    On the menu, click System. Under Configuration, click Device Configuration.
    The Configuration window is displayed.
  3. Click System > Scheduled tasks > Custom scripts.
  4. Click  to add a custom script.
  5. For Label, type Show system application.
  6. For Run mode, select On boot.
  7. For Exit action, select Restart script.
  8. For Commands, type python /etc/config/scripts/showsystem.py.
  9. Click Apply to save the configuration and apply the change.
   Command line
  1. Select the device in Remote Manager and click Actions > Open Console, or log into the EX15 local command line as a user with full Admin access rights.
    Depending on your device configuration, you may be presented with an Access selection menu. Type admin to access the Admin CLI.
  2. At the command line, type config to enter configuration mode:
    > config (config)>
  3. Add an application entry:
    (config)> add system schedule script end (config system schedule script 0)>
    Scheduled scripts are enabled by default. To disable:
    (config system schedule script 0)> enable false (config system schedule script 0)>
  4. Provide a label for the script:
    (config system schedule script 0)> label "Show system application"
  5. Configure the application to run automatically when the device reboots:
    (config system schedule script 0)> when boot (config system schedule script 0)>
  6. Configure the application to restart if it crashes:
    (config system schedule script 0)> exit_action restart (config system schedule script 0)>
  7. Set the command that will execute the application:
    (config system schedule script 0)> commands "python /etc/config/scripts/showsystem.py" (config system schedule script 0)>
  8. Save the configuration and apply the change:
    (config)> save Configuration saved. >
2. Run the showsystem.py application. You can run the application by either rebooting the device, or by running it from the shell prompt.
  - To reboot the device:
    1. From the WebUI:
      1. From the main menu, click System.
      2. Click Reboot.
    2. From the command line, at the Admin CLI prompt, type:
```
> reboot
```
  - To run the application from the shell prompt:
    1. Select a device in Remote Manager that is configured to allow shell access to the admin user, and click Actions > Open Console. Alternatively, log into the EX15 local command line as a user with shell access.
      Depending on your device configuration, you may be presented with an Access selection menu. Type shell to access the device shell.
    2. Type the following at the shell prompt:
```
# python /etc/config/scripts/showsystem.py &
#
```
    3. Exit the shell:
```
# exit
```
In Remote Manager, click Documentation > API Explorer.
Select the devices to use as the SCI targest:
1. Click SCI Targets.
2. Click Add Targets.
3. Enter or select the device ID of one of the devices.
4. Click Add.
5. Enter or select the device ID of the second device and click Add.
6. Click OK.

Click Examples > SCI > Data Service > Send Request.

Code similar to the following will be displayed in the HTTP message body text box:

<sci_request version="1.0">
  <data_service>
  <targets>
    <device id="00000000-00000000-0000FFFF-A83CF6A3"/>
    <device id="00000000-00000000-0000FFFF-485740BC"/>
  </targets>
    <requests>
      <device_request target_name="myTarget">
        my payload string
      </device_request>
    </requests>
  </data_service>
</sci_request>

For the device_request element, replace the value of target_name with showSystem. This matches the target parameter of the device_request.register function in the showsystem.py application.
```
      <device_request target_name="showSystem">
```
Click Send.

You should receive a response similar to the following:

<sci_reply version="1.0">
  <data_service>
    <device id="00000000-00000000-0000FFFF-A83CF6A3"/>
      <requests>
        <device_request target_name="showSystem" status="0">Model                    : Digi EX15
          Serial Number            : EX15-000068
          Hostname                 : EX15
          MAC                      : 00:40:D0:13:35:36

          Hardware Version         : 50001959-01 A
          Firmware Version         : 25.5
          Bootloader Version       : 1
          Firmware Build Date      : Fri, Jan 12, 2024 12:10:00
          Schema Version           : 461

          Timezone                 : UTC
          Current Time             : Thu, Jan 11, 2024 12:10:00
          CPU                      : 1.1
          Uptime                   : 1 day, 21 hours, 49 minutes, 47 seconds (164987s)
          Temperature              : 39C

          Contact                  : Jane Smith

          Disk
          ----
          Load Average             : 0.10, 0.05, 0.00
          RAM Usage                : 85.176MB/250.484MB(34%)
          Disk /etc/config Usage   : 0.068MB/13.416MB(1%)
          Disk /opt Usage          : 47.724MB/5309.752MB(1%)
          Disk /overlay Usage      : MB/MB(%)
          Disk /tmp Usage          : 0.004MB/40.96MB(0%)
          Disk /var Usage          : 0.820MB/32.768MB(3%)</device_request>
      </requests>
    </device>
    <device id="00000000-00000000-0000FFFF-485740BC"/>
      <requests>
        <device_request target_name="showSystem" status="0">Model                    : Digi EX15
          Serial Number            : EX15-000023
          Hostname                 : EX15
          MAC                      : 00:40:D0:26:79:1C

          Hardware Version         : 50001959-01 A
          Firmware Version         : 25.5
          Bootloader Version       : 1
          Firmware Build Date      : Fri, Jan 12, 2024 12:10:00
          Schema Version           : 461

          Timezone                 : UTC
          Current Time             : Thu, Jan 11, 2024 12:10:00
          CPU                      : 1.1
          Uptime                   : 4 day, 13 hours, 43 minutes, 22 seconds (395002s)
          Temperature              : 37C

          Contact                  : Omar Ahmad
          Disk
          ----
          Load Average             : 0.10, 0.05, 0.00
          RAM Usage                : 85.176MB/250.484MB(34%)
          Disk /etc/config Usage   : 0.068MB/13.416MB(1%)
          Disk /opt Usage          : 47.724MB/5309.752MB(1%)
          Disk /overlay Usage      : MB/MB(%)
          Disk /tmp Usage          : 0.004MB/40.96MB(0%)
          Disk /var Usage          : 0.820MB/32.768MB(3%)</device_request>
      </requests>
    </device>
  </data_service>
</sci_request>