moos-ivp.org IvP ManPages Pavlab MIT 2.680 LAMSS Goby NOWISTHETIMEFORALLGOODMENTOCO NOWISTHETIMEFORALN Edit

uQueryDB: Querying the MOOSDB from the Command Line

Maintained by: mikerb@mit.edu Get PDF

src: project-pavlab/appdocs/app_uquerydb

1  Overview
     1.1 A Simple Example
2  Using the Output Generated by uQueryDB
3  Using uQueryDB within a Shell Script
4  Command-line Arguments of uQueryDB
     4.1 Logic Pass Conditions on the Command Line
     4.2 Logic Fail Conditions on the Command Line
     4.3 Waiting for Success
     4.4 Waiting for a Logic Variable to be Published
5  Check Variables
     5.1 Specifying Check Variables on the Command Line
     5.2 Specifying Check Variables in the Mission File
     5.3 Check Variable Output and Format
6  Configuration Parameters for uQueryDB
7  Publications and Subscriptions for uQueryDB

1 Overview

The uQueryDB utility is a command-line tool for querying a MOOSDB with a logic condition provided on the command line. It finds the MOOSDB via a mission file provided on the command line, or the IP address and port number given on the command line. It will connect to the DB, register for the variables involved in the logic condition and determine if the condition holds. It will then exit with 0 if it holds or 1 otherwise. It will return its value as soon as the app has received mail for all variables involved in the logic condition. Otherwise it will wait for 10 seconds. This can be changed with the --wait=N parameter. If a variable in the logic condition is unknown to the MOOSDB, then the whole condition will fail after the wait period.

The motivation for uQueryDB is to facilitate automated testing of missions launched from within a shell script, by checking for termination criteria and automatically halting the test mission.

1.1 A Simple Example [top]

As a simple example, try launching the alpha mission in the s1_alpha example mission folder. From the command line, launch with:

  $ cd moos-ivp/ivp/missions/s1_alpha
  $ ./launch.sh

Once this simulation has started, deploy the vehicle with the button on the viewer. At this point we can try out the uQueryDB utility. In another terminal window try typing:

  $ cd moos-ivp/ivp/missions/s1_alpha
  $ uQueryDB alpha.moos --condition="DB_UPTIME<130"

This will check the value of the MOOS variable DB_UPTIME which is the number of seconds that the MOOSDB has been up. The above check will simply report success until after 130 seconds has passed. The report comes in human-readable form in the terminal output:

 $ uQueryDB alpha.moos --condition="DB_UPTIME<130"
 Mission File was provided: alpha.moos
 Condition: [DB_UPTIME<130]

 -------------- moos connect ----------------------
   contacting a MOOS server localhost:9000 -  try 00001 
   Handshaking as uQueryDB               [ok]
   DB reports async support is           [on]
   DB is running on                      leonardo
   Timing skew estimation is             [off] (not needed)
 --------------------------------------------------

 uQueryDB is Running:
  |-Baseline AppTick   @ 5.0 Hz
  |--Comms is Full Duplex and Asynchronous
  -Iterate Mode 0 :
    |-Regular iterate and message delivery at 5 Hz

 ==============================================================
 uQueryDB alpha                                          0/0(1)
 ==============================================================
 Config:
   m_sServerHost: localhost
   m_lServErport: 9005
   Max Time:      n/a
 State:           
   Start Time:    1640112857.63442
   Curr Time:     1640112857.83831
   Elapsed Time:  n/a
   Exit Value:    1
 Config (pass/fail):
   pass_conditions: 1
   fail_conditions: 0
 Result: fail: DB_UPTIME<13


 InfoBuffer: (pass condition vars)            
 ============================================ 
 DB_UPTIME  107.35
     WFLAG  waypoints=3

 InfoBuffer: (fail condition vars)            
 ============================================ 
 DB_UPTIME  107.35
     WFLAG  waypoints=3

 InfoBuffer: (check vars)                     
 ============================================ 
 WFLAG  waypoints=3

Note in the last two lines the current value of the MOOS variable DB_UPTIME is reported and the result of the logic condition is declared along with the value returned by the command, exit(1).

2 Using the Output Generated by uQueryDB

In addition to the human-readable output above, the uQueryDB utility also generates a return value available on the command line. In line with common GNU/Linux tradition, this utility returns 0 when it is successful and a non-zero value when not successful. In our case uQueryDB returns 0 when the logic condition succeeds, and 1 when it does not. As a simple exercise, launch the alpha mission again as in the previous example. After it has again launched, enter the following in another terminal window:

 $ uQueryDB alpha.moos --condition="DB_UPTIME<130" >[=&=] /dev/null

By redirecting to /dev/null the normal terminal output is suppressed but the result is generated nevertheless, and can be seen by examining the special shell variable $? with:

 $ echo $?
 0

The 0 indicates success, i.e., the logic condition succeeded. This approach is especially useful when used inside a shell script, described next.

3 Using uQueryDB within a Shell Script

The motivation for uQueryDB is to support the automation of simulation experiments by launching a mission from within a script and exiting the script (and the mission) when a specified condition is met within the simulation environment. By example we return to the alpha mission. The example script below launches the alpha mission and halts the alpha mission after 20 seconds.

 #!/bin/bash -e   

 # Part 1: Launch the mission
 pAntler alpha.moos >& /dev/null &

 # Part 2: After a short wait deploy the vehicle
 sleep 5
 uPokeDB alpha.moos MOOS_MANUAL_OVERRIDE=false DEPLOY=true	
 sleep 5

 # Part 3: Continually check for the termination criteria
 while true; do
     uQueryDB alpha.moos --condition="DB_UPTIME>30"
     if [ "$?" = 0 ]; then 
         echo -n "Quitting..."
         killall pAntler
         sleep 2
         echo "Done."
         exit 0
     fi
     sleep 5
     echo "continuing..."
 done

Of course the above example simply uses time as a termination criteria, which could be accomplished by just changing the sleep command and terminating. But uQueryDB allows the termination to be based on mission related criteria. For example, in the alpha mission, termination can be set to happen after the vehicle traverses its set of waypoints twice, by setting the logic condition with --condition="CYCLE_INDEX>2".

4 Command-line Arguments of uQueryDB

Configuration parameters can be passed to uQueryDB from the command line or from the mission (.moos) configuration file. Launching it without logic conditions will simply result in uQueryDB returning immediately with a value of 0 (success).

The specification of a MOOS file on the command line is optional. The primary two pieces of information uQueryDB needs from this file are (a) the server_host IP address, and (b) the server_port number of the running MOOSDB to poke. These values can instead be provided on the command line:

  $ uQueryDB --condition="NUM>30" --host=18.38.2.158  --port=9000

If the host or the port are not provided on the command line, and a MOOS file is also not provided, the user will be prompted for the two values. Since the most common scenario by convention has the MOOSDB running on the local machine ("localhost") with port 9000, these are the default values and the user can simply hit the return key.

 $ uQueryDB --condition="DEPLOY=true"  // User launches with no server host/port info
 $ Enter Server: [localhost]           // User accepts default by hitting Return key
 $    The server is set to "localhost" // Server host confirmed to be set to "localhost"
 $ Enter Port: [9000] 9123             // User overrides the default 9000 port with 9123
 $    The port is set to "9123"        // Server port confirmed to be set to "9123"

4.1 Logic Pass Conditions on the Command Line [top]

On the command line uQueryDB takes any number of logic pass conditions. If all pass conditions are satisfied, then uQueryDB will return with 0, indicating success. A pass condition may be specified with either the --condition or --pass_condition parameter. They are interchangeable. A conjuction of pass conditions can be applied simply by specifying mulitiple conditions:

  $ uQueryDB alpha.moos --condition="DEPLOY=true" --condition="STATION=false"

A disjunction of conditions can be specified as described in http://oceanai.mit.edu/ivpman/logic, within a single condition. For example:

  $ uQueryDB alpha.moos --condition="((DB_TIME>36000) or (MISSION=complete))"

Since white-space characters on a command line delineate arguments, the use of double-quotes must be used if using white space as in the examples above.

4.2 Logic Fail Conditions on the Command Line [top]

Similar to the pass conditions described above, a fail condition may also be specified. Depending on what you're trying to do, it may be just easier to express things with a fail condition(s) instead of pass conditions. If any fail condition is satisfied, then uQueryDB will return with a value of 1, indicating failure. For example:

  $ uQueryDB alpha.moos --fail_condition="DEPLOY=false"   \
                        --fail_condition="STATION=true"

Pass and fail conditions may both be used simultaneously. If all pass conditions are satisfied, and no fail conditions are satisfied, then uQueryDB will return with a value of 0, success. Otherwise it will return with a value of 1, failure.

4.3 Waiting for Success [top]

A note of caution: by default, uQueryDB will immediately connect to the MOOSDB, evaluate conditions and return with either a 0 or 1. In some cases the user may want to allow uQueryDB a period of time before exiting with failure. The --wait=N command line parameter may be used, with the default being N=0. If uQueryDB detects success, it will return immediately. Otherwise, if the pass conditions are not initially all satisfied, or if one or more fail conditions are satisfied initially, uQueryDB will continue to evaluate for N seconds before returning with failing (1) value.

4.4 Waiting for a Logic Variable to be Published [top]

Normally a logic condition of the form (FOO<20) would evaluate to false if the variable FOO has never been written to. This may seem counter-intuitive in conditions like (DEPLOY!=true) since clearly DEPLOY does not have the value of true if DEPLOY has never been written to. But nevertheless the latter condition would also evaluate to false.

5 Check Variables

uQueryDB can be optionally configured to report the values of one or more check variables at the time that uQueryDB exits, regardless of the return value. Check variables are named on either the command line or in the mission configuration. A variety of formats are supported. The motivation for check variables is to enable uQueryDB to be further useful in scripts that may be involved in automated mission testing.

5.1 Specifying Check Variables on the Command Line [top]

One or more check variables may be specified on the command line. If variables are also specified in the mission file, the union of all variables will be used.

   $ uQueryDB --check_var=RESULT --check_var=SCORE

5.2 Specifying Check Variables in the Mission File [top]

One or more check variables may be specified in the mission file. If variables are also specified on the command line, the union of all variables will be used.

   check_var = RESULT 
   check_var = SCORE

5.3 Check Variable Output and Format [top]

The output of check variables is written to a file .checkvars. This file will be overwritten upon each run of uQueryDB. By default the output will be equals-separated-value. For example:

   RESULT = pass 
   SCORE = 98

Another format option is comma-separated-value. For example:

   RESULT,pass 
   SCORE,98

Another format option is whitespace-separated-value. For example:

   RESULT pass 
   SCORE 98

Another format option is value-only. For example:

   pass 
   98

The format option can be specified on the command line with --esv for equals-separated-value, or --csv for comma-separated-value, or --wsv for whitespace-separated-value, --vo for value-only.

The format option can also specified in mission file with:

   check_var_format = esv          // Default setting
   check_var_format = wsv
   check_var_format = csv
   check_var_format = vo

If conflicting formats are specified between the command line and the mission file, the mission file setting will take precedence.

6 Configuration Parameters for uQueryDB

In addition to accepting query parameters from the command line, uQueryDB may accept configuration parameters from a configuration block with a .moos file, similar to most MOOS applications. This feature was added after Release 19.8.x.

The following parameters are defined for uQueryDB. A more detailed description is provided in other parts of this section. Parameters having default values indicate so in parentheses below.

Listing 6.1 - Configuration Parameters for uQueryDB.

check_var:	When the query results in a return value of zero, an optional variable report can be written to a file. Section 5.
check_var_format:	Sets the output format for check variables written to the .checkvars file. Options are esv, or csv, or wsv, or vo. The default is esv. 5.3.
condition:	Same as pass_condition. When all pass conditions are met, the query will result in a return value of zero. Section 4.1.
fail_condition:	When any fail condition is unsatisfied, the query will result ina return value of zero. Section 4.2.
pass_condition:	When all pass conditions are met, the query will result in a return value of zero. Section 4.1.
wait:	If uQueryDB initially fails, rather than returning with a value of 1 immediatly, it will wait N seconds to receive new mail updates that may perhaps result in successfully satisfying conditions. Default is 0 seconds. Section 4.3.

7 Publications and Subscriptions for uQueryDB

Variables published by the uQueryDB application [top]

The uQueryDB application publishes no variables. In fact there will likely be no trace at all in a mission alog file, with the possible exception being the MOOS variable DB_CLIENTS. If uQueryDB does not immediately find the values for all variables involved in the logic expression, it will stay connected for as long as the --wait parameter specifies. The default is 0 seconds. In this case uQueryDB will be logged in the list of clients in DB_CLIENTS during this period.

Variables subscribed for by the uPokeDB application [top]

All MOOS variables involved in the logic conditions provided to uQueryDB will be subscribed for automatically.

Page built from LaTeX source using texwiki, developed at MIT. Errata to issues@moos-ivp.org. Get PDF