mardtb 248x110
Edited on 19-May-2023

REST API


1. Overview

As mentioned in chapter "Command File" in section "Input" the mar345dtb may be driven by external commands. Starting with program version 16.0, instead of receiving commands via a command file or via a TCP/IP-socket connection, it is also possible to run a REST server within the program that listens for HTTP requests. This feature is enabled with keyword "COMMAND REST <port>   TOKEN <length>" in the mar345dtb configuration file when the given port number is a positive integer, e.g. 8888. The length of the token string defaults to 16 characters. HTTP requests can be sent via a web browser, via command line tools like curl or by implementing them in an app for mobile devices. There actually is an app for Android and iOS that makes use of this feature. The app "mardtb" is available for free in the Google Play Store & Apple Store.


2. Database

For using the REST API, it is required to authenticate yourself before actually sending commands. The authentication requires a user name and password. Both will reside in a database, that can be created with program mardb (not to be confused with mardtb). The default name and location for the data base file is $MARTABLEDIR/mar.db, but environment variable MARDB can be used to override that pathname. The username is a key in mar.db and the password is the encrypted value for this key. You may use any user and password but it is suggested to create users 'mar' and 'admin' in order to use the program with the official app. In order to create an empty data base, do the following:

      mardb -d $MARTABLEDIR/mar.db -c

You may now add users to that database, e.g. user 'admin' with password 'mardtb' using command:

      mardb -d $MARTABLEDIR/mar.db -c -u admin -p mardtb

In order to verify that the creation has been successful, the command

      mardb -d $MARTABLEDIR/mar.db -u admin mardtb

should return:

      INFO: Password for user 'admin' OK

Otherwise, it will either return:

      ERROR: User 'admin' does not exist
      or
      ERROR: Password for user 'admin' does not match

Typical other command line arguments for program 'mardb' are:



3. API


3.1 Introduction

The API is a full featured interface, that can be used to do simple operations like opening and closing the mardtb shutter and moving motors but also to start a beam optimization or beam search and even trigger and stop a data collection. For safety reasons only authenticated users may trigger actions on the hardware or obtain hardware information. A typical implementation of the program should therefore start with an authentication using a valid username and password (stored as encrypted strings in the database, see chapter 2). A successful authentication will return a webtoken, that will expire after some time. The webtoken is a string of given length, that from now on must be passed in the HTTP request header together with the actual command. The webtoken will be used instead of username and password to decide whether a user is allowed to issue a command or not. An authentication request using curl typically looks like this:

      curl -u admin:mardtb http://localhost:8888/auth

and typically returns something like:

      Token: 8vwLGfss1EhgzeXD

In subsequent requests, the given token must be used to be able to e.g. open or close the mardtb shutter using a command like:

      curl -H "Token: 8vwLGfss1EhgzeXD" http://localhost:8888/cmd/shutter/open

With a valid token, a command then typically returns:

      OK: Command accepted

With a wrong or expired token, the return string would become:

      ERROR: Token invalid: 8vwLGfss1EhgzeXD
or without token
      ERROR: Token missing for /cmd/shutter/open



3.2 HTTP requests

Almost all HTTP requests are using the GET method (default) except for the "json" request, where data are passed to the server as a payload using the POST method. The general form of a HTTP request is:

      [METHOD] [TOKEN] [TYPE] [DATA] URL/CMD

with the following [optional] parameters and their corresponding syntax:

Item Example Description
METHOD -X GET | POST" POST is only required for "json" command.
TOKEN -H "Token: string" Optional webtoken returned by the authentication command URL/auth
Must be provided in the header of the HTTP request for action commands.
TYPE -H "Content-type: application/json" Mandatory when used together with optional DATA, otherwise obsolete.
Must be provided in the header of the HTTP request for certain action commands.
DATA -d "{'Key' : 'value' }" Parameters for programming a data set must be given in the data payload of the HTTP request. Details are described below.
URL http://HOST:PORT Base address of the HTTP request.
CMD cmd/shutter/open Actual hardware command.

The syntax for the CMD part is identical to the command interface, except for the following:

Thus, a command like "COMMAND MOVE PHI 90.0" given on the command line interface is converted to "cmd/move/phi/90.0". This conversion applies to all commands described on the command line interface and will therefore not be repeated here.


3.3 Commands

There are only very few base commands. A base command is the first instruction after the URL part of the HTTP request. If the syntax is invalid, the server returns the following string:
ERROR: command not implemented!

CMD Parameters Returns Description
ping none mardtb @ IP-address If program mar345dtb is not listening on the given URL, a standard error message like "Failed to connect to HOST port 8888: Connection refused" will be returned. The ping command is the only command that does not require a webtoken authentication.
auth -u user:password Token: string The user name and password given with option -u is checked against entries in the database ($MARDB, see above). If a match is found, a webtoken is returned. The default token length is 16 characters. The webtoken is valid for a limited period of time. When expired, the authentication needs to be repeated in order to receive a new token.
show/args TOKEN Depends on args Shows status information of the mardtb. Details see below.
cmd/args TOKEN Depends on args Trigger hardware action. Details see below.
img/args TOKEN Depends on args Show information about image name, numbers, etc. If 'args' is 'jpg' or 'webp' or 'new', the command returns an actual graphics image as full binary file. Details see below.
json TOKEN TYPE DATA Depends on args Start a data collection. Data collection parameters must be provided in the keyworded DATA section and the transfer method must be POST and not GET. Details see below.

Examples:

  1. curl -H "Token: abcdefghi12345678" http://localhost:8888/img/new
  2. curl -X POST -H "Content-Type: application/json" -H "Token: abcdefghi12345678" -d '{"set":1, "nfrm":10, "time":5.0, "dphi":0.1, "dir":/home/mar345/data", "root":"xtal"}'   http://localhost:8888/json



3.3.1 ping

The ping command is the only command that can be used without a webtoken. It can be used to see if the server is alive and listening.

Example: curl http://localhost:8888/ping
Returns: mardtb @ IP-address (e.g. mardtb @ 192.168.0.88)



3.3.2 auth

The user name and password given with option -u is checked against entries in the database ($MARDB, see above). If a match is found, a webtoken is returned. The default token length is 16 characters. The webtoken is valid for a limited period of time. When expired, the authentication needs to be repeated in order to receive a new token. The returned webtoken is required as authentication string for all other commands except 'ping'.

Example: curl -u admin:mardtb http://localhost:8888/auth
Returns: Token: abcdefgh12345678



3.3.3 show

The "show" command is one of the base commands. It requires an additional argument. Depending on the choice, the string returned differs. The command is used to show status information about the hardware. It is mandatory to provide the webtoken obtained from authentication with the show command, i.e. all commands must be issued in the form similar to:

Example: curl -H "Token: abcdefgh12345678" http://localhost:8888/show/type

CMD Returns Description
show/type DTBTYPE: gstring
DETECTOR: dstring
Provides information about the basic hardware configuration of the mardtb goniostat and detector. <gstring> can be one of STANDARD, AUTOPHI, EASYMOUNT, CSC or XPS. <dstring> can be one of MAR345, EIGER4M, EIGER1M, PILATU1M, PILATUS2M, PILATUS300K or PILATUS200K.


E.g.: DTBTYPE: AUTOPHI     DETECTOR: EIGER4M
show/motors AVAILABLE MOTORS: strings Lists all the available motors in the current mardtb configuration.


E.g.: AVAILABLE MOTORS: PHI CHI THETA DISTANCE SLIT_1_HOR SLIT_1_VER SLIT_2_HOR SLIT_2_VER BEAMSTOP XTAL_Z TRANS_HOR TRANS_VER ROT_HOR ROT_VER XTAL_X XTAL_Y
show/<motor> <motor>: <position> Here, <motor> is the actual name of a single motor, e.g. 'phi'. Available motors and their names can be obtained with "show/motors". BTW: here, the <motor>-name is case-insensitive! The value returned is the position of the named motor.


E.g.: PHI 90.000
show/brief string Lists the status of the shutter (OPEN|CLOSED), readings of ionization chambers 1 and 2, the current DISTANCE and PHI positions.


E.g.: CLOSED XRAY 28224 25888 DIST 400.000 PHI 90.000
show/all string Similar to brief, but lists also positions of SLITS, THETA, CHI and BEAMSTOP.


E.g.: SHUTTER CLOSED SLIT1H/V 0.800 0.800 SLIT2H/V 0.600 0.600 XRAY 28232 25899 DIST 400.00 THET 0.0 CHI 0.0 BEAM 17.6 PHI 90.000
show/compact string Similar to above, but leaves out motor names. The order of values is fixed.


E.g.: CLOSED XRAY 28219 25889 MOTORS 0.80 0.80 0.60 0.60 17.6 0.0 0.0 400.000 90.000
show/full strings Lists for all available motors the positions and hardware bits (not documented). Also lists the current digital I/O params and current activity of the hardware.


E.g.:
	TASK 34 IDLE OP 0 MOVING PHI DIO 6d7fc7e7 XRAY 28229 25892 SHUTTER CLOSED
	PHI           90.000  OP 0   4000
	CHI            0.000  OP 0   2107
	THETA          0.000  OP 0   2107
	...
		
show/net string As full, but output more compact on one single long line, e.g. like


E.g.: TASK 34 IDLE OP 0 MOVING PHI DIO 6d7fc7e7 XRAY 28233 25883 SHUTTER CLOSED PHI 90.000 0 4000 0 CHI 0.000 0 2107 0 THETA 0.000 0 2107 0 DISTANCE 400.000 0 2107 0 SLIT_1_HOR 0.800 0 40 0 SLIT_1_VER 0.800 0 40 0 SLIT_2_HOR 0.600 0 40 0 SLIT_2_VER 0.600 0 40 0 BEAMSTOP 17.550 0 2107 0 XTAL_Z 0.000 0 2107 0 TRANS_HOR -1.000 0 2107 0 TRANS_VER 1.000 0 2107 0 ROT_HOR 2.250 0 2107 0 ROT_VER 0.160 0 2107 0 XTAL_X -0.000 0 2107 0 XTAL_Y 0.000 0 2107 0



3.3.4 cmd/args

The "cmd" command is one of the base commands. It requires an additional argument. Depending on the choice, the string returned differs. The command is used to trigger some hardware action. It is mandatory to provide the webtoken obtained from authentication with the "cmd" command, i.e. all commands must be issued in the form similar to:

Example: curl -H "Token: abcdefgh12345678" http://localhost:8888/cmd/shutter/open
Returns: OK: Command accepted

or in case of of an unknown argument:

Example: curl -H "Token: abcdefgh12345678" http://localhost:8888/cmd/unknown
Returns: ERROR: Invalid URL /cmd/unknown

CMD                 Description
cmd/shutter/open Opens mardtb shutter
cmd/shutter/close Closes mardtb shutter
cmd/move/<motor>/<target> Absolute movement of <motor> to target value


Example: cmd/move/phi/120.0
cmd/relmove/<motor>/<delta> Relative movement of <motor> by <delta> units. Units is in degrees for phi, chi and theta or in mm for all others. Use the sign for positive or negative direction!


Example: cmd/relmove/phi/+90.0
cmd/init/<motor>/min|near Initialize <motor> at near end switch. Use either 'min', or 'near', not both.


Example: cmd/init/theta/min
cmd/init/<motor>/max|far Initialize <motor> at far end switch. Use either 'max', or 'far', not both.


Example: cmd/init/distance/far
cmd/init/<motor>/reference Initialize <motor> at reference position. Some motors like PHI and BEAMSTOP only have one reference position and no end switches.


Example: cmd/init/phi/reference
cmd/find/first|second Find beam in first or second ionization chamber. Please note, that the parameters for beam search are the default values taken from the configuration file.


Example: cmd/find/first
cmd/opti/first|second Optimize beam in first or second ionization chamber. Please note, that the parameters for beam search are the default values taken from the configuration file.


Example: cmd/opti/second
cmd/abort Abort all current motor movements, exposures and data collections.


Example: cmd/abort
cmd/stop Gently stop all current motor movements, exposures and data collections.


Example: cmd/abort
cmd/csc/load|unload Loads or unloads a sample from the automatic sample changer or easymount system


Example: cmd/csc/load

The list of available commands is even longer. Essentially, all commands defined in the command interface on the "COMM" keyword can be used. The REST API only requires the keyword "COMM" to be replaced by "cmd", empty spaces between keywords by a single backslash "/" and all characters to be lowercase.



3.3.5 img/args

The "img" command is one of the base commands. It requires an additional argument. Depending on the choice, the string returned differs. The "img" command is used to show current image names and numbers for ongoing data collections. It can also be used to transfer graphical images produced out of the underlying diffraction images. For this to work, it is necessary to select the option "Save thumbnail for each image" in the set used for data collection. When this option is selected, the program will run a script that converts the diffraction image into either a jpg, png or webp graphical image. As of 2019, the webp format might be preferred since webp images are smaller than jpgs of comparable quality. The command to run to do the conversion is given on keyword "THUMBNAIL" in the configuration file (see section Input for details). It is assumed that the graphical images live in subdirectory jpg, png or webp of the data directory where the diffraction images are stored.

It is mandatory to provide the webtoken obtained from authentication with the "img" command, i.e. all commands must be issued in the form similar to:

Example: curl -H "Token: abcdefgh12345678" http://localhost:8888/img/name
Returns: IMAGE: /home/mar/data/xtal/xtal_00001.cbf 1

or in case of of an unknown argument:

Example: curl -H "Token: abcdefgh12345678" http://localhost:8888/cmd/unknown
Returns: ERROR: Invalid URL /cmd/unknown

CMD                 Description
cmd/shutter/open Opens mardtb shutter
cmd/shutter/close Closes mardtb shutter
cmd/move/<motor>/<target> Absolute movement of <motor> to target value



3.3.6 json

The "json" command is one of the base commands. It is used to provide parameters for a data collection and to actually start and run a data collection. Please note, that the command will be only be executed if the program is idle and not busy with some other hardware task.

It is mandatory to use the following parameters with the json command:

In the data section, essentially all data set parameters that are visible on the "Edit" page of the GUI can be speficied. Motor positions may or may not be given. If they are missing, current positions are assumed. The table lists the keywords, their default values and a description.

Keyword Type Default Description
set Integer 30 Equivalent to selecting a data set in the "Use" section of the "Edit" page of the GUI
dir String auto Data directory for series of images. Keyword "auto" means: default location as configured by keyword DIRECTORY in the configuration file (see section Input for details).
root String xtal Root name of images in series
nfrm Integer 1 Number of images to be collected
ffrm Integer 1 Starting image number
time Float 1.0 Exposure time per image in sec
dphi Float 1.0 Phi-range per image
options String Valid option strings are:
  • erase (= Erase detector before starting set)
  • photo (= Save crystal photo for each image)
  • thumbnail (= Save thumbnail for each image)
  • shutterless (= Shutterless data collection)
  • optimize (= Optimize beam before starting set)
  • Multiple options may be given as combined argument, e.g. like: "erase photo". The default for each option is: don't use.
MOTOR Float current Motor position at start of data collection. MOTOR must be replaced by a valid motor name, one of: phi, distance, theta, beamstop, slit1h, slit1v,slit2h, slit2v

Example: curl -H "Token: abcdefgh12345678" -H "Content-Type: application/json" -d '{"set":1, "nfrm":10, "time":5.0, "dphi":0.1, "dir":"/home/mar345/data", "root":"xtal"}' http://localhost:8888/json
Returns: {"message":"Command accepted","request":{"set":1,"nfrm":10,"time":5.0,"dphi":0.10000000000000001,"dir":"/home/mar345/data","root":"xtal"}}

In case, the program is still busy, the following string will be returned: {"message":"Command accepted","request":{"title":"ERROR","message":"Program busy with other task!"}}

In case of an invalid token, the following string will be returned: ERROR: Token invalid: abcdefgh12345678

In case of a missing data section, the following string will be returned: ERROR: command not implemented!