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):
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.
vfctrl Installation¶
Control and configuration of the XVF3610-UA are achieved via the control interface implemented over USB. A VocalFusion Host Control application, vfctrl_usb, is provided pre-compiled and as source code for this purpose.
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/).
The following steps show how to install the libusb driver using Zadig:
Connect the XVF3610 board to the host PC using a USB cable.
Open Zadig and select XMOS Control (Interface 3) from the list of devices. If the device is not present, ensure Options -> List All Devices is checked.
Select libusb-win32 from the list of drivers.
Click the Reinstall Driver button
Fig. 38 Selecting the libusb driver in Zagdig¶
Once installed the vfctrl_usb utility is ready to use. The following steps explain how to use the host control utility.
Copy the host directory of the Firmware Release Pack to the host platform.
Navigate, from a terminal window, to the copied host directory and execute one of the following commands, depending on the specific platform, to list the supported commands and the general form of the utility usage.
./Linux/bin/vfctrl_usb –help for general instructions
./Linux/bin/vfctrl_usb –help-params to list out the control commands
./MAC/bin/vfctrl_usb –help for general instructions
./MAC/bin/vfctrl_usb –help-params to list out the control commands
.\WIN32\bin\vfctrl_usb –help for general instructions
.\WIN32\bin\vfctrl_usb –help-params for general instructions to list out the control commands
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_.
Note
The <COMMAND> verb is case insensitve, e.g. GET_VERSION and get_version are equivalent and both supported
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. All arguments are integer or floating-point numbers separated by a space. All the values are transferred to the device as integers and the host utility converts the floating-point values to the appropriate Q format.
The specification of the Q format for representing floating-point numbers is given in Q format conversion section section of the User Guide.
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
-f, --cmd-list <filename> : Execute the commands in the given <filename>
Note
For the last option the filename should be a text file with one command per line. The format is the same as the data partition generator input files.
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.
It is recommended 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 the command list in the command reference section of this guide which summarises all the commands.
The full list of commands can also 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 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.