====== DeviceServer ======
The device server is an easy-to-use user interface for accessing ZTEX Boards. It's a part of the ZTEX SDK. Main features are:
* Two access methods: HTTP (e.g. using a web browser) and a simple socket protocol
* Supports uploading of Firmware and Bitstream into volatile and non-volatile memory
* Supports simple I/O: read and write to Endpoints
===== Usage =====
The Deviceserver can either be started using the bash script ''DeviceServer'' in the directory ''java/DeviceServer'' or by calling
java -cp []DeviceServer.jar DeviceServer
where '''' stands for the directory where DeviceServer.jar is installed (e.g. the java directory of the SDK package).
If the bash script is used it has to be installed in the same directory as DeviceServer.jar.
==== Options ====
The following options are supported
^ Option ^ Description ^
| -nc | Do not scan for Cypress EZ-USB devices without ZTEX firmware |
| -id | Scan for devices with given Vendor ID and Product ID |
| -sp | Port number for the socket interface (default: 9081; <0: disabled) |
| -hp | Port number for the HTTP interface (default: 9080; <0: disabled) |
| -sa [-][/][,...] | Allow or permit HTTP connection from this address(es), see below |
| -ha [-][/][,...] | Allow or permit HTTP connection from this address(es), see below |
| -sb | Bind socket server to this address (default: listen on all interfaces) |
| -hb | Bind HTTP server to this address (default: listen on all interfaces) |
| -v | Be verbose |
| -q | Be quit |
| -l | Log file |
| -l2 | Verbose log file |
| -h | Print help |
By default default DeviceServer listens on port 9080 for HTTP connections and on port 9081 for socket connections and only accepts connections from localhost (127.0.0.1). The ports can be changed using ''-sp'' and ''-hp''.
Client addresses can be specified using ''-sa'' and ''-sb''. Addresses with preceded "-" are permitted all addresses without "-" are allowed. the value it the number of highest significant bits hat have to math, i.e. a mask value of 24 is denotes the netmask 255.255.255.0. Multiple addresses can be separated by ",".
==== Examples ====
DeviceServer -ha localhost/24,192.168.1.0/24,-192.168.1.10 -sp -1 -v -l2 logfile
Starts the DeviceServer verbosely and only listens for HTTP connections at default port 9080. Connections from 127.0.0.0 to 127.0.0.255, 192.168.1.0 to 192.168.1.9 and 192.168.1.11 to 192.168.1.255 are accepted. A verbose log is written to ''logfile''.
===== Socket interface =====
The socket protocol is very simple: the client sends a command delimited by a newline "\n", optionally payload data and the DeviceServer returns a response.
This simple protocol allows to access the socket interface using command line tools like netcat. For example, the call ''help'' returns a list of supported. Options:
$ echo help | nc localhost 9081
Supported commands:
scan Scan buses
info Print device capabilities
upload Upload firmware
config Configure FPGA
read Read data from given endpoint
write Write data to given endpoint
errors Returns errors
help Help
quit Quit Device Server
See help |all for detailed info
A detailed description of one/all comment can be btained using ''help |all'':
$ echo help all | nc localhost 9081
[]scan [-bin]
(Re)scan buses and returns the device list. If and -bin are specified
errors are stored and can be read out using "errors ". If -bin is not
specified errors are returned directly.
-bin print it in (computer friendly) binary format
info
Returns device capabilities.
upload [-v] [-nv] [-e] [-f]
Upload firmware to USB controller. Returns errors, if any.
-v upload to volatile memory (default if neither -nv nor -env is given)
-nv upload to non-volatile memory
-e erase / disable firmware in non-volatile memory
-f force upload of incompatible firmware
config [-v] [-nv] [-e] [-f]
Configure FPGA. Returns errors, if any.
-v upload to volatile memory (default if -nv is not given)
-nv upload to non-volatile memory
-e erase / disable bitstream in non-volatile memory
-f force upload if already configured
[:]read []
Read data from endpoint and returns them. If if not specified
data is read until end. If is specified errors are stored and can be
read out using "errors "
write
write data to endpoint. Returns errors, if any.
errors
Returns errors stored under .
quit
Quit Device Server
Usually the response of the command consists in error or other messages, if any. If the response contains payload data (e.g. the command ''read'') these information can be obtained using a . For example,
$ echo abc:read 1 10 2 | nc localhost 9081 > outfile
$ echo errors abc | nc localhost 9081
first reads data from endpoint 2 and writes it to ''outfile'' and then (2nd command) prints messages (if any) to stdout.
The usage of the Socket interface shall be demonstrated step by step with then ucecho example on a FPGA Board:
**Step 1:** Find out the device id's:
~$ echo scan | nc localhost 9081
# :
7:17 001 (unconfigured) "" "" ""
**Step 2:** Load the firmware into the RAM of the EZ-USB:
$ (echo upload 7 17 -v; cat ucecho.ihx) | nc localhost 9081
Firmware uploaded to volatile memory: 96ms
Device re-numerated: 7:17 -> 7:18
**Step 3:** Configure the FPGA:
$ (echo config 7 18 -v; cat fpga/ucecho.bit) | nc localhost 9081
Bitstream uploaded to volatile memory: 57ms
**Step 4:** Get device information (optional):
$ echo info 7 18 | nc localhost 9081
Bus name: 001
Device Number: 18
USB ID's: 221a:100
Product ID's: 10.13.0.0
Firmware version: 0
Serial Number String: 04A32DCB9A
Manufacturer String: ZTEX
Product String: ucecho example for UFM 1.15
Capability: EEPROM read/write
Capability: FPGA configuration
Capability: High speed FPGA configuration
Capability: MAC EEPROM read/write
FPGA State: FPGA configured
Endpoint: 1 read
Endpoint: 1 write
Endpoint: 2 read
Endpoint: 4 write
===== HTTP interface (using a web browser) =====
The HTTP interface is even easier to use then the socket interface. This shall be demeonstrated with the same example as above.
Note that at least some Windows versions does not know their name: the numeric address '127.0.0.1' has to be used instead of 'locahost'.
**Step 1:** Point you internet browser to localhost:9080 (provided that you started the DeviceServer with the standard settings) and click on the device link:\\
{{:en:software:deviceserver-ss01.png|Step 1}}
**Step 2:** Upload the firmware: Select the correct firmware, check the "Upload to volatile memory" and click the submit button.\\
{{:en:software:deviceserver-ss02.png|Step 2}}
**Step 3:** Configure the FPGA: Select the Bitstream, check the "Upload to volatile memory" and click the submit button.\\
{{:en:software:deviceserver-ss03.png|Step 3}}
{{indexmenu_n>7000}}