Keck Instrument Keyword Access

Documentation

Installation

Requirements

KeckKeywords has the following requirements:

  • Requests

The Flask-based keyword server has many more dependencies that are described in the appropriate installation page.

Installing KeckKeywords

Using github

To install KeckKeywords, first clone the repository using:

git clone https://github.com/KeckObservatory/KeckKeywords.git

Go to the newly created KeckKeyword directory, and install the package with:

python setup.py install
Testing the installation

The easiest way to test that your KeckKeyword built correctly is to run this from the root of the source tree:

python setup.py test

Basic Usage

Important note

The Flask Keyword server must be running on the host computer to be able to access keywords.

Command line access

The commands are similar to the show/modify commands available on instrument servers, but with a ‘k’ in front. Because this package can run on any computer, it needs to know which instrument host or other host to connect to. This is specified with the option -host. For example, to get the tmp1 keyword from the kt1s server on KCWI, use:

kshow -host kcwiserver kt1s tmp1

A keyword can be modified using:

kmodify -host kcwiserver kbds object "Feige110"

The list of keywords for a server can be obtained with:

kshowkeywords -host kcwiserver kbgs

A day worth of values can be plotted using:

kplot -host kcwiserver kbvs pressure

If both ports 5002 and 5006 are accessible or forwarded, a live stream can be generated with:

kstream -host kcwiserver kt1s tmp1

Permanently specify the default host

If you are mostly using a single instrument, it is convenient to permanently specify the host to connect to. This is done by creating a file called .config/keckkeywords.ini in your home directory. The file should contain the following lines:

[keckkeywords]
host = kcwiserver

A simple way to create such a file is to run the kshow command without specifying a host:

kshow kt1s tmp1

If the configuration file doesn’t exist, KeckKeywords will not show the keyword and report an error, but it will also create a default configuration file that can be edited.

Running the keyword server

The keyword server is Flask mini-service that must run on a host that has access to keywords. For example, in the case of KCWI the options are kcwiserver, vm-kcwi or kcwibuild. To produce keyword plots, the server must be able to access the keyword history. This limits the available options and requires the server to run on selected users. For example, in the case of KCWI, the user kcwirun@kcwiserver is authorized to connect to the history grabber.

Requirements

A number of packages must be available to run the keyword server:

  • Flask
  • Python KTL access (KTL)

If the graphics capabilities are required, to plot keywords, then these packages are required:

  • pandas
  • holoviews
  • bokeh

If these packages are not available, the server will run anyway but no graphics will be generated.

To import KTL, there are a few options:

  • use kpython3

  • add the released library path to PYTHONPATH with:

    setenv PYTHONPATH /kroot/rel/default/lib/python

  • make sure that the RELDIR environment variable is defined. In this case PYTHONPATH will be updated automatically.

Running the server

The server is contained in keyword_server/keyword_server.py

To run it, just type:

(k)python keyword_server.py

The script can be copied to any other directory and run from there.

Connecting to the server

If the server is running on hostname, it is accessible at: http://hostname:5002.

If hostname is not accessible from your location, it is possible to establish a tunnel and then access the localhost connection:

ssh user@hostname -L 5002:localhost:5002  (add: -L 5006:localhost:5006 if live stream is desired)

Localhost becomes the new server, so it’s possible to do:

kshow -host localhost kt1s tmp1

API access and plots

API access to the keywords

If the server is running, you can use a browser to directly access the keywords by visiting the following routes:

Plots

It is possible to plot the history of the last day for a keyword with:

http://hostname:5002/plot/<server>/<keyword>

Note that the plot is dynamic: you can pan and zoom.

If both ports 5002 and 5006 are forwarded to localhost or are open, it is possible to plot a live stream for a keyword:

http://hostmame:5002/teststream/<server>/<keyword>

Note that the stream should be stopped by accessing:

http://hostname:5002/stop

This interrupts the remote monitoring of the keyword

Command line tools

kshow

kmodify

kshowkeywords

kplot

kstream

Module functions

keck_keywords.kaccess.kmodify(host, server, keyword, value)

Modify the value of a keyword.

Reproduces the behaviour of modify -s server keyword

Parameters:
  • host (str) – Instrument host computer
  • server (str) – Server
  • keyword (str) – Keyword
  • value (generic) – New value for the keyword
Returns:

response – Ok status and reason for failure
Return type:

tuple
keck_keywords.kaccess.kplot(host, server, keyword)

Plot a day worth of value for the specified keyword

Parameters:
  • host (str) – Instrument host computer
  • server (str) – Server
  • keyword – Keyword
keck_keywords.kaccess.kshow(host, server, keyword)

Show the value of a keyword

Reproduces the behaviour of show keywords -s server

Parameters:
  • host (str) – Instrument host computer
  • server (str) – Server to be queried
  • keyword (str) – Keyword to be queried
Returns:

value – Value of the keyword
Return type:

json
keck_keywords.kaccess.kshow_keywords(host, server)

Show the list of keywords for a given server.

Reproduces the behaviour of show -s server keyword

Parameters:
  • host (str) – Instrument host computer
  • server (str) – Server
Returns:

response – Array of keywords
Return type:

array
keck_keywords.kaccess.kstop(host)

Stop the monitoring of the currently streamed keyword

Parameters:host (str) – Instrument host
keck_keywords.kaccess.kstream(host, server, keyword)

Streams values and plots a keyword (EXPERIMENTAL, only works on localhost)

Parameters:
  • host (str) – Instrument host
  • server (str) – Server
  • keyword (str) – Keyword

This package provide remote access to the Keck Keyword system without connecting to a specific instrument server.

Indices and tables