.. _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 `_
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 `_ (make sure you select to
install git bash during the installation of Git.)
* `MinGW `_
* `Cygwin `_
#. 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 ` has all the information about what functions,
and classes are at your disposal.