Add learning path "get started with CMSIS-DSP using Python"

Author: christophe0606

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

@@ -0,0 +1,71 @@
+---
+title: Learn how to get started with CMSIS-DSP using Python
+
+minutes_to_complete: 10
+
+who_is_this_for: Developers writing DSP/AI software
+
+learning_objectives: 
+    - Understand how to use the CMSIS-DSP Python package
+    - Understand how the Python implementation maps to the C one
+    - Develop a complex application with CMSIS-DSP
+
+prerequisites:
+    - Some familiarity with DSP programming
+    - Some familiarity with Python programming
+    - Knowledge of C
+    - Some familiarity with CMSIS-DSP
+    - Python installed on your computer
+
+author: Christophe Favergeon
+
+### Tags
+skilllevels: Advanced
+subjects: Libraries
+armips:
+    - Cortex-M
+    - Cortex-A
+tools_software_languages:
+    - VS Code
+    - CMSIS-DSP
+    - Python
+    - C
+    - Jupyter Notebook
+operatingsystems:
+    - Linux
+    - Windows
+    - macOS
+
+
+
+
+
+further_reading:
+    - resource:
+        title: Biquad filters with CMSIS-DSP Python package
+        link: https://developer.arm.com/documentation/102463/latest/
+        type: documentation
+    - resource:
+        title: CMSIS-DSP library
+        link: https://github.com/ARM-software/CMSIS-DSP
+        type: Open-source project
+    - resource:
+        title: CMSIS-DSP python package
+        link: https://pypi.org/project/cmsisdsp/
+        type: Open-source project
+    - resource:
+        title: CMSIS-DSP Python package examples and tests
+        link: https://github.com/ARM-software/CMSIS-DSP/tree/main/PythonWrapper/examples
+        type: Open-source project
+    - resource:
+        title: CMSIS-Stream
+        link: https://github.com/ARM-software/CMSIS-Stream
+        type: Open-source project
+   
+
+### FIXED, DO NOT MODIFY
+# ================================================================================
+weight: 1                       # _index.md always has weight of 1 to order correctly
+layout: "learningpathall"       # All files under learning paths have this same wrapper
+learning_path_main_page: "yes"  # This should be surfaced when looking for related content. Only set for _index.md of learning path content.
+---

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

@@ -0,0 +1,8 @@
+---
+# ================================================================================
+#       FIXED, DO NOT MODIFY THIS FILE
+# ================================================================================
+weight: 21                  # Set to always be larger than the content in this path to be at the end of the navigation.
+title: "Next Steps"         # Always the same, html page title.
+layout: "learningpathall"   # All files under learning paths have this same wrapper for Hugo processing.
+---

content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/audiowidget.png

@@ -0,0 +1,24 @@
+---
+title: What is the CMSIS-DSP Python package ?
+weight: 2
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## 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 ?
+
+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.
+
+For this reason, the Python API is as close as possible to the C one.
+
+Fixed point arithmetic is not often provided by Python packages which generally focus on floating-point operations. The CMSIS-DSP Python package provides the same fixed point arithmetic functions as the C version : Q31, Q15 and Q7. The package is also providing float functions and in the future will also provide half-precision floats like the C API.
+
+Finally, the CMSIS-DSP Python package is compatible with NumPy and can be used with all other scientific and AI Python packages such as SciPy or PyTorch.
+

content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/cleaned.png

@@ -0,0 +1,76 @@
+---
+title: Install the Python packages
+weight: 3
+
+### FIXED, DO NOT MODIFY
+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.
+
+Activate the Python environment you have chosen.
+
+The first package to install is CMSIS-DSP:
+
+```bash
+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:
+
+```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:
+
+
+```bash
+pip install soundfile
+pip install matplotlib
+```
+
+you can now launch the Jupyter notebook:
+
+```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. 
+
+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.
+
+```python
+import cmsisdsp as dsp 
+import cmsisdsp.fixedpoint as fix
+import numpy as np
+from numpy.lib.stride_tricks import sliding_window_view
+
+# Package for plotting
+import matplotlib.pyplot as plt
+
+# Package to display audio widgets in the notebook and upload sound files
+import ipywidgets
+from IPython.display import display,Audio
+
+# To convert a sound file to a NumPy array
+import io
+import soundfile as sf
+
+# To load test patterns from the Arm Virtual Hardware Echo Canceller dem
+from urllib.request import urlopen
+```
+
+You're now ready to move on to the next steps.

content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/hanning.png

@@ -0,0 +1,87 @@
+---
+title: Load an audio file
+weight: 4
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Load an audio file
+
+Load 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"
+f = urlopen(test_pattern_url)
+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:
+
+![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.
+
+
+Next, convert the audio into a NumPy array so that it can be processed using CMSIS-DSP:
+
+```python
+data, samplerate = sf.read(io.BytesIO(filedata))
+if len(data.shape)>1:
+    data=data[:,0]
+data = data.astype(np.float32)
+data=data/np.max(np.abs(data))
+dataQ15 = fix.toQ15(data)
+```
+
+The code above does the following:
+- Converts the audio into a NumPy array
+- If the audio is stereo, only one channel is kept
+- Normalizes the audio to ensure no value exceeds 1
+- Converts the audio to Q15 fixed-point representation to enable the use of CMSIS-DSP fixed-point functions
+
+Now, plot the audio waveform:
+
+```python
+plt.plot(data)
+plt.show()
+```
+
+You'll get the following output:
+
+![audio signal alt-text#center](signal.png "Figure 2. Audio signal")
+
+In the picture, you can see a sequence of words. Between the words, the signal is not zero: there is some noise.
+
+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.
+
+
+
+```python
+winDuration=30e-3/6
+winOverlap=15e-3/6
+
+winLength=int(np.floor(samplerate*winDuration))
+winOverlap=int(np.floor(samplerate*winOverlap))
+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.
+
+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.
+

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

@@ -0,0 +1,126 @@
+---
+title: Write a simple VAD
+weight: 5
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Write a simple voice activity detection
+
+To remove the noise between speech segments, you need to detect when voice is present.
+
+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.
+
+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.
+
+### NumPy VAD
+
+First, you need to compute the energy of the signal within a block of samples. You'll ignore any constant component and focus only on the varying part of the signal:
+
+```python
+# Energy of the window
+def signal_energy(window):
+    w = window - np.mean(window)
+    return(10*np.log10(np.sum(window * window)))
+```
+Then, compare the energy to a threshold to determine whether the block of audio is speech or noise:
+
+```python
+def signal_vad(window):
+    if signal_energy(window)>-11:
+        return(1)
+    else:
+        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.
+
+```python
+def clean_vad(v):
+    v = np.hstack([[0],v,[0]])
+    # Remove isolated peak
+    vmin=[np.min(l) for l in sliding_window_view(v,3)]
+    vmin = np.hstack([[0,0],vmin,[0]])
+    # Remove isolated hole
+    vmax=[np.max(l) for l in sliding_window_view(vmin,4)]
+    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:
+
+```python
+_,ax=plt.subplots(1,1)
+cleaned=clean_vad([signal_vad(w) for w in slices])
+vad = np.array([[w]*(winLength-winOverlap) for w in cleaned]).flatten()
+ax.plot(data)
+ax.plot(vad)
+```
+The reference implementation works. You can now implement the same version using CMSIS-DSP.
+
+![vad alt-text#center](vad.png "Figure 3. VAD")
+
+
+### CMSIS-DSP Q15 VAD
+
+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. 
+
+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):
+    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=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])
+```
+
+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.
+
+The clean VAD function is the same for both the NumPy and Q15 versions. 
+
+Now 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)
+cleaned=clean_vad([signal_vad_q15(w) for w in slices_q15])
+vad_q15 = np.array([[w]*winOverlap for w in cleaned]).flatten()
+ax.plot(data)
+ax.plot(vad_q15)
+
+```