.. |br| raw:: html

   <br/>

.. _electron-guide-index:

Electron Guide
==============

Introduction
------------

"Electron is a framework that enables you to create desktop applications with JavaScript, HTML, and CSS." - https://www.electronjs.org/docs/tutorial/quick-start

Electron requires **nodejs** and **npm** on your target to run.

This article will introduce you to run Electron on one of our Modules.


Demo Video
----------

.. youtube:: xY2QZl7sgZ8


Precompiled Images
------------------

.. note:: There are precompiled images, including our Electron Demo, available. |br|
   If you want to start developing yourself, just continue reading this guide.

+-------------------------------------+-----------------------------------------------+------------------------------------------------+
| Module                              | Precompiled Demo Image                        | Flashtools                                     |
+=====================================+===============================================+================================================+
| QSMP-1570                           | `qsmp-1570-electron-demo.zip`_                | :ref:`stm32-programmer-setup`                  |
+-------------------------------------+-----------------------------------------------+------------------------------------------------+


Yocto Setup
-----------

For creating the neccessary RootFS, a complete Yocto build environment is required.

Depending on your module choose the correct guide - if not already set up.

.. note:: **QSXP, QSXM, QS8M, TX8M, TX8P** use :ref:`nxp-yocto-guide-index`

.. note:: **QSMP, TXMP, TX6, TXUL** use :ref:`mainline-yocto-guide-index`


1. Setup the Yocto build-directory as described in the Yocto guide for your machine. Use the following values:

* ``DISTRO=karo-xwayland``

* ``MACHINE=<desired-machine>``

2. Append your ``conf/local.conf`` as follows.

+------------------------------------+-----------------------------------------+
| TX6, TXUL, QSMP, TXMP              | QS8M, QSXM, QSXP, TX8                   |
+====================================+=========================================+
|                                    |                                         |
| .. code-block:: text               | .. code-block:: text                    |
|                                    |                                         |
|    IMAGE_INSTALL_append = " \      |    IMAGE_INSTALL_append = " \           |
|        git \                       |        git \                            |
|        nodejs \                    |        nodejs \                         |
|        nodejs-npm \                |        nodejs-npm \                     |
|        cups \                      |        cups \                           |
|        libxscrnsaver \             |        libxscrnsaver \                  |
|    "                               |        at-spi2-atk \                    |
|                                    |        libxcomposite \                  |
|                                    |        libxrandr \                      |
|                                    |    "                                    |
|                                    |                                         |
|                                    |    IMAGE_ROOTFS_EXTRA_SPACE = "1048576" |
+------------------------------------+-----------------------------------------+

3. Compile the image.

.. code-block:: text

   bitbake karo-image-weston

4. Program your board using our manufacturing tools. **You can also boot the image from net/tftp**.

.. note:: **QSXP, QSXM, QS8M, TX8M, TX8P** use :ref:`uuu`

.. note:: **QSMP, TXMP** use :ref:`stm32-programmer-setup`

.. note:: **TX6, TXUL** use :ref:`mfg-tool-setup`


Start Demo Application
----------------------

.. note:: The Demo was written for a 640x480 screen. |br|

   Depending on the display you use, it could be, that backlight adjustment is not working.


.. list-table::
   :header-rows: 1
   :widths: 30 30

   * - Module Prequisites
     - Host Prequisites

   * - Network with Internet access connected
     - Network connection to Module

   * - Display connected
     - Chrome Web Browser

   * - SSH accessible
     - SSH Client
     

Boot the target, and log-in using SSH or Serial Terminal connection.

Check out our Demo application by cloning it from GitHub.

+-----------------------------------+------------------------+
| Module                            | Branch Name            |
+===================================+========================+
| TX6, TXUL                         | ``tx6``                |
+-----------------------------------+------------------------+
| TXMP, QSMP                        | ``txmp``               |
+-----------------------------------+------------------------+
| QSXP, QSXM, QS8M, TX8M, TX8P      | ``tx8``                |
+-----------------------------------+------------------------+

.. code-blocK:: text

   $ git clone https://github.com/karo-electronics/electron-demo.git -b <branch>

.. tip:: If you're receiving any SSL/certificate erros make sure your module has set the correct time. |br|
   
   .. code-block:: text
      
      ntpdate -s -u <ntp-server>

Into the *electron-demo* folder install the npm dependencies.

.. code-blocK:: text

   $ cd electron-demo
   $ npm install

Set the display variable and start the application.

.. code-blocK:: text

   $ export DISPLAY=:0
   $ npm start


Remote Debugging
----------------

In the ``package.json`` file of the demo application there are two scripts specified.

.. code-block:: js

   "scripts": {
       "start": "electron main.js --no-sandbox",
       "test": "electron --inspect --remote-debugging-port=9223 main.js --no-sandbox"
   },

.. hint:: For TX6 Modules you have to add the extra flag ``--use-gl=egl`` to get GPU acceleration.

For remote debugging we will run the **test** script.

.. code-block:: text

   $ export DISPLAY=:0
   $ npm test

On our host we now have to open two SSH tunnels.

.. code-block:: text

   ssh -L 9222:localhost:9223 root@<module-ip>
   ssh -L 9221:localhost:9229 root@<module-ip>

When the application is started the debug ports should be forwarded to your host.

Next open Chrome and goto: ``chrome://inspect``

Press :kbd:`Configure...` and configure like shown below.

.. figure:: ./images/configure-debug.png
   :scale: 100 %
   :align: left
   :figwidth: 100 %

Then the nodejs main process and the frontend should both appear and you're able to inspect/debug each of them.

.. figure:: ./images/devtools-devices.png
   :scale: 100 %
   :align: left
   :figwidth: 100 %

After clicking **inspect** you're able to remote control the application and debug the frontend.

.. figure:: ./images/frontend-debug.png
   :scale: 100 %
   :align: left
   :figwidth: 100 %


.. _`qsmp-1570-electron-demo.zip`: https://www.karo-electronics.com/fileadmin/download/demos/qsmp-1570-electron-demo.zip