The Charlie Mission


Maintained by: mikerb@mit.edu         Get PDF


src: project-pavlab/chapters/chap_xmiss_charlie


1  The Charlie Mission
     1.1 Launching the Charlie Mission
     1.2 Topic #1: Hierarchical Mode Declarations in the Charlie Mission
     1.3 Topic #2: The Loiter Behavior
          1.3.1 Loiter Traversal - Clockwise vs. Counter-Clockwise
          1.3.2 Loiter Polygon Shapes, Hexagons, and Ellipses
          1.3.3 Loiter Dynamic Changes to the Polygon Position
          1.3.4 Loiter Robustness to Periodic External Forces
     1.4 Topic #3: The StationKeep Behavior
          1.4.1 Putting the Vehicle into the Station Keeping Mode
          1.4.2 What is Happening in the Station Keeping Mode
     1.5 Suggestions for Tinkering in the Charlie Mission

1   The Charlie Mission


Behaviors:Loiter, StationKeep, Waypoint
MOOS Apps:pHelmIvP, pLogger, uSimMarine, pMarinePID, pNodeReporter, pMarineViewer, uTimerScript
Primary Topics:(1) Hierarchical Mode Declarations
(2) The Loiter behavior
(2a) Loiter traversal - Clockwise vs. counter-clockwise
(2b) Loiter polygon shapes, hexagons, ellipses
(2c) Loiter dynamic changes to the polygon center position
(2d) Loiter robustness to periodic external forces
(3) The StationKeep Behavior
Side Topics:(1) uTimerScript is used to simulate wind gusts, external forces
(2) Use of pMarineViewer action buttons and action pull-down menu

1.1   Launching the Charlie Mission    [top]


The charlie mission may be launched from the command line in the following manner:

  $ cd moos-ivp/missions/s3_charlie/
  $ ./launch.sh --warp=10

This should bring up a pMarineViewer window like that shown in , with a single vehicle, henry, initially in the PARK mode. After hitting the DEPLOY button in the lower right corner, the vehicle enters the "LOITERING" mode and begins to proceed to the polygon shown. To get a quick feel for what's possible in this simulation, the following are some things to try. (a) Click on the "CWISE" and "CCWISE" buttons to change the direction of loitering around the polygon. (b) Click the RETURN and DEPLOY buttons repeatedly to see the vehicle switch between two primary modes. (c) Select the "WIND_GUSTS=true" option in the ACTION pull-down menu to see the vehicle adjust to random periodic external forces. (d) Select the "STATION_KEEP=true" option in the ACTION pull-down menu to see how the vehicle station keeps with simulated wind gust. (e) Let the vehicle return to its return point and watch how it automatically switches to the station keeping mode, and then re-deploy it. (f) Select the ellipse polygon from the ACTION pull-down menu to see a different loiter shape. (g) Select the different center points for the loiter ellipse from the ACTION pull-down menu to see just the location of the loiter polygon change and the vehicle adjust.

1.2   Topic #1: Hierarchical Mode Declarations in the Charlie Mission    [top]


The Charlie mission is organized by hierarchical mode declarations into four modes: INACTIVE, LOITERING, RETURNING, and STATION-KEEPING. The mode declarations are given a the top of the charlie.bhv file and shown again in . The pMarineViewer application by default shows the vehicle's mode alongside the vehicle name, and when the simulation is first launched, the Charlie vehicle is shown on the screen with the mode PARK.

Figure 1.1: Charlie Mission Mode Declarations: The helm, when in drive, will be in one of the four modes indicated by the leaf nodes on the tree. The hierarchical mode structure means, for example, that when the vehicle is in the "RETURNING" mode, it is also considered to be in the "ACTIVE" mode. The vehicle mode, by default, is displayed alongside the vehicle name in the pMarineViewer window.

    The "PARK" mode displayed with the vehicle when the simulation is launched is actually the high level helm state. As described in Section ???, the helm has a higher level helm state which is either PARK or DRIVE, analogous to a car in either the "Park" or "Drive" modes. When the Charlie mission is first launched, the helm is not yet in drive, and is put into drive when the DEPLOY button is hit. This button is configured in the pMarineViewer configuration block to make several MOOS pokes with a single button click. It posts MOOS_MANUAL_OVERRIDE=false, to put the vehicle in the DRIVE helm state. It posts DEPLOY=true to put the helm in the ACTIVE mode, and it posts LOITER=true to put the helm in the ACTIVE:LOITERING mode.

    The Charlie mission is configured to allow for easy transition between the other modes via the pMarineViewer interface. The vehicle may be put into the STATION-KEEPING mode at any time via the STATION_KEEP=true option in the ACTION pull-down menu in pMarineViewer. This does nothing more than make the STATION_KEEP=true post to the MOOSDB. The same could have been accomplished by uPokeDB for example:

  $ cd moos-ivp/missions/s3_charlie/
  $ uPokeDB charlie.moos STATION_KEEP=true

Referring to the mode declarations in , the LOITERING and RETURNING modes both have the condition STATION_KEEP != true, so both of those mode requirements fail to be satisfied. The STATION-KEEPING mode is the default mode, i.e., the "else" mode when the requirements of the RETURNING mode are not met. The STATION_KEEP=true posting could also have been made by another MOOS process, for example, connected to an acoustic modem, an Iridium satellite, or wifi interface.

    The helm mode is communicated to pMarineViewer from the helm via the MOOS variable IVPHELM_SUMMARY. This variable is parsed and the mode is rendered next to the vehicle name in the viewer. This rendering may be turned off by toggling through the "name options", with the 'n' key, or setting the vehicles_name_viewable parameter in the pMarineViewer configuration block to one of the values described in the "Vehicles Pull-Down Menu" Section of \cite{?} .

1.3   Topic #2: The Loiter Behavior    [top]


The LOITERING mode in the Charlie mission is characterized by the BHV_Loiter behavior, and we explore some of capabilities and options for this behavior here. The behavior configuration, in file charlie.bhv is shown in below. The first configuration block, in lines 3-6, are for parameters defined generally for all IvP Helm behaviors, and the second block, in lines 8-16, are for parameters defined explicitly for the Loiter behavior.

Listing 1.1 - Configuration of the Loiter behavior in the Charlie mission, from the file charlie.bhv.

   1  //----------------------------------------------
   2  Behavior = BHV_Loiter
   3  {
   4    name      = loiter
   5    priority  = 100
   6    condition = MODE==LOITERING
   7    updates   = UP_LOITER
   8  
   9             speed = 1.3
  10         clockwise = false
  11    capture_radius = 4.0
  12         nm_radius = 15.0
  13           polygon = format=radial, x=0, y=-75, radius=40, pts=6, snap=1,
  14      visual_hints = nextpt_color=white, nextpt_lcolor=khaki
  15      visual_hints = edge_color=blue, vertex_color=yellow
  16      visual_hints = edge_size=1, vertex_size=2, label=LOITER_POLYGON
  17  }

When the vehicle is first deployed, it heads to the hexagon shaped polygon shown in , configured in line 13. It traverses the polygon in a counter-clockwise manner due to the configuration in line 10. The Loiter behavior maintains an internal mode, the "acquire_mode" which is true when the vehicle is not sufficiently close to the polygon, defined by the acquire_dist parameter which is by default 10 meters. It also keeps track of how many vertex arrivals come by way of achieving the capture radius, and how many by way of the non-monotonic radius. These internal state variables are summarized by the Loiter behavior by publishing a variable LOITER_REPORT. An example might look like:

   LOITER_REPORT = "index=2,capture_hits=12,nonmono_hits=3,acquire_mode=false"

    In the Charlie mission, pMarineViewer is configured to scope on this variable by default, and the evolving LOITER_REPORT may be monitored as the vehicle progresses around the polygon.

1.3.1   Loiter Traversal - Clockwise vs. Counter-Clockwise    [top]


The traversal direction of the Loiter behavior is by default clockwise and can be set to counter-clockwise with the parameter clockwise=false. In the Charlie mission, the traversal direction can be changed by selecting UP_LOITER = clockwise=true and UP_LOITER=clockwise=false from the ACTION pull-down menu. This is a good way to observe the algorithm used by the behavior to acquire the polygon when sufficiently far inside the polygon. The traversal direction could also have been affected by any other MOOS application capable of executing the above two MOOS pokes, including uPokeDB, or any application connected to a communications device.

1.3.2   Loiter Polygon Shapes, Hexagons, and Ellipses    [top]


The only restriction on the shape traversed by the Loiter behavior is that it be a convex polygon. The typical specification of the polygon is shown in line 13, via the "radial" syntax, which accepts a center position ("x=0, y=-75"), a distance from the center point to each vertex ("radius=40"), the number of points in the polygon, ("pts=6"), and a snap value, which rounds the vertex positions to, in this case, the nearest whole meter ("snap=1"). Ellipse shapes are supported with a string such as:

   polygon = format=ellipse, x=110, y=-75, degs=150, pts=14, major=80, minor=20

The above ellipse specification is selectable in the Charlie mission via the ACTION pull-down menu. If selected while in the loiter mode, the vehicle immediately begins traversing to this new polygon, as shown in .

1.3.3   Loiter Dynamic Changes to the Polygon Position    [top]


In addition to the an outright change to the loiter polygon as described above, which includes shape changes, number of vertices and position, there are a few methods for just changing the polygon position while leaving the other characteristics in tact. The Loiter behavior accepts a parameter for just the center position. The following two such assignments are selectable in the ACTION pull-down menu in the pMarineViewer for the Charlie mission:

   center_assign = 40,-40
   center_assign = x=100, y=-80

Try selecting either of these options, with the polygon set to either the hexagon or ellipse and confirm that only the position changes. One other method for affecting the polygon position is via the center_activate parameter, which is false by default. When set to true, the polygon center is set to be the vehicle's present position when the Loiter behavior enters the running state. In the Charlie mission, try selecting center_activate=true from the ACTION pull-down menu. If already in the LOITERING mode, then nothing happens immediately. If and when the helm exits and returns to the LOITERING mode, for example after clicking the RETURN button, and then the DEPLOY button again, note that the loiter polygon is centered on the vehicle's present position. The center_activate feature is particularly useful when the Loiter behavior is used more or less as a station keeping behavior and one wants to be able to command the vehicle to loiter at the present position at any given time.

1.3.4   Loiter Robustness to Periodic External Forces    [top]


When the Loiter behavior is active and the vehicle is proceeding around the polygon vertices, it is proceeding more or less like the Waypoint behavior (both behaviors share the same WaypointEngine class as a sub-component). Things get interesting when the vehicle is approaching the polygon from the outside or from a distance internally (for example when the center_activate parameter set to true. To test and demonstrate this robustness, the Charlie mission is configured with the uTimerScript utility to generate periodic random forces to simulate wind gusts, to push the vehicle off the loiter polygon in unpredictable ways. An example is shown in .

    The simulated wind gusts may be activated by selecting the WIND_GUSTS=true option from the pMarineViewer ACTION pull-down menu. The details of the simulated forces can be found in the uTimerScript configuration block in the charlie.moos file. The script works by posting external force vectors to the MOOS variable USM_DRIFT_VECTOR_ADD, which is read by the uSimMarine application to alter the prevailing external force vector, which by default has a magnitude of zero. The syntax of the uTimerScript script to implement the drift effects in this example are described in more detail in the "A Script as a Proxy for Simulating Random Wind Gusts" Section of the uTimerScript documentation, \cite{?} .

1.4   Topic #3: The StationKeep Behavior    [top]


The STATION-KEEPING mode in the Charlie mission is characterized by the BHV_StationKeep behavior, and we explore some of capabilities and options for this behavior here. The behavior configuration, in file charlie.bhv is shown in below. The first configuration block, in lines 3-5, are for parameters defined generally for all IvP Helm behaviors, and the second block, in lines 7-11, are for parameters defined explicitly for the Loiter behavior.

Listing 1.2 - Configuration of the StationKeep behavior in the Charlie mission, from the file charlie.bhv.

   0  //----------------------------------------------
   1  Behavior = BHV_StationKeep
   2  {
   3    name      = station-keep
   4    priority  = 100
   5    condition = MODE==STATION-KEEPING
   6   
   7    center_activate = true 
   8       inner_radius = 5 
   9       outer_radius = 10  
  10        outer_speed = 1.0
  11         swing_time = 0
  12  }

1.4.1   Putting the Vehicle into the Station Keeping Mode    [top]


The vehicle is put into the station keeping mode by posting STATION_KEEP=true to the MOOSDB. This results in the helm mode, represented by the MOOS variable MODE, being set to station keeping. The hierarchical mode declarations used in the Charlie mission are declared in the top of the charlie.bhv file and were shown in . The StationKeep behavior is conditioned on MODE==STATION-KEEPPING, on line 5 above. The StationKeep behavior may be configured to station keep at a specified point in water (with the station_pt parameter), or it may be configured to station keep wherever it happens to be when it enters or re-enters the running state, as it is configured in the Charlie mission by virtue of line 7 above. In the Charlie mission, pMarineViewer is configured with four on-screen buttons. For more info, see the "Command-and-Control" section of the pMarineVeiwer documentation, \cite{?} . Two of the buttons are used for toggling the STATION_KEEP variable to the MOOSDB.

1.4.2   What is Happening in the Station Keeping Mode    [top]


The station keeping behavior (the only running behavior in this mode) attempts to keep the vehicle within a certain distance, given by the inner_radius parameter, to a center point. Inside this radius, it simply lets the vehicle drift. Outside the radius it sets a heading and speed to drive the vehicle back to the center point. The speed decreases as it approaches the inner circle, and is at its highest speed (set by the outer_speed parameter on line 10 above) when its range to the center point is greater than that given by the outer_radius distance. It also makes two postings to the VIEW_POLYGON object to represent the circles implied by the inner_radius and outer_radius parameters, as shown in .

1.5   Suggestions for Tinkering in the Charlie Mission    [top]


  • Station keeping is trivial if the vehicle doesn't drift. Try turning on the artificial wind gusts available in the Charlie mission, courtesy of the uTimerScript script, available by selecting WIND_GUSTS=true from the Action pull-down menu. The vehicle performance is a bit more interesting now in the station keeping mode.
  • Try configuring the simulator, uSimMarine, to reflect a vehicle that takes much more time to come to a full stop in the water. This can be done by setting deceleration=0.1 in the uSimMarine configuration block, or by posting USM_DECELERATION=0.1 to the MOOSDB once the mission is running. Note that when the vehicle is put into station keeping mode, its station point is set to the point where it is when it enters this mode. Since the vehicle takes so long to slow down, it immediately drifts out of the inner radius and turns around 180 degrees. This is a typical situation seen in the field. This can be countered a bit by setting the swing_time parameter in the StationKeep behavior. This parameter is the number of elapsed seconds after the vehicle enters the station keeping mode before the station keeping behavior marks its present position as the point to station keep around. Try setting swing_time=5 and re-running the above to see the difference.

Figure 1.2: The Charlie Mission (1): The vehicle "charlie" proceeds to a loiter polygon, traversing in a counter-clockwise manner to the first waypoint labelled "charlie's next waypoint".

Figure 1.3: The Charlie Mission (2): The loiter traversal polygon for the vehicle "charlie" has been dynamically changed to an ellipse via a selection from the ACTION pull-down menu.

Figure 1.4: The Charlie Mission (3): The vehicle, "charlie" recovers from a wind gust and proceeds to re-enter the polygon trajectory at the tangential vertex labelled "charlie's next waypoint".

Figure 1.5: The Charlie Mission (4): The vehicle "charlie" is put into the station keeping mode. The two rings around the vehicle are the inner_radius and outer_radius parameters.


Document Maintained by: mikerb@mit.edu        
Page built from LaTeX source using texwiki, developed at MIT. Errata to issues@moos-ivp.org. Get PDF