Engineering/lineCaptureHoming.tl

#   Copyright (c) 2024 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 lineCaptureHoming {
  """
  Home to transponder while maintaining altitude or depth. Altitude gets
  priority if non nan. The mission sequence: (*) Start (1) Midcourse
  guidance: nav to target WP while querying transponder (2) Terminal
  guidance: home to target using USBL tracking data (4) Dock: final
  approach using fixed heading.
  """

  # Define mission arguments

  arguments {
    MissionTimeout = 4 hour
      """
      Maximum length of mission
      """

    NeedCommsTime = 240 minute
      """
      How often to surface for commumications
      """

    MicromodemCommsInterval = 5 minute
      """
      How often to trigger Umodem communications
      """

    Repeat = 1 count
      """
      Number of times the vehicle should try to cycle through the homing
      sequence.
      """

    WaitOnDockTimeout = 5 minute
      """
      Time duration to wait on the dock after a successful line capture.
      """

    StayOnDock = false
      """
      If true, mission terminates after WaitOnDockTimeout following a successful
      catpture, without executing the undock sequence.
      """

    TrySlide = false
      """
      If true, once docked, try to slide down the docking rod until charging and
      comms are acheived
      """

    SlideRetries = 2 count
      """
      If using slide mode, max number of times to try the slide sequence before
      giving up
      """

    SlideSinkDuration = 5 minute
      """
      Time duration to slide down by sinking during each slide mode iteration
      """

    SlideCloseDuration = 5 minute
      """
      Time duration to close arm to check for power/comms during each slide mode
      iteration
      """

    SlideDriveDuration = 2 minute
      """
      Time duration for actions that involve the prop (either bumping or continuous
      driving) during each slide mode iteration
      """

    TryWiggle = false
      """
      If true, uses mass shifter to try to wiggle down the rod after sinking in
      slide mode
      """

    SlideWiggleCount = 2 count
      """
      Number of mass shifter wiggles to try during each slide mode iteration
      """

    TryJog = false
      """
      If true, bumps prop repeatedly in forward and reverse after sinking in
      slide mode
      """

    JogLength = 3 second
      """
      Length of time to run the prop in each direction while jogging in slide mode
      """

    TryWhirl = false
      """
      If true, sets elevators to dive, rudders to turn, and drives continuously
      after sinking in slide mode
      """

    WhirlSpeed = 1 meter_per_second
      """
      Speed at which to drive while whirling in slide mode
      """

    TransponderCode = Dock:Dock.transponderCode
      """
      Transponder Address.
      """

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

    TrackingUpdatePeriodTerminal = 2.5 second
      """
      How long to wait between acoustic queries.
      """

    TrackingUpdatePeriodDocked = 2 minute
      """
      How long to wait between acoustic queries.
      """

    TrackingNumFixesLowPassFilter = 5 count
      """
      Median filter bin size. Filters the contact estimated lat/lon position.
      Prefer odd number, set to 1 to disable filter.
      """

    NumberOfPings = 1 count
      """
      Number of pings requested each time.
      """

    NumPingsUSBL = 1 count
      """
      Number of pings requested while in USBL mode range.
      """

    RangeUSBL = 40 meter
      """
      USBL mode range.
      """

    LightRange = 50.0 meter
      """
      Range to activate the dock light.
      """

    TrackingNumFixesLowPassFilterUSBL = 5 count
      """
      Median filter bin size. Filters the contact estimated lat/lon position.
      Prefer odd number, set to 1 to disable filter.
      """

    DockingAltitude = NaN meter
      """
      Docking altitude. Ignored when NaN and used over depth when a valid
      altitude is set.
      """

    InvalidAltitudeTimeout = NaN minute
      """
      The mission will use the last good depth command if no valid altitude
      readings are received within this specified time duration.
      """

    AltitudeDepthLimit = NaN meter
      """
      Vehicle will not be commanded deeper than this regardless of altitude
      command.
      """

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

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

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

    ApproachDepthTimeout = 20 minute
      """
      Maximum wait time for the vehicle to reach the target depth on initial
      dive.
      """

    ApproachDepthRate = 0.05 meter_per_second
      """
      Descent depth rate (positive depth is down). Used only as a smoothing
      parameter.
      """

    Lat1 = NaN degree
      """
      Latitude of rollout waypoint. If nan, waypoint is skipped.
      """

    Lon1 = NaN degree
      """
      Longitude of rollout waypoint. If nan, waypoint is skipped.
      """

    CaptureRadius = NaN meter
      """
      How close to call the waypiont behavior satisfied. Nan uses default
      value.
      """

    # Mission Variables (don't change)

    MidcourseDepth = Dock:LineCapture.midcourseDepth
      """
      Desired vehicle depth when navigating to dock WP (during midcourse
      phase).
      """

    MidcourseSpeed = Dock:LineCapture.midcourseSpeed
      """
      Speed during initial dive and waypoint.
      """

    TrackingPeriod = 60 second
      """
      Mission variable (don't change). The mission sets this variable to
      update the how long to wait between acoustic queries.
      """
  }

  output {
    Mode = -1 count
      """
      Mission variable (don't change). The mission sets this variable to
      reflect the termination status of the LineCapture insert.
      """

    NumPings = 1 count
      """
      Mission variable (don't change). The mission sets this variable to
      update the requested ping number and enter usbl mode.
      """

    LowPassFilterWinSize = 1 count
      """
      Mission variable (don't change). The mission sets this variable to
      update the requested ping number and enter usbl mode.
      """

    LowPassFilterWinOverlap = true
      """
      Mission variable (don't change). The mission sets this variable to
      update the requested ping number and enter usbl mode.
      """
  }

  # Mission timeout

  timeout duration=MissionTimeout

  insert Insert/Science.tl {
    """
    Most missions will run the science sensors. If you don't place this
    aggregate above NeedComms, science instruments get turned off on the
    last upcast and while floating on the surface.
    """
  }

  # Safety nets and surfacing behaviors

  insert Insert/StandardEnvelopes.tl

  assign in sequence StandardEnvelopes:MinAltitude = MinAltitude
  assign in sequence StandardEnvelopes:MaxDepth = MaxDepth
  assign in sequence StandardEnvelopes:MinOffshore = MinOffshore
  insert id="NeedComms" Insert/NeedComms.tl

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

  # Micromodem comms

  insert id="MicromodemComms" Insert/MicromodemComms.tl {
    redefineArg CommsInterval = MicromodemCommsInterval
  }

  # Add LineCapture directives.

  insert Insert/LineCapture.tl

  assign in sequence LineCapture:MaxDepth = MaxDepth
  assign in sequence LineCapture:MinOffshore = MinOffshore
  assign in sequence LineCapture:MinAltitude = MinAltitude
  assign in sequence LineCapture:DockingAltitude = DockingAltitude
  assign in sequence LineCapture:InvalidAltitudeTimeout = InvalidAltitudeTimeout
  assign in sequence LineCapture:AltitudeDepthLimit = AltitudeDepthLimit

  # Add track acoustic contact directive.

  assign in sequence NumPings = NumberOfPings

  behavior Estimation:TrackAcousticContact id="TrackAC" {
    run in parallel

    set contactLabelSetting = TransponderCode

    set numberOfSamplesSetting = NumPings

    set updatePeriodSetting = TrackingPeriod

    set numFixesLowPassSetting = LowPassFilterWinSize

    set lowPassOverlapSetting = LowPassFilterWinOverlap
  }

  # Add USBL mode directives.

  aggregate UpdateNumPings_NotTerminal {
    run while (
      not ( LineCapture:GuidanceMode == LineCapture:Terminal )
      and not ( NumPings == NumberOfPings )
    )

    syslog info "No longer in Terminal. Resuming normal ranging with " + NumberOfPings~count
         + "pings."
    assign in sequence NumPings = NumberOfPings
    assign in sequence LowPassFilterWinSize = TrackingNumFixesLowPassFilter
    assign in sequence LowPassFilterWinOverlap = true
  }

  aggregate UpdateNumPings_Terminal {
    run while (
      LineCapture:GuidanceMode == LineCapture:Terminal
    )

    aggregate UpdateNumPingsUSBL {
      run when (
        not ( NumPings == NumPingsUSBL )
        and (
          ( LineCapture:Range < RangeUSBL ) # don't enter USBL mode during rollout
          and not ( Dock:LineCapture.guidanceMode == 5 count )
        )
      )

      syslog info "Entering USBL mode with " + NumPingsUSBL~count + "pings at "
           + LineCapture:Range~meter + "(mode " + Dock:LineCapture.guidanceMode~count + ")."
      assign in sequence NumPings = NumPingsUSBL
      assign in sequence LowPassFilterWinSize = TrackingNumFixesLowPassFilterUSBL
      assign in sequence LowPassFilterWinOverlap = true
    }

    aggregate UpdateNumPingsATR {
      run when (
        not ( NumPings == NumberOfPings )
        and (
          ( LineCapture:Range >= RangeUSBL ) # do ATR mode during rollout
          or Dock:LineCapture.guidanceMode == 5 count
        )
      )

      syslog info "Resuming normal ranging with " + NumberOfPings~count + "pings "
           + LineCapture:Range~meter + "(mode " + Dock:LineCapture.guidanceMode~count + ")."
      assign in sequence NumPings = NumberOfPings
      assign in sequence LowPassFilterWinSize = TrackingNumFixesLowPassFilter
      assign in sequence LowPassFilterWinOverlap = true
    }
  }

  aggregate UpdatePingUpdateRate_Midcourse {
    run when (
      not ( TrackingPeriod == TrackingUpdatePeriodMidcourse )
      and (
        ( LineCapture:Range > LineCapture:TerminalRange ) # do slow ping mode during rollout
        or Dock:LineCapture.guidanceMode == 5 count
      )
    )

    syslog info "Entering Midcourse tracking update period " + TrackingUpdatePeriodMidcourse~second
         + "sec at" + LineCapture:Range~meter + "(mode " + Dock:LineCapture.guidanceMode~count + ")."
    assign in sequence TrackingPeriod = TrackingUpdatePeriodMidcourse
    assign in sequence LowPassFilterWinSize = TrackingNumFixesLowPassFilter
    assign in sequence LowPassFilterWinOverlap = true
  }

  aggregate UpdatePingUpdateRate_Terminal {
    run when (
      not ( TrackingPeriod == TrackingUpdatePeriodTerminal )
      and (
        ( LineCapture:Range <= LineCapture:TerminalRange )
        and not ( Dock:LineCapture.guidanceMode == 5 count )
        and not ( LineCapture:GuidanceMode == 0 count )
      ) # don't enter fast ping mode during rollout or on dock
    )

    syslog info "Entering Terminal tracking update period " + TrackingUpdatePeriodTerminal~second
         + "sec at" + LineCapture:Range~meter + "(mode " + Dock:LineCapture.guidanceMode~count + ")."
    assign in sequence TrackingPeriod = TrackingUpdatePeriodTerminal
    assign in sequence LowPassFilterWinSize = TrackingNumFixesLowPassFilter
    assign in sequence LowPassFilterWinOverlap = true
  }

  aggregate restartDHCP {
    run when ( called )

    syslog important "Restarting DHCP..."

    behavior Guidance:Execute {
      run in sequence

      set command = "! /mnt/mmc/LRAUV/Tools/dhcp.sh"
    }
  }

  # Start mission sequence.

  call id="StartingMission" refId="NeedComms"

  syslog important "Restarting logs"

  behavior Guidance:Execute {
    run in sequence

    set command = "restart logs"
  }

  aggregate InitialDive {
    run in sequence

    behavior Guidance:SetSpeed {
      run in parallel

      set speed = MidcourseSpeed
    }

    behavior Guidance:Pitch {
      run in sequence

      timeout duration=ApproachDepthTimeout {
        syslog important "Timed out trying to reach the target depth. Stopping mission at current depth of "
             + Universal:depth~meter

        behavior Guidance:Execute {
          run in sequence

          set command = "stop"
        }
      }

      set depth = MidcourseDepth
      set depthRate = ApproachDepthRate
    }
  }

  aggregate Lap {
    run in sequence repeat=Repeat

    assign in sequence Mode = -99 count

    # Execute the LineCapture sequence.

    call refId="LineCapture"
    assign in sequence Mode = LineCapture:GuidanceMode
    syslog info "Mode" + Mode~count

    aggregate ActivateLight {
      run while (
        Universal:acoustic_contact_range <= LightRange
      )

      readData id="RequestLightOn" {
        Sensor:DAT.deviceEnableRequested
      }
    }

    call refId="restartDHCP"

    aggregate Docked {
      run in sequence

      break if ( Mode < 0 count )

      syslog info "Waiting on dock for " + WaitOnDockTimeout~minute

      # Add SetNav directives.

      insert Insert/SetNavAcoustic.tl

      assign in sequence TrackingPeriod = TrackingUpdatePeriodDocked

      behavior Dock:Docked id="Docked" {
        run in sequence

        timeout duration=WaitOnDockTimeout

        set slideSinkTime = SlideSinkDuration
        set slideCloseTime = SlideCloseDuration
        set slideDriveTime = SlideDriveDuration
        set jogLength = JogLength
        set whirlSpeed = WhirlSpeed
        set slideRetries = SlideRetries
        set wiggleCount = SlideWiggleCount
        set slideAllowed = TrySlide
        set massWiggle = TryWiggle
        set propJog = TryJog
        set driveWhirl = TryWhirl
      }

      aggregate Detach {
        run in sequence

        break if ( StayOnDock == true )

        syslog important "Breaking off. Range: " + Universal:acoustic_contact_range~meter + "."

        behavior Dock:Undock id="Undock" {
          run in sequence
        }

        call refId="restartDHCP"
      }

      aggregate Wpt1 {
        run in sequence

        break if (
          isNaN ( Lat1 )
          or isNaN ( Lon1 )
          or ( StayOnDock == true )
        )

        syslog important "Driving to post-undock waypoint " + Lat1~degree + "," + Lon1~degree

        behavior Guidance:Pitch {
          run in parallel

          set depth = MidcourseDepth
        }

        behavior Guidance:SetSpeed {
          run in parallel

          set speed = MidcourseSpeed
        }

        behavior Guidance:Waypoint {
          run in sequence

          set latitude = Lat1

          set longitude = Lon1

          set captureRadius = CaptureRadius
        }
      }

      aggregate Drift {
        """
        Drift before next docking attempt
        """

        run in sequence

        break if (
          not isNaN ( Lat1 )
          and not isNaN ( Lon1 )
          or ( StayOnDock == true )
        )

        syslog important "No post-undock waypoint, drifting for "
             + Dock:LineCapture.rolloutTimeout~minute + " minutes"

        behavior Guidance:Buoyancy {
          run in parallel

          set position = Control:VerticalControl.buoyancyNeutral
        }

        behavior Guidance:Pitch {
          run in parallel

          set massPosition = Control:VerticalControl.massDefault

          set elevatorAngle = 0 degree
        }

        behavior Guidance:Point {
          run in parallel

          set rudderAngle = 0 degree
        }

        behavior Guidance:SetSpeed {
          run in parallel

          set speed = 0 meter_per_second
        }

        behavior Guidance:Wait {
          run in sequence

          set duration = Dock:LineCapture.rolloutTimeout
        }
      }
    }
  }
}