The Starter Kit Utility (SKUtility.py) is a python command-line tool that enables remote operation of the Starter Kit hardware. It eliminates the need for logging in to the Raspberry Pi by means of SSH or VNC server by providing a command-line interface for tasks such as running diagnostics, rebooting the Raspberry Pi, resetting the AWX Amp application, configuring the audio hardware, etc., over the network (ethernet or Wi-Fi).
The Starter Kit Utility is installed along with GTT in the default location “C:\Program Files\Harman\HarmanAudioworX\StarterKit\StarterKitUtility”. This page describes the utility tool and its usage in detail, and some common useful commands are given in Useful SKUtility Commands. Installation of its pre-requisites are covered in Required Software Applications.
The SKUtility.py script must be run in the location that it is installed in since its functioning depends on files that are in the same directory. Ensure that the commands are run in a CMD (command prompt) window in the installed location.
The “SKUtility.py” script is run using “python3” and takes command-line arguments as shown in the help text, which can be displayed running the following command:
python3 SKUtility.py -h
SKUtility Command-line Help Text
The script, by default, connects to a target with the hostname “raspberrypi.local” and the username and password as “awx” (default credentials for the Starter Kit). This can be changed using the “-hname” argument for the hostname, “-u” argument for the username and “-pwd” argument for the password, if they are different from the default.
The Utility tool supports operations/actions that are classified into 3 functions or sub-commands:
Sub-command
Function
Description
diag
Diagnostics
Verify if the target device is connected and is functioning as expected
rmt
Remote Control
Perform actions such as reboot, reset the AWX amp application, etc.
conf
Configuration
Configure the audio device to use and Wi-Fi to connect to
The following sub-sections describe each function in detail along with the usage.
SKUtility Diagnostics
This function runs a series of checks to verify if the Starter Kit hardware is functioning as expected. The diagnostics report can be generated by running the command:
python3 SKUtility.py diag
Following is an example report that shows a working Starter Kit setup.
The diagnostics only identifies issues in the configurations of the hardware that may be preventing proper operation of the AWX Amp application. If the Starter Kit is not functioning properly despite the diagnostics report showing no issues, refer the log files fetched during the diagnostics to debug. The details on debugging using the Amp log file are given in the “AWX Amp Application Logs” section of Starter Kit Troubleshooting.
The “SKUtility Diagnostics Report” section in Starter Kit Troubleshooting describes the steps in the diagnostics in detail and highlights troubleshooting steps for resolving issues detected.
SKUtility Remote Control
This function/sub-command provides actions such as rebooting the Raspberry Pi, resetting the AWX Amp application, fetching log files and taking a snapshot of the Starter Kit data files.
The following image shows the help text for this function.
SKUtility Remote Control Command-line Help Text
Following are the actions that can be executed under the Remote-Control function:
Remote-Control Function
Command
Reboot the Raspberry Pi
To reboot the Raspberry Pi remotely, run the command: python3 SKUtility.py rmt -rbtThe utility tool will then trigger reboot and wait until the Raspberry Pi is booted up and reachable by the PC. This command may take about a minute.
Reset the AWX Amp Application running in the Starter Kit Hardware
To reset the AWX Amp application (required when updating the device definition on GTT), run the command: python3 SKUtility.py rmt -rst
Stop the AWX Amp Application
To stop the AWX Amp application, run the command: python3 SKUtility.py rmt -s
Fetch Log Files
To fetch the log files from target, run the command python3 SKUtility.py rmt -flogThis will fetch two log files from the target Starter Kit hardware:
awx_log.txt: This file contains logs related to booting up of the Starter Kit hardware and running of the AWX Amp application
VirtualAmpLog.txt: This file contains logs from the xAF framework that include initialization of the audio core, core AO, xAF instances, etc., based on the signal flow flashed on the Starter Kit hardware from GTT.
Take a Snapshot of the Data Files on the Starter Kit Hardware
The SKUtility.py can be used to take a snapshot of the data files in the Starter Kit hardware, either for saving the state of the Starter Kit or to send Harman AudioworX support for debugging, run the command: python3 SKUtility.py rmt -snpThis will take a snapshot and fetch a .zip file from the Starter Kit to “C:\ProgramData\Harman\StarterKit”.
SKUtility Configuration
This function provides configuration options for the user to configure the behavior of the Starter Kit hardware and the audio interface connected. Following is the help text for this function.
Following are the actions that can be executed under the Configuration function:
SKUtility Configuration
Descriptions
Interactive Audio Device Configuration
The utility tool provides an interactive setup wizard for configuring the audio device to be used by the AWX Amp application. This is necessary when using a different audio interface than the Creative Sound Blaster X4.
To start the interactive setup wizard, run the command: python3 SKUtility.py conf -i
The wizard takes the user through the following steps:
Specify the name of the .json file to save the configuration locally. This is useful to avoid going through the interactive menu if the user wants to revert to a known configuration. Type the file name (default file name is if no input is provided is “config.json”) when prompted.
Set the start-up mode for the Starter Kit hardware. The Starter Kit can be set to boot up in one of 2 modes.
Amp Mode – In this mode AWX Amp application is automatically started on when the Raspberry Pi is booted up.
Dev Mode – In this mode, the auto start of the AWX Amp application is disabled. This mode is only meant for developers.
If no input is provided by the user, the default mode chosen in the “Amp” mode.
Select the device for capture and playback from the displayed list of connected the audio devices with their audio capabilities. Type the IDs for capture and playback devices when prompted.
Set the selected configuration on the Starter Kit hardware by sending the saved config.json file to the target hardware.
The below figure shows the interactive configuration menu where the no input is provided for the filename and the Starter Kit modes, and the sound card named “X4” (Creative Sound Blaster X4) is chosen as the device for both input and output.
Send a Previously Saved Audio Device Configuration
This is used to send a previously saved audio device configuration file generated by the interactive wizard.
run the command:
python3 SKUtility.py conf -sndCfg
List Audio Devices Connected to Raspberry Pi
To list the audio device connected to Raspberry Pi, run the command: python3 SKUtility.py conf -laThis command will display all the connected audio capable devices along with their capture and playback capabilities.
Set a Wi-Fi for Raspberry Pi to Connect
This command is used to configure a new Wi-Fi for the Starter Kit to connect to, by specifying the ssid (Wi-Fi name), password and optionally, the auto-connect priority for the Wi-Fi. Run the command: python3 SKUtility.py conf -wifiConf new <SSID> <password> <priority>The below figure shows how to configure a Wi-Fi named “awx_wifi” with the password “awx_wifi_password” and an auto-connect priority of 10.
The optional “priority” parameter can be used to set the priority of the Wi-Fi connection for the Starter Kit to auto-connect on boot-up in the range (-999, 999), where higher the number, higher the priority. By default, the priority is set to 0. This parameter is useful when there are multiple Wi-Fi connections available and to prioritize them as required. The user can choose to reboot the Starter Kit to finalize changes and connect to the Wi-Fi network based on priority. The above figure shows that the Starter Kit has successfully connected to the new Wi-Fi on reboot. The user can also configure the Raspberry Pi 5 to behave as a Wi-Fi hotspot for the PC to connect to, using the following command: python3 SKUtility.py conf -wifiConf hotspot <SSID> <password> <priority>To turn off the Wi-Fi on Raspberry Pi, use below command: python3 SKUtility.py conf -wifiConf off
To turn on the Wi-Fi on Raspberry Pi, use below command: python3 SKUtility.py conf -wifiConf on
Flash a Device File
To flash a device file generated from GTT on to the Starter Kit hardware, run the command: python3 SKUtility.py conf -df <device file path>The “device.flash” is necessary for a signal flow to run on the AWX Amp application. The steps for generating the “device.flash” file on GTT are illustrated in “Configuring a Custom Device Compatible with the AudioworX Starter Kit” in the “Adding a Device to the Project” section of Creating a New Project on GTT.
List Data Files on the Starter Kit
To list the data files that are currently stored in the Starter Kit, run the command: python3 SKUtility.py conf -lsThe AWX Amp application makes use of data files with the extensions “.flash”, “.set” or “.info” sent from GTT for initializing the device, signal flow, presets, etc.
Remove Data Files from the Starter Kit
To delete data files (“.flash”, “.set”, “.info”) from the Starter Kit hardware, run the command: python3 SKUtility.py conf -rm <list of files to be deleted or wildcards>It may be required by a user to delete some or all the data files to roll back actions or start afresh before flashing a new project with device definition being different than the project that the Starter Kit hardware is currently flashed with. For example, the new project may have a different number of audio inputs, outputs, xAF instances, virtual cores, etc. In such cases, the user may need to wipe out the data files from the Starter Kit and flash new data files from GTT.The files that are stored in the Starter Kit hardware can be listed by using the “-ls” argument.Alternatively, to remove all data files from the Starter Kit hardware, run the command: python3 SKUtility.py conf -rm a
Running the “conf -rm a” command will all data files command will also delete the “device.flash” file which will have to be restored as directed in Flash a Device File or by resetting configuration (given below).
Reset All Configurations to Default
To reset the Starter Kit hardware to its default state, run the command: python3 SKUtility.py conf -rstAllThe reset all action goes through the following steps:
Get confirmation from the user to reset all configurations. If confirmed, all files related to AWX will be deleted from the Starter Kit hardware and restored to default that is shipped with the Starter Kit Utility tool.
Go through the interactive audio device configuration step if required by the user. For complete details of this step refer to Interactive Audio Device Configuration.
The following sections explains them and how to troubleshoot problems.
SKUtility Diagnostics Report
The Starter Kit diagnostics, goes through a series of steps to verify the hardware connections and configuration of the Starter Kit.
Following are the different stages:
Verify that the Starter Kit hardware is reachable by the PC over the LAN.
Verify that the configuration files and AWX Amp application are present in the target Starter Kit hardware.
Verify that the audio hardware required by the set audio configuration are connected and verify their playback and capture capabilities.
Verify that the AWX Amp application is running if the Starter Kit hardware is set to “Amp” mode.
Fetch log files for further diagnosis.
The diagnostics only verifies and flags issues related to connectivity between the PC and the Starter Kit, configuration files on the Starter Kit, audio hardware connected and configured for the AWX Amp application and the status of the amp application. Harman AudioworX Support can be contacted to diagnose issues outside of these.
The following sub-sections provide instructions on how to fix the issues identified in the diagnostics report.
Issues in Connectivity
If there is a connectivity issue between the PC and the Starter Kit, it will be identified in the very first step of the diagnostics. In such cases, the diagnostics will exit soon after as shown below:
SKUtility Diagnostics – Connectivity Issue
To fix this issue, ensure that the Starter Kit and the PC are both on the same network. As mentioned in Hardware Components Setup of this document, direct connection between the PC and the Starter Kit over ethernet is preferred due to zero network traffic. However, there may be situations where a direct connection is not possible, for example, if the PC’s ethernet port is already in use or the PC does not have an ethernet port at all.
In such cases, the Starter Kit’s hotspot feature may be used to establish connection between the PC and the Starter Kit. The Starter Kit is configured to automatically start a Wi-Fi hotspot with the following login credentials, when it is not connected to any known Wi-Fi network:
SSID: AP_AWXStarterKit
Password: starterkithotspot
Connect to this hotspot from the PC to first establish direct Wi-Fi connection to the Starter Kit and then run the diagnostics again. Step one of the diagnostics should be successful, indicating that the Starter Kit is accessible from the PC.
AWX Starter Kit Wi-Fi hotspot
The IP address of the Starter Kit starts with a number other than ”192“or ”169“, which indicates that the PC is connected to the Starter Kit’s Wi-Fi hotspot. The user must be warned that in this setup, the PC will no longer have access to the internet via Wi-Fi. For convenience, it is recommended that the Starter Kit is configured to connect to a common Wi-Fi network using the instructions in Set a Wi-Fi for Raspberry Pi to Connect in SKUtility Configuration after connecting to the Starter Kit hotspot.
Issues with Configuration Files
The second step of the diagnostics verifies if all the files that are required for functioning of the Starter Kit are present in the file system of the Starter Kit. If the diagnostic report indicates missing files, a simple brute-force solution would be to reset all files to their original states using the command python3 SKUtility.py conf -rstAll, which is described in SKUtility Configuration.
All the data files in the Starter Kit will also be restored to their original states (corresponding to the example project), which means that any changes made to the audio hardware configurations or the signal flow flashed on the device (.flash files) will be lost, and need to be reconfigured.
It is recommended to take a snapshot for back up using the command python3 SKUtility.py rmt -snp before resetting all the configurations.
The following table shows the solution to restore individual files:
Missing File
Solution
/AWX/config.json
Reconfigure the audio device using below command.
python3 SKUtility.py conf -i
/AWX/device.json
Export device file and send it to the device (refer to Configuring a Custom Device) using the below command.
python3 SKUtility.py conf -df
All other files
Restore all files using below command.
python3 SKUtility.py conf -rstAll
Issues with the Audio Device
The Starter Kit diagnostics verifies if the audio input and output devices mentioned in the “/AWX/config.json” file (the audio device configuration) are connected as expected. Below is an example diagnostic report showing an error with the audio device:
SKUtility Diagnostics – Audio Device Issue
If such an error is shown, verify if the required audio device is physically connected via USB and is powered on.
Two separate audio devices, one for input and the other for output, may be used simultaneously. If the input or output device is not capable of capture or playback, respectively, the diagnostic report will show a warning (in yellow).
SKUtility Diagnostics – Audio Device Warning
If this is not intended, reconfigure the audio device using python3 SKUtility.py conf -i.
Issues in the AWX Amp Application
The AWX Starter Kit has two start up modes set via the interactive config menu described under Interactive Audio Device Configuration in SKUtility Configuration.
Amp mode
Dev mode
Step 4 in the diagnostics verifies the status of the AWX Amp application based on the mode that is configured. If the Starter Kit hardware is set to “Amp” mode, the AWX Amp application is expected to be running.
An error may be reported in this step for the following reasons:
Failure in any of the previous steps.
The expected audio interface is not available at the time of amp start-up. Ensure that the audio device (Sound Blaster X4 or any other audio interface) is plugged in and powered on (if the interface has dedicated power) before powering-on the Raspberry Pi 5.
Problem in starting the AudioworX Amp application due to audio device setup or framework initialization, refer to AudioworX Amp Application Logs section.
Once the issues detected are rectified, reset the AudioworX Amp application using the python3 SKUtility.py rmt -rst command and re-run the diagnostics. If problems persist, contact Harman AudioworX support by following the information given in Reporting Issues section .
AudioworX Amp Application Logs
The Starter Kit produces logs at different points showing information on boot times, the AWX Amp application start and stop times and includes logs from the AWX Amp application showing initialization and configuration statuses during the audio driver setup.
Following figure shows an example log file in the Starter Kit.
AWX Amp Application Logs
The above figure shows 4 parts in a log:
Start Time: This part of the log shows the boot time and date if the log was generated at boot time, or the start time and date of the AWX Amp application if the amp was reset or started using the Starter Kit Utility. The first half (highlighted text) shows logs generated on boot, and the second half shows logs generated at amp reset by the user (notice the text “AWX Amp starter by user”).
Amp Mode: This part shows the mode in which the Starter Kit is configured. This text is only shown at boot time and not when the amp is started using the Start Kit Utility, as shown in the second half of the figure.
AWX Amp Application Logs: This part of the log shows logs generated by the AWX Amp application, which includes logs from the amp front-end, audio driver, etc. Logs related to SFD initialization from the xAF framework can be found in the other log file (VirtualAmpLog.txt), which is downloaded along with the awx_log.txt file using the command python3 SKUtility.py rmt -flog.
AWX Amp Stop Time: Finally, the last part of the log indicates the stop time of the AWX Amp application. Note that this part of the log will not be printed if the Starter Kit is abruptly powered off or shutdown while the AWX Amp application is still running.
The latest logs are written to the end of the file. The above figure shows that the amp may be running since the end of the log file has logs from the AWX Amp application and not the stop time.
Running the “Reset All Configurations” command will remove all log files on the Starter Kit hardware. Before resetting configurations, it is recommended that a snapshot is taken by running the command python3 SKUtility.py rmt -snp or fetch the log files by running the command python3 SKUtility.py rmt -flog.
Reporting Issues
For reporting issues related to the AudioworX Starter Kit, write to AudioworXSupport@harman.com with the following information:
Subject line — “AudioworX Starter Kit – short description of the issue faced”
Detailed description of the issue.
Attach the following files (if any).
The GTT project file (.gttd) used, which can be exported from GTT (File > Export Project).
Snapshot of the flash files on the Starter Kit hardware which can be generated using the command python3 SKUtility.py rmt -snp. The snapshot will be downloaded to “C:\ProgramData\Harman\StarterKit”.
To turn off the Wi-Fi on Raspberry Pi, use below command:
