.. _support: support@visionect.com

.. _javascript-sleep-support-label:

Device power management and sleep
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Device power consumption and, as a consequence, its battery life can be significantly reduced by turning the device off (i.e. sending it into sleep mode) for periods of time when the display content does not need to be changed. While the device is in sleep mode, its display will continue showing the last content displayed.

.. warning::
    While in sleep mode, client devices rely on an internal clock, making it impossible to wake them up remotely.

Sending client devices to sleep mode with okular.Sleep(periodMinutes)
---------------------------------------------------------------------

Users can set the sleep mode settings using by Sleep Manager in Management Interface. To activate the Sleep Manager feature, go to ``Settings ->Global ->Features`` in the Management Interface and check the ``Sleep Manager`` box.ore information is available in  :ref:`Device power management and Sleep Manager  <sleep-manager>`.

It is also possible to send a sleep command to a device directly from its WebKit session with the help of a simple JavaScript command. This function will send the device to sleep mode for the amount of time specified in minutes.

.. code-block:: javascript

    //periodMinutes = int, device sleep time in minutes
    //periodMinutes = 0, cancel unsent sleep command
    okular.Sleep(periodMinutes);

The Visionect Software Suite will make sure that in the event of an early wakeup (caused by a device reboot or other external factors), the device will return back to sleep mode. This functionality can be canceled by invoking ``okular.Sleep(0)``.

.. warning::
    You should call this function only if you know what are you doing. You have the power to send the device into the sleep mode for a very long time, but it might be difficult if not impossible to wake it up before schedule - especially if the hardware is physically inaccessible and cannot be power-cycled or rebooted manually.

Since the sleep command is in most cases sent immediately after the function call, you must be very careful not to call this function at the wrong time.

If you want to update the screen prior to sending the device to sleep mode, make sure you delay the sleep command - a call to this function can cause the device to go into sleep mode before the image is rendered on the device display.

This is even more important if you intend to send a device back into sleep mode every time it wakes up (``"device-connect"`` event), as the problem might not be apparent the first time you execute the function (due to the async nature of JavaScript). To avoid the problems and difficulties described above, you can use the Software Suite’s internal sleep scheduling mechanism which will handle all the details for you.

Sleep Manager
-------------

Some users do not need a very fine-grained control over the sleep functionality and only need to schedule a periodical wakeup for the screen sync. If that is the case, than you can use Software Suite’s internal sleep scheduling mechanism which will handle all the details for you. See :ref:`Device power Management and Sleep Manager <sleep-manager>` for more.  We recommend you use this mechanism if there is no real need to implement your own.


If the Sleep Manager is turned on and configured, then it will manage the periodical connect of the client devices. You can configure when the devices are to connect by using the Management Interface or by running the JavaScript functions created for this purpose:

.. code-block:: javascript

    okular.SleepSchedule(time, periodic);

The parameters are:

``time``: Time in minutes.
``periodic``: The boolean parameter that defines how time is handled.

- If ``periodic == true`` then the ``time`` parameter defines the  the lenghts of time in minutes the device is to sleep.


.. code-block:: javascript

    //lets device to connect every full hour and refresh its display.
    okular.SleepSchedule(60, true);

- If ``periodic == false`` then the ``time``  parameter defines the minute of day the device is to wake up.

.. code-block:: javascript

    //sets the device to wake up at 2:00 am every day.
    okular.SleepSchedule(120, false);

- To remove the schedule run:

.. code-block:: javascript

    okular.RemoveSleepSchedule()

Example:

.. code-block:: html

    <!DOCTYPE html>
    <html>
    <head>
    <script>
            window.onload = function() {
                    //setup scheduler
                    var time = new Date().toString();
                    console.log("okular.SleepSchedule(60, true)");
                    okular.SleepSchedule(60, true);
                    document.getElementById("timep").innerHTML = time;
            }

    </script>
    </head>
    <body>
            <p>Simple Page</p>
            Load Time: <p id='timep'></p>
    </body>
    </html>

React to a connect event
------------------------

The device connect event functionality can be used to set a device’s session to a certain state when a device disconnects  (example: printing out “out of range” on the screen) or can be used as a periodical sleep setup in conjunction with ``"okular.Sleep(periodMinutes);"``. When a device connects to the Software Suite, the ``"device-connect"`` event is triggered and provides two ``detail`` parameters.

- *Connected device uuid:* ``e.detail.device``

- *Connect reason:* ``e.detail.reason``

    The possible values are:

    - ``"unknown"``
    - ``"reboot"``
    - ``"wakeup"``
    - ``"heartbeat"``
    - ``"logs full"``
    - ``"connection error"``
    - ``"protocol error"``
    - ``"command line"``

Example:

.. code-block:: javascript

    document.addEventListener("device-connect", handleConnect, true);

    function handleConnect(e)
    {
        console.log("device-connect", e.detail.reason, e.detail.device);
    }


.. note::
    When a device connects to the Visionect Software Server for the first time, or when a new WebKit session is created, a connection event is not triggered.



Configure device's hardware settings
------------------------------------

The following API is designed to change a client device’s configuration, requiring you to  connect the client device to the Micro USB configuration cable and configure by using CLI. As an alternative way, you can also change a device’s configuration by using TCLV commands as described in :ref:`js-device-config`.

.. note::
    Use the following configuration settings only when sure of what you are doing.

**Change or disable the heartbeat interval**

The following command changes the device heartbeat interval - the time after which the device will report back to the Software Suite.

.. code-block:: javascript

    okular.SetHeartbeat(minutes);

- *minutes* is the new HB interval for device(s)
- *limitations:* 0 <= minutes < 60
- *disabling HB:* if minutes == 0, HB will be disabled

------

**Enable/Disable the battery indicator and touch**

Configure a client device’s battery indicator, connection indicator and its touch panel operation.

.. code-block:: javascript

    okular.ConfigureSystem(batteryIndicator, touch [,disconnectedIndicator]);

*bateryIndicator* (bool) Sets the device to display a “battery empty” display when the battery is depleted.

The supported values for the bit-field *touch* (bool or int) are:

.. code-block:: javascript

    // system command touch options
    okular.SystemTouchOff          = 0x00000000; // touch is disabled
    okular.SystemTouchOn           = 0x00000001; // touch is enabled
    okular.SystemTouchOnBeep       = 0x00000003; // touch is enabled and device will beep when touched

.. note::

    In Visionect Software Suite version 2.7 touch was always a boolean type. Depending on its value, it switched touch support on device ON(true) or OFF(false). This behavior is deprecated in Software Suite version 2.8 +, but still supported.
    The following touch options will only work on devices with the touchscreen and firmware version that supports buzzer.


*disconnectedIndicator* (optional bool) Sets the device to display a “disconnected” screen when disconnected from the network.

------

**Configure the battery indicator**

Configure when the battery indicator is displayed on screen. The default values should work best, but you could tweak this to suit your needs.

.. code-block:: javascript

   okular.ConfigureBattery(tresholdOff, tresholdOn [, tresholdCount = 1])

- *tresholdOff* Battery integer value in [mV]. The value that client devices use to decide if the battery is empty and display an “battery empty” display.

- *tresholdOn* Battery integer value in [mV]. The bootloader will refuse to boot if the battery is lower than this value.

- *tresholdCount* - (optional) Integer that defaults to 1. If the battery is being charged, this count lets the bootloader know how many times it should compare the battery to the ``tresholdOn`` before giving up.

Example:

.. code-block:: javascript

 okular.ConfigureBattery(3497, 3696, 1).then(function(result) {
      console.log(result); // Success: stuff worked!
  }, function(err) {
      console.log(err);
      // Error: Maybe retry later.
  });

------

**Configure a client device’s display VCOM**


For optimal display drawing performance, each Visionect client device display comes with it’s optimal VCOM voltage. The API allows us to set the VCOM voltages for up to 8 displays. Since VCOM is always a negative value, the API omits the minus sign, and also accepts absolute values. The value should be sent in [mV].

.. code-block:: javascript

   okular.SetVcom(vcomArray)

.. warning::

    Your client device is already configured with the VCOM setting, so it is not recommended to change it. If you have accidentally overwritten the VCOM or need more information about this setting, please contact our support_ .

------

**Configure the device display type**

Visionect firmware supports many different display types. Different display types support different waveforms and different sizes. A device can render images correctly only if it knows what type of display is connected to it. Do not change this setting unless you know the display ID you should use.

.. code-block:: javascript

   okular.SetDisplayID(displayID)

.. warning::

    Your client device is already configured with this setting, so it is not recommended to change it. If you require more information about this setting, please contact our support_ .