/** \page req Tethys/LRAUV Requirements
 *
 * The Tethys/LRAUV software requirements are divided in the following sections:
 * \li \subpage req_arch
 * \li \subpage req_timing
 * \li \subpage req_scripting
 * \li \subpage req_bit
 * \li \subpage req_storage
 * \li \subpage req_decimation
 * \li \subpage req_syslog
 * \li \subpage req_processing
 * \li \subpage req_comms
 * \li \subpage req_sim
 */

/**
 * \page req_arch Architectural Requirements
 *
 * \section req_arch_layered Use a state-configured layered control architecture
 * - This requirement is based on favorable experience with layered control
 *   in the past, combined with its capability to working in conjunction
 *   with out-of-process planners and schedulers, as demonstrated on the MBARI
 *   Dorado AUV.
 *
 * \section req_arch_modular Limit the interconnectedness of code to minimize full-system recompiles.
 * - The intent of this requirement is to:
 *   -# allow users to add functionality to the code base, without having
 *      access to the entire code base -- only to those headers required
 *      for building a module. This may be intellectual property issue for
 *      the party that licenses the Tethys/LRAUV for production.
 *   -# reduce the need for full recompilation as part of the vehicle
 *      reconfiguration process
 *   -# allow the distribution of new vehicle functionality as software modules
 *   -# allow a faulty module to be swapped out, potentially at sea,
 *      without swapping out the entire executable.
 *   -# enforce a "clean" interface between software components.
 *   -# provide a flexible API that can accommodate scripted code as
 *      well as compiled code.
 * - The classes under the modules \ref module and \ref component
 *   provide this functionality.
 *
 * \section req_arch_slate Channel communications between software units through a single “slate”
 * - The intent is to provide asynchronous communication between software
 *   elements, and provide a single-point view on the state of the vehicle and
 *   the software at any point in time.  The state table also provides a common
 *   location and mechanism for data logging.
 *
 * \section req_arch_universal Use "Universal" Data Values
 * - In some cases, there will be multiple sources of information for a given
 * measurement.  For example, there will likely be a primary pressure sensor,
 * but possibly also auxiliary pressure sensors on other instrumentation, as
 * well as a dead-reckoned pressure estimate.  What if the primary pressure
 * sensor fails?  If a controller is expecting pressure from the primary
 * pressure sensor, it too will fail.  However, if it is just expecting
 * "pressure", an intelligent agent could give it the "best available" pressure
 * at the time of request.
 * - The intent of this requirement is to provide such a strategy for the LRAUV.
 *
 * \section req_arch_simple Simplify code execution to simplify debugging
 * - The intent of this requirement is to ensure that if the code hits a
 *   breakpoint, the programmer has a high degree of confidence that the
 *   other parts of the code will also stop.
 * - This requirement does not preclude using multiple threads or multiple
 *   processes.
 * - Our approach to meeting this requirement is to use sequential nested
 *   threads, described under \ref des_threads
 *
 * \section req_arch_isolate Isolate, log, and tolerate software faults
 * - e.g. segmentation faults, etc.
 * - Our approach to meeting this requirement, along with the requirement:
 *   \ref req_arch_simple, is to use sequential nested threads, described
 *   under \ref des_threads
 *
 * \section req_arch_dependency Track dependencies of code segments upon each other
 * - Intent is to be able to see how failures propagate through the system,
 *   automating and internalizing a portion of the vehicle's failure mode
 *   effects analysis.
 * - Information for tracking dependencies is provided by having components
 *   declare to the slate what their inputs and outputs are, by name. This
 *   allows the system to create a forward and backward dependency tree for
 *   each variable. It allows one to see what failures may affect a
 *   computation unit, and to see how the failure of a sensor (for example) may
 *   affect the capability of the system to execute mission commands and
 *   behaviors.
 * - \todo Automatically generate failure effects analyses in the event of
 *   failures, and use these analyses to avoid unachievable mission states.
 *
 * \section req_arch_plannerCompatablity Allow future integration of on-vehicle mission planning and scheduling.
 * - Implemented by allowing vehicle to accept new plans via communications channels (including on-vehicle communications)
 * - See (\ref req_comms) \ref req_comms_sendMission
 *
 */

/**
 * \page req_timing Control and Timing Requirements
 *
 * \section req_timing_adjustablePeriod Allow the core vehicle control and navigation loop period to be changed.
 * - Fulfilled by class LoopControl
 * - todo Provide behavior that sets LoopControl
 *
 * \section req_timing_accurateStart The vehicle control loop (start time) must be accurate to within 10 ms
 * - Supervisor::Supervisor() sets process priority to -20 to meet this requirement
 * - \todo Need to do profile testing to verify this requirement has been met
 *
 * \section req_timing_dataAsync Allow science data acquisition to occur asynchronous to core vehicle control
 * - Awaiting implementation of science sensor serial electronics
 * - \todo Modify ReadSensor to allow asynchronous reads
 *
 * \section req_timing_dataLoop Allow science data acquisition to occur at a variable loop period
 * - \todo Modify ReadSensor to allow variable loop periods.
 *
 * \section req_timing_dataTrigger Allow science data acquisition to be triggered by some state change
 * - i.e. going through a depth, etc.
 * - Allowed by applying When and While constructs to the ReadSensor behavior/command
 *
 * \section req_timing_tolerant Vehicle attitude/navigation/control software must be tolerant to the presence/absence of sensors
 * - i.e. turning off sensors (for low power) and should be able to handle the on/off transients without incident.
 * - InternalSim may provide missing sensor readings for short periods of time during on/off transients.
 * - \todo Need to test this.
 *
 * \section req_timing_timeStamp It must be possible to control (in code) how the time tag for a particular piece of data is selected.
 * - i.e. timestamp when sent to log vs. when measurement was actually made
 * - DataWriter::write and DataWriter::writeWithAccuracy meet this requirement
 *
 * \section req_timing_accurateStorage Time values must be stored to at least millisecond resolution, with the option for less resolution.
 * - Default is to store data with 1 microsecond resolution, as coded in
 *	 implementations of LogEntry::Read and LogEntry::write
 * - \todo Implement 1 millisecond optional resolution to save log space
 *
 * \section req_timing_lastUpdate Time of last update for every data value must be available.
 * - Available through DataReader::getTimestamp and DataWriter::getTimestamp
 *
 */

/**
 * \page req_scripting Mission Scripting Requirements
 *
 * \section req_scripting_simple Simple operations must be simple to "code"
 * - "code" may mean writing a script or using a gui to create bytecode, etc.
 * - Important, but subjective requirement.
 *
 * \section req_scripting_constants Allow specification of constants in the Mission that are stored in the Slate
 * - Not implemented yet.
 * - \todo Implement \ref req_scripting_constants
 *
 * \section req_scripting_byName In mission, function arguments must be specified by name
 * - Since values can only be passed through readers and writers (which must be named), this is pretty well enforced.
 *
 * \section req_scripting_units In mission, function arguments must have intrinsic units
 * - i.e., meter(9), celsius(12), etc.
 * - Enforced through the definition of DataValue: a value associated with a unit.
 *
 * \section req_scripting_combination Allow creation of more complex behaviors by combining simpler behaviors
 * - Achieved - for example, one could combine a temperature-controlled DepthEnvelope behavior with a YoYo behavior to achieve a temperature-controlled YoYo
 *
 * \section req_scripting_behaviors Must be possible to develop new commands and behaviors without recompiling code.
 * - Allowed though Scripting
 * - \todo fix and test Scripting
 *
 * \section req_scripting_startStop Allow mission stacks, commands, and behaviors to be started and stopped based on observations or system state
 * - i.e., GPS fixes to keep vehicle on track, uploads to keep ground personnel aware of status
 * - Enabled through When, While, and Until mission clauses (see MissionItem)
 *
 * \section req_scripting_branching Allow for branching in mission
 * - While there is no "If/Then/Else" syntax yet, the desired effect
 *   can be achieved reactively via When and While mission clauses (see MissionItem),
 *   or imperatively by embedding the clauses in a sequential stack
 *   that wraps each branch.
 *
 * \section req_scripting_looping Allow for looping in mission
 * - Enabled through Repeat mission clause (see MissionItem)
 *
 * \section req_scripting_humanReadable Mission language must be human readable
 * - Implemented through an API that leverages the Lua scripting language
 *
 * \section req_scripting_machineReadable Mission language must machine readable.
 * - Implemented through an API that leverages the Lua scripting language
 *
 * \section req_scripting_typeChecking Mission language must enable strong type checking
 * - Scripting API makes it hard to specify the wrong parameter for a behavior/command
 *
 * \section req_scripting_unitChecking Mission language must enable unit checking.
 * - Units must be specified for all DataValues passed to behaviors and commands
 */

/**
 * \page req_bit Built in Test (BIT) Requirements
 *
 * \section req_bit_estimateEnergy Must be able to estimate energy required to fulfill the "next" mission state.
 * - i.e., always know that you have enough energy to get "home" after completing the next behavior or set of behaviors.
 * - Not implemented yet.
 * - likely requires the fufillment of (\ref req_sim) \ref req_sim_emulation
 * - \todo Implement \ref req_bit_estimateEnergy
 *
 * \section req_bit_estimateDegredation Estimate vehicle degradation, based on performance history and use these estimates in vehicle control and energy estimates.
 * - Not implemented yet.
 * - \todo Implement \ref req_bit_estimateDegredation
 */

/**
 * \page req_storage Data Storage Requirements
 *
 * \section req_storage_metadata Data must must be self-describing or tightly coupled to a metadata descriptor/schema file
 * - Should include units, description of data.
 * - In the current implementation, a file named "slate.dir" is written along with
 *   the binary output log. This "slate.dir" is managed by the Slate class.
 * - Every time a reference to a named code unit is made via
 *   Slate::GetName( const Str& name ) (called by Component and Logger constructors),
 *   if the name is new and unique, then Slate::WriteNameDirectory is called to
 *   add the name to slate.dir
 * - Every time Slate::NewInputReader Slate::NewReader or Slate::NewWriter
 *   or Slate::NewUniversalReader or Slate::NewUniversalWriter is called
 *   a new DataElement (aka slate variable) is constructed.
 *   The DataElement constructor calls Slate::GetElementURI( const ElementURI& elementURI ),
 *   which calls Slate::WriteElementURIDirectory to add the element name to slate.dir.
 * - Also, calls to create new instances of DataReader or DataWriter call the
 *   DataAccessor constuctor, which calls Slate::GetDataAccess -- which
 *   may call Slate::WriteDataAccessDirectory if the DataAccess is new. The
 *   DataAccess contains metadata about the variable.
 *
 * \section req_storage_compact Data must be logged in a space-efficient format.
 * - This is a subjective requirement, but efforts have been made to
 *   keep the log as compact as possible. For example:
 *   -# Bit-packing flags
 *   -# The creation of DataValue types such as Float, Float3, and Float2 to
 *      allow for low-resolution logging of floating-point values.
 *   -# Logging of compressed 16 and 64 bit integers (for ids and timestamps) using
 *      OutStream::writeShortCompact OutStream::writeLongLongCompact -- and
 *      logging only timestamp differences within a cycle.
 *
 * \section req_storage_bufferLoss Lose no more than one compute cycle of data in the event of a catastrophic failure
 * - i.e. kernel crash or sudden power disconnect.
 * - LogEngine runs at the end of computations in each compute cycle.
 * - Each cycle starts with a "0" in the log file. Due to compression of
 *   values in the log, the value "0" is surprisingly unique. However, testing may
 *   encourage us to select a more unique (i.e., multi-byte) value.
 * - \todo Test ability to recover from corrupted files.
 *
 * \section req_storage_fileLoss Data file format must minimize data loss in the event of file corruption
 * - i.e. to minimize the amount of data lost in the case of one or more byte-errors.
 * - Also, a new log file will be started each hour during a mission, so that a
 *   completely corrupted log file will destroy at most one hour of data.
 * - \todo Implement new file every hour.
 *
 * \section req_storage_efficient Data logging system must be optimized for power- and processor efficiency
 * - Data is logged at the end of each cycle. Achieves requirement
 *   \ref req_storage_bufferLoss, while avoiding complications
 *   of running logging in its own thread (and there
 *   appears to be a significant cost for context-switching on the arm9 processor).
 *
 * \section req_storage_new New variables (from control and science sensors) must be handled without recompilation.
 * - As described under requirement req_storage_metadata, the system can
 *   accommodate new variables appearing on the fly.
 *
 * \section req_storage_version Data files must include format versioning information
 * - to address cross- and backwards compatibility between writers and readers.
 * - The first write to slate.dir is a version packet, written by Slate::WriteVersion
 *
 * \section req_storage_missionState Data sets must include information on the currently running missions and the current state within that mission.
 * - Currently, such transitions are only stored as free-text SyslogEntry instances.
 * - \todo Log mission transitions as EventEntry instances.
 *
 * \section req_storage_double Double-precision floating point must be loggable.
 * - The Double class extends the abstract DataValue class to provide logging of
 *   double-precision floats.
 *
 * \section req_storage_float Less than double-precision floating point must be loggable for space efficiency.
 * - The Float, Float3, and Float2 classes extend the abstract DataValue class to provide logging of
 *   4-byte, 3-byte, and 3-byte lower precision floats (internally, they all use 4-byte floats).
 * - The Location class logs latitude and longitude pairs as 6-byte floats (but uses
 *   a full 8-byte float internally).
 *
 * \section req_storage_integer 32-bit, and 8-bit integers must be loggable.
 * - The Int and UChar classes extends the abstract DataValue class to provide logging of
 *   4-byte, 1-byte integers (internally, they both use 4-byte integers).
 *
 * \section req_storage_scaling Scaling values for storing floating values as integers must be available.
 * - Not implemented
 * - \todo Implement \ref req_storage_scaling
 *
 * \section req_storage_string It must be possible to log variable-length strings
 * - The StrValue class DataValue the abstract DataValue class to provide logging of
 *   Str "string" values.
 *
 */

/**
 * \page req_decimation Data Decimation for Transfer Requirements
 *
 * A key component of the vehicle communications scheme is the ability to
 * transmit subsets of mission data back to shore, either for mid-mission
 * quality control or to provide input for mission changes.
 *
 * A "decimator" software component could fulfill this role by using flexible
 * data parsing "recipes" to sub-select log data and compress the data
 * to minimize packet size.
 *
 * The decimator could run in two modes: running persistent recipes to make
 * data subsets in realtime, and executing recipes over archived data, for
 * example in anticipation of communications (as the vehicle is surfacing) or
 * on demand from the topside.
 *
 * \section req_decimation_recipes Allow selection of pre-defined decimation "recipes".
 * - Not implemented.
 * - \todo Implement \ref req_decimation_recipes
 *
 * \section req_decimation_adhoc Allow specification of ad-hoc decimation commands
 * - i.e. "now send me temperature data from 8 PM to 10 PM in higher resolution"
 * - Not implemented.
 * - \todo Implement \ref req_decimation_adhoc
 *
 * \section req_decimation_optimization Allow for optimization on data packet size, data precision, time resolution
 * - Not implemented.
 * - \todo Implement \ref req_decimation_optimization
 *
 * \section req_decimation_variables Include provisions for including or excluding variables.
 * - Not implemented.
 * - \todo Implement \ref req_decimation_variables
 *
 * \section req_decimation_windows Allow selection based on time windows
 * - Not implemented.
 * - \todo Implement \ref req_decimation_windows
 *
 * \section req_decimation_state Allow selection based on vehicle state changes
 * - e.g. data from the first hour of the mission "Mission1"
 * - Not implemented.
 * - \todo Implement \ref req_decimation_state
 *
 * \section req_decimation_indirect Allow selection based on other variables
 * - e.g. data from 20 minutes centered around every time the temperature went about 20deg K)
 * - Not implemented.
 * - \todo Implement \ref req_decimation_indirect
 */

/**
 * \page req_processing Data Post-Processing Tool Requirements
 *
 * \section req_processing_selfDescribing A priori knowledge of the data types and fields in data files not required.
 * - Implemented in unserialize.cpp and LogEntry::Read, which can read the
 *   data and metadata stored in a LRAUV log file.
 *
 * \section req_processing_timeCorrelation Provide some basic time correlation functionality
 * - e.g., through binning
 * - TextTableLogWriter can provide this in a very basic way -- it assumes values stay constant
 *   until they are reported as changed.
 * - \todo Provide more robust Data Post-Processing tool for meeting requirement: \ref req_processing_timeCorrelation
 *
 * \section req_processing_spaceCorrelation Provide basic position (lat/lon/depth) correlation functionality
 * - KmlLogWriter and GPXLogWriter provided such correlations in a very rudimentary way,
 *   but only for lat, lon, and depth data.
 * - \todo Provide more robust Data Post-Processing tool for meeting requirement: \ref req_processing_spaceCorrelation
 *
 * \section req_processing_renavigation Allow for renavigation of vehicle data.
 * - This should be done in a way which is traceable and without modifying original source data.
 * - \todo Provide Data Post-Processing tool for meeting requirement: \ref req_processing_renavigation
 *
 * \section req_processing_stream Deal with data files both as a continuous time stream and as a sequence of discrete missions
 * - \todo Provide Data Post-Processing tool for meeting requirement: \ref req_processing_stream
 *
 * \section req_processing_syslog Filter system logs (see \ref req_syslog) on software unit or severity.
 * - Implemented through SeverityRule
 */

/**
 * \page req_syslog System Log Requirements
 *
 * \section req_syslog_info Provide capability for generating informational text logs
 * - Provided through Logger:syslog
 *
 * \section req_syslog_unified Write a single log for all software units.
 * - All logs are combined into the unified "syslog" text file.
 * - Optionally, logs may also be stored in the binary "slate"
 *   (doing so requries a change to the Supervisor::initialize
 *   code that assigns logging rules to the FileLogWriter for "slate")
 *
 * \section req_syslog_metadata Embed metadata to specify software unit and severity.
 * - Done via SyslogEntry::write
 *
 * \section req_syslog_timestamps Provide timestamps on all strings.
 * - Done via SyslogEntry::write
 *
 */

/**
 * \page req_comms Communications Requirements
 *
 * \section req_comms_multiple Establish and maintain communications across multiple media
 * - Ideally, choose the "fastest" pipe currently available
 * - Not implemented
 * - \todo Implement \ref req_comms_multiple
 *
 * \section req_comms_data Provide methods to transfer whole or parts of vehicle data to shore.
 * - Not implemented
 * - \todo Implement \ref req_comms_data
 *
 * \section req_comms_logs Provide methods to transfer whole or parts of vehicle system logs to shore.
 * - Not implemented
 * - \todo Implement \ref req_comms_logs
 *
 * \section req_comms_abstract Ideally Provide single communications API for different pipes
 * - e.g. An ethernet socket would run the same protocol as used across the satcomms,
 *   and the interface would appear the same to readers and writers
 * - Not implemented
 * - \todo Implement \ref req_comms_abstract
 *
 * \section req_comms_checksum Communications protocols must include checksumming capabilities commensurate with each pipe's specifications
 * - Not implemented
 * - \todo Implement \ref req_comms_checksum
 *
 * \section req_comms_setValue Allow any DataValue to be set via communications so that mission can respond to it.
 * - Not implemented
 * - \todo Implement \ref req_comms_setValue
 *
 * \section req_comms_pickMission Allow selection of currently running mission to be changed via communications
 * - Not implemented yet.
 * - \todo Implement \ref req_comms_pickMission
 *
 * \section req_comms_sendMission Allow user to send a new mission to vehicle via communications
 * - Not implemented yet.
 * - \todo Implement \ref req_comms_sendMission
 *
 * \section req_comms_sendMissionDifs Allow user to send a diffs for a new mission to vehicle via communications
 * - Not implemented yet.
 * - \todo Implement \ref req_comms_sendMissionDifs
 */

/**
 * \page req_sim Simulation Requirements
 *
 * In the context of this software, "simulation" refers to running a subset of
 * the vehicle software in an environment where vehicle elements outside the
 * purview of the software (actuators, sensors, the physical world) are
 * replaced by artificial substitutes. Due to the complexity and expense of
 * in-water testing (not to mention the opacity of the vehicle software while
 * underway), simulation is a key element in software testing.
 *
 * \section req_sim_source Use the vehicle source code for guidance (Layered Control), navigation, control, and logging.
 * - It need not include hardware-level drivers.
 * - Currently implemented (See ExternalSim and SimSlate)
 *
 * \section req_sim_remote Allow for running the simulation off the target while running the vehicle code on the target.
 * - Currently implemented (See ExternalSim and SimSlate)
 *
 * \section req_sim_dynamic Allow for full dynamic simulation.
 * - Currently implemented in Simulator class
 *
 * \section req_sim_kinematic Allow for fast kinematic simulation.
 * - Not implemented
 * - \todo Implement \ref req_sim_kinematic
 *
 * \section req_sim_emulation Allow for very fast mission emulation
 * - Faster than kinematic simulation.
 * - Not implemented
 * - \todo Implement \ref req_sim_emulation
 *
 *
 */