ESPER TOOL

Overview

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

Installation

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

Interactive

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.

Read

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

Write

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

Upload

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

Download

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