Dive Cycle & Control Files¶

A Seaglider is piloted indirectly: the vehicle repeats a canonical dive — surface, dive, apogee, climb, and back to the surface — entirely on its own, and the pilot influences the next dive by leaving files on the basestation for the glider to collect when it calls in. There is no live terminal: everything the pilot wants to change is expressed as a handful of plain-text control files. Understanding the dive cycle and those files is the foundation of Seaglider piloting — every other topic (trim, flight model, sampling) builds on it.

The control design in one paragraph¶

Seaglider flight control follows two guiding principles: hold a constant vertical velocity and spend as little energy as possible doing it. The glider samples its sensors evenly in time, so constant vertical speed gives evenly spaced samples in depth. The pump that moves hydraulic oil to the external bladder is roughly half the energy budget of the vehicle, so the control scheme is built around avoiding unnecessary pump strokes: no bleeding is allowed on the dive (excess speed is tolerated), and pumping on the climb is allowed freely because that oil would have to be pumped at the surface anyway.

The desired vertical velocity is never set directly. It falls out of two parameters:

w_desired = (2 × $D_TGT × 100 cm/m) / ($T_DIVE × 60 s/min)   [cm/s]

For each dive the software picks a pitch angle and a buoyancy, bounded by $GLIDE_SLOPE (steepest glide allowed), $MAX_BUOY (most negative buoyancy allowed on the dive), the stall angle, and neutral buoyancy. Pitch is chosen first, from the distance to the next waypoint — steep if the waypoint is far, shallow if it is close — and buoyancy is then chosen to achieve the desired vertical velocity in the densest water expected on the dive.

The guidance & control (G&C) loop¶

During the profile phases the glider alternates between two modes:

• Active G&C — at intervals set in the science file, the glider wakes and performs up to three corrections, always in this order: pitch, VBD, roll. Only one actuator moves at a time.
• Passive G&C — between corrections the processor drops into a low-power sleep and the glider simply flies in the state left by the last active cycle.

Science data acquisition is never interrupted by G&C: the glider samples on its own schedule through dive, apogee, and climb, whether or not the actuators are moving.

Run phases¶

flowchart LR
    L[Launch] --> S[Surface]
    S --> D[Dive]
    D --> A[Apogee]
    A --> C[Climb]
    C --> S
    S -.->|"$QUIT / error"| R[Recovery]
    R -.->|"$RESUME"| S

Surface¶

Everything the pilot ever changes takes effect here. The surface phase runs through a fixed sequence:

1. Surface maneuver — pitch full forward, roll neutral, pump to $SM_CC (typically near maximum VBD) so the antenna mast clears the water. If the glider is still deeper than $D_SURF, it pumps to maximum first and re-checks — this is the escape path after a $T_MISSION timeout.
2. GPS1 — first fix; the receiver runs until a position with HDOP < 2.0 is found or $T_GPS / $N_GPS limits are hit. (Known quirk on older 1KA gliders: the replacement Garmin 15xH GPS warms up slightly slower than the original 15H and misses the firmware's initial 2-second response window, so every dive logs a benign GPS error — a trailing 1 in the log's $ERRORS line — and then fixes normally.)
3. Communications — the glider calls the basestation over Iridium, uploads its data/log/capture files, and downloads any control files the pilot has staged. Failed sessions retry every $CALL_WAIT seconds up to $CALL_TRIES times; a completely failed surfacing increments $N_NOCOMM.
4. Surface depth & pitch — averages of 10 pressure and 10 pitch readings are logged as the surface reference for the next dive.
5. GPS2 — the last position before diving.
6. Navigation & flight calculations — heading, pitch, and buoyancy for the next profile are computed (including the bathymetry-map lookup if enabled), and a new dive begins.

Dive¶

The dive starts with a bleed-only first G&C cycle to get the glider moving down while pitch is still full forward. At $D_FLARE it flares into normal flight: regular G&C cycles trim pitch, VBD, and roll to the computed values. If the glider runs fast on the dive (too heavy), no corrective pumping is done — the excess speed is tolerated to save energy. One quirk worth remembering: on the dive the Seaglider turns to starboard by banking to port, the opposite of aircraft convention.

Apogee¶

At $D_TGT (or an altimeter/bathymetry-triggered bottom), a two-cycle maneuver swings the glider from diving to climbing without stalling: first pitch to $APOGEE_PITCH with VBD pumped to 0 cc (neutral), then pitch and VBD to the mirror image of the dive values. Sampling continues throughout.

Climb¶

The glider rises at the same target vertical speed. Bleeding is never used to correct a too-fast climb (that oil would just be pumped again at the surface); pumping is used if the glider is slow, and $MAX_BUOY does not constrain the climb. On the climb the glider banks to starboard to turn to starboard, as in aircraft flight. At $D_SURF it goes passive, samples briefly while coasting up (at most ~50 more data points), then enters the surface phase.

Recovery¶

Recovery is the "park on the surface and phone home" state — entered by pilot command ($QUIT) or automatically on an error condition. The glider loops: GPS fix, call the basestation, sleep $T_RSLEEP minutes (plus ~2 min of overhead), repeat. It leaves recovery only when the pilot places a $RESUME directive in the cmdfile.

The four control files¶

The pilot commands the Seaglider through four plain-text files in the mission directory on the basestation. At every call-in the basestation uploads any that have changed, then archives the sent version as <name>.ddd.nnn (dive number ddd, call cycle nnn) — so the mission directory keeps a complete history of every command ever sent.

cmdfile — parameters and directives¶

Each line is either a parameter assignment or a directive:

$D_TGT,45
$T_DIVE,15
$T_MISSION,25
$GO

The file must end in exactly one directive, which sets the glider's state:

targets — where to fly¶

A line-oriented waypoint list; / in column 0 marks a comment. Each target names its successor, so the file forms a route (a target may point back to itself to station-keep):

/ Shilshole targets (small rectangle)
SE lat=4743.0 lon=-12224.0 radius=100 goto=NE
NE lat=4743.5 lon=-12224.0 radius=100 goto=NW
NW lat=4743.5 lon=-12225.0 radius=100 goto=SW
SW lat=4743.0 lon=-12225.0 radius=100 goto=SE

Optional per-target fields:

The glider resumes its last active target from nonvolatile storage after a reset; otherwise it starts at the first listed target. $HEADING overrides the navigation logic entirely (fly a fixed course).

science — sampling and G&C by depth band¶

Depth-binned, tab-separated lines (tabs, not spaces — a classic hand-editing pitfall; sciedit gets it right):

// depth  gc-interval  sampling  sensor-mask  compass  pressure
45  gc=60   seconds=5   sensors=11  compass=1   pressure=1
1000    gc=180  seconds=15  sensors=12  compass=1   pressure=1

Each line gives, for all depths down to bottom_depth: the G&C interval (seconds), the base sensor sampling interval (seconds), a sensor mask (one digit per installed sensor in $SENSORS order — 0 = off, 1 = every interval, 2 = every 2nd, and so on), and compass/pressure intervals as multipliers of the base interval. On gliders fitted with a science controller (scicon), sensor scheduling moves to scicon.sch and the science file's sensor mask is ignored — it then mainly sets G&C intervals.

pdoscmds.bat — housekeeping¶

A batch of Extended PicoDOS commands run at the end of a call-in: resending or deleting files on the compact flash, uploading new bathymaps, and similar maintenance. Powerful and unvalidated — see the Extended PicoDOS Reference Manual before using it.

What else lives in the mission directory¶

Beyond the four control files, the basestation side of a mission involves:

Basestation3 housekeeping best practices¶

• Start every mission with NewMission.py — it creates the mission directory, seeds sg_calib_constants.m, links pagers.yml, and points the glider's current symlink at it. Never mkdir mission directories by hand; wrong permissions break file conversion later.
• Keep the pre-launch self-test in the mission directory. The self-test review features of vis expect it there, and remote troubleshooters will ask for it first.
• Never mix deck-dive data and real mission data in one directory — move simulated dives out with MoveData.py (or start a fresh mission directory). Leftover simulated dives can stop the Flight Model System from running on the real mission.
• List every mission you want visible in missions.yml (active mission at the top; add status: complete when done), and test edits with vis.py … -t before installing them.

Deck dives (simulated dives)¶

A deck dive exercises the entire end-to-end path — glider software, Iridium, basestation conversion, plots — with simulated pressure:

1. Configure glider and basestation exactly as for a real mission.
2. Set $SIM_W,0.1 (simulated 10 cm/s vertical speed) and launch with Test Launch instead of Sea Launch.
3. No sky view? Either set $SIMULATE,3 to fake GPS and Iridium too, or stay on the serial console and set $N_NO_SURFACE to a large negative number so the glider skips the surface comms entirely.

Quick parameter reference¶

The parameters met on this page, in one table:

For the complete list, see the Parameter Reference Manual.

See also¶

• Trim & Flight Model — choosing $C_VBD, pitch/roll trim, and how the basestation's Flight Model System tunes flight coefficients.
• Mission Files (Slocum) — the equivalent page for the Slocum platform, for pilots flying both.