.. _coarseSunSensor:

:module-type:`C++` Module: coarseSunSensor
==========================================

.. sidebar:: Auxiliary Files
   :class: bsk-module-auxiliary

   * :doc:`Unit tests <_UnitTest/index>`

.. toctree::
   :hidden:
   :maxdepth: 1

   Unit tests <_UnitTest/index>

Executive Summary
-----------------

This class is designed to model the state of a single coarse sun sensor
attached to a spacecraft.  It emulates the "counts" that will typically be
output by the ADC on board of a spacecraft.

The module
:download:`PDF Description </../../src/simulation/sensors/coarseSunSensor/_Documentation/Basilisk-CoarseSunSensor-20170803.pdf>`
contains further information on this module's function,
how to run it, as well as testing.
The corruption types are outlined in this
:download:`PDF Description </../../src/simulation/sensors/imuSensor/_Documentation/BasiliskCorruptions.pdf>`.

Sensor Noise Model
------------------

The nominal sensor error is a scalar Gauss-Markov process,

.. math::

    e_{k+1} = a e_k + w_k, \qquad
    w_k \sim \mathcal{N}(0, \mathtt{senNoiseStd}^2),

where ``a`` is the one-by-one propagation matrix configured with
``setAMatrix()``. The default value is ``a = 0``, so setting only a positive
``senNoiseStd`` adds independent white Gaussian noise with the requested
standard deviation to each measurement::

    css = coarseSunSensor.CoarseSunSensor()
    css.senNoiseStd = 0.017  # [-]

Temporally correlated noise is enabled explicitly by setting a nonzero
propagation factor. For :math:`|a| < 1`, the stationary error standard
deviation is

.. math::

    \sigma_e = \frac{\mathtt{senNoiseStd}}{\sqrt{1-a^2}}.

An identity propagation matrix creates a random walk. A positive
``walkBounds`` value applies a hard bound to that error state::

    css.setAMatrix([[1.0]])
    css.walkBounds = 0.05  # [-]

A non-positive ``walkBounds`` disables hard clipping; it does not disable
state propagation. The matrix configured by ``setAMatrix()`` applies only to
the nominal measurement-noise model and does not alter the separate CSS fault
noise model.

.. warning::
  Be careful when generating CSS objects in a loop or using a function! It is often
  convenient to initialize many CSS' with the same attributes using a loop with a
  function like ``setupCSS(CSS)`` where ``setupCSS`` initializes the field of view,
  sensor noise, min / max outputs, etc. To prevent the CSS object from being garbage collected,
  you need to keep a reference to it by storing it on your simulation object. For example:

.. code-block:: python

    # Create and configure CSS
    css = coarseSunSensor.CoarseSunSensor()
    setupCSS(css)
    # Store reference on simulation object to keep it alive
    scSim.css = css  # This prevents Python from garbage collecting the CSS object

The coarse sun sensor module also supports user-enabled faulty behavior by assigning
a values to the ``.faultState`` member of a given sensor. An example of such call
would is ``cssSensor.faultState = coarse_sun_sensor.CSSFAULT_OFF`` where ``cssSensor``
is an instantiated sensor, and ``coarse_sun_sensor`` is the imported module.

The module currently supports the following faults:

.. list-table:: ``CoarseSunSensor`` Fault Types
    :widths: 35 50
    :header-rows: 1

    * - Fault Enumeration
      - Description
    * - ``CSSFAULT_OFF``
      - CSS no longer provides a signal (output = 0)
    * - ``CSSFAULT_STUCK_CURRENT``
      - CSS signal is stuck on value from past timestep
    * - ``CSSFAULT_STUCK_MAX``
      - CSS signal is stuck on the maximum value
    * - ``CSSFAULT_STUCK_RAND``
      - CSS signal is stuck on a random value
    * - ``CSSFAULT_RAND``
      - CSS produces random values



Message Connection Descriptions
-------------------------------
The following table lists all the module input and output messages.  The module msg connection is set by the
user from python.  The msg type contains a link to the message structure definition, while the description
provides information on what this message is used for.

.. bsk-module-io:: coarseSunSensor
    :caption: ``CoarseSunSensor`` Module I/O Messages

    input sunInMsg SpicePlanetStateMsgPayload
       input message for sun data

    input stateInMsg SCStatesMsgPayload
       input message for spacecraft state

    output cssDataOutMsg CSSRawDataMsgPayload
       output message for CSS output data

    output cssConfigLogOutMsg CSSConfigLogMsgPayload
       output message for CSS configuration log data

    input sunEclipseInMsg EclipseMsgPayload
       (optional) input message for sun eclipse state message

    input albedoInMsg AlbedoMsgPayload
       (optional) input message for albedo message

.. bsk-module-io:: CSSConstellation
    :caption: ``CSSConstellation`` Module I/O Messages

    output constellationOutMsg CSSArraySensorMsgPayload
       CSS constellation output message


----

.. bsk-module-guide-end::

.. doxygenfile:: coarseSunSensor.h
   :project: coarseSunSensor