====== 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.
<code>
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
</code>

===== 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 [[software:digilent-agent:protocol-status-codes]]
   * **devices** - (Array<String>) - An array of device names.

===Example===
<WRAP group>
<WRAP half column>
**Command**
<code>
{
   "agent":[
      {
         "command":"enumerateDevices"
      }
   ]
}
</code>
</WRAP>
<WRAP half column>**Response**</WRAP>
<code>
{
   "agent":[
      {
         "command":"enumerateDevices",
         "statusCode":0,
         "devices":[
            "COM1",
            "COM3",
            "COM6"
         ]
      }
   ]
}
</code>
</WRAP>
\\ \\ 

===== 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 [[software:digilent-agent:protocol-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===
<WRAP group>
<WRAP half column>
**Command**
<code>
{  
   "agent":[  
      {  
         "command":"getInfo"
      }
   ]
}
</code>
</WRAP>
<WRAP half column>**Response**</WRAP>
<code>
{
   "agent":[
      {
         "command":"getInfo",
         "statusCode":0,
         "version":{
            "major":1,
            "minor":0,
            "patch":0
         }
      }
   ]
}
</code>
</WRAP>
\\ \\ 

===== 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 [[software:digilent-agent:protocol-status-codes]]
   * **device** - (String) - The active device name.

===Example===
<WRAP group>
<WRAP half column>
**Command**
<code>
{
   "agent":[
      {
         "command":"getActiveDevice"
      }
   ]
}
</code>
</WRAP>
<WRAP half column>**Response**</WRAP>
<code>
{
   "agent":[
      {
         "command":"getActiveDevice",
         "statusCode":0,
         "device":"COM3"
      }
   ]
}
</code>
</WRAP>
\\ \\ 

===== 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 [[software:digilent-agent:protocol-status-codes]]

===Example===
<WRAP group>
<WRAP half column>
**Command**
<code>
{  
   "agent":[  
      {  
         "command":"setActiveDevice",
         "device":"COM3"
      }
   ]
}
</code>
</WRAP>
<WRAP half column>**Response**</WRAP>
<code>
{
  "agent": [
    {
      "command": "setActiveDevice",
      "statusCode": 0
    }
  ]
}
</code>
</WRAP>
\\ \\ 

===== 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 [[software:digilent-agent:protocol-status-codes]]

===Example===
<WRAP group>
<WRAP half column>
**Command**
<code>
{
   "agent":[
      {
         "command":"enterJsonMode"
      }
   ]
}
</code>
</WRAP>
<WRAP half column>**Response**</WRAP>
<code>
{
   "agent":[
      {
         "command":"enterJsonMode",
         "statusCode":0
      }
   ]
}
</code>
</WRAP>
\\ \\ 

===== 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 [[software:digilent-agent:protocol-status-codes]]

===Example===
<WRAP group>
<WRAP half column>
**Command**
<code>
{
   "agent":[
      {
         "command":"releaseActiveDevice"
      }
   ]
}
</code>
</WRAP>
<WRAP half column>**Response**</WRAP>
<code>
{
   "agent":[
      {
         "command":"releaseActiveDevice",
         "statusCode":0
      }
   ]
}
</code>
</WRAP>
\\ \\ 


===== 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 [[software:digilent-agent:protocol-status-codes]]

===Example===
<WRAP group>
<WRAP half column>
**Command**
<code>
{
   "agent":[
      {
         "command":"saveTempFile",
         "fileName":"openscope-mz-firmware.hex"
      }
   ]
}
</code>
</WRAP>
<WRAP half column>**Response**</WRAP>
<code>
{
   "agent":[
      {
         "command":"saveTempFile",
         "statusCode":0
      }
   ]
}
</code>
</WRAP>
\\ \\ 


===== 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 [[software:digilent-agent:protocol-status-codes]]

===Example===
<WRAP group>
<WRAP half column>

<code>
{  
   "agent":[  
      {  
         "command":"updateFirmware",
         "firmwarePath":"openscope-mz-firmware.hex",
         "enterBootloader": true
      }
   ]
}
</code>
</WRAP>
<WRAP half column>**Response**</WRAP>
<code>
{
  "agent": [
    {
      "command": "updateFirmware",
      "statusCode": 0
    }
  ]
}
</code>
</WRAP>
\\ \\ 


===== 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 [[software:digilent-agent:protocol-status-codes]]


===Example===
<WRAP group>
<WRAP half column>

<code>
{  
   "agent":[  
      {  
         "command":"updateWaveFormsLiveBrowser",
         "updateZipFileName":"waveforms-live-0.1.0.zip"
      }
   ]
}
</code>
</WRAP>
<WRAP half column>**Response**</WRAP>
<code>
{
  "agent": [
    {
      "command": "updateWaveFormsLiveBrowser",
      "statusCode": 0
    }
  ]
}
</code>
</WRAP>
\\ \\ 


===== 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 [[software:digilent-agent:protocol-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===
<WRAP group>
<WRAP half column>

<code>
{  
   "agent":[  
      {  
         "command":"updateFirmwareGetStatus"
      }
   ]
}
</code>
</WRAP>
<WRAP half column>**Response**</WRAP>
<code>
{
  "agent": [
    {
      "command": "updateFirmwareGetStatus",
      "statusCode": 0,
      "status": "uploading",
      "progress" 25
    }
  ]
}
</code>
</WRAP>
\\ \\