Configuration and control

The XVF3610 family of processors are designed 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.

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 be used by a host application to control the behaviour of the device.

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.

Two versions of this utility are provided for control of the device (a third is used internally by the Data Partition generation process):

Table 4 vfctrl versions and platforms

Version

Function

Host platforms supported

vfctrl_usb

Control of XVF3610-UA over a USB interface
Windows, MacOS, Linux,
Raspberry Pi OS

vfctrl_i2c

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.

Note

For cross-platform support vfctrl_usb uses libusb. While this is natively supported in macOS and most Linux distributions, it requires the installation of a driver for use on a Windows host. Driver installation should be done using a third-party installation tool like Zadig (https://zadig.akeo.ie/).

vfctrl syntax

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. Each command either reads or writes parameters to the XVF3610 device. Commands that read parameters begin with GET_. Commands that write parameters begin with SET_.

The available commands are described in detail in the command reference section 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

vfctrl [options]

Where [options] can be:

-h, --help : List basic 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 about 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 full list of commands can be obtained through the use of the -H or –help-params option of the control utility.

vfctrl --help-params

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.

Control operation

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.

Host Application

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.

Device Application

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

The XVF3610 device flash firmware configuration comprises 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.