Merge pull request #1890 from annietllnd/content-review

Technical review of CMSIS-DSP LP

Author: pareenaverma

content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/_index.md

@@ -3,16 +3,19 @@ title: Getting Started with CMSIS-DSP Using Python
 
 minutes_to_complete: 30
 
-who_is_this_for: Developers writing DSP/AI software
+draft: true
+cascade:
+    draft: true
 
-learning_objectives: 
+who_is_this_for: Developers who want to learn how the CMSIS-DSP package can be integrated into their applications
+
+learning_objectives:
     - Understand how to use the CMSIS-DSP Python package
     - Understand how the Python implementation maps to the C implementation
     - Develop a complex application using CMSIS-DSP
 
 prerequisites:
-    - Some familiarity with DSP programming
-    - Some familiarity with Python programming
+    - Some familiarity with Python and DSP programming
     - Knowledge of C
     - Some familiarity with CMSIS-DSP
     - Python installed on your system
@@ -26,20 +29,16 @@ armips:
     - Cortex-M
     - Cortex-A
 tools_software_languages:
-    - VS Code
     - CMSIS-DSP
     - Python
     - C
     - Jupyter Notebook
+    - numpy
 operatingsystems:
     - Linux
     - Windows
     - macOS
 
-
-
-
-
 further_reading:
     - resource:
         title: Biquad filters with CMSIS-DSP Python package
@@ -61,7 +60,7 @@ further_reading:
         title: CMSIS-Stream
         link: https://github.com/ARM-software/CMSIS-Stream
         type: Open-source project
-   
+
 
 ### FIXED, DO NOT MODIFY
 # ================================================================================

content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-1.md

@@ -1,18 +1,18 @@
 ---
-title: What is the CMSIS-DSP Python package ?
+title: CMSIS-DSP Python package
 weight: 2
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## What is CMSIS-DSP ?
+## What is CMSIS-DSP?
 
 CMSIS-DSP is a general-purpose compute library with a focus on DSP. It was initially developed for Cortex-M processors and has recently been upgraded to also support Cortex-A.
 
 On each processor, CMSIS-DSP is optimized for the architecture: DSP extensions on M4 and M7; Helium on M55 and M85; Neon on A55, etc.
 
-## What is the CMSIS-DSP Python package ?
+## What is the CMSIS-DSP Python package?
 
 The CMSIS-DSP Python package is a Python API for CMSIS-DSP. Its goal is to make it easier to develop a C solution using CMSIS-DSP by decreasing the gap between a design environment like Python and the final C implementation.
 

content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-2.md

@@ -6,10 +6,13 @@ weight: 3
 layout: learningpathall
 ---
 
-## Installing the Python packages
-The application you will develop with CMSIS-DSP requires a few additional Python packages besides CMSIS-DSP. These need to be installed before you start writing code.
+The application you will develop requires a few additional Python packages besides CMSIS-DSP. These need to be installed before you start writing code.
 
-Activate the Python environment you have chosen.
+You should install the packages in a Python virtual environment. For example, you can use:
+
+```
+python -m venv cmsis-dsp-venv
+```
 
 The first package to install is CMSIS-DSP:
 
@@ -18,43 +21,32 @@ pip install cmsisdsp
 ```
 It will also install `NumPy`, which is a dependency of the CMSIS-DSP Python package.
 
-You'll be working with a Jupyter notebook, so the jupyter package must also be installed:
+You'll be working with a Jupyter notebook, so the `jupyter` package must also be installed:
 
 ```bash
 pip install jupyter
 ```
 
-In the Jupyter notebook, you'll be using widgets to play sound, so you'll need to install some additional Jupyter widgets.
-
-```bash
-pip install ipywidgets
-```
-
-Finally, you'll need packages to read sound files and display plots:
-
+Finally, you'll need packages to read sound files, play sound using widgets, and display plots:
 
 ```bash
-pip install soundfile
-pip install matplotlib
+pip install soundfile ipywidgets matplotlib
 ```
 
-you can now launch the Jupyter notebook:
+You can now launch the Jupyter notebook with the following command:
 
 ```bash
 jupyter notebook
 ```
-Create a new Jupyter notebook by clicking `new` and selecting `Python 3 (ipykernel)`.
-
-The new notebook will be named `Untitled`. Rename it to something more descriptive.
-
-You can now import all the required packages. 
+A browser window should open showing the source tree your terminal launched from. Create a new Jupyter notebook by clicking the `New` dropdown and selecting `Python 3 (ipykernel)`. The new notebook will be named `Untitled`. Rename it to something more descriptive, for example `cmsis-dsp`.
 
-Type the following Python code into your notebook and run the cell (shift-enter).
-All the Python code in this learning path is intended to be executed in the same Jupyter notebook.
+You can now import all the required packages. Copy the following Python code into your notebook and run the cell (Shift+Enter).
+All the Python code blocks in this learning path are intended to be executed in the same Jupyter notebook.
 
 ```python
-import cmsisdsp as dsp 
+import cmsisdsp as dsp
 import cmsisdsp.fixedpoint as fix
+from cmsisdsp import datatype as dt
 import numpy as np
 from numpy.lib.stride_tricks import sliding_window_view
 
@@ -69,8 +61,8 @@ from IPython.display import display,Audio
 import io
 import soundfile as sf
 
-# To load test patterns from the Arm Virtual Hardware Echo Canceller dem
+# To load test patterns from the Arm Virtual Hardware Echo Canceller demo
 from urllib.request import urlopen
 ```
 
-You're now ready to move on to the next steps.
+You're now ready to move on to the next steps, where you will set up some audio files for processing.

content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-3.md

@@ -8,8 +8,7 @@ layout: learningpathall
 
 ## Load an audio file
 
-Load an audio file from one of the Arm demo repositories on GitHub.
-
+You will use an audio file from one of the Arm demo repositories on GitHub.
 
 ```python
 test_pattern_url="https://github.com/ARM-software/VHT-SystemModeling/blob/main/EchoCanceller/sounds/yesno.wav?raw=true"
@@ -18,20 +17,17 @@ filedata = f.read()
 ```
 
 You can now play and listen to the audio:
+
 ```python
 audio=Audio(data=filedata,autoplay=False)
 audio
 ```
 
-An audio widget will appear in your Jupyter notebook. It will look like this:
+An audio widget will appear in your Jupyter notebook:
 
 ![audio widget alt-text#center](audiowidget.png "Figure 1. Audio widget")
 
-You can use it to listen to the audio.
-
-You'll hear a sequence of the words "yes" and "no", with some noise between them.
-The goal of this learning path is to design an algorithm to remove the noise.
-
+You can use it to listen to the audio. You'll hear a sequence of the words "yes" and "no", with some noise between them. The goal of this learning path is to design an algorithm to remove the noise.
 
 Next, convert the audio into a NumPy array so that it can be processed using CMSIS-DSP:
 
@@ -65,9 +61,7 @@ In the picture, you can see a sequence of words. Between the words, the signal i
 
 In a real application, you don't wait for the entire signal to be received. The signal is continuous. The samples are processed as they are received. Processing can either be sample-based or block-based. For this learning path, the processing will be block-based.
 
-Before you can move to the next step, this signal must be split into blocks. The processing will occur on small blocks of samples of a given duration.
-
-
+Before you can move to the next step, this signal must be split into blocks. The processing will occur on small blocks of samples of a given duration, known as windows.
 
 ```python
 winDuration=30e-3/6
@@ -79,9 +73,7 @@ slices=sliding_window_view(data,winLength)[::winOverlap,:]
 slices_q15=sliding_window_view(dataQ15,winLength)[::winOverlap,:]
 ```
 
-Refer to the [NumPy documentation](https://numpy.org/doc/stable/reference/generated/numpy.lib.stride_tricks.sliding_window_view.html) for details about `sliding_window_view`. It's not the most efficient function, but it is sufficient for this tutorial.
-
-The signal is split into overlapping blocks: each block reuses half of the samples from the previous block as defined by the `winOverlap` variable.
+Refer to the [NumPy documentation](https://numpy.org/doc/stable/reference/generated/numpy.lib.stride_tricks.sliding_window_view.html) for details about `sliding_window_view`. It's not the most efficient function, but it is sufficient for this tutorial. The signal is split into overlapping blocks: each block reuses half of the samples from the previous block as defined by the `winOverlap` variable.
 
-You are now ready to move on to the next step: you have an audio signal that has been split into overlapping blocks, and processing will occur on those blocks.
+By running that last block, you have an audio signal that has been split into overlapping blocks. The next step is to do some processing on those blocks.
 

content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-4.md

@@ -8,15 +8,11 @@ layout: learningpathall
 
 ## Write a simple voice activity detection
 
-To remove the noise between speech segments, you need to detect when voice is present.
+To remove the noise between speech segments, you need to detect when voice is present. Voice activity detection (VAD) can be complex, but for this learning path, you'll implement a very simple and naive approach based on _energy_. The idea is that if the environment isn't too noisy, speech should have more energy than the noise.
 
-Voice activity detection can be complex, but for this learning path, you'll implement a very simple and naive approach based on energy. The idea is that if the environment isn't too noisy, speech should have more energy than the noise.
+The detection will rely on a comparison with a threshold that must be manually tuned. That threshold will be hard-coded, which might not work in a real-life use-case, but is a sufficient solution for this learning path. You'll first implement a version of the VAD with NumPy, which will serve as a reference. Then you'll implement the same version using CMSIS-DSP with the Q15 fixed-point format.
 
-The detection will rely on a comparison with a threshold that must be manually tuned.
-
-You'll first implement a version of the voice activity detection (VAD) with NumPy, which will serve as a reference.
-
-Then you'll implement the same version using CMSIS-DSP with the Q15 fixed-point format.
+Throughout this section, you should copy the code-blocks and run them in your Jupyter notebook.
 
 ### NumPy VAD
 
@@ -38,9 +34,7 @@ def signal_vad(window):
         return(0)
 ```
 
-The threshold is hard-coded. It's not a very clean solution, but it's sufficient for a tutorial.
-
-When using such a detector, you'll quickly find that it is not sufficient. You'll need another pass to clean up the detection signal.
+Additionally, you'll need another pass to clean up the detection signal.
 
 ```python
 def clean_vad(v):
@@ -53,7 +47,7 @@ def clean_vad(v):
     return(vmax)
 ```
 
-Now you can apply this algorithm to the audio signal and plot the VAD detection over it to see if it's working:
+Now you can apply this algorithm to the audio signal and plot the VAD over it to see if it's working:
 
 ```python
 _,ax=plt.subplots(1,1)
@@ -62,58 +56,58 @@ vad = np.array([[w]*(winLength-winOverlap) for w in cleaned]).flatten()
 ax.plot(data)
 ax.plot(vad)
 ```
-![vad alt-text#center](vad.png "Figure 3. VAD")
+![vad alt-text#center](vad.png "Figure 3. VAD reference implementation")
 
-The reference implementation works. You can now implement the same version using CMSIS-DSP.
+This plot shows you that the reference implementation works. The next step is to implement a similar graph using CMSIS-DSP.
 
 ### CMSIS-DSP Q15 VAD
 
-First, you need to compute the signal energy from audio in Q15 format using CMSIS-DSP. 
+#### Energy
+First, you need to compute the signal energy from audio in Q15 format using CMSIS-DSP.
 
-If you look at the CMSIS-DSP documentation, you'll see that the power and log functions don't produce results in Q15 format. Tracking the fixed-point format throughout all lines of an algorithm can be challenging. 
+If you look at the CMSIS-DSP documentation, you'll see that the `power` and `vlog` functions don't produce results in Q15 format. Tracking the fixed-point format throughout all lines of an algorithm can be challenging. In this example, this means that:
+
+* Subtracting the mean to center the signal - as you did in the reference implementation - is handled in CMSIS-DSP by negating the mean and applying it as an offset to the window. Because the mean is small and the shift is minor relative to the Q15 range, this adjustment won't cause saturation.
+* The resulting `energy` and `dB` values are not in Q15 format because the `power` and `vlog` functions are used
+* The multiplication by 10 from the reference implementation is missing
+
+This means that the `signal_energy_q15` will have a different output than the above implementation. Instead of trying to determine the exact fixed-point format of the output and applying the necessary shift to adjust the output's fixed-point format, you will address it in the next step. By tuning the threshold of the detection function, the comparison with the reference VAD can be valid.
 
-For this tutorial, instead of trying to determine the exact fixed-point format of the output and applying the necessary shift to adjust the output's fixed-point format, we'll simply tune the threshold of the detection function.
 
 ```python
 def signal_energy_q15(window):
+    # Calculate window
     mean=dsp.arm_mean_q15(window)
-    # Subtracting the mean won't cause saturation
-    # So we use the CMSIS-DSP negate function on an array containing a single sample.
     neg_mean=dsp.arm_negate_q15([mean])[0]
     window=dsp.arm_offset_q15(window,neg_mean)
+
+    # Energy of the window
     energy=dsp.arm_power_q15(window)
-    # Energy is not in Q15 format (refer to the CMSIS-DSP documentation).
     energy=dsp.ssat(energy>>20,16)
     dB=dsp.arm_vlog_q15([energy])
-    # The output of the `vlog` is not in q15
-    # The multiplication by 10 is missing compared to the NumPy
-    # reference implementation.
-    # The result of this function is not equivalent to the float implementation due to different 
-    # formats used in intermediate computations.
-    # As a consequence, a different threshold must be used to compensate for these differences.
+
     return(dB[0])
 ```
 
+#### VAD
+
 The comparison function is very similar to the NumPy reference, but the threshold is different:
 
 ```python
 def signal_vad_q15(window):
-    # The threshold is not directly comparable to the float implementation
-    # due to the different intermediate formats used in the fixed-point implementation.
     if signal_energy_q15(window)>fix.toQ15(-0.38):
         return(1)
     else:
         return(0)
 ```
 
-Note that in a C code, you would use the output of `fix.toQ15(-0.38)`.
-
-`fix.toQ15` is a utility of the Python package to convert float to fixed-point. It is not available in the CMSIS-DSP C implementation.
-CMSIS-DSP C has functions like `arm_float_to_q15` which work on arrays and are meant to be used at runtime. If you need a precomputed constant, you can use a utility function like `fix.toQ15` and use the resulting value in the code.
+{{% notice Note %}}
+In C code, you would hard-code the output of `fix.toQ15(-0.38)`. `fix.toQ15` is a utility of the Python package to convert float to fixed-point, but it is not available in the CMSIS-DSP C implementation. CMSIS-DSP C has functions like `arm_float_to_q15` which work on arrays and are meant to be used at runtime. If you need a pre-computed constant, you can use a utility function like `fix.toQ15` during development and use the resulting value in the C code.
+{{% /notice %}}
 
-The clean VAD function is the same for both the NumPy and Q15 versions. 
+#### Plot the Q15 implementation
 
-Now you can check whether the Q15 version is working by plotting the signal and the output of the Q15 VAD algorithm.
+The clean VAD function is now the same for both the NumPy and Q15 versions. You can check whether the Q15 version is working by plotting the signal and the output of the Q15 VAD algorithm.
 
 ```python
 _,ax=plt.subplots(1,1)
@@ -122,4 +116,6 @@ vad_q15 = np.array([[w]*winOverlap for w in cleaned]).flatten()
 ax.plot(data)
 ax.plot(vad_q15)
 
-```
+```
+
+Now that you have a working VAD implementation, move on to the next section to combine the principles into a Python class for noise suppression.