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 } ] }