A python-based command line utility for accessing a device running the ESPER web service. Works with Python 2 and 3.
The tool allows for the reading and writing of ESPER variables via the command line.
The available subcommands are:
interactive
_read
_write
_upload
_download
_
For a list of interactive shell commands type help
in the interactive shell prompt
The recommended installation method is via pip
To install:
pip install esper-tool
To upgrade:
pip install -U esper-tool
To run it locally from the github source:
python -m esper_tool
Command:
esper-tool interactive [-h] [-u USER] [-p PASS] [-t TIMEOUT] <url> [mid]
Purpose:
Connects to an esper service located at url
and opens an interactive shell
Options:
-h
--help
Print out help for this subcommand
-u USER
or --user USER
User to use for HTTP basic authentication
-p PASS
or --password PASS
Password to use for HTTP basic authentication. If -u
is specified, but -p
is not, the user will be prompted for a password
-t TIMEOUT
or --timeout TIMEOUT
Time to wait for response before timing out. Can be given in fractions of a second. Defaults to 5 seconds.
url
Location of ESPER web service given in standard web URL format. If the port is excluded, it defaults to 80
mid
Module ID or MID to start in. May be given as numerical value, or module key.
Command:
esper-tool read [-h] [-u USER] [-p PASS] [-t TIMEOUT] [-o OFFSET] [-l LEN] <url> <mid> <vid>
Purpose: Read an ESPER variable's data, located at URL. Return value is JSON data type
Options:
-h
--help
Print out help for this subcommand
-u USER
or --user USER
User to use for HTTP basic authentication
-p PASS
or --password PASS
Password to use for HTTP basic authentication. If -u
is specified, but -p
is not, the user will be prompted for a password
-t TIMEOUT
or --timeout TIMEOUT
Time to wait for response before timing out. Can be given in fractions of a second. Defaults to 5 seconds.
-o OFFSET
or --offset OFFSET
Element to start read at within ESPER variable. Defaults to first element (0)
-l LEN
or --len LEN
Number of elements to read
url
Location of ESPER web service given in standard web URL format. If the port is excluded, it defaults to 80
mid
Module ID or MID. May be given as numerical value, or module key.
vid
Variable ID or VID. May be given as numerical value, or variable key.
Examples:
esper-tool read -o 1 -l 32 localhost:8080 0 0
Reads 32
elements of variable 0
starting at offset 1
, at localhost:8080
module 0
, variable 0
Command:
esper-tool write [-h] [-u USER] [-p PASS] [-t TIMEOUT] [-d DATA] [-f FILE] [-o OFFSET] <url> <mid> <vid>
Purpose: Writes JSON data to an ESPER variable. May write the full array or a slice. Data can be specified on the command line or by a file
Options:
-h
--help
Print out help for this subcommand
-u USER
or --user USER
User to use for HTTP basic authentication
-p PASS
or --password PASS
Password to use for HTTP basic authentication. If -u
is specified, but -p
is not, the user will be prompted for a password
-t TIMEOUT
or --timeout TIMEOUT
Time to wait for response before timing out. Can be given in fractions of a second. Defaults to 5 seconds.
-d DATA
or --data DATA
JSON data to write. May take the form of any standard JSON datatype. Datatype must be compatible with ESPER datatype of variable
-f FILE
or --file FILE
File containing JSON data to be written to variable. Same as -d
but data is written in FILE
-o OFFSET
or --offset OFFSET
Element to start read at within ESPER variable. Defaults to first element (0)
url
Location of ESPER web service given in standard web URL format. If the port is excluded, it defaults to 80
mid
Module ID or MID. May be given as numerical value, or module key.
vid
Variable ID or VID. May be given as numerical value, or variable key.
Examples:
esper-tool write -d 255 localhost 1 2
Writes the value 255
to module 1
, variable 2
at localhost
esper-tool write -d [0,2] -o 1 http://localhost:8080 mymodule myvar
Writes the array [0,2]
to the variable myvar
starting at the second element. The variable is located in the module mymodule
on host localhost:8080
Command:
esper-tool upload [-h] [-u USER] [-p PASS] [-t TIMEOUT] -f FILE [-r RETRY] <url> <mid> <vid>
Purpose: Upload a binary file to an ESPER variable. Particularly useful for updates to large variable arrays, binary data must match binary format of ESPER variable, or data loaded will be erroneous.
Options:
-h
--help
Print out help for this subcommand
-u USER
or --user USER
User to use for HTTP basic authentication
-p PASS
or --password PASS
Password to use for HTTP basic authentication. If -u
is specified, but -p
is not, the user will be prompted for a password
-t TIMEOUT
or --timeout TIMEOUT
Time to wait for response before timing out. Can be given in fractions of a second. Defaults to 5 seconds.
-f FILE
or --file FILE
File containing binary data to be written to variable
-r RETRY
or --retry RETRY
Number of times to retry if timeout occurs, can be useful if ESPER service connected to is slow to write to disk/flash
url
Location of ESPER web service given in standard web URL format. If the port is excluded, it defaults to 80
mid
Module ID or MID. May be given as numerical value, or module key.
vid
Variable ID or VID. May be given as numerical value, or variable key.
Examples:
esper-tool upload -v --file ~/waveform.bin -r 3 http://localhost:80/ 5 waveform_replay
Uploads the contents of file waveform.bin
to localhost
module 5
, variable waveform_replay
. It will retry 3
times in the event of failure
Command:
esper-tool download [-h] [-u USER] [-p PASS] [-t TIMEOUT] -f FILE [-r RETRY] <url> <mid> <vid>
Purpose: Downloads variable data to a binary file.
Options:
-h
--help
Print out help for this subcommand
-u USER
or --user USER
User to use for HTTP basic authentication
-p PASS
or --password PASS
Password to use for HTTP basic authentication. If -u
is specified, but -p
is not, the user will be prompted for a password
-t TIMEOUT
or --timeout TIMEOUT
Time to wait for response before timing out. Can be given in fractions of a second. Defaults to 5 seconds.
-f FILE
or --file FILE
Location of file to write variable data to
-r RETRY
or --retry RETRY
Number of times to retry if timeout occurs, can be useful if ESPER service connected to is slow to write to disk/flash
url
Location of ESPER web service given in standard web URL format. If the port is excluded, it defaults to 80
mid
Module ID or MID. May be given as numerical value, or module key.
vid
Variable ID or VID. May be given as numerical value, or variable key.
Examples:
esper-tool download -v --file ~/waveform.bin -r 3 http://localhost:80/ 5 waveform_replay
Download the contents of file localhost
module 5
, variable waveform_replay
to waveform.bin
. It will retry 3
times in the event of failure