Skip to content
Branch: master
Find file Copy path
Find file Copy path
1 contributor

Users who have contributed to this file

163 lines (111 sloc) 8.39 KB

Wiperf - Configuration on the WLAN Pi

This instruction paper assumes you are running Wiperf on a WLAN Pi on an image version of v1.9 or later (which has Wiperf installed and available as part of the image.)

(Special note for WLAN Pi image v1.9.0: please see the Known Issues) section of this document)

The Wiperf probe is activated via the front panel menu system (FPMS) of the WLAN Pi. But, before flipping in to the Wiperf mode, a few configuration steps need to be completed:

Configuration File (config.ini)

The operation of Wiperf is configured using the file '/home/wanpi/wiperf/config.ini' This needs to be edited prior to entering Wiperf mode.

Prior to the first use of Wiperf, the config.ini file does not exist in the required WLAN Pi directory. However, a default template config file (config.default.ini) is supplied that can be used to create the config.ini file. Here is the suggested workflow:

Connect to the WLAN Pi, create a copy of the config template file and edit the newly created config (as the wlanpi user):

        cd /home/wlanpi/wiperf
        cp ./config.default.ini ./config.ini
        nano ./config.ini

By default, the configuration file is set to run all tests. However, there is a minimum configuration that must be applied for Wiperf mode to run out-of-the-box. Here are the minimum configuration parameters you need to configure (just to get you going...):

; interface name over which mgt traffic is sent (i.e. how we get to Splunk) - options: wlan0, eth0, zt
mgt_if: wlan0

; Splunk host IP/name - set this to the address of your Splunk server

; Splunk token to access Splunk server created by Splunk (example token: 84adb9ca-071c-48ad-8aa1-b1903c60310d)
; (you need to have your Splunk server up & configure to get this)
splunk_token: 84adb9ca-071c-48ad-8aa1-b1903c60310d

; IP address of iperf3 server - set this to your iperf3 server (if you have one)

; IP address of iperf3 server - set this to your iperf3 server (if you have one)

If there are some tests you'd like to disable (e.g. if you don't have an iperf3 server set up), then you'll need to open up the config.ini file and look through each section for the "enabled" parameter for that test and set it to "no". For example, to disable the iperf tcp test:

; yes = enabled, no = disabled
enabled: no

For a full description of the configuration file parameters, please review the following page: config.ini reference guide. The Splunk token is obtained from your Splunk server (see Splunk build guide).

Wireless Client Configuration (wpa_supplicant.conf)

When the WLAN Pi is flipped in to Wiperf mode, it will need to join the SSID under test to run the configured tests. We need to provide a configuration (that is only used in Wiperf mode) to allow the WLAN Pi to join a WLAN.

Edit the following file with the configuration and credentials that will be used by the WLAN Pi to join the SSID under test once it is switched in to Wiperf mode (make edits logged in as the wlanpi user):

        cd /home/wlanpi/wiperf/conf/etc/wpa_supplicant
        nano ./wpa_supplicant.conf


Once the required edits have been made to configure Wiperf mode, flip the WLAN Pi in to Wiperf mode using the following FPMS options:

        Actions > Wiperf > Confirm

If no errors are observed on the FPMS during flip-over, inspect the following files to double-check for errors & verify that test data is generated (as indicated in the log messages):

    cat /home/wlanpi/wiperf/logs/agent.log
    cat /home/wlanpi/wiperf/wiperf.log 

Note that by default the tests are run every 5 mins unless the interval has been changed in the config.ini file. Wait at least this interval before determining that there is an issue - the test cycle will NOT begin immediately upon entering Wiperf mode.

Check your instance of Splunk and verify that data is being received.


To get the latest updates from the GitHub repo (when available), use the following commands when logged in as the wlanpi user:

        cd ~/wiperf
        git pull

(note that this will update config.default.ini but not config.ini, so remember to re-edit it after a pull if the config file format changes)


If things seem to be going wrong, try the following:

  • Connect to the WLAN Pi using the USB OTG connection to check log files:
    • cat /home/wlanpi/wiperf/logs/agent.log
    • cat /home/wlanpi/wiperf/wiperf.log
  • SSH to the device & tail the agent log file in real-time, watching for errors and dumps of test results being performed:tail -f /home/wlanpi/wiperf/logs/agent.log
  • Flip back in to classic mode and activate Wiperf mode from the CLI of the WLAN Pi, watching for errors:
    • cd /home/wlanpi/wiperf
    • sudo ./wiperf_switcher
  • Try disabling tests & see if one specific test is causing an issue
  • Make sure all pre-reqs have definitely been fulfilled
  • Make sure your WLAN Pi and Splunk servers are NTP sync'ed
  • Flip back to classic mode and re-check the edits made to the config.ini & wpa_supplicant.conf files

Additional Features:


Wiperf has a watchdog feature that it uses to try to reset things when it is having connectivity related difficulties.

There may be instances when tests are continually failing or wireless connectivity is intermittent due to perhaps being stuck on a remote AP that is sub-optimal from a connectivity perspective.

If persistent issues are detected, then Wiperf will reboot the WLAN Pi to try to remediate the issue. This will provide the opportunity to the reset all network connectivity and internal processes.

Note that this is a last ditch mechanism. Wiperf will try bouncing the WLAN interface to remediate any short-term connectivity issues, which will likely fixe many issues without the need for a full reboot.

If you observe your WLAN Pi rebooting on a regular basis (e.g. a couple of times a hour), then check its logs as it is very unhappy about something.


Wiperf employs the following security mechanisms in an attempt to harden the WLAN Pi when deployed in Wiperf mode:

  • No forwarding is allowed between interfaces
  • The internal UFW firewall is configured to only allow incoming connectivity on port 22 on the wlan0 & eth0 interfaces

CLI Mode Switch

If you are remote from your WLAN Pi you may not be able to flip it in to Wiperf mode using the front panel buttons. However, it is possible to flip it in to Wiperf mode using the CLI (via an SSH session).

To flip in to Wiperf mode using the CLI, SSH to your WLAN Pi and execute the following on the CLI (CAVEAT: make sure you have correctly configured the /home/wlanpi/wiperf/conf/etc/wpa_suplicant/wpa_supplicant.conf file before do this...otherwise you may lose comms with the WLAN Pi after it reboots if you rely on the WLAN connection for access):

 # performed as the wlanpi user
 cd ~/wiperf
 sudo ./wiperf_switcher on

After executing this command, the WLAN Pi will reboot in to the Wiperf mode.

If you'd like to flip back from Wiperf mode, SSH to the WLAN Pi and execute:

 # performed as the wlanpi user
 cd ~/wiperf
 sudo ./wiperf_switcher off

Known Issues:

  • There is an issue with the v1.9.0 WLAN Pi image that means that the iperf tests fail when running in Wiperf mode. To get the fixed version, follow the update process detailed in the Updating section of this document (3rd Jan 2020)
  • There seems to be an issue with the Comfast CF-912 adapter when using it with the WLAN Pi and associating as a client to SSIDs that use 80MHz width channels. If you hit an issue where the WLAN Pi seems to lock up or does not boot correctly, try a different adapter or a network that does not use 80Mhz channels.
  • In several dashboard reports, the reported MCS values & Rx Phy rate may be blank. This is because these values are only reported by MediaTek wireless NICs. Therefore, the CF-912 will not show these values (as it is a Realtek NIC). Sorry, not much I can do about this.
You can’t perform that action at this time.