V5:Installing ChipWhisperer

This page describes how to install the ChipWhisperer 5.0 software.

There are currently three ways to set up ChipWhisperer:

• VirtualBox Virtual Machine Get a pre-prepared virtual machine image with all of the required tools already installed. Recommended for beginners.
• ChipWhisperer Releases: Get a zip file with the latest stable ChipWhisperer code and run it on your own environment.
• Git Repository: Get the latest, bleeding-edge features and bugs. Recommended if you're an experienced developer and you want to contribute to ChipWhisperer.

The following setup methods are planned but not yet updated for the 5.0 release:

• Windows Installer Get a Windows binary that installs the ChipWhisperer repository to your computer. Does not include WinAVR compiler.
• PyPi Package: pip install chipwhisperer. Only includes the software - doesn't come with the hardware source files, drivers, or example firmware.

NOTE TO USERS WITH AN ARM TARGET: To build firmware, you'll need the GNU Embedded Toolchain For ARM. This is included with the VM. Otherwise please see Installing ARM Toolchain in the instructions for your platform of choice (Windows, Mac, Linux).

You may need to add --trusted-host pypi.python.org to the pip install command to allow HTTP connections. This is done as follows for example: sudo pip install --trusted-host pypi.python.org pyusb

Using VirtualBox Virtual Machine

If this is your first time using the ChipWhisperer toolchain, the easiest way to start is to use a virtual machine with everything already set up for you. Note that Linux users may find it easier to do a manual install.

These instructions are for the newest version of CW5 (v5.0.1+) and will not work with CW5's initial alpha release (v5.0.0). Virtualbox 6 is assumed here, but these instructions should work for Virtualbox 5 as well, provided the correct extension pack is installed.

1. Install VirtualBox. This program is freely available on Windows, Mac, and Linux.
2. Install the VirtualBox Extension Pack. This is necessary for the VM to interact with the ChipWhisperer hardware
3. Download a ChipWhisperer virtual machine image release or build it yourself using Vagrant.
4. Unzip the VirtualBox image, go to Machine>Add in VirtualBox and select the VM that was unzipped
5. Verify that the VM boots

Next, we'll need to update some passwords for the VM. Boot the virtual machine then:

1. Log in (user: vagrant pass: vagrant). You will be asked to update your password. Do so (make sure to record this password).
2. Setup a new password for Jupyter. This can be done by typing jupyter notebook password, then entering and verifying your new password. Note that Jupyter will not start until this is done. This password will be needed to log into Jupyter, so make sure you record it as well.
3. Reboot the VM.
4. Once the VM is booted, you can connect to Jupyter via localhost:8888 (Firefox/Chrome ONLY). You will be asked for the password you set via jupyter notebook password

You shouldn't need to log in to the VM again to run Jupyter (which provides the interface) as it should start automatically, but make sure you still record the password you set for the vagrant account, as you will need to log in to update ChipWhisperer.

=== Using VirtualBox Virtual Machine === If this is your first time using the ChipWhisperer toolchain, the easiest way to start is to use a virtual machine with everything already set up for you. Note that Linux users may find it easier to do a manual install.

These instructions are for the newest version of CW5 (v5.0.1+) and will not work with CW5's initial alpha release (v5.0.0). Virtualbox 6 is assumed here, but these instructions should work for Virtualbox 5 as well, provided the correct extension pack is installed.

1. Install VirtualBox. This program is freely available on Windows, Mac, and Linux.
2. Install the VirtualBox Extension Pack. This is necessary for the VM to interact with the ChipWhisperer hardware
3. Download a ChipWhisperer virtual machine image release or build it yourself using Vagrant.
4. Unzip the VirtualBox image, go to Machine>Add in VirtualBox and select the VM that was unzipped
5. Verify that the VM boots

Next, we'll need to update some passwords for the VM. Boot the virtual machine then:

1. Log in (user: vagrant pass: vagrant). You will be asked to update your password. Do so (make sure to record this password).
2. Setup a new password for Jupyter. This can be done by typing jupyter notebook password, then entering and verifying your new password. Note that Jupyter will not start until this is done. This password will be needed to log into Jupyter, so make sure you record it as well.
3. Reboot the VM.
4. Once the VM is booted, you can connect to Jupyter via localhost:8888 (Firefox/Chrome ONLY). You will be asked for the password you set via jupyter notebook password

You shouldn't need to log in to the VM again to run Jupyter (which provides the interface) as it should start automatically, but make sure you still record the password you set for the vagrant account, as you will need to log in to update ChipWhisperer.

Automatic Windows Installer

A 32-bit and a 64-bit Windows installer will also be available in the future, typically from the releases page on Github. The installer packages together:

• ChipWhisperer directory (same as in GIT)
• Python binary & required libraries.
• Windows USB Drivers
• Binary to run Jupyter

This will install ChipWhisperer to a location on your hard drive. Note it must be somewhere your user owns, as the portable Jupyter install will not run from areas the user cannot write to. C:\Users\<YOUR_USER> is a good install location, but C:\Program Files (x86)\ isn't.

You will need to install compilers for the firmware manually (i.e. WinAVR, Arm GCC) as described in Manual Install - Windows.

=== Automatic Windows Installer === A 32-bit and a 64-bit Windows installer will also be available in the future, typically from the releases page on Github. The installer packages together:

• ChipWhisperer directory (same as in GIT)
• Python binary & required libraries.
• Windows USB Drivers
• Binary to run Jupyter

This will install ChipWhisperer to a location on your hard drive. Note it must be somewhere your user owns, as the portable Jupyter install will not run from areas the user cannot write to. C:\Users\<YOUR_USER> is a good install location, but C:\Program Files (x86)\ isn't.

You will need to install compilers for the firmware manually (i.e. WinAVR, Arm GCC) as described in Manual Install - Windows.

Manual Install - Windows

Python

For any of the other installation methods, you'll need to have Python 3 installed on your computer. If you already a recent version of Python installed (3.5.x+), you can skip this step. Note that Python 2.x will not work with this codebase. There's also a bit of setup that's needed to get other tools and prepare other drivers.

The recommend method of installing Python is to use a distribution called WinPython. This setup avoids installing Python globally, and includes most of the software you will need. In addition it makes it possible to install 32-bit and 64-bit Python on the same system with minimal problems. This can be very useful as the 64-bit version is handy for doing analysis on large data sets.

To install WinPython 3.7.x, Download a release in the 3.7.x branch from the WinPython site. ChipWhisperer works with both 32-bit and 64-bit versions of Python. If you run into issues connecting on Windows with 64-bit Python, see https://github.com/newaetech/chipwhisperer/issues/199.

Choose a reasonable location to install this to - note the default is simply in the download directory. Instead it's recommended to find a directory such as c:\WinPython32bit-3.7.1.0, or into your local directory such as c:\Users\yourname\<code>WinPython32bit-3.7.1.0</code>.

Go to your installation directory for WinPython, and run the shortcut called WinPython Command Prompt.exe. This will give you a command prompt which is setup to run Python along with associated scripts.

Optional: You can add the python.exe you just installed to your PATH. To do so navigate to your installation folder, and run the WinPython Control Panel.exe program. Then select Advanced -> Register distribution.... If you do not do this, you will have to run all commands in this document via the WinPython Command Prompt.exe. If you plan on running both 32-bit and 64-bit Python, you should not register them. Instead explicitly call the correct Python by always running the WinPython Command Prompt.exe, and then calling specific scripts or notebooks.

Python Packages

There are a number of packages that the ChipWhisperer project uses. You'll need to install these so that the software can run. With your WinPython command prompt, navigate to where you downloaded ChipWhisperer to, then move to the software/ directory.

Run the following commands to get the needed packages:

• ConfigObj: pip install -r requirements.txt

Installing Hardware Drivers

Details of driver installation are on specific pages for supported hardware (such as cwcapturerev2 and naecw1173_cwlite). Drivers are available from ChipWhisperer release section.

Getting AVR Compiler Toolchain

The following section is not required for your first attack - you can jump right to the tutorial if you wish. However you'll ultimately wish to modify the code of the device under test, and these instructions tell you how. You should first follow the tutorial to confirm your system is working before modifying the code however!

To build the code, you'll need to install avr-gcc on Windows (if using the Virtual Machine, the following is not required, as the VM comes setup with the AVR compiler already). On Windows, you could choose to install:

• AVR-GCC standalone - see avr-gcc standalone. You'll need to unzip this file and add the bin folder to your path. See this link for instructions on how to add something to your path.
• WinAVR. WinAVR is rather old at this point, so its use is not recommended. Last release - 2010, see WinAVR Page

To test the code build, follow these steps:

cd to the directory with the avr-serial example, and run make:

cd c:\chipwhisperer\hardware\victims\firmware\simpleserial-aes
make

If this is successful, you'll see an output like the following:

If instead you get an error something like make: *** No rule to make target `simpleserial.elf', needed by `elf'. Stop., this means a required file was missing.

Programming the target AVR is accomplished in one of two methods depending on your hardware. The ChipWhisperer Capture Rev 2 uses the external "AVR Studio" program, whereas the CW1173 and CW1200 use a programmer menu from the ChipWhisperer-Capture software.

For details about programming the targets, see Tutorial B1 Building a SimpleSerial Project.

WinAVR Path Settings

By default, WinAVR is added to your system path. This means you can run avr-gcc, make and other programs from your normal Windows command line. You may not want this on certain systems where you already have similar tools installed. In which case either uncheck the Add WinAVR to Path option, or edit your system path to remove the WinAVR directories.

If you do not add it to the system path, you’ll need a method of readding the WinAVR directories when you want to use WinAVR. To do so create a file called winavr.bat in C:\WinAVR-20100110 with the following contents:

set PATH=%PATH%;C:\WinAVR-20100110\bin;C:\WinAVR-20100110\utils\bin
cmd

Now when you want to run WinAVR (e.g. to continue the examples here), you can simply double-click on the winavr.bat file. This will configure the path for just that terminal, rather than every terminal you open.

Note if using WinAVR on Windows 8.1 and possibly Windows 10, you must replace the dll msys-1.0.dll with an updated version. See Windows 8.1 Fix for a link to this DLL replacement.

Installing Arm Toolchain

To be able to build firmware for ARM Targets, you'll need to install the GNU Toolchain for ARM Devices. An installer for Windows and archives for Linux/Windows can be found here. Make sure you install the 2018-q2 version of the software, as 2018-q4 has a bug that prevents compiling and earlier ones may not work once uploaded. If you use the installer, make sure the "Add path to environment variable", "Add registry information", and "Launch gccvar.bat" boxes are ticked. Otherwise, you'll need to add the compiler to your path as with avr-gcc.

Once you've done this, open a terminal and type arm-none-eabi-gcc. If this fails, you'll need to add the toolchain to your path manually.

This doesn't install make like WinAVR does, so if you haven't installed that, you'll need to on your own (the easiest way is just to install WinAVR as well).

=== Manual Install - Windows ===

Python

For any of the other installation methods, you'll need to have Python 3 installed on your computer. If you already a recent version of Python installed (3.5.x+), you can skip this step. Note that Python 2.x will not work with this codebase. There's also a bit of setup that's needed to get other tools and prepare other drivers.

The recommend method of installing Python is to use a distribution called WinPython. This setup avoids installing Python globally, and includes most of the software you will need. In addition it makes it possible to install 32-bit and 64-bit Python on the same system with minimal problems. This can be very useful as the 64-bit version is handy for doing analysis on large data sets.

To install WinPython 3.7.x, Download a release in the 3.7.x branch from the WinPython site. ChipWhisperer works with both 32-bit and 64-bit versions of Python. If you run into issues connecting on Windows with 64-bit Python, see https://github.com/newaetech/chipwhisperer/issues/199.

Choose a reasonable location to install this to - note the default is simply in the download directory. Instead it's recommended to find a directory such as c:\WinPython32bit-3.7.1.0, or into your local directory such as c:\Users\yourname\<code>WinPython32bit-3.7.1.0</code>.

Go to your installation directory for WinPython, and run the shortcut called WinPython Command Prompt.exe. This will give you a command prompt which is setup to run Python along with associated scripts.

Optional: You can add the python.exe you just installed to your PATH. To do so navigate to your installation folder, and run the WinPython Control Panel.exe program. Then select Advanced -> Register distribution.... If you do not do this, you will have to run all commands in this document via the WinPython Command Prompt.exe. If you plan on running both 32-bit and 64-bit Python, you should not register them. Instead explicitly call the correct Python by always running the WinPython Command Prompt.exe, and then calling specific scripts or notebooks.

Python Packages

There are a number of packages that the ChipWhisperer project uses. You'll need to install these so that the software can run. With your WinPython command prompt, navigate to where you downloaded ChipWhisperer to, then move to the software/ directory.

Run the following commands to get the needed packages:

• ConfigObj: pip install -r requirements.txt

Installing Hardware Drivers

Details of driver installation are on specific pages for supported hardware (such as cwcapturerev2 and naecw1173_cwlite). Drivers are available from ChipWhisperer release section.

Getting AVR Compiler Toolchain

The following section is not required for your first attack - you can jump right to the tutorial if you wish. However you'll ultimately wish to modify the code of the device under test, and these instructions tell you how. You should first follow the tutorial to confirm your system is working before modifying the code however!

To build the code, you'll need to install avr-gcc on Windows (if using the Virtual Machine, the following is not required, as the VM comes setup with the AVR compiler already). On Windows, you could choose to install:

• AVR-GCC standalone - see avr-gcc standalone. You'll need to unzip this file and add the bin folder to your path. See this link for instructions on how to add something to your path.
• WinAVR. WinAVR is rather old at this point, so its use is not recommended. Last release - 2010, see WinAVR Page

To test the code build, follow these steps:

cd to the directory with the avr-serial example, and run make:

cd c:\chipwhisperer\hardware\victims\firmware\simpleserial-aes
make

If this is successful, you'll see an output like the following:

If instead you get an error something like make: *** No rule to make target `simpleserial.elf', needed by `elf'. Stop., this means a required file was missing.

Programming the target AVR is accomplished in one of two methods depending on your hardware. The ChipWhisperer Capture Rev 2 uses the external "AVR Studio" program, whereas the CW1173 and CW1200 use a programmer menu from the ChipWhisperer-Capture software.

For details about programming the targets, see Tutorial B1 Building a SimpleSerial Project.

WinAVR Path Settings

By default, WinAVR is added to your system path. This means you can run avr-gcc, make and other programs from your normal Windows command line. You may not want this on certain systems where you already have similar tools installed. In which case either uncheck the Add WinAVR to Path option, or edit your system path to remove the WinAVR directories.

If you do not add it to the system path, you’ll need a method of readding the WinAVR directories when you want to use WinAVR. To do so create a file called winavr.bat in C:\WinAVR-20100110 with the following contents:

set PATH=%PATH%;C:\WinAVR-20100110\bin;C:\WinAVR-20100110\utils\bin
cmd

Now when you want to run WinAVR (e.g. to continue the examples here), you can simply double-click on the winavr.bat file. This will configure the path for just that terminal, rather than every terminal you open.

Note if using WinAVR on Windows 8.1 and possibly Windows 10, you must replace the dll msys-1.0.dll with an updated version. See Windows 8.1 Fix for a link to this DLL replacement.

Installing Arm Toolchain

To be able to build firmware for ARM Targets, you'll need to install the GNU Toolchain for ARM Devices. An installer for Windows and archives for Linux/Windows can be found here. Make sure you install the 2018-q2 version of the software, as 2018-q4 has a bug that prevents compiling and earlier ones may not work once uploaded. If you use the installer, make sure the "Add path to environment variable", "Add registry information", and "Launch gccvar.bat" boxes are ticked. Otherwise, you'll need to add the compiler to your path as with avr-gcc.

Once you've done this, open a terminal and type arm-none-eabi-gcc. If this fails, you'll need to add the toolchain to your path manually.

This doesn't install make like WinAVR does, so if you haven't installed that, you'll need to on your own (the easiest way is just to install WinAVR as well).

Manual Install - Linux

Python

On Linux, installing Python & all the associated packages is straightforward. Typically you can install them from a package manager.

On Ubuntu or similar:

$ sudo apt install python3 python3-pip python3-tk

Getting the AVR Toolchain

Many of the tutorials use the AVR XMEGA microcontrollers as a target. In order to compile code for these targets, you'll need the AVR toolchain. This is easy to set up:

$ sudo apt-get install avr-libc gcc-avr

Getting the Arm Toolchain

Many of the tutorials use the STM32F303 Arm microcontrollers as a target. In order to compile code for these targets, you'll need the GNU Arm toolchain:

$ sudo apt install gcc-arm-none-eabi

Some versions of Ubuntu (Ubuntu Bionic and likely before) provide a GNU Arm toolchain that links incorrect files during the build process. To install a working version of the toolchain:

$ wget https://mirrors.kernel.org/ubuntu/pool/universe/n/newlib/libnewlib-dev_3.0.0.20180802-2_all.deb
$ wget https://mirrors.kernel.org/ubuntu/pool/universe/n/newlib/libnewlib-arm-none-eabi_3.0.0.20180802-2_all.deb
$ sudo dpkg -i libnewlib-arm-none-eabi_3.0.0.20180802-2_all.deb libnewlib-dev_3.0.0.20180802-2_all.deb

Hardware Drivers

The driver for Linux is built in, however you need to allow your user account to access the peripheral. To do so, you'll have to make a file called /etc/udev/rules.d/99-newae.rules . The contents of this file should be:

# CW-Lite
SUBSYSTEM=="usb", ATTRS{idVendor}=="2b3e", ATTRS{idProduct}=="ace2", MODE="0664", GROUP="plugdev"

# CW-1200
SUBSYSTEM=="usb", ATTRS{idVendor}=="2b3e", ATTRS{idProduct}=="ace3", MODE="0664", GROUP="plugdev"

# CW-Nano
SUBSYSTEM=="usb", ATTRS{idVendor}=="2b3e", ATTRS{idProduct}=="ace0", MODE="0664", GROUP="plugdev"

# CW-305 (Artix Target)
SUBSYSTEM=="usb", ATTRS{idVendor}=="2b3e", ATTRS{idProduct}=="c305", MODE="0664", GROUP="plugdev"

# CW-CR2
SUBSYSTEM=="usb", ATTRS{idVendor}=="04b4", ATTRS{idProduct}=="8613", MODE="0664", GROUP="plugdev"
SUBSYSTEM=="usb", ATTRS{idVendor}=="221a", ATTRS{idProduct}=="0100", MODE="0664", GROUP="plugdev"

Then add your username to the plugdev group:

$ sudo usermod -a -G plugdev YOUR-USERNAME

And reset the udev system:

$ sudo udevadm control --reload-rules

Finally log out & in again for the group change to take effect.

You can always find the latest version of this file in GIT.

=== Manual Install - Linux ===

Python

On Linux, installing Python & all the associated packages is straightforward. Typically you can install them from a package manager.

On Ubuntu or similar:

$ sudo apt install python3 python3-pip python3-tk

Getting the AVR Toolchain

Many of the tutorials use the AVR XMEGA microcontrollers as a target. In order to compile code for these targets, you'll need the AVR toolchain. This is easy to set up:

$ sudo apt-get install avr-libc gcc-avr

Getting the Arm Toolchain

Many of the tutorials use the STM32F303 Arm microcontrollers as a target. In order to compile code for these targets, you'll need the GNU Arm toolchain:

$ sudo apt install gcc-arm-none-eabi

Some versions of Ubuntu (Ubuntu Bionic and likely before) provide a GNU Arm toolchain that links incorrect files during the build process. To install a working version of the toolchain:

$ wget https://mirrors.kernel.org/ubuntu/pool/universe/n/newlib/libnewlib-dev_3.0.0.20180802-2_all.deb
$ wget https://mirrors.kernel.org/ubuntu/pool/universe/n/newlib/libnewlib-arm-none-eabi_3.0.0.20180802-2_all.deb
$ sudo dpkg -i libnewlib-arm-none-eabi_3.0.0.20180802-2_all.deb libnewlib-dev_3.0.0.20180802-2_all.deb

Hardware Drivers

The driver for Linux is built in, however you need to allow your user account to access the peripheral. To do so, you'll have to make a file called /etc/udev/rules.d/99-newae.rules . The contents of this file should be:

# CW-Lite
SUBSYSTEM=="usb", ATTRS{idVendor}=="2b3e", ATTRS{idProduct}=="ace2", MODE="0664", GROUP="plugdev"

# CW-1200
SUBSYSTEM=="usb", ATTRS{idVendor}=="2b3e", ATTRS{idProduct}=="ace3", MODE="0664", GROUP="plugdev"

# CW-Nano
SUBSYSTEM=="usb", ATTRS{idVendor}=="2b3e", ATTRS{idProduct}=="ace0", MODE="0664", GROUP="plugdev"

# CW-305 (Artix Target)
SUBSYSTEM=="usb", ATTRS{idVendor}=="2b3e", ATTRS{idProduct}=="c305", MODE="0664", GROUP="plugdev"

# CW-CR2
SUBSYSTEM=="usb", ATTRS{idVendor}=="04b4", ATTRS{idProduct}=="8613", MODE="0664", GROUP="plugdev"
SUBSYSTEM=="usb", ATTRS{idVendor}=="221a", ATTRS{idProduct}=="0100", MODE="0664", GROUP="plugdev"

Then add your username to the plugdev group:

$ sudo usermod -a -G plugdev YOUR-USERNAME

And reset the udev system:

$ sudo udevadm control --reload-rules

Finally log out & in again for the group change to take effect.

You can always find the latest version of this file in GIT.

Manual Install - Mac OS X

Not yet available. Once users have brew installed, instructions should be similar to Linux.

=== Manual Install - Mac OS X === Not yet available. Once users have brew installed, instructions should be similar to Linux.

Installing ChipWhisperer from Releases

Once you have a working Python installation, you're ready to install and run ChipWhisperer.

First, download a ChipWhisperer release. You can get these from the Releases page. Generally, the latest release is a good choice, but you might need an older version for various reasons. You want the source code in .zip or .tar.gz format - not a VBox image.

Next, uncompress your downloaded source code somewhere. Generally, 'somewhere' will become your ChipWhisperer working directory. For example, on Windows, you might want to use C:\chipwhisperer\.

Once you've got the file, install the python dependencies and run the Python install procedure (setup.py). Use the develop command to indicate that the files will probably be changing frequently. to do this, open a terminal and run the following, adjusting paths as needed:

cd chipwhisperer/software
pip install -r requirements.txt
python setup.py develop 

NB: This assumes the python command links to Python-3.x, and not Python-2.7. You may need to specify python3 and pip3 as the command instead of python and pip to force this.

To test, run python and try importing the chipwhisperer module:

python
>>> import chipwhisperer as cw

If you want to run the tutorial notebooks, run

jupyter notebook

. A new window should be opened in your browser.

=== Installing ChipWhisperer from Releases === Once you have a working Python installation, you're ready to install and run ChipWhisperer.

First, download a ChipWhisperer release. You can get these from the Releases page. Generally, the latest release is a good choice, but you might need an older version for various reasons. You want the source code in .zip or .tar.gz format - not a VBox image.

Next, uncompress your downloaded source code somewhere. Generally, 'somewhere' will become your ChipWhisperer working directory. For example, on Windows, you might want to use C:\chipwhisperer\.

Once you've got the file, install the python dependencies and run the Python install procedure (setup.py). Use the develop command to indicate that the files will probably be changing frequently. to do this, open a terminal and run the following, adjusting paths as needed:

cd chipwhisperer/software
pip install -r requirements.txt
python setup.py develop 

NB: This assumes the python command links to Python-3.x, and not Python-2.7. You may need to specify python3 and pip3 as the command instead of python and pip to force this.

To test, run python and try importing the chipwhisperer module:

python
>>> import chipwhisperer as cw

If you want to run the tutorial notebooks, run

jupyter notebook

. A new window should be opened in your browser.

Installing ChipWhisperer from PyPi

=== Installing ChipWhisperer from PyPi === V5:Installing ChipWhisperer/Installing ChipWhisperer from PyPi

Installing ChipWhisperer from Git

If you want the cutting-edge version of ChipWhisperer, you can clone the repository.

NOTE: On Unix based OS (Mac, Linux, etc), python often links to python2. You may need to replace python and pip calls with python3 and pip3 calls, respectively

If you have Git already set up, this is easy to do:

git clone https://github.com/newaetech/chipwhisperer.git
cd chipwhisperer
git checkout cw5dev
cd software
pip install -r requirements.txt
python setup.py develop --user

The user flag installs ChipWhisperer in the user's local python site-packages directory.

You probably also want the Jupyter notebooks, which are the tutorial interface for ChipWhisperer 5. If not, you can skip this step.

cd ..
git submodule init jupyter/
git submodule update

If you want to contribute to chipwhisperer-jupyter, you'll want to checkout the cw5dev branch in chipwhisperer-jupyter:

cd jupyter
git checkout cw5dev

You may also want the OpenADC software, which is necessary to build new firmware for the ChipWhisperer FPGA. This is unnecessary for most users. If you need it:

cd ..
git submodule init openadc/
git submodule update
cd openadc/controlsw/python
python setup.py develop --user

Once ChipWhisperer and the Jupyter notebooks are installed, you can the tutorials through Jupyter by typing

jupyter notebook

into the command prompt, which should open a new Window in your browser. Navigate to chipwhisperer/software/jupyter/ to get started with the new Jupyter tutorials.

NOTE: To run %%bash blocks on Windows, you need run jupyter notebook using a bash console, such as git bash. Jupyter will still work without this, but %%bash blocks will not run

=== Installing ChipWhisperer from Git === If you want the cutting-edge version of ChipWhisperer, you can clone the repository.

NOTE: On Unix based OS (Mac, Linux, etc), python often links to python2. You may need to replace python and pip calls with python3 and pip3 calls, respectively

If you have Git already set up, this is easy to do:

git clone https://github.com/newaetech/chipwhisperer.git
cd chipwhisperer
git checkout cw5dev
cd software
pip install -r requirements.txt
python setup.py develop --user

The user flag installs ChipWhisperer in the user's local python site-packages directory.

You probably also want the Jupyter notebooks, which are the tutorial interface for ChipWhisperer 5. If not, you can skip this step.

cd ..
git submodule init jupyter/
git submodule update

If you want to contribute to chipwhisperer-jupyter, you'll want to checkout the cw5dev branch in chipwhisperer-jupyter:

cd jupyter
git checkout cw5dev

You may also want the OpenADC software, which is necessary to build new firmware for the ChipWhisperer FPGA. This is unnecessary for most users. If you need it:

cd ..
git submodule init openadc/
git submodule update
cd openadc/controlsw/python
python setup.py develop --user

Once ChipWhisperer and the Jupyter notebooks are installed, you can the tutorials through Jupyter by typing

jupyter notebook

into the command prompt, which should open a new Window in your browser. Navigate to chipwhisperer/software/jupyter/ to get started with the new Jupyter tutorials.

NOTE: To run %%bash blocks on Windows, you need run jupyter notebook using a bash console, such as git bash. Jupyter will still work without this, but %%bash blocks will not run