CW5 - Revision history

Adewar at 14:21, 12 July 2019

2019-07-12T14:21:08Z

Adewar at 19:51, 28 June 2019

2019-06-28T19:51:33Z

Adewar: /* Running Tutorials */

2019-06-04T15:43:03Z

‎Running Tutorials

Adewar: /* Running Tutorials */

2019-06-04T15:42:07Z

‎Running Tutorials

Adewar: /* Getting Started */

2019-06-04T15:41:37Z

‎Getting Started

Adewar at 19:30, 3 June 2019

2019-06-03T19:30:27Z

Adewar at 16:55, 13 May 2019

2019-05-13T16:55:07Z

Adewar at 16:54, 13 May 2019

2019-05-13T16:54:54Z

Adewar: /* Jupyter Notebook Tutorials */

2019-05-13T15:46:13Z

‎Jupyter Notebook Tutorials

Adewar: /* Running Jupyter */

2019-05-13T15:45:06Z

‎Running Jupyter

@@ Line 28: / Line 28: @@
 === Editing Blocks ===
 To edit code blocks, simple click on the text portion of the block and begin making your changes. You'll know if you're in edit mode for a block because it will be highlighted in green.
 == New Features ==

@@ Line 1: / Line 1: @@
-The release of ChipWhisperer v5.0 has brought major changes to the front end of the ChipWhisperer software as well as a switch to Python 3: the GUI and the wiki tutorials have been replaced with Jupyter Notebooks, which allow users to run interactive Python blocks in their browser. Most of the API remains unchanged from v4 and, with the exception of Python 2.7 specific code, most GUI-less scripts should run as is. Additional features, such as ChipWhipserer Analyzer support, are now available outside of any GUI.
+The release of ChipWhisperer v5.0 has brought major changes to the front end of the ChipWhisperer software as well as a switch to Python 3: the GUI and the wiki tutorials have been replaced with Jupyter Notebooks, which allow users to run interactive Python blocks in their browser. The API is being updated and documented, with a push towards a stable and consistent interface. Most GUIless scripts for v4 should be compatible with the final release of v5, though users will be warned via the logging library about deprecated parts of the code base. Additional features, such as ChipWhipserer Analyzer support, are now available outside of any GUI.
@@ Line 30: / Line 30: @@
 == New Features ==
-New features that are available in CW5 include:
+New features that are planned to be available in the final CW5 release include:
 * Analyzer and project support via the Python API
@@ Line 37: / Line 37: @@
 * New tutorials, including one submitted by a user via Github
 * Support for multiple ChipWhisperers via Python API
 * Improved capture speed

@@ Line 19: / Line 19: @@
 Starting with ChipWhisperer v5.0, tutorials have been moved from the wiki into Jupyter Notebooks. Use Jupyter's file browser to navigate to <code>software/Jupyter</code>, which contains all of the tutorial notebooks. If you'd like to see our suggested completion order, you can open <code>!!Suggested_Completion_Order!!.ipynb</code>. Once you've decided which tutorial to run, open the tutorial via Jupyter.
-Once you've got a notebook open, you'll find a combination of rich text and Python (and few special blocks, like the [code]%%bash[/code] blocks. Near the top of the page, you'll find a special Python block with <code>#Parameters</code> in it. This block is used to select which scope (via <code>SCOPETYPE</code>) as well as which target (via <code>PLATFORM</code>) you'll be using for the tutorial. Make sure to edit these parameters for which hardware you're using. A list of common SCOPETYPE and PLATFORM values can be found [http://www.example.com here (not yet available)].
+Once you've got a notebook open, you'll find a combination of rich text and Python (and few special blocks, like the <code>%%bash</code> blocks. Near the top of the page, you'll find a special Python block with <code>#Parameters</code> in it. This block is used to select which scope (via <code>SCOPETYPE</code>) as well as which target (via <code>PLATFORM</code>) you'll be using for the tutorial. Make sure to edit these parameters for which hardware you're using. A list of common SCOPETYPE and PLATFORM values can be found [http://www.example.com here (not yet available)].
 Now that this setup is complete, you can start actually running through the tutorials. To run a block, click on the block and make sure it's highlighted (the block should have either a green or blue outline around it), then click the <code>>| Run</code> button on the toolbar at the top of the screen. This will run the code inside of the block and move to the next one. Run the rest of the code block in the tutorial (all tutorials are designed to be able to be run with minimal modifications to the Python code).

@@ Line 17: / Line 17: @@
 === Running Tutorials ===
-Starting with ChipWhisperer v5.0, tutorials have been moved from the wiki into Jupyter Notebooks. Use Jupyter's file browser to navigate to <code>software/Jupyter</code>, which contains all of the tutorial notebooks. If you'd like to see our suggested completion order, you can open [code]!!Suggested_Completion_Order!!.ipynb[/code]. Once you've decided which tutorial to run, open the tutorial via Jupyter.
+Starting with ChipWhisperer v5.0, tutorials have been moved from the wiki into Jupyter Notebooks. Use Jupyter's file browser to navigate to <code>software/Jupyter</code>, which contains all of the tutorial notebooks. If you'd like to see our suggested completion order, you can open <code>!!Suggested_Completion_Order!!.ipynb</code>. Once you've decided which tutorial to run, open the tutorial via Jupyter.
 Once you've got a notebook open, you'll find a combination of rich text and Python (and few special blocks, like the [code]%%bash[/code] blocks. Near the top of the page, you'll find a special Python block with <code>#Parameters</code> in it. This block is used to select which scope (via <code>SCOPETYPE</code>) as well as which target (via <code>PLATFORM</code>) you'll be using for the tutorial. Make sure to edit these parameters for which hardware you're using. A list of common SCOPETYPE and PLATFORM values can be found [http://www.example.com here (not yet available)].

@@ Line 12: / Line 12: @@
 === Running Jupyter ===
-Once you have ChipWhisperer/Jupyter installed and have the associated hardware, you should be all set to run ChipWhisperer 5! To run ChipWhisperer 5 via a Virtual Machine, open your VM and start the ChipWhisperer Jupyter image. Once the Virtual Machine is booted, open either Firefox or Chrome. Go to your address bar and type in [code]localhost:8888[/code]. A page requesting a password should appear. Enter your password that you set for Jupyter during installation and you'll be taken to the Jupyter homescreen.
+Once you have ChipWhisperer/Jupyter installed and have the associated hardware, you should be all set to run ChipWhisperer 5! To run ChipWhisperer 5 via a Virtual Machine, open your VM and start the ChipWhisperer Jupyter image. Once the Virtual Machine is booted, open either Firefox or Chrome. Go to your address bar and type in <code>localhost:8888</code>. A page requesting a password should appear. Enter your password that you set for Jupyter during installation and you'll be taken to the Jupyter homescreen.
-For a native installation, open a Bash-like shell terminal (for Windows users, Git Bash will work fine) and navigate to where you installed ChipWhisperer. In Bash, run [code]$ jupyter notebook[/code]. You should be taken to the Jupyter homescreen.
+For a native installation, open a Bash-like shell terminal (for Windows users, Git Bash will work fine) and navigate to where you installed ChipWhisperer. In Bash, run <code>$ jupyter notebook</code>. You should be taken to the Jupyter homescreen.
 === Running Tutorials ===
-Starting with ChipWhisperer v5.0, tutorials have been moved from the wiki into Jupyter Notebooks. Use Jupyter's file browser to navigate to [code]software/Jupyter[/code], which contains all of the tutorial notebooks. If you'd like to see our suggested completion order, you can open [code]!!Suggested_Completion_Order!!.ipynb[/code]. Once you've decided which tutorial to run, open the tutorial via Jupyter.
+Starting with ChipWhisperer v5.0, tutorials have been moved from the wiki into Jupyter Notebooks. Use Jupyter's file browser to navigate to <code>software/Jupyter</code>, which contains all of the tutorial notebooks. If you'd like to see our suggested completion order, you can open [code]!!Suggested_Completion_Order!!.ipynb[/code]. Once you've decided which tutorial to run, open the tutorial via Jupyter.
-Once you've got a notebook open, you'll find a combination of rich text and Python (and few special blocks, like the [code]%%bash[/code] blocks. Near the top of the page, you'll find a special Python block with [code]#Parameters[/code] in it. This block is used to select which scope (via [code]SCOPETYPE[/code]) as well as which target (via [code]PLATFORM[/code]) you'll be using for the tutorial. Make sure to edit these parameters for which hardware you're using. A list of common SCOPETYPE and PLATFORM values can be found [http://www.example.com here (not yet available)].
+Once you've got a notebook open, you'll find a combination of rich text and Python (and few special blocks, like the [code]%%bash[/code] blocks. Near the top of the page, you'll find a special Python block with <code>#Parameters</code> in it. This block is used to select which scope (via <code>SCOPETYPE</code>) as well as which target (via <code>PLATFORM</code>) you'll be using for the tutorial. Make sure to edit these parameters for which hardware you're using. A list of common SCOPETYPE and PLATFORM values can be found [http://www.example.com here (not yet available)].
-Now that this setup is complete, you can start actually running through the tutorials. To run a block, click on the block and make sure it's highlighted (the block should have either a green or blue outline around it), then click the [code]>| Run[/code] button on the toolbar at the top of the screen. This will run the code inside of the block and move to the next one. Run the rest of the code block in the tutorial (all tutorials are designed to be able to be run with minimal modifications to the Python code).
+Now that this setup is complete, you can start actually running through the tutorials. To run a block, click on the block and make sure it's highlighted (the block should have either a green or blue outline around it), then click the <code>>| Run</code> button on the toolbar at the top of the screen. This will run the code inside of the block and move to the next one. Run the rest of the code block in the tutorial (all tutorials are designed to be able to be run with minimal modifications to the Python code).
 === Special Blocks ===
-While running tutorials, you will come across special blocks. For ChipWhisperer's notebooks, the two most common ones are [code]%%bash[/code] and [code]%run[/code]. The [code]%%bash[/code] blocks run the following lines using the Bash-like shell you used to open Jupyter with and are typically used for building firmware. The [code]%run[/code] blocks, on the other hand, are used to run other Jupyter notebooks. This avoids duplicating some common blocks across tutorials. To find these notebooks, follow the path specified after the [code]%run[/code] command. For example, if you see a block with [code]%run "Helper_Scripts/Setup.ipynb"[/code], you can find that file at [code]software/Jupyter/Helper_Scripts/Setup.ipynb[/code].
+While running tutorials, you will come across special blocks. For ChipWhisperer's notebooks, the two most common ones are <code>%%bash</code> and <code>%run</code>. The <code>%%bash</code> blocks run the following lines using the Bash-like shell you used to open Jupyter with and are typically used for building firmware. The <code>%run</code> blocks, on the other hand, are used to run other Jupyter notebooks. This avoids duplicating some common blocks across tutorials. To find these notebooks, follow the path specified after the <code>%run</code> command. For example, if you see a block with <code>%run "Helper_Scripts/Setup.ipynb"</code>, you can find that file at <code>software/Jupyter/Helper_Scripts/Setup.ipynb</code>.
 === Editing Blocks ===

@@ Line 1: / Line 1: @@
-The release of ChipWhisperer v5.0 has brought major changes to the front end of the ChipWhisperer software as well as a switch to Python3: the GUI and the wiki tutorials have been replaced with Jupyter Notebooks, which allow users to run interactive Python blocks in their browser. Most of the API remains unchanged from v4 and, with the exception of Python2.7 specific code, most GUI-less scripts should run as is. Additional features, such as ChipWhipserer Analyzer support, are now available outside of any GUI.
+The release of ChipWhisperer v5.0 has brought major changes to the front end of the ChipWhisperer software as well as a switch to Python 3: the GUI and the wiki tutorials have been replaced with Jupyter Notebooks, which allow users to run interactive Python blocks in their browser. Most of the API remains unchanged from v4 and, with the exception of Python 2.7 specific code, most GUI-less scripts should run as is. Additional features, such as ChipWhipserer Analyzer support, are now available outside of any GUI.
-== Jupyter Notebook Tutorials ==
+== What are Jupyter Notebooks? ==
-Starting with ChipWhisperer v5.0, tutorials have been moved from the wiki into Jupyter Notebooks. These are located in <code>software/jupyter</code>, have the extension <code>.ipynb</code>, and can be run by opening the tutorials via the Jupyter Notebook interface. These tutorials contain interactive code blocks, which can run by clicking on them to highlight them, then hitting the run button in the menu at the top of your screen:
+Jupyter notebooks are documents that combine Python code, rich text, and additional code (such as Bash), organized into executable blocks. Notebooks allow users to run blocks out of order and multiple times, giving greater control over what's being run than a Python script. To run these notebooks, you'll need to install the Jupyter Notebook application (installation is covered in a later section), which also includes file browser and text editor capabilities.
-[[File:Running jupyter blocks.PNG|frameless|876x876px]]
+Starting with ChipWhisperer 5, the GUI and Wiki tutorials have been replaced by notebooks. For users, this means that instead of clicking buttons and modifying values in a GUI, users now run and edit Python blocks that use ChipWhisperer's Python API. This has a number of advantages, including less complexity than a full GUI (hopefully fewer bugs), less separation between tutorials and running the software, and teaching users how to use ChipWhisperer's Python API.
-If you need to change anything inside the blocks, double click the block to begin editing them. Since Jupyter runs in your browser, you can improve your workflow by using tabs and windows to open multiple files at a time:
+== Getting Started ==
-[[File:Jupyter Multiple Tabs.PNG|frameless|867x867px]]
+=== Running Jupyter ===
-Everything in these code blocks are actual Python code (unless you see something like <code>%%bash</code> at the top), so these tutorials also provide a reference for creating Python scripts. These tutorials often make use of helper scripts, which are located in the Helper_Scripts folder. The Jupyter folder also contains a <code>Helpful_Code_Blocks</code> file which, as the name suggests, contains blocks of Python code that are often a good start for creating your own notebooks or scripts. The final file of note is <code>!!Suggested_Completion_Order!!</code>, which contains a list of the tutorials in the suggested order that you complete them in.
+For a native installation, open a Bash-like shell terminal (for Windows users, Git Bash will work fine) and navigate to where you installed ChipWhisperer. In Bash, run [code]$ jupyter notebook[/code]. You should be taken to the Jupyter homescreen.
 == New Features ==

@@ Line 21: / Line 21: @@
 * Python 3 support (no longer supports Python 2)
 * Tutorials via Jupyter Notebooks, which showcase how to use the Python API
-** New tutorials, including one submitted by a user via Github
+* New tutorials, including one submitted by a user via Github
 * Support for multiple ChipWhisperers via Python API
 * Improved capture speed

← Older revision		Revision as of 16:54, 13 May 2019
Line 14:		Line 14:

	Everything in these code blocks are actual Python code (unless you see something like <code>%%bash</code> at the top), so these tutorials also provide a reference for creating Python scripts. These tutorials often make use of helper scripts, which are located in the Helper_Scripts folder. The Jupyter folder also contains a <code>Helpful_Code_Blocks</code> file which, as the name suggests, contains blocks of Python code that are often a good start for creating your own notebooks or scripts. The final file of note is <code>!!Suggested_Completion_Order!!</code>, which contains a list of the tutorials in the suggested order that you complete them in.		Everything in these code blocks are actual Python code (unless you see something like <code>%%bash</code> at the top), so these tutorials also provide a reference for creating Python scripts. These tutorials often make use of helper scripts, which are located in the Helper_Scripts folder. The Jupyter folder also contains a <code>Helpful_Code_Blocks</code> file which, as the name suggests, contains blocks of Python code that are often a good start for creating your own notebooks or scripts. The final file of note is <code>!!Suggested_Completion_Order!!</code>, which contains a list of the tutorials in the suggested order that you complete them in.
		+
		+	== New Features ==
		+	New features that are available in CW5 include:
		+
		+	* Analyzer and project support via the Python API
		+	* Python 3 support (no longer supports Python 2)
		+	* Tutorials via Jupyter Notebooks, which showcase how to use the Python API
		+	** New tutorials, including one submitted by a user via Github
		+	* Support for multiple ChipWhisperers via Python API
		+	* Improved capture speed

@@ Line 2: / Line 2: @@
 == Running Jupyter ==
-To run Jupyter natively (aka outside a VM), navigate to the ChipWhisperer directory via a bash command line and run <code>jupyter notebook</code>. A new window should open in your browser. If you're using a ChipWhisperer VM, ensure the VM is booted, open your browser and connect to either 192.168.33.10 (initial 5.0.0 VM release) localhost:8888 (5.0.1+ VM releases). Once you have it started, Jupyter behaves as a mostly normal file explorer inside your browser, allowing you to click on directories to enter them or on files to open them. Once you have files open, you can use Jupyter to edit them as you would any normal text editor.
+To run Jupyter natively (aka outside a VM), navigate to the ChipWhisperer directory via a bash command line and run <code>jupyter notebook</code>. A new window should open in your browser. If you're using a ChipWhisperer VM, ensure the VM is booted, open your browser and connect to either 192.168.33.10 (initial 5.0.0 VM release) or localhost:8888 (5.0.1+ VM releases). Once you have it started, Jupyter behaves as a mostly normal file explorer inside your browser, allowing you to click on directories to enter them or on files to open them. Once you have files open, you can use Jupyter to edit them as you would any normal text editor.
 == Jupyter Notebook Tutorials ==