%~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
% $Id: RemoteControl.tex,v 1.6 2008/07/14 17:02:19 swift Exp $
%~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
% RCS Log:
%
% $Log: RemoteControl.tex,v $
% Revision 1.6  2008/07/14 17:02:19  swift
% Added compensator hyper-retraction feature to allow floats to be
% parked at mid-water pressures.
%
% Revision 1.5  2007/10/05 22:33:48  swift
% Change telemetry retry interval and add definitions of bit-masks for status words.
%
% Revision 1.4  2007/05/07 23:48:34  swift
% Added description of TimeOfDay feature including its remote control.
%
% Revision 1.3  2006/11/24 23:57:02  swift
% Change comment description from FlashFsCreate() to FlashCreate().
%
% Revision 1.2  2006/11/22 02:52:23  swift
% Added descriptions of FlashErase() and FlashFsCreate() configurators.  Added
% warning about activating CP mode below the main thermocline.
%
% Revision 1.1  2006/11/03 19:08:57  swift
% Added user manual to CVS control.
%
% Revision 1.1  2006/04/14 23:18:05  swift
% Initial revision
%
%~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

\section{Remote control (a.k.a 2-way commands).}
\label{sec:RemoteControl}

The ability to accomplish 2-way communication and remote control via the
\iridium\ system was the major motivator for implementing remotely
configurable operation.

\textbf{WARNING:} Remote control of \iridium\ floats is a new and advanced
feature that requires a careful and knowledgeable operator.  For example, it
is quite possible to send the float remote commands that will render it
incapable of re-establishing a communications session with the remote host.
Without physical possession of the float, this condition is not recoverable
and therefore the float would be effectively killed.  The
\emph{Configuration Supervisor} (see Section~\ref{sec:ConfigSupervisor})
attempts to protect against some common classes of misconfigurations.
However, there is no substitute for a careful, knowledgeable, prudent, and
conservative operator.  Furthermore, \textbf{it is my advice that new
  mission configurations should always first be tried on a laboratory
  simulator before being applied to a float in the field}.

Remote control of the mission is accomplished by creating a configuration
file, ``mission.cfg'', on the float's remote-host computer.  The name of the
configuration file can not be changed and the syntax of configuration files
is tightly controlled and accomplished through the use of ``configurators''.
A lexical analyzer is implemented in firmware to parse the configuration
file and install the configurator arguments as the float's new mission
configuration.

Strict syntax rules are rigidly enforced as a protective measure against
accidental and perhaps fatal misconfiguration.  Every line in the
configuration file must be either a blank line (ie., all white space), a
comment (first non-whitespace character must be '\#'), or a well-formed
configurator.  Configurators have a fixed syntax:

      \begin{verbatim}
      ParameterName(argument) [CRC]
      \end{verbatim}
  
where ParameterName satisfies the regex ``[a-zA-Z0-9]\{1,31\}'' (ie.,
maximum of 31 characters), argument satisfies the regex ``.*'', and the
[CRC] field is optional (but strongly encouraged) and, if present, must
satisfy the regex ``[(0x[0-9a-fA-F]\{1,4\})]''.  That is, the opening and
closing brackets are literal characters ``[]'' that bracket a string that
represents a 4-16 bit hexidecimal number.  If the CRC field is present then
it represents the 16-bit CRC of the configurator:
``ParameterName(argument)''.  The CRC of the configurator is computed and
checked against the CRC specified in the configurator.  The CRCs must have
the same value or else the configuration attempt fails.  The CRC is
generated by the CCITT polynomial\footnote{Ssee the comment section of the C
  source file, ``crc16bit.c'', for details of the CRC generator.}.

It is important to note that any white space in the argument is treated as
potentially significant.  Every byte (including white space) between the
parentheses is considered to be a non-negligible part of the argument.  In
cases where the argument string is converted to a number then the presence
of extraneous white space won't matter.  However, if the argument
represents, say, a login name or a passord then extraneous space would be
fatal.

Only one configurator per line is allowed and the configurator must be the
left-most text on the line except that it can be preceeded by an arbitrary
amount of whitespace.  No text, except for an arbitrary amount of white
space, is allowed to the right of the rightmost closing parenthesis.  The
maximum length of a line (including white space) is 126 bytes and the
maximum length of the ParameterName is 31 bytes.

The order that configurators are given in the file does not matter except
that if configurators are repeated then only the last one is relevant.  The
ParameterName of the configurator is not case sensitive.  However, the
argument is potentially case sensitive as, for example, a user name or
password.  

If any syntax error is detected in the configuration file or if the argument
of a configurator fails a range check then the configuration attempt fails
in its entirety.  In this case then the new configuration attempt is
completely disregarded and the previous configuration remains active.

Configurators virtually never come in complete sets.  It is normal to adjust
the values of some mission parameters while leaving others unchanged.
However, certain mission parameters interact with each other and it is very
important that the float operator understand the details of these
interactions because float operation can be significantly affected.
Moreover, be mindful that the float itself will change the values of some
mission parameters (eg., park piston position, deep profile piston position)
during the course of the mission.

\begin{minipage}{6in}
The following is an example of a valid configuration file, \textbf{mission.cfg}:
\begin{verbatim}
   # Activate continuous profiling at 1000dbars (spot sampling in deep water).
   CpActivationP(1000)     [0xF2CC]
   
   # Allow 5 hours to descend from the surface to the park pressure.
   ParkDescentTime(300)    [0xB880]
   
   # Set the park pressure to be 1000dbars.
   ParkPressure(1000)      [0x899C]
   
   # Set the park-n-profile cycle length to 4.
   PnPCycleLen(4)          [0x2825]
   
   # Set the down-time to 5 days
   DownTime(7200)          [0xBC7F]

\end{verbatim}
\end{minipage}

A description of each configurator follows:

\begin{description}
\item[ActivateRecoveryMode()]---This configurator induces the float into
  recovery mode and initiate telemetry at regular intervals given by the
  telemetry retry period.  This configurator requires no argument.

\item[AirBladderMaxP(Counts)]---The cut-off pressure (in A/D counts) for
  air-bladder inflation.  The air pump will be deactivated when the air
  bladder pressure exceeds the cut-off.  The valid range of the argument is
  1-240~counts. This configurator is for disaster recovery only and should
  rarely be necessary.

\item[AscentTimeOut(Minutes)]---The initial segment of the uptime that is
  designated for profiling and vertical ascent.  If the surface has not been
  detected by the time this timeout expires then the profile will be aborted
  and the telemetry phase will begin.  The valid range of the argument is
  1~minute to 10~hours.
                               
\item[AtDialCmd()]---The modem AT dialstring used to connect to the primary
  host computer.  Be sure to include ``ATDT'' as the leading part of the
  string.  Changing both AtDialCmd() and AltDialCmd() at the same time is
  dangerous and strongly discouraged.
                               
\item[AltDialCmd()]---The modem AT dialstring used to connect to the
  alternate host computer.  Be sure to include ``ATDT'' as the leading part
  of the string.  Changing both AtDialCmd() and AltDialCmd() at the same
  time is dangerous and strongly discouraged.

\item[BuoyancyNudge(Counts)]---The piston extension (counts) applied each
  time the ascent rate falls below the user-specified minimum.  This adds
  buoyancy to the float in order to maintain the ascent rate.

\item[ConnectTimeOut(Seconds)]---The number of seconds allowed after dialing
  for a connection to be established with the host computer.  The valid
  range of the argument is 30-300~sec.

\item[CpActivationP(Decibars)]---The pressure where the \apf\ firmware
  transitions from subsampling the water column (in the deep water) to where
  the continuous profiling mode of the SBE41CP is activated for a high
  resolution profile to the surface.

  \textbf{WARNING:} The SBE41CP is not designed for subsampling in the
  presence of significant temperature gradients.  The pump period for spot
  samples is insufficient to drive thermal mass errors down to an acceptable
  level and will result in degraded hydrographic data.  An activation
  pressure deeper than the main thermocline is strongly encouraged.  An
  minimum activation pressure of 1000~dbar is recommended and a sanity-check
  violation will be encountered if the activation pressure is less than
  750~dbars.

\item[DeepProfileDescentTime(Minutes)]---This time determines the maximum
  amount of time allowed for the float to descent from the park pressure to
  the deep profile pressure.  The deep profile is initiated when the deep
  profile descent time expires or else the float reaches the deep profile
  pressure, whichever occurs first.  The valid range of the argument is
  0-8~hours.

\item[DeepProfilePistonPos(Counts)]---The \apf\ firmware retracts the piston
  to the deep profile piston position in order to descend from the park
  pressure to the deep profile pressure.  The deep profile piston position
  should be set so that the float can reach the deep profile pressure before
  the deep profile descent period expires.  The valid range of the argument
  is 1-254~counts.

\item[DeepProfilePressure(Decibars)]---This is the target pressure for deep
  profiles.  The valid range of the argument is 0-2000~decibars.

\item[CompensatorHyperRetraction(Counts)]---Floats with N2-compensators
  require the piston to be hyper-retracted in order to descend from the
  surface to the park level.  The valid range is 0-254 counts.

\item[DownTime(Minutes)]---This determines the length of time that the float
  drifts at the park pressure before initiating a profile.  The valid range
  of the argument is 1~minute to 30~days.

  \emph{Note:} If the \textbf{TimeOfDay} feature is enabled then the length
  of the whole profile cycle will turn out to be an integral number of days.
  The user should specify the down-time to be precisely 1~day less than the
  desired length of the profile cycle.  For example, if profiles are to be
  executed every 10~days then the down-time should be specified to be 9~days
  (ie., 12960~minutes).

\item[FlashErase()]---This command requires no argument and causes the FLASH
  memory chip to be reformatted.  \textbf{WARNING:} All contents of the
  FLASH file system will be destroyed.

\item[FlashCreate()]---This command requires no argument and causes the
  FLASH file system to be reinitialized.  This command is time consuming
  (~30 minutes) and energy-expensive.  The process involves writing a test
  pattern to each 8KB block of the FLASH ram and then re-reading the
  contents to ensure that the test pattern matches what was written.  If bad
  blocks are discovered then they are added to a bad-block list.  Blocks
  identified in the bad block list are not used for storage.
  \textbf{WARNING:} All contents of the FLASH file system will be destroyed.

\item[FloatId()]---The 4-digit float identifier.  This configurator is for
  disaster recovery only and should never be necessary.
      
\item[MaxLogKb(Kilobytes)]---The maximum size of the logfile in kilobytes.
  Once the log grows beyond this size, logging is inhibited and the logfile
  will be automatically deleted at the start of the next profile.  The valid
  range of the argument is 5-60~kilobytes.

\item[ParkDescentTime(Minutes)]---This time determines the maximum amount of
  time allowed for the float to descent from the surface to the park
  pressure.  The active ballasting phase is initiated when the park descent
  time expires.  The valid range of the argument is 0-8~hours.

\item[ParkPistonPos(Counts)]---The \apf\ firmware retracts the piston to the
  park piston position in order to descend from the surface to the park
  pressure.  The park piston position should be set so that the float will
  become neutrally buoyant at the park pressure.  The valid range of the
  argument is 1-254~counts.
                                 
\item[ParkPressure(Decibars)]---This is the target pressure for the active
  ballasting algorithm during the park phase of the mission cycle.  The
  valid range of the argument is 0-2000~decibars.

\item[PnPCycleLen()]---A deep profile is initiated when the internal profile
  counter is an integral multiple of park-n-profile cycle length.  All other
  profiles will be collected from the park pressure to the surface.
      
\item[Pwd()]---The password used to login to the host computer.  This
  configurator is dangerous and intended for disaster recovery only---its
  use is strongly discouraged.

\item[TelemetryRetry(Minutes)]---This determines the time period between
  attempts to successfully complete telemetry tasks after each profile.  The
  valid range of the argument is 1~minute to 6~hours.

\item[TimeOfDay(Minutes)]---This allows the user to specify that the
  down-time should expire at a specific time of day (ToD).  For example, the
  ToD feature allows the user to schedule profiles to happen at night.

  The ToD is expressed as the number of minutes after midnight (GMT).  The
  valid range is 0-1439 minutes.  Any value outside this range will cause
  the ToD feature to be disabled.

\item[UpTime(Minutes)]---This determines the maximum amount time allowed to
  execute the profile and complete telemetry.  The valid range of the
  argument is 1~minute to 1~day.

\item[User()]---The login name on the host computer that the float uses to
  upload and download data.  This configurator is dangerous and intended for
  disaster recovery only---its use is strongly discouraged.

\item[Verbosity()]---An integer in the range [0,4] that determines the
  logging verbosity with higher values producing more verbose logging.  A
  verbosity of 2 yields standard logging.  Increased verbosity will probably
  require increased logging capacity via the \textbf{MaxLogKb()}
  configurator.

\end{description}

\subsection{The (linux) \emph{chkconfig} utility.}
\label{sec:MissionNazi}

The ocean is very skilled at finding and exploiting the weaknesses of both
the float and its operator.  The remote control feature offers new and
useful applications for floats but it also necessarily introduces new
weaknesses.  

One particularly worrisome weakness is the potential for accidental
misconfiguration of a float via 2-way commands as described in
Secion~\ref{sec:RemoteControl}.  The \emph{chkconfig} utility helps to
protect against common kinds of misconfigurations by subjecting a mission
configuration file to the \emph{Configuration Supervisor} (see
Section~\ref{sec:ConfigSupervisor}).  The \emph{chkconfig} utility reads a
proposed mission configuration file and merges its parameters with the
float's existing configuration.  The merged configuration is then subjected
to the \emph{Configuration Supervisor} to determine if the merged
configuration is valid.

For example, suppose that the float's current configuration is represented
by the configurators in \textbf{mission.current}:
\begin{verbatim}
   AscentTimeOut(540)
   AtDialCmd(ATDT0012066859312)
   AtDialCmd(ATDT0012066163256) 
   BuoyancyNudge(5)
   CompensatorHyperRetraction(0)
   ConnectTimeOut(60)
   CpActivationP(1000)
   DeepProfileDescentTime(300)
   DeepProfilePistonPos(16)
   DeepProfilePressure(2000)
   DownTime(1440)
   InitialBuoyancyNudge(22)
   MaxLogKb(40) 
   ParkDescentTime(300)
   ParkPistonPos(24)
   ParkPressure(1000)
   PnPCycleLen(1)
   TelemetryRetry(15)
   TimeOfDay(-1)
   UpTime(660)
   Verbosity(2)
\end{verbatim}

Next suppose that the mission is to be configured for rapid cycling by
applying a single configurator in \textbf{mission.cfg}:
\begin{verbatim}
   # Configure the down-time for 8 hours
   DownTime(480) [0x2493]
\end{verbatim}

To check the validity of the proposed configuration for rapid cycling,
execute the command:
\begin{verbatim}
   chkconfig if=mission.cfg cfg=mission.current
\end{verbatim}
{\tiny \begin{verbatim}
         (Apr 14 2006 22:17:37) chkconfig            Validating the float's current configuration.
         [snippage]
         (Apr 14 2006 22:17:37) chkconfig            The float's current configuration is accepted.
         (Apr 14 2006 22:17:37) chkconfig            Validating the float's new configuration.
         (Apr 14 2006 22:17:37) configure()          Parsing configurators in "mission.cfg".
         (Apr 14 2006 22:17:37) configure()             DownTime(480) [0x605A] [DownTime(480)].
         (Apr 14 2006 22:17:37) configure()          Configuration CRCs and syntax OK.
         (Apr 14 2006 22:17:37) ConfigSupervisor()   Constraint violated: cfg->TimeDown > cfg->TimeParkDescent+cfg->TimeDeepProfileDescent
         (Apr 14 2006 22:17:37) ConfigSupervisor()   Sanity check violated: cfg->TimeDown > cfg->TimeDeepProfileDescent + cfg->TimeParkDescent + 2*Hour
         (Apr 14 2006 22:17:37) ConfigSupervisor()   Configuration rejected.
         (Apr 14 2006 22:17:37) configure()          Configuration rejected by configuration supervisor.
         (Apr 14 2006 22:17:37) chkconfig            Configuration file invalid.
\end{verbatim}}
   
The \emph{Configuration Supervisor} detected violations of one constraint
and one sanity check---the proposed configuration is rejected on the basis
of the constraint violation.  

The constraint violation indicates that the down-time must be (strictly)
greater than the park descent period plus the deep-profile descent period.
The definition of the sequence points in
Section~\ref{sec:DeconstructProfileCycle} requires that the down-time
includes the park-descent phase, the park phase, and the deep-descent phase.
Since 480~minutes of down-time does not allow for 300~minutes for each of
the two descent periods then the proposed configuration is an example of an
impossible mission.

If the down-time is lengthed to 601~minutes to make the mission possible
then the \emph{chkconfig} command responds with
{\tiny \begin{verbatim}
         (Apr 14 2006 22:54:22) chkconfig            Validating the float's current configuration.
         [snippage]
         (Apr 14 2006 22:54:22) chkconfig            The float's current configuration is accepted.
         (Apr 14 2006 22:54:22) chkconfig            Validating the float's new configuration.
         (Apr 14 2006 22:54:22) configure()          Parsing configurators in "mission.cfg".
         (Apr 14 2006 22:54:22) configure()             DownTime(601) [CRC=0x17A2] [DownTime(601)].
         (Apr 14 2006 22:54:22) configure()          Configuration CRCs and syntax OK.
         (Apr 14 2006 22:54:22) ConfigSupervisor()   Sanity check violated: cfg->TimeDown > cfg->TimeDeepProfileDescent + cfg->TimeParkDescent + 2*Hour
         (Apr 14 2006 22:54:22) ConfigSupervisor()   Configuration accepted.
         [snippage]
         (Apr 14 2006 22:54:22) ../bin/chkconfig     Configuration file OK.
\end{verbatim}}
   
This fixed the constraint violation but the \emph{Configuration Supervisor}
still warns of a sanity check violation.  The sanity check indicates that
the proposed configuration does not allow sufficient time for the active
ballasting mechanism to make any buoyancy adjustments.  This condition is
not likely to be fatal to the float.  However, the float will not likely to
be able to perform the intended mission because the active ballasting
mechanism will not drive the float to the programmed park pressure.
   
\subsection{Group-wise or fleet-wise remote control.}
\label{sec:FleetRemoteControl}

As an advanced technique, it is possible to write configurations suitable
for uniform control of groups or fleets of floats.  Such techniques
facilitate some kinds of field experiments while obviously limiting some
kinds of flexibility or individualization.  This technique is still
experimental and beyond the scope of this manual (for now).  Contact the
author for more details.

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "IridiumApex"
%%% End: