This is an old revision of the document!

Digilent Agent Protocol

Command Format

  • The JSON data below is expanded for readability. All JSON should be minified (white space removed) before transmission.
  • Unless otherwise noted all commands are sent using the POST method when using HTTP.
  • All Digilent Agent Protocol commands must be a JSON object or a chunked transfer:
    • JSON Object
      • Must start with a '{' character and ends with a '}' character.
      • May be followed by one or more '\r\n'.
    • Chunked Transfer
      • Composed of one or more chunks.
      • Each chunk must begin with the number of bytes in the chunk in ASCII hexidecimal format followed by one '\r\n', the binary data, and one '\r\n'.
        • The chunk length does not include the '\r\n' between the chunk length and the data.
        • The chunk length does not include the trailing '\r\n' after the binary data.
      • Each chunked transfer is terminated with a zero length chunk.
      • Ex.
6\r\n
chunk1\r\n
8\r\n
somedata\r\n
E\r\n
 in\r\n\r\nchunks.\r\n
0\r\n
\r\n

Enumerate Devices

Enumerate devices on the system and return a device list.

Command

  • command - (String) - The Enumerate Devices command “enumerateDevices”.

Response

  • command - (String) - The Enumerate Devices command “enumerateDevices”.
  • statusCode - (Integer) - A numeric value representing the device status. See Digilent Agent Status Codes
  • devices - (Array<String>) - An array of device names.

Example

Command 

{
   "agent":[
      {
         "command":"enumerateDevices"
      }
   ]
}

Response 

{
   "agent":[
      {
         "command":"enumerateDevices",
         "statusCode":0,
         "devices":[
            "COM1",
            "COM3",
            "COM6"
         ]
      }
   ]
}



Get Agent Info

Get information about the Digilent agent.

Command

  • command - (String) - The Get Info command “getInfo”.

Response

  • command - (String) - The Get Info command “getInfo”.
  • statusCode - (Integer) - A numeric value representing the device status. See Digilent Agent Status Codes
  • version - (Object) - An object representing the Agent version.
    • major - (Integer) - The Agent major version.
    • minor - (Integer) - The Agent minor version.
    • patch - (Integer) - The Agent patch version.

Example

Command 

{  
   "agent":[  
      {  
         "command":"getInfo"
      }
   ]
}

Response 

{
   "agent":[
      {
         "command":"getInfo",
         "statusCode":0,
         "version":{
            "major":1,
            "minor":0,
            "patch":0
         }
      }
   ]
}



Get Active Device

Note: Not yet implemented as of Digilent Agent 1.2.1. Get the active device.

Command

  • command - (String) - The Get Active Device command “getActiveDevice”.

Response

  • command - (String) - The Get Active Device command “getActiveDevice”.
  • statusCode - (Integer) - A numeric value representing the device status. See Digilent Agent Status Codes
  • device - (String) - The active device name.

Example

Command 

{
   "agent":[
      {
         "command":"getActiveDevice"
      }
   ]
}

Response 

{
   "agent":[
      {
         "command":"getActiveDevice",
         "statusCode":0,
         "device":"COM3"
      }
   ]
}



Set Active Device

Set the active device.

Command

  • command - (String) - The Set Active Device command “setActiveDevice”.
  • device - (String) - The name of the device to set as the active device.

Response

  • command - (String) - The Set Active Device command “setActiveDevice”.
  • statusCode - (Integer) - A numeric value representing the device status. See Digilent Agent Status Codes

Example

Command 

{  
   "agent":[  
      {  
         "command":"setActiveDevice",
         "device":"COM3"
      }
   ]
}

Response 

{
  "agent": [
    {
      "command": "setActiveDevice",
      "statusCode": 0
    }
  ]
}



Enter JSON Mode

Put the active device in JSON command mode.

Command

  • command - (String) - The Enter JSON Mode command “enterJsonMode”.

Response

  • command - (String) - The Enter JSON Mode command “enterJsonMode”.
  • statusCode - (Integer) - A numeric value representing the device status. See Digilent Agent Status Codes

Example

Command 

{
   "agent":[
      {
         "command":"enterJsonMode"
      }
   ]
}

Response 

{
   "agent":[
      {
         "command":"enterJsonMode",
         "statusCode":0
      }
   ]
}



Release Active Device

Release the active device and free the hardware resource. Command

  • command - (String) - The Release Active Device command “releaseActiveDevice”.

Response

  • command - (String) - The Release Active Device command “releaseActiveDevice”.
  • statusCode - (Integer) - A numeric value representing the device status. See Digilent Agent Status Codes

Example

Command 

{
   "agent":[
      {
         "command":"releaseActiveDevice"
      }
   ]
}

Response 

{
   "agent":[
      {
         "command":"releaseActiveDevice",
         "statusCode":0
      }
   ]
}



Save To Temp File

Save the provided binary data as the specified file in a temp directory.

Command

  • command - (String) - The Save Temp File command “saveTempFile”.
  • fileName - (String) - The file name used when saving the binary data.

Response

  • command - (String) - The Save Temp File command “saveTempFile”.
  • statusCode - (Integer) - A numeric value representing the device status. See Digilent Agent Status Codes

Example

Command 

{
   "agent":[
      {
         "command":"saveTempFile",
         "fileName":"openscope-mz-firmware.hex"
      }
   ]
}

Response 

{
   "agent":[
      {
         "command":"saveTempFile",
         "statusCode":0
      }
   ]
}



Upload Firmware

Upload new firmware to the active device.

Command

  • command - (String) - The Upload Firmware command “updateFirmware”.
  • enterBootloader - (Boolean) - If true the Agent will attempt to put the device in bootloader mode.
  • firmwarePath - (String) - The path to the firmware file. If only the file name is provided the directory is assumed to be the temp directory.

Response

  • command - (String) - The Upload Firmware command “updateFirmware”.
  • statusCode - (Integer) - A numeric value representing the device status. See Digilent Agent Status Codes

Example

{  
   "agent":[  
      {  
         "command":"updateFirmware",
         "firmwarePath":"openscope-mz-firmware.hex",
         "enterBootloader": true
      }
   ]
}

Response 

{
  "agent": [
    {
      "command": "updateFirmware",
      "statusCode": 0
    }
  ]
}



Update WaveForms Live Browser

Update the offline browser version of WaveForms Live.

Command

  • command - (String) - The Update WaveForms Live Browser command “updateWaveFormsLiveBrowser”.
  • updateZipFileName - (String) - The path to the file name of the zip file containing the update including the .zip extension (file must be in temp directory).

Response

  • command - (String) - The Update WaveForms Live Browser command “updateWaveFormsLiveBrowser”.
  • statusCode - (Integer) - A numeric value representing the device status. See Digilent Agent Status Codes

Example

{  
   "agent":[  
      {  
         "command":"updateWaveFormsLiveBrowser",
         "updateZipFileName":"waveforms-live-0.1.0.zip"
      }
   ]
}

Response 

{
  "agent": [
    {
      "command": "updateWaveFormsLiveBrowser",
      "statusCode": 0
    }
  ]
}



Get Update Firmware Status

Get the status of the firmware update process.

Command

  • command - (String) - The Update Firmware Get Status command “updateFirmwareGetStatus”.

Response

  • command - (String) - The Update Firmware Get Status “updateFirmwareGetStatus”.
  • statusCode - (Integer) - A numeric value representing the device status. See Digilent Agent Status Codes
  • status - (String) - The status of the firmware update process ('idle', 'uploading', 'failed');
  • progress - (Integer) - An integer value 0-100 representing the percent complete.

Response

Example

{  
   "agent":[  
      {  
         "command":"updateFirmwareGetStatus"
      }
   ]
}

Response 

{
  "agent": [
    {
      "command": "updateFirmwareGetStatus",
      "statusCode": 0,
      "status": "uploading",
      "progress" 25
    }
  ]
}