APIs for Esper Foundation Updates

If you have devices running Esper Foundation, you’ll work with Esper to update those devices. Esper releases two types of updates for Android devices running Foundation: 

• Esper Agent Releases 
• Foundation Releases

This article provides steps to create API-based Foundation firmware updates (also known as FOTA).

Requirements: 

• An Esper API Key 
• Your Enterprise ID as it appears in the API Management section of the console
• Access to a platform that sends API requests, such as Postman or cURL
• Ensure Firewall rules are applied

In this article: 

• Obtaining Your Metadata
• Creating an API Request
  • Setting Up the Postman Request
  • Setting Up the cURL Request
• Viewing the Updated Version

Obtaining Your Metadata 

Once an update is ready, your Esper contact will reach out to you with a folder containing the iso file and your metadata. They may also provide metadata that can be used in an API request. Save this metadata in a location where it can be accessed later.

Sample Metadata

"{\n \"url\": \"https://shoonya-os-builds.s3-us-west-2.amazonaws.com/builds/DeltaOTAGenerator/44/artifacts/sample-build-device-11111a-delta-debug.zip\",
\n \"md5hash\":\"11a111a111a111aa111\"\n}"

Creating an API Request

Once you’ve provisioned the device through Esper, obtain the device’s ID or the group ID. 

Then, construct your API request. It may be helpful to review our Getting Started with the APIs guide to familiarize yourself with our APIs, Postman, and cURL.

Setting Up the Postman Request

Once in your Postman account, create a new request.

Authorization 

In the Authorization tab, select Bearer Token as the Type. Then paste the API key in the Token field.

Request

Body

In the Body tab, select raw and JSON.

Then create the JSON body based on your OTA requirements. Reach out to your Esper contact to obtain your metadata.

Single Device

{
   "command_type": "DEVICE",
   "command": "UPDATE_DEVICE_CONFIG",
   "command_args": {
       "custom_settings_config": {
           "scripts": [
               {
                   "action": "LAUNCH",
                   "launchType": "SERVICE",
                   "actionParams": {
                       "componentName": "io.esper.otamanager/io.esper.otamanager.OTAUpdateService",
                       "intentAction": "io.esper.otamanager.INSTALL_OTA",
                       "serviceType": "BACKGROUND",
                       "extras": {
                           "otaType": "TRADITIONAL",
                           "metaData": "{{metadata}}"
                       }
                   }
               }
           ]
       }
   },
   "devices": [
       "{{device-id}}"
   ],
   "device_type": "all"
}

Multiple Devices

{
   "command_type": "DEVICE",
   "command": "UPDATE_DEVICE_CONFIG",
   "command_args": {
       "custom_settings_config": {
           "scripts": [
               {
                   "action": "LAUNCH",
                   "launchType": "SERVICE",
                   "actionParams": {
                       "componentName": "io.esper.otamanager/io.esper.otamanager.OTAUpdateService",
                       "intentAction": "io.esper.otamanager.INSTALL_OTA",
                       "serviceType": "BACKGROUND",
                       "extras": {
                           "otaType": "TRADITIONAL",
                           "metaData": "{{metadata}}"
                       }
                   }
               }
           ]
       }
   },
   "devices": [
       "{{device-id}}", "{{device-id}}", "{{device-id}}"
   ],
   "device_type": "all"
}

Group

Be sure to change the command_type to GROUP.

{
   "command_type": "GROUP",
   "command": "UPDATE_DEVICE_CONFIG",
   "command_args": {
       "custom_settings_config": {
           "scripts": [
               {
                   "action": "LAUNCH",
                   "launchType": "SERVICE",
                   "actionParams": {
                       "componentName": "io.esper.otamanager/io.esper.otamanager.OTAUpdateService",
                       "intentAction": "io.esper.otamanager.INSTALL_OTA",
                       "serviceType": "BACKGROUND",
                       "extras": {
                           "otaType": "TRADITIONAL",
                           "metaData": "{{metadata}}"
                       }
                   }
               }
           ]
       }
   },
   "groups": [
       "{{group-id}}"
   ],
   "device_type": "all"
}

Setting Up the cURL Request

cURL

Construct a cURL request using the following template.

curl -XPOST -H 'Authorization: Bearer {{API KEY}}' -H "Content-type: application/json" -d '{
   "command_type": "DEVICE",
   "command": "UPDATE_DEVICE_CONFIG",
   "command_args": {
       "custom_settings_config": {
           "scripts": [
               {
                   "action": "LAUNCH",
                   "launchType": "SERVICE",
                   "actionParams": {
                       "componentName": "io.esper.otamanager/io.esper.otamanager.OTAUpdateService",
                       "intentAction": "io.esper.otamanager.INSTALL_OTA",
                       "serviceType": "BACKGROUND",
                       "extras": {
                           "otaType": "TRADITIONAL",
                           "metaData": "{{metadata}}"
                       }
                   }
               }
           ]
       }
   },
   "devices": [
       "{{device-id}}"
   ],
   "device_type": "all"
}' 'https://{{tenant-name}}-api.esper.cloud/api/v0/enterprise/{{enterprise-id}}/command/'

You may add multiple devices or groups as well. See the Postman example for more information.

Viewing the Updated Version

Once the API is sent, the devices should update. Locate the device in Devices & Groups and check its Device Details to see the latest Foundation version installed.

You can also access this information from the device’s Esper Settings app.

Update your devices running Esper Foundation to get the latest features, security patches, and more.