Engineering/track_acoustic_open_loop.tl

#   Copyright (c) 2026 MBARI
#   MBARI Proprietary Information. Confidential. All Rights Reserved
#   Unauthorized copying or distribution of this file via any medium is strictly
#   prohibited.
#
#   WARNING - This file contains information whose export is restricted by the
#   Export Administration Act of 1979 (Title 50, U.S.C., App. 2401 et seq.), as
#   amended. Violations of these export laws are subject to severe civil and/or
#   criminal penalties.

mission track_acoustic_open_loop {
  """
  Drive the vehicle along a fixed waypoint trajectory while tracking an
  acoustic contact in the background. The acoustic tracker is run for data
  collection only; the mission does NOT consume Estimation:TrackAcousticContact
  outputs to steer the vehicle, so the loop on the acoustic estimate is open.
  Use this to characterize what the acoustic estimator does for a given
  trajectory geometry.

  Flight mode is controlled by FixedDepth: if FixedDepth is set, the vehicle
  flies flat-and-level at that depth (no fancy approach dive, transit-style);
  if FixedDepth is NaN, the vehicle yo-yos between YoYoMinDepth and
  YoYoMaxDepth. Up to 7 waypoints can be specified, and the whole sequence
  is repeated Repeat times.
  """

  arguments {
    # Mission-wide settings

    MissionTimeout = 2 hour
      """
      Maximum duration of mission
      """

    NeedCommsTime = 60 minute
      """
      Elapsed time after previous surface communications when vehicle will
      begin to ascend for additional surface communications.
      """

    AcousticContactTimeout = 4 hour
      """
      If the vehicle does not receive an acoustic signal for more than this
      length of time, it will surface for communications.
      """

    # Acoustic tracking

    ContactLabel = 0 count
      """
      The acoustic address of the asset to be tracked.
      """

    ContactDepth = NaN meter
      """
      The depth of the asset to be tracked, if known.
      """

    TrackingUpdatePeriod = 60 second
      """
      How long to wait between acoustic queries.
      """

    NumberOfPings = 1 count
      """
      Number of return pings to request with each acoustic query
      """

    # Trajectory

    Lat[1..7] = NaN degree
      """
      Latitude of waypoint {$}. If NaN, waypoint is skipped.
      """

    Lon[1..7] = NaN degree
      """
      Longitude of waypoint {$}. If NaN, waypoint is skipped.
      """

    Repeat = 1 count
      """
      Number of times the vehicle should cycle through the full waypoint list.
      """

    FixEveryLeg = false
      """
      If true, surface for a GPS fix before starting each waypoint leg (in
      addition to the end-of-lap fix). Tightens the dead-reckoning bounds
      for post-hoc trajectory reconstruction at the cost of extra
      surfacing time (~one NeedComms cycle per leg).
      """

    Speed = 1 meter_per_second
      """
      Vehicle speed.
      """

    CaptureRadius = NaN meter
      """
      Waypoint capture radius. NaN uses the Guidance:Waypoint default.
      """

    # Depth strategy

    FixedDepth = NaN meter
      """
      If non-NaN, vehicle flies flat-and-level at this depth instead of
      yo-yoing. See yo-yo settings below for the NaN case.
      """

    YoYoMinDepth = 3 meter
      """
      Minimum depth during yo-yos. Ignored when FixedDepth is set.
      """

    YoYoMaxDepth = 50 meter
      """
      Maximum depth during yo-yos. Ignored when FixedDepth is set.
      """

    YoYoMinAltitude = 10 meter
      """
      Minimum altitude during yo-yos. Ignored when FixedDepth is set.
      """

    YoYoUpPitch = 20 degree
      """
      Up pitch during yo-yos. Ignored when FixedDepth is set.
      """

    YoYoDownPitch = -20 degree
      """
      Down pitch during yo-yos. Ignored when FixedDepth is set.
      """

    # Static actuator settings

    BuoyancyNeutral = Control:VerticalControl.buoyancyNeutral
      """
      Buoyancy bladder position. Set to NaN cc for active buoyancy control.
      """

    MassDefault = Control:VerticalControl.massDefault
      """
      Mass shifter position. Set to NaN mm for active mass control.
      """

    # Safety envelopes

    MinAltitude = 7 meter
      """
      Minimum height above the sea floor for the entire mission.
      """

    MaxDepth = 105 meter
      """
      Maximum depth for the entire mission.
      """

    MinOffshore = 1.5 kilometer
      """
      Minimum offshore distance for the entire mission.
      """
  }

  timeout duration=MissionTimeout

  # Acoustic tracker, high in the stack so it runs even at the surface.

  insert Insert/AbortDrift.tl {
    redefineArg AcousticTimeout = AcousticContactTimeout
  }

  behavior Estimation:TrackAcousticContact {
    run in parallel

    set contactDepthSetting = ContactDepth
    set contactLabelSetting = ContactLabel
    set numberOfSamplesSetting = NumberOfPings
    set updatePeriodSetting = TrackingUpdatePeriod
  }

  insert id="NeedComms" Insert/NeedComms.tl

  assign in sequence NeedComms:DiveInterval = NeedCommsTime
  assign in sequence NeedComms:WaitForPitchUp = 0 minute

  insert Insert/StandardEnvelopes.tl

  assign in sequence StandardEnvelopes:MinAltitude = MinAltitude
  assign in sequence StandardEnvelopes:MaxDepth = MaxDepth
  assign in sequence StandardEnvelopes:MinOffshore = MinOffshore

  insert Insert/BackseatDriver.tl

  insert Insert/PowerOnly.tl

  insert Insert/Science.tl

  behavior Guidance:Buoyancy id="BuoyancyHold" {
    run in parallel

    set position = BuoyancyNeutral
  }

  behavior Guidance:Pitch id="MassHold" {
    run in parallel

    set massPosition = MassDefault
  }

  behavior Guidance:SetSpeed {
    run in parallel

    set speed = Speed
  }

  aggregate FlatAndLevel {
    run while ( not isNaN ( FixedDepth ) )

    behavior Guidance:Pitch {
      run in parallel

      set depth = FixedDepth
    }
  }

  aggregate YoYos {
    run while ( isNaN ( FixedDepth ) )

    behavior Guidance:DepthEnvelope {
      run in parallel

      set minDepth = YoYoMinDepth
      set maxDepth = YoYoMaxDepth
      set upPitch = YoYoUpPitch
      set downPitch = YoYoDownPitch
    }

    behavior Guidance:AltitudeEnvelope {
      run in parallel

      set minAltitude = YoYoMinAltitude
    }

    behavior Guidance:YoYo {
      run in parallel

      set upPitch = YoYoUpPitch
      set downPitch = YoYoDownPitch
    }
  }

  call id="StartingMission" priorityHere=false refId="NeedComms"

  # The contact_latitude / contact_longitude outputs of TracAC
  # are intentionally NOT fed back here -- this is the open-loop test.

  aggregate Lap {
    run in sequence repeat=Repeat

    macro $i = 1..7 {
      aggregate Wpt$i {
        run in sequence

        aggregate LegStartFix$i {
          """
          Optional GPS fix at the start of each leg so every leg is bounded
          by fixes for DR drift correction. NOTE: the syslog before the
          call is required. A call that is the first executable item
          of an aggregate fires during init before the break is evaluated
          (calls take effect at initialize, breaks gate only the run path).
          """

          run in sequence

          break if (
            not FixEveryLeg
            or isNaN ( Lat[$i] )
          )

          syslog info "Surfacing for GPS fix at leg start"

          call priorityHere=false refId="NeedComms"
        }

        behavior Guidance:Waypoint {
          run in sequence

          set latitude = Lat[$i]
          set longitude = Lon[$i]
          set captureRadius = CaptureRadius
        }
      }
    }

    # Surface for a GPS fix at the end of every lap so DR drift can be
    # bounded per-lap when reconstructing the trajectory. Set NeedCommsTime
    # comfortably longer than one lap so the elapsed-time trigger never
    # fires mid-leg.
    call id="LapEndFix" priorityHere=false refId="NeedComms"
  }
}