lukipedio/esper-tool

Simple CLI-based tool for accessing ESPER via HTTP

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