Merge pull request #380 from xmos/develop

Release 2.3.0

.gitmodules

@@ -19,16 +19,12 @@
 [submodule "modules/xscope_fileio"]
 	path = modules/xscope_fileio/xscope_fileio
 	url = [email protected]:xmos/xscope_fileio.git
-[submodule "modules/inferencing/lib_nn"]
-	path = modules/inferencing/lib_nn
-	url = [email protected]:xmos/lib_nn.git
 [submodule "modules/lib_qspi_fast_read"]
 	path = modules/lib_qspi_fast_read
 	url = [email protected]:xmos/lib_qspi_fast_read.git
-[submodule "modules/inferencing/lib_tflite_micro"]
-	path = modules/inferencing/lib_tflite_micro
-	url = [email protected]:xmos/lib_tflite_micro.git
-	ignore = dirty
 [submodule "modules/xua"]
 	path = modules/xua
 	url = [email protected]:xmos/lib_xua.git
+[submodule "modules/sw_pll"]
+	path = modules/sw_pll
+	url = [email protected]:xmos/lib_sw_pll

CHANGELOG.rst

@@ -1,6 +1,34 @@
 XCORE-VOICE change log
 ======================
 
+2.3.0
+-----
+
+  * CHANGED: Updated Cyberon Wake Word engine.
+  * CHANGED: Updated XTC Tools to 15.3.0.
+  * CHANGED: Updated submodule fwk_io to version v3.6.0 from v3.3.0.
+  * CHANGED: Updated submodule fwk_core to version v1.1.0 from v1.0.2.
+  * CHANGED: Updated submodule fwk_voice to version v0.8.0 from v0.7.0.
+  * CHANGED: Updated submodule fwk_rtos to version 3.2.0 from 3.0.5.
+  * CHANGED: Updated submodule lib_src to version 2.7.0 from 2.4.0.
+  * CHANGED: Updated submodule xscope_fileio to version 1.2.0 from 1.1.2.
+  * ADDED: lib_sw_pll submodule v2.3.1.
+  * ADDED: xmos-ai-tools v1.3.1 Python requirement. 
+  * REMOVED: Deleted inferencing submodule.
+  * ADDED: FFVA INT example with Cyberon speech recognition engine and model
+    (DSpotter v2.2.18.0).
+  * CHANGED: Moved files in folders device_memory, gpio_ctrl, intent_engine and
+    intent_handler from examples/ffd/src to folder modules/asr.
+  * CHANGED: Remove need to use external MCLK in FFVA INT examples
+  * ADDED: Support for DFU over I2C for FFVA INT example.
+  * ADDED: FFD example with I2S audio input to Cyberon speech recognition
+    engine and model.
+  * REMOVED: flash settings in .xn files, as they are not required by XMOS
+    Tools 15.3.0.
+  * ADDED: Support for reading registers over I2C slave in FFD examples.
+  * ADDED: Note in ASRC demo documentation about large latency in ASRC
+    processing. References to alternative application notes have been provided.
+
 2.2.0
 -----
 
@@ -83,4 +111,3 @@ XCORE-VOICE change log
 ------
 
   * ADDED: FFD demo using OLED display
-

Jenkinsfile

@@ -1,4 +1,4 @@
-@Library('xmos_jenkins_shared_library@v0.28.0') _
+@Library('xmos_jenkins_shared_library@v0.34.0') _
 
 getApproval()
 
@@ -15,20 +15,24 @@ pipeline {
     parameters {
         string(
             name: 'TOOLS_VERSION',
-            defaultValue: '15.2.1',
+            defaultValue: '15.3.0',
             description: 'The XTC tools version'
         )
+        string(
+            name: 'XMOSDOC_VERSION',
+            defaultValue: 'v6.2.0',
+            description: 'The xmosdoc version'
+        )
         booleanParam(name: 'NIGHTLY_TEST_ONLY',
             defaultValue: false,
-            description: 'Tests that only run during nightly builds.')
-    }
+            description: 'Tests that only run during nightly builds.'
+        )
+    } // parameters
     environment {
         REPO = 'sln_voice'
         VIEW = getViewName(REPO)
-        PYTHON_VERSION = "3.8.11"
         VENV_DIRNAME = ".venv"
         BUILD_DIRNAME = "dist"
-        XMOSDOC_VERSION = 'v4.0'
         VRD_TEST_RIG_TARGET = "XCORE-AI-EXPLORER"
         PIPELINE_TEST_VECTORS = "pipeline_test_vectors"
         ASR_TEST_VECTORS = "asr_test_vectors"
@@ -52,23 +56,20 @@ pipeline {
                         }
                         stage('Build tests') {
                             steps {
-                                script {
-                                    uid = sh(returnStdout: true, script: 'id -u').trim()
-                                    gid = sh(returnStdout: true, script: 'id -g').trim()
-                                }
-                                // pull docker images
-                                sh "docker pull ghcr.io/xmos/xcore_builder:latest"
-                                sh "docker pull ghcr.io/xmos/xcore_voice_tester:develop"
-                                // host apps
-                                sh "docker run --rm -u $uid:$gid -w /sln_voice -v $WORKSPACE:/sln_voice ghcr.io/xmos/xcore_builder:latest bash -l tools/ci/build_host_apps.sh"
-                                // test firmware and filesystems
-                                sh "docker run --rm -u $uid:$gid -w /sln_voice -v $WORKSPACE:/sln_voice ghcr.io/xmos/xcore_builder:latest bash -l tools/ci/build_tests.sh"
-                                // List built files for log
-                                sh "ls -la dist_host/"
-                                sh "ls -la dist/"
+                                createVenv(reqFile: "requirements.txt")
+                                withTools(params.TOOLS_VERSION) {
+                                    withVenv {
+                                        // host apps
+                                        sh "tools/ci/build_host_apps.sh"
+                                        // test firmware and filesystems
+                                        sh "tools/ci/build_tests.sh"
+                                        // List built files for log
+                                        sh "ls -la dist_host/"
+                                        sh "ls -la dist/"
+                                    } // venv
+                                } // tools
                             }
                         }
-
                         stage('ASRC Unit tests') {
                             steps {
                                 withTools(params.TOOLS_VERSION) {
@@ -98,14 +99,11 @@ pipeline {
                                 }
                             }
                         }
-                        stage('Create virtual environment') {
+                        stage('Install test requirements') {
                             when {
                                 expression { params.NIGHTLY_TEST_ONLY == true }
                             }
                             steps {
-                                // Create venv
-                                sh "pyenv install -s $PYTHON_VERSION"
-                                sh "~/.pyenv/versions/$PYTHON_VERSION/bin/python -m venv $VENV_DIRNAME"
                                 // Install dependencies
                                 withVenv() {
                                     sh "pip install git+https://github0.xmos.com/xmos-int/xtagctl.git"
@@ -182,10 +180,8 @@ pipeline {
                                 withTools(params.TOOLS_VERSION) {
                                     withVenv {
                                         script {
-                                            uid = sh(returnStdout: true, script: 'id -u').trim()
-                                            gid = sh(returnStdout: true, script: 'id -g').trim()
                                             withXTAG(["$VRD_TEST_RIG_TARGET"]) { adapterIDs ->
-                                                sh "docker run --rm -u $uid:$gid --privileged -v /dev/bus/usb:/dev/bus/usb -w /sln_voice -v $WORKSPACE:/sln_voice ghcr.io/xmos/xcore_voice_tester:develop bash -l test/device_firmware_update/check_dfu.sh " + adapterIDs[0]
+                                                sh "test/device_firmware_update/check_dfu.sh " + adapterIDs[0]
                                             }
                                             sh "pytest test/device_firmware_update/test_dfu.py --readback_image test/device_firmware_update/test_output/readback_upgrade.bin --upgrade_image test/device_firmware_update/test_output/test_ffva_dfu_upgrade.bin"
                                         }
@@ -220,6 +216,7 @@ pipeline {
                                 withTools(params.TOOLS_VERSION) {
                                     withVenv {
                                         script {
+                                            sh "xtagctl reset_all $VRD_TEST_RIG_TARGET"
                                             withXTAG(["$VRD_TEST_RIG_TARGET"]) { adapterIDs ->
                                                 sh "test/pipeline/check_pipeline.sh $BUILD_DIRNAME/test_pipeline_ffva_adec_altarch.xe $PIPELINE_TEST_VECTORS test/pipeline/ffva_quick.txt test/pipeline/ffva_test_output $WORKSPACE/amazon_wwe " + adapterIDs[0]
                                             }
@@ -236,6 +233,7 @@ pipeline {
                             steps {
                                 withTools(params.TOOLS_VERSION) {
                                     withVenv {
+                                        sh "xtagctl reset_all $VRD_TEST_RIG_TARGET"
                                         script {
                                             withXTAG(["$VRD_TEST_RIG_TARGET"]) { adapterIDs ->
                                                 sh "test/pipeline/check_pipeline.sh $BUILD_DIRNAME/test_pipeline_ffd.xe $PIPELINE_TEST_VECTORS test/pipeline/ffd_quick.txt test/pipeline/ffd_test_output $WORKSPACE/amazon_wwe " + adapterIDs[0]
@@ -254,10 +252,13 @@ pipeline {
                                 withTools(params.TOOLS_VERSION) {
                                     withVenv {
                                         script {
+                                            sh "xtagctl reset_all $VRD_TEST_RIG_TARGET"
                                             withXTAG(["$VRD_TEST_RIG_TARGET"]) { adapterIDs ->
-                                                sh "test/asr/check_asr.sh Sensory $ASR_TEST_VECTORS test/asr/ffd_quick.txt test/asr/sensory_output " + adapterIDs[0]
+                                                sh "test/asr/check_asr.sh Sensory $ASR_TEST_VECTORS test/asr/ffd_quick_sensory.txt test/asr/sensory_output " + adapterIDs[0]
+                                                sh "test/asr/check_asr.sh Cyberon $ASR_TEST_VECTORS test/asr/ffd_quick_cyberon.txt test/asr/cyberon_output " + adapterIDs[0]
                                             }
                                             sh "pytest test/asr/test_asr.py --log test/asr/sensory_output/results.csv"
+                                            sh "pytest test/asr/test_asr.py --log test/asr/cyberon_output/results.csv"
                                         }
                                     }
                                 }
@@ -273,28 +274,24 @@ pipeline {
                         }
                     }
                 }
-                stage('Build docs') {
-                    agent { label 'docker' }
-                    stages {
-                        stage ('Build docs with docker') {
-                            steps {
-                                checkout scm
-                                sh 'git submodule update --init --recursive --depth 1 --jobs \$(nproc)'
-                                sh "docker pull ghcr.io/xmos/xmosdoc:$XMOSDOC_VERSION"
-                                sh """docker run -u "\$(id -u):\$(id -g)" \
-                                        --rm \
-                                        -v ${WORKSPACE}:/build \
-                                        ghcr.io/xmos/xmosdoc:$XMOSDOC_VERSION -v"""
-                                archiveArtifacts artifacts: 'doc/_build/**', allowEmptyArchive: true
-                            }
-                        }
+                stage('Build Documentation') {
+                    agent {
+                        label 'documentation&&docker'
                     }
+                    steps {
+                        checkout scm
+                        sh 'git submodule update --init --recursive --depth 1 --jobs \$(nproc)'
+                        warnError("Docs") {
+                            buildDocs(archiveZipOnly: true)
+                        } // warnError("Docs")
+                    } // steps
                     post {
                         cleanup {
                             xcoreCleanSandbox()
                         }
                     }
-                }
+                } // stage('Build Documentation')
+
             }
         }
     }

README.rst

@@ -2,14 +2,14 @@
 XCORE:registered:-VOICE Solution Repository
 *******************************************
 
-The XCORE-VOICE Solution consists of example designs and a C-based SDK for the development of audio front-end applications to support far-field voice use cases on the xcore.ai family of chips (XU316). The XCORE-VOICE design is currently based on FreeRTOS, leveraging the flexibility of the xcore.ai platform and providing designers with a familiar environment to customize and develop products.
+The XCORE-VOICE Solution consists of example designs and a C-based SDK for the development of audio front-end applications to support far-field voice use cases on the xcore.ai family of chips (XU316). Most of the XCORE-VOICE designs are based on FreeRTOS, leveraging the flexibility of the xcore.ai platform and providing designers with a familiar environment to customize and develop products. The only exception is the Microphone Aggregation example which runs on bare-metal; this architecture was selected as it suits high IO bandwidth and low latency bridging type applications.
 
 XCORE-VOICE example designs provide turn-key solutions to enable easier product development for smart home applications such as light switches, thermostats, and home appliances. xcore.ai’s unique architecture providing powerful signal processing and accelerated AI capabilities combined with the XCORE-VOICE framework allows designers to incorporate keyword, event detection, or advanced local dictionary support to create a complete voice interface solution.
 
-Cloning
-*******
+Obtaining the Source Code
+*************************
 
-Some dependent components are included as git submodules. These can be obtained by cloning this repository with the following command:
+If you are interested in compiling and/or modifying the source code, you can download it from GitHub. As some dependent components are included as git submodules, the following command must be used for cloning this repository:
 
 ::
 
@@ -27,17 +27,15 @@ Documentation
 
 See the READMEs for the early example applications:
 
-`ASRC Demo <https://github.com/xmos/sln_voice/blob/develop/examples/asrc_demo/README.rst>`_
-
-`FFD <https://github.com/xmos/sln_voice/blob/develop/examples/ffd/README.rst>`_
+  * `ASRC Demo <https://github.com/xmos/sln_voice/blob/develop/examples/asrc_demo/README.rst>`_: an example design for an asynchronous sampling rate converter (ASRC)
 
-`FFVA <https://github.com/xmos/sln_voice/blob/develop/examples/ffva/README.rst>`_
+  * `FFD <https://github.com/xmos/sln_voice/blob/develop/examples/ffd/README.rst>`_: two example designs for a far-field voice local control, each example contains a boot image and data partition binary
 
-`Low Power FFD <https://github.com/xmos/sln_voice/blob/develop/examples/low_power_ffd/README.rst>`_
+  * `FFVA <https://github.com/xmos/sln_voice/blob/develop/examples/ffva/README.rst>`_: two example designs for a far-field voice assistant, each example contains a boot image and data partition binary
 
-`Microphone Aggregator <https://github.com/xmos/sln_voice/blob/develop/examples/mic_aggregator/README.rst>`_
+  * `Low Power FFD <https://github.com/xmos/sln_voice/blob/develop/examples/low_power_ffd/README.rst>`_: an example design for a low-power far-field voice local control, the example contains a boot image and data partition binary
 
-`Speech Recognition <https://github.com/xmos/sln_voice/blob/develop/examples/speech_recognition/README.rst>`_
+  * `Microphone Aggregator <https://github.com/xmos/sln_voice/blob/develop/examples/mic_aggregator/README.rst>`_: two example designs bridging 16 PDM microphones to either TDM16 slave or USB Audio
 
 Getting Help
 ************

doc/programming_guide/asr/deploying/linux_macos.rst

@@ -27,15 +27,16 @@ Run the following commands in the root folder to build the host application usin
 
 The host application, ``xscope_host_endpoint``, will be installed at ``/opt/xmos/bin``, and may be moved if desired.  You may wish to add this directory to your ``PATH`` variable.
 
-Before running the host application, you may need to add the location of ``xscope_endpoint.so`` to your ``LD_LIBRARY_PATH`` environment variable.  This environment variable will be set if you run the host application in the XTC Tools command-line environment.  For more information see `Configuring the command-line environment <https://www.xmos.ai/documentation/XM-014363-PC-LATEST/html/tools-guide/install-configure/getting-started.html>`__.
+Before running the host application, you may need to add the location of ``xscope_endpoint.so`` to your ``LD_LIBRARY_PATH`` environment variable.  This environment variable will be set if you run the host application in the XTC Tools command-line environment.  For more information see `Configuring the command-line environment <https://xmos.com/xtc-install-guide>`__.
 
 Building the Firmware
 =====================
 
-Run the following commands in the root folder to build the firmware:
+After having your python environment activated, run the following commands in the root folder to build the firmware:
 
 .. code-block:: console
 
+    pip install -r requirements.txt
     cmake -B build --toolchain=xmos_cmake_toolchain/xs3a.cmake
     cd build
     make example_asr
@@ -64,7 +65,7 @@ From the build folder run:
 
 .. code-block:: console
 
-    xrun --xscope-realtime --xscope-port localhost:12345 example_asr.xe
+    xrun --xscope --xscope-port localhost:12345 example_asr.xe
 
 In a second console, run the following command in the ``examples/speech_recognition`` folder to run the host server: