.. _starting:

########
Starting
########

After finishing the installation process, there are two different ways of
using the **chipwhisperer** software. You will most likely be using a Jupyter
server to run a Jupyter notebook inside of your browser. 

*****************
Jupyter Notebooks
*****************

Recommended reading for using Jupyter notebooks:

  * `Jupyter Notebook ReadtheDocs <https://jupyter-notebook.readthedocs.io/en/stable/>`_

Here is a quick start guide based on you having finished the installation
of **chipwhisperer**. It only covers steps unique to our chipwhisperer/Jupyter
installation. 

If you've installed via the VirtualBox VM image:

 #. Open VirtualBox and start the virtual machine

 #. Open your browser outside the VM

 #. Connect to localhost:8888 in your browser


If you've installed via the Windows Installer:

 #. Run the ChipWhisperer shortcut.
      * This shortcut is available in the ChipWhisperer install folder,
         the start menu, and optionally as a shortcut on the desktop.

If you've installed natively:

 #. Make sure you are using a bash like terminal. Many of the jupyter
    notebooks use bash to run **make** or remove files for building
    firmware. This may be changed in the future but for now it is
    required. If you installed using the Virtual Machine (VM) the
    terminal is a bash like terminal and you should have no problem.
    If you installed on linux, same deal. However, if you installed
    on Windows/Mac you may have to install a bash like terminal. If
    you installed Git to install **chipwhisperer** you already have
    **git-bash** available to you. Here are a few bash-like terminals
    available on other windows:

      * (Recommended) `Git-Bash <https://git-scm.com/>`_ (make sure you select to
        install git bash during the installation of Git.)

      * `MinGW <http://mingw.org/>`_

      * `Cygwin <https://www.cygwin.com/>`_

 #. Start the bash terminal. Make sure you have access to
    **chipwhisperer** in the terminal using::

        python -c "import chipwhisperer as cw"

    This should exit without printing anything. If you get something
    like "module not found" then you should read up on PYTHONPATH and
    system PATH.

 #. Navigate to the **chipwhisperer** directory. If you installed
    **chipwhisperer** to /home/user/chipwhisperer then use:

    .. code:: bash

        cd /home/user/chipwhisperer

 #. Start the Jupyter Server in that directory:

    .. code:: bash

        jupyter notebook

    The Jupyter Notebook Server interface should be automatically opened in
    your browser. If not see next step.

 #. Navigate to the Jupyter Notebook Server interface at **localhost:8888**
    using a browser and typing the address in the address bar.


 #. You should see the **chipwhisperer** folder in your browser, the tutorials
    can be found in the **jupyter** folder, **not** in the tutorials folder
    which unless you pulled the submodule should be empty.

    .. note:: The tutorials folder is for autogenerated ReST files for
        the tutorials you see on readthedocs documentation. The tutorials
        folder is not the folder you are looking for, **jupyter** is.


**************
Python Package
**************

The **chipwhisperer** software can also be used without Jupyter Notebooks if
you prefer. After you install **chipwhisperer** to the correct Python
interpreter, use **chipwhisperer** as you normally would any python package::

    import chipwhisperer as cw
    help(cw)

The :ref:`Python API <api>` has all the information about what functions,
and classes are at your disposal.