Device Policy Commands (DPC Commands)

Whenever you provision, edit a blueprint, or create a compliance policy, you can apply custom settings to your devices (also known as Device Policy Controller parameters, or ‘DPC params’ for short). 

DPC params can be applied during provisioning to a template, blueprint, or after provisioning via the API. When DPC params are added through a template or blueprint, every device linked to that template or blueprint will receive those parameters. As a best practice to avoid errors, test this code  on a small group of devices before applying the changes to a larger group. 

In this article:

• Applying DPC Params
• Boot on Power
• Disable the Power Button
• Install a File
• Power Off a Device
• Rename Esper Settings
• Apply Fallback Wi-Fi Access Points
• Disable Task Bar for Lenovo Devices (Android 13+)
• Schedule a Power Off or On for Lenovo Devices

Applying DPC Params 

DPC params are essentially device commands.  They tell the device to perform certain behaviors that are not yet part of the templates or blueprints workflow. Once fired to a device, a DPC param needs to be disabled explicitly for changes to take effect. For example, if you push a DPC param to change the Esper Setting’s app name, and then push another param that installs a file, the Esper Setting’s app name will remain the same until the next time you change it. 

After Provisioning

After provisioning, devices can receive DPC parameters from the API. See our API Reference or our API documentation for more information.

API

POST https://{tenant_name}-api.esper.cloud/api/v0/enterprise/{enterprise_id}/command/

Body

{
 "command_type": "DEVICE",
 "command": "UPDATE_DEVICE_CONFIG",
 "command_args": {
   "custom_settings_config": {
     "dpcParams": [
       {
         "key": "allowPowerOff",
         "value": "false"
       }
     ]
   }
 },
"devices": [
  "{device_id}"
],
 "groups": [
   "{group_id}"
 ],
 "device_type": "all"
 }
 

Use the request Body above as a template to update the device’s DPC parameters. DPC parameters can also be separated by a comma in the dpcParams array.

Boot on Power 

Requirements: Most Samsung and Lenovo devices. 

Whenever a device is plugged into a power source, it will turn on. If allowPowerOff (Disable the Power Button) is also enabled, the device won’t be able to turn on except by being plugged into a power source. 

{
           "dpcParams": [
               {
                   "key": "bootDeviceOnChargerDisabled",
                   "value": "false"
               }
           ]
       }

Disable the Power Button

Requirements: Most Samsung and Lenovo devices.

If bootDeviceOnChargerDisabled (Boot on Power) is also enabled, the device won’t be able to turn on except by being plugged into a power source.

{
           "dpcParams": [
               {
                   "key": "allowPowerOff",
                   "value": "false"
               }
           ]
       }

Install a File

Requirements: Files must be uploaded in the tenant’s Content Management before using this DPC param. 

Install a file on a device, either during provisioning (through a template or blueprint) or after provisioning (through a blueprint or API). Separate multiple file paths by commas. 

• Key: fileDownloads 
• Value: {'The name of the file as it appears in the Content Management section of the Esper Console' : 'the file path it will be saved to in the device. You can install multiple files by separating the file and path by commas'} 

The provided file path is a generic example. File paths vary from device to device. Read more about transferring to the correct file path.

{
           "dpcParams": [
               {
                   "key": "fileDownloads",
                   "value": "{"example.json": "/storage/emulated/Download/"}"
               }
           ]
       }

Power Off a Device

Requirements: Most Samsung, Lenovo, and Supervisor enabled devices. 

Power off devices. Intended for powering off a large number of devices intended for storage.

 "dpcParams": [
               {
                   "key": "powerOff",
                   "value": "true"
               }
           ]
       }

Rename Esper Settings

Rename the Esper Settings app. 

{
           "dpcParams": [
               {
                   "key": "renameESettings",
                   "value": "Other Settings"
               }
           ]
       }

       

Before DPC param applied:

After DPC param applied: 

Apply Fallback Wi-Fi Access Points

Apply fallback Wi-Fi access points to the device. The device will connect to these access points in the event it loses access to its primary network. Allow 10 - 15 minutes for the device to re-connect. This parameter also accepts Regex (as shown in the example). In many cases, providers append 5G to network names. Instead of manually entering a Wi-Fi network for each instance (5G and non-5G), use Regex to add all networks containing a matching string. Learn more about Regex or use this tool to check your Regex expressions.

To use this DPC param, edit the following information: 

• hidden: true or false. Indicate if the network is hidden or not. 
• wifiSsid: the name of the access point with optional Regex. 
• wifiPassword: the password for the access points. The access points will need to have the same password if using Regex for the SSIDs.
• wifiPhase2Auth: Access point authentication or NONE.
• wifiSecurityType: Any of the following: WEP, WPA, WPA2, SAE, EAP, or NONE. SAE security types require Android 11+ and Esper Agent version 7.18.0000+.  

{
           "dpcParams": [
               {
                   "key": "wifiRegex",
                   "value": "[{\"hidden\":false,\"wifiSsid\":\"Pixel[^*]*\",\"wifiPhase2Auth\":\"NONE\",\"wifiSecurityType\":\"SAE\",\"wifiPassword\":\"password\"}]"
               }
           ]
       }
       

Disable Task Bar for Lenovo Devices (Android 13+)

Lenovo devices that run Android 13+ come with a taskbar by default. You can disable this taskbar by using a DPC param. 

The taskbar can be set on or off with the following param: 

• value: true or false. true to disable the taskbar, false to enable the taskbar (default). 

{
  "commands": [
    {
      "command": "UPDATE_OEM_CONFIG",
      "oemSettingsConfig": "{\"lenovoConfig\":[{\"key\":\"hideTaskBar\",\"value\":\"true\"}]}",
      "type": "Simple"
    }
  ]
}

You can also use an API to disable the taskbar. Learn more about Esper's API.

URI

POST https://{tenant_name}-api.esper.cloud/api/v0/{enterprise_id}/command/

Body

{
  "command_type": "DEVICE",
  "devices": [
    "{device_id}"
  ],
  "command": "UPDATE_DEVICE_CONFIG",
  "command_args": {
    "custom_settings_config": {
      "commands": [
        {
          "type": "Simple",
          "command": "UPDATE_OEM_CONFIG",
          "oemSettingsConfig": "{\"lenovoConfig\":[{\"key\":\"hideTaskBar\",\"value\":\"true\"}]}"
        }
      ]
    }
  }
}

Schedule a Power Off or On for Lenovo Devices

Schedule a power on or off. 

Requirements: Select supervised Lenovo devices 

Notes 

1. The scheduled power-on command should be fired before the device powers off. For example, if you scheduled the device to power off at 6 PM, it will need to receive the scheduled power on command before that time. 
2. The scheduled power-on and power-off commands will need to be fired at least three minutes before they are scheduled to occur. 
3. In some devices, the power-on command may execute a minute or so before it is scheduled to occur. 
4. Use a tool, such as Postman or cURL, to fire these commands. You can also paste the JSON body into a blueprint.
5. If the device lacks sufficient power, it will not boot up.

Request

POST https://{tenant_name}-api.esper.cloud/api/v0/enterprise/{enterprise_id}/command/

Body 

{
  "command_type": "DEVICE",
  "devices": [
    "{device-id}"
  ],
  "command": "UPDATE_OEM_CONFIG",
  "command_args": {
    "oem_settings_config": {
      "lenovoConfig": [
        {
          "key": "{lenovoBootUp/lenovoShutDown}",
          "value": "argument 1 (Hours in 24 hours time), argument 2 (Minutes in 24 hours time), argument 3 (days of week) (default value 0), argument 4 (switch time) (default value 0)"
        }
      ]
    }
  }
}

Key values 

Key: Use lenovoBootUp to power on a device and lenovoShutDown to power off a device. 

Value: 

A string of four numbers separated by commas. 

• Argument 1: Hours. Accepts 0 - 23, with 0 being 12 AM and 23 being 11 PM. 
• Argument 2: Minutes. Accepts 00, 01, etc. (or 0, 1, etc) - 59. 
• Argument 3: Refer to the Days of the Week table below.
• Argument 4: Should be kept at 0. 

Use the following values to specify the schedule for days of the week (argument 3): 

Examples 

Power on 

Request

POST https://{tenant_name}-api.esper.cloud/api/v0/enterprise/{enterprise_id}/command/

Body 

{
  "command_type": "DEVICE",
  "devices": [
    "device_id"
  ],
  "command": "UPDATE_OEM_CONFIG",
  "command_args": {
    "oem_settings_config": {
      "lenovoConfig": [
        {
          "key": "lenovoBootUp",
          "value": "10,0,0,0"
        }
      ]
    }
  }
}

The following will turn on the device at the next 10 AM. This action will occur every day. 

Power off

Request

POST https://{tenant_name}-api.esper.cloud/api/v0/enterprise/{enterprise_id}/command/

Body

{
  "command_type": "DEVICE",
  "devices": [
    "device_id"
  ],
  "command": "UPDATE_OEM_CONFIG",
  "command_args": {
    "oem_settings_config": {
      "lenovoConfig": [
        {
          "key": "lenovoShutDown",
          "value": "9,58,0,0"
        }
      ]
    }
  }
}

The following will turn off the device at 9:58 AM. This action will occur every day. 

Not working? Contact Esper with your model information. 

Use DPC parameters to customize your device fleet interactions.