Configuration and control¶
The XVF3610 family of processors are intended to be used to provide a far-field voice interface to a host system or processor in speech recognition and communication applications, either closely integrated to the main processor or as a USB accessory. As such the XVF3610 provides boot mechanisms from either an external QSPI flash or by the host processor over SPI interface.
To facilitate control in both boot configurations and to allow the specification of the default behaviour, the XVF3610 implements two mechanisms for control and parameterisation. The first is the Control Interface which is a direct connection between the host and the XVF3610 and is operational at runtime. The second is the Data Partition which is held in flash and contains configuration data to parameterise the XVF3610 on boot up. Both mechanisms have access to the full set of parameters and can both be used in the application to control and specify the behaviour of the device.
A host tool (vfctrl) is also provided provides command-line access to the control interface, allowing user access to all the configuration parameters of the XVF3610.
Command-line interface (vfctrl)¶
To allow command-line access to the control interface on the XVF3610 processor, the vfctrl (VocalFusion Control) utility is provided as part of the release package. This utility
Two versions of this utility are provided for control of the device (a third is used internally by the Data Partition generation process):
Host platforms supported
Control of XVF3610-UA over a USB interface
Windows, MacOS, Linux,
Raspberry Pi OS
Control of XVF3610-INT over i2c interface
Raspberry Pi OS
Source code for the utility is also provided for compilation for other host devices if required.
The general syntax of the command line tool, when used for device control, is as follows:
vfctrl_usb <COMMAND> [ arg 1] [arg 2]....[arg N] ['# Comment']
The <COMMAND> is required and is used to control the parameters of
the device. Commands can be read and write commands and are
distinguished by the prefix
SET_ for parameter read and
The available commands are described in detail in specific sections of the user guide, and a summary table of all the parameters is provided.
Following the <COMMAND> there are a number of optional arguments [arg 1]..[arg N] which depend on the specific parameter. These are detailed in the command tables later in the document.
If the <COMMAND> is a GET_ command, the output of the operation is printed to the terminal as in the example below:
vfctrl_usb GET_GPI GET_GPI: 13
The number and type of arguments depend on the command and these are detailed in the command tables. Arguments are integer numbers separated by a space. For setting some parameters that require floating-point data, the numbers have to be first converted to a Q format and then transferred as integers.
The specification of the Q format for representing floating-point numbers is given in Appendix H.
A secondary form of vfctrl is also available which provides information for developers
Where [options] can be:
-h, --help : List all command options -d, --dump-params : Print list of parameter values -n, --no-check-version : Do not check version of firmware image
Configuration via Control interface¶
The XVF3610 Voice Processor contains parameters which can be read and written by the host processor at run time. For information writing parameters at boot time for initial configuration, please see Configuration via Data Partition
The XVF3610 firmware is provided as two pre-compiled builds, -UA and -INT, which provide a parameter control mechanism over USB endpoint 0 and I2C respectively.
Device functions have controllable parameters for the audio pipeline, GPIO, sample rate settings, audio muxing, timing and general device setup and adjustment. Commands support either read using the GET_ prefix or write using the SET_ prefix. Controllable parameters may either be readable and writeable, read-only or write-only. Various data types are supported including signed/unsigned integer of either 8b or 32b, fixed point signed/unsigned and floating-point.
In addition, the -UA build includes volume controls for input (processed mic from XVF3610) and output (far-end reference signal). These are USB Audio Class 1.0 compliant controls and are accessed via the host OS audio control panel instead of the XVF3610 control interface. The volumes are initialised to 100% (0dB attenuation) on device power up, which is the recommended setting.
Ensure that the XVF3610-UA USB Audio input and output volume controls on the host are set to 100% (no attenuation) to ensure proper operation of the device. Some host OS (eg. Windows) may store volume setting in between device connections.
For a comprehensive list of parameters, their data types and an understanding of their function within the device please consult the User Guide section relevant to the function of interest, or Appendix A which summarises all the commands. The control utility can also be used by supplying the -h argument to the command line. This dumps a list of commands to the console along with a brief description of the function of each command. The remainder of this section will cover the generic operation of the control interface.
The control interface works by sending a message from the host to the control process within the XVF3610 device. The time required to execute commands can vary, but most will respond within 30ms. Since the commands are fully acknowledged, by design, the control utility blocks until completion. This interface is designed to allow real-time tuning and adjustment but may stall due to bus access or data retrieval.
The control interface consists of two parts a host side application and the device application. These are briefly summarised below.
The example host applications, found in the /host directory in the Release Package, are command-line utilities that accept text commands and, in the case of a read, provides a text response containing the read parameter(s). Full acknowledgement is included in the protocol and an error is returned in the case of the command not being executed properly or handled correctly by the device.
Example host source code and makefiles for are provided in the release package for x86 Linux, ARM Linux (Raspberry Pi), Windows and Mac platforms along with pre-compiled executables to allow fast evaluation and integration. For more information refer to the Building the host utilities from source code section.
The device is always ready to receive commands. The device includes command buffering and an asynchronous mechanism which means that Endpoint 0, NACKing for USB or clock stretching for I2C is not required. This simplifies the host requirements particularly in the cases where clock stretching is not supported by the host I2C peripheral.
Configuration via Data Partition¶
VocalFusion device flash firmware configuration is comprised of a Boot image and a Data Partition.
The Boot image in the form of an .xe archive is the executable code. It is provided as part of the XVF3610-UA or XVF3610-INT Release Package. This configures the underlying operation of the device.
The Data Partition configures a running Boot image instance at startup with a set of commands which are customisable for the specific application. This contains any command that can be issued at run-time via USB or I2C, plus some more that are boot-time only. Pre-configured Data Partitions are supplied in the release packages for default operation.
This combination of Boot image and Data Partition allow the functionality of the processor to be configured and defined without requiring any modification or recompilation of base firmware. The commands discussed in subsequent sections can be stored in the Data Partition, for execution at startup redefining the default operation of the device.