.. currentmodule:: obs
.. _obs:

Module OBS
==========

This module contains classes and functions specific to the Observator products.
The ``obs`` module contains functions for observator products accessing product information 

delay
-----------------------

.. function:: delay(ms)

   Delay for the given number of milliseconds.

udelay
-----------------------

.. function:: udelay(us)

   Delay for the given number of microseconds.

millis
-----------------------


.. function:: millis() -> integer

   Returns the number of milliseconds since the board was last reset.

   The result is always a MicroPython smallint (31-bit signed number), so
   after 2^30 milliseconds (about 12.4 days) this will start to return
   negative numbers.

micros
-----------------------

.. function:: micros() -> integer

   Returns the number of microseconds since the board was last reset.

   The result is always a MicroPython smallint (31-bit signed number), so
   after 2^30 microseconds (about 17.8 minutes) this will start to return
   negative numbers.

elapsed_millis
-----------------------

.. function:: elapsed_millis(start) -> integer

   Returns the number of milliseconds which have elapsed since ``start``.

   This function takes care of counter wrap, and always returns a positive
   number. This means it can be used to measure periods up to about 12.4 days.

   Example::

        import omc048
        import obs

        start = obs.millis()
        r1 = omc048.relay(1)
        #toggle a relay at 1 second interval
        while True:
            if obs.elapsed_millis(start) > 1000:
                r1.toggle()
                start = obs.millis()

elapsed_micros
-----------------------
.. function:: elapsed_micros(start) -> integer

   Returns the number of microseconds which have elapsed since ``start``.

   This function takes care of counter wrap, and always returns a positive
   number. This means it can be used to measure periods up to about 17.8 minutes.

   Example::

        import omc048
        import obs

        start = obs.micros()
        r1 = omc048.relay(1)

        #toggle a relay at 1 second interval
        while True:
            if obs.elapsed_micros(start) > 1000000:
                r1.toggle()
                start = obs.micros()

hard_reset
---------------------

.. function:: hard_reset()

   Resets the board on processor level.

soft_reset
---------------------
.. function:: soft_reset()

   Performs a soft reset of the interpreter, deleting all Python objects and resetting the Python heap.

fault_debug
---------------------
.. function:: fault_debug(value)

   Enable or disable hard-fault debugging.  A hard-fault is when there is a fatal
   error in the underlying system, like an invalid memory access.

   If the *value* argument is ``False`` then the board will automatically reset if
   there is a hard fault.

   If *value* is ``True`` then, when the board has a hard fault, it will print the
   registers and the stack trace, and then cycle the LEDs indefinitely.

   The default value is disabled, i.e. to automatically reset.

idle
-----------------------

.. function:: idle()

   Gates the clock to the CPU, useful to reduce power consumption at any time during
   short or long periods. Peripherals continue working and execution resumes as soon
   as any interrupt is triggered (on many ports this includes system timer
   interrupt occurring at regular intervals on the order of millisecond).

light/deep -sleep
---------------------
.. function:: lightsleep([time_ms])
              deepsleep([time_ms])

   Stops execution in an attempt to enter a low power state.

   If *time_ms* is specified then this will be the maximum time in milliseconds that
   the sleep will last for.  Otherwise the sleep can last indefinitely.

   With or without a timout, execution may resume at any time if there are events
   that require processing.  Such events, or wake sources, should be configured before
   sleeping, like `Pin` change or `RTC` timeout.

   The precise behaviour and power-saving capabilities of lightsleep and deepsleep is
   highly dependent on the underlying hardware, but the general properties are:

   * A lightsleep has full RAM and state retention.  Upon wake execution is resumed
     from the point where the sleep was requested, with all subsystems operational.

   * A deepsleep may not retain RAM or any other state of the system (for example
     peripherals or network interfaces).  Upon wake execution is resumed from the main
     script, similar to a hard or power-on reset.

device
---------------------
.. function:: device() -> 4-tuple

   Return a tuple (possibly a named tuple) containing information about the
   underlying machine and/or its operating system.  The tuple has four fields
   in the following order, each of them being a string:

        * ``serial`` -- the serial number of the device
        * ``name`` -- the device name
        * ``firmware`` -- the version of the firmware
        * ``bootloader`` -- the version of the firmware

==============================================================================================