Iperf3 Benchmark

Summary

Internal name: Iperf3
Category: Communication
Purpose: Run an iperf3 network throughput test against a remote iperf3 server and store the measured performance metrics as a JSON string.
Task type: Normal

Compatibility

Minimum AndroMate version: 1.1.0
Maximum AndroMate version: 1.1.0
Minimum Android: Android 13 (API 33)
Maximum Android tested: Android 16 (API 36)
Supported manufacturers:
- ✅ Samsung (One UI 6.x / 7.x / 8.x)
- ✅ Google Pixel (Android Stock)
- ⚠️ Other manufacturers — not tested
Required permissions:
- INTERNET
- ACCESS_NETWORK_STATE

Detailed description

The Iperf3 Benchmark task executes the iperf3 client on the Android device via JNI (Iperf3Runner.run()) to measure network throughput between the device and a remote iperf3 server. It supports both TCP and UDP protocols and both upload and download directions.

The task builds an Iperf3Options object from the provided parameters and invokes the iperf3 JNI layer with json=true and oneOff=true. The raw JSON output from iperf3 is parsed and stored as a single string in value_output. There are no pre-defined exception codes in AndromateExceptionTypes for this task — connection and execution errors surface as runtime exceptions from the JNI layer.

Note: packetLength is only applied if greater than 0. bandwidth is only applied if greater than 0 (appended as "<value>M" to target Mbit/s).

Input parameters

Parameter	Type	Required	Possible values	Android Compatibility	AndroMate Compatibility	Default
`serverHost`	String	Yes	IP address or hostname of the iperf3 server — supports `$variable`	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`""`
`serverPort`	Integer	No	Valid port number (1–65535)	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`5201`
`packetLength`	Integer	No	Buffer/packet length in bytes; `0` = use iperf3 default	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`0`
`bandwidth`	Integer	No	Target bandwidth in Mbit/s for UDP; `0` = use iperf3 default	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`0`
`protocol`	String	No	`"TCP"` or `"UDP"`	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`"TCP"`
`direction`	String	No	`"UPLOAD"` (client→server) or `"DOWNLOAD"` (server→client, reverse `-R`)	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`"UPLOAD"`

Output parameters

Field	Type	Trigger condition	Android Compatibility	AndroMate Compatibility	Default
`value_output`	String	Always on success — iperf3 result as JSON string	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`<ANDROMATE_NULL_VALUE>`

The value_output JSON string contains the following fields:

JSON field	Present	Description
`exitCode`	Always	iperf3 process exit code
`sentBps`	Always	Sent throughput in bits/second
`receivedBps`	Always	Received throughput in bits/second
`seconds`	Always	Test duration in seconds
`startTimeMs`	Always	Test start timestamp in milliseconds
`localHost`	Always	Local endpoint host
`localPort`	Always	Local endpoint port
`remoteHost`	Always	Remote server host
`remotePort`	Always	Remote server port
`jitterMs`	UDP only	Measured jitter in milliseconds
`lostPackets`	UDP only	Number of lost packets
`packets`	UDP only	Total number of packets sent
`lostPercent`	UDP only	Packet loss percentage

Exceptions

There are no exception codes defined in AndromateExceptionTypes for Iperf3. Connection failures, host unreachable errors, and other execution problems surface as runtime exceptions from the JNI layer.

Execution flowchart

flowchart TD
    Start([▶ Iperf3]) --> ResolveParams[🔄 Resolve serverHost + parameters]

    ResolveParams --> BuildOptions[🔧 Build Iperf3Options\nprotocol, direction, serverHost, serverPort\npacketLength if >0\nbandwidth+M if >0\njson=true, oneOff=true]

    BuildOptions --> RunJNI[⚙️ Iperf3Runner.run via JNI]

    RunJNI -->|Connection/execution error| ERuntime[❌ Runtime exception\nfrom JNI layer]
    RunJNI -->|Success| ParseJSON[📊 Parse iperf3 JSON output]

    ParseJSON --> WriteOutput[💾 Set value_output\niperf3 result JSON string]

    WriteOutput --> Success([✅ StrTaskResult])

    ERuntime --> Error([❌ Exception])

    style Start fill:#e3f2fd
    style Success fill:#c8e6c9
    style Error fill:#ffcdd2
    style ERuntime fill:#ffcdd2
    style ResolveParams fill:#fff9c4
    style BuildOptions fill:#fff9c4
    style RunJNI fill:#f3e5f5
    style ParseJSON fill:#f3e5f5
    style WriteOutput fill:#c8e6c9

How it works:

Resolve parameters: serverHost and all other parameters are resolved from the workflow context
Build Iperf3Options: constructs the options object with protocol, direction, serverHost, serverPort; applies packetLength only if > 0; applies bandwidth as "<value>M" only if > 0; always sets json=true and oneOff=true
Run via JNI: calls Iperf3Runner.run() through the JNI layer — connection/execution errors surface as runtime exceptions
Parse output: parses the iperf3 JSON result
Set output: stores the iperf3 result JSON string in value_output
Result: returns StrTaskResult

Code examples

Example 1 — TCP upload test (default)

{
  "Iperf3": [
    {
      "id": "1",
      "title": "TCP upload test",
      "serverHost": "192.168.1.100",
      "protocol": "TCP",
      "direction": "UPLOAD",
      "value_output": "$iperf3_result"
    }
  ]
}

Example 2 — TCP download test (reverse mode)

{
  "Iperf3": [
    {
      "id": "2",
      "title": "TCP download test",
      "serverHost": "192.168.1.100",
      "serverPort": 5201,
      "protocol": "TCP",
      "direction": "DOWNLOAD",
      "value_output": "$iperf3_result"
    }
  ]
}

Example 3 — UDP test with bandwidth target

{
  "Iperf3": [
    {
      "id": "3",
      "title": "UDP quality test at 10 Mbit/s",
      "serverHost": "$iperf3_server",
      "protocol": "UDP",
      "direction": "UPLOAD",
      "bandwidth": 10,
      "value_output": "$udp_result"
    }
  ]
}

UDP test — value_output JSON will include jitterMs, lostPackets, packets, and lostPercent.

Example 4 — Custom port and packet length

{
  "Iperf3": [
    {
      "id": "4",
      "title": "Custom port iperf3",
      "serverHost": "10.0.0.5",
      "serverPort": 5210,
      "packetLength": 1400,
      "protocol": "TCP",
      "direction": "UPLOAD",
      "value_output": "$raw_json"
    }
  ]
}

Input parameter details

1. `serverHost` — Server address

The IP address or hostname of the remote iperf3 server. The server must be running in server mode (iperf3 -s). Supports $workflow_variable references.

Default: ""
Supports variables: Yes

2. `serverPort` — Server port

The port on which the remote iperf3 server is listening.

Default: 5201 (iperf3 default port)

3. `packetLength` — Buffer/packet length

The buffer or packet length in bytes passed to iperf3. A value of 0 means iperf3 uses its own default. Applied only when greater than 0.

Default: 0 (use iperf3 default)

4. `bandwidth` — Target bandwidth (UDP)

Target bandwidth in Mbit/s for UDP tests. A value of 0 means iperf3 uses its own default. Applied only when greater than 0 — passed to iperf3 as "<value>M".

Default: 0 (use iperf3 default)
Applies to: UDP protocol primarily

5. `protocol` — Transport protocol

Selects the transport layer protocol for the test.

Value	Protocol	Notes
`"TCP"`	TCP	Measures throughput with congestion control
`"UDP"`	UDP	Measures throughput, jitter, packet loss

Default: "TCP"

6. `direction` — Traffic direction

Controls which direction the test traffic flows.

Value	Direction	iperf3 flag
`"UPLOAD"`	Upload — device sends to server	(default, no extra flag)
`"DOWNLOAD"`	Download — server sends to device	`-R` (reverse mode)

Default: "UPLOAD"

Output parameter details

`value_output` — iperf3 result JSON string

Stores the complete iperf3 result as a JSON string (from StrTaskResult). The JSON contains throughput fields for both TCP and UDP, and additionally jitterMs, lostPackets, packets, and lostPercent for UDP tests.

Example of the JSON content for a UDP test:

{
  "exitCode": 0,
  "sentBps": 9876543.0,
  "receivedBps": 9654321.0,
  "seconds": 10.0,
  "startTimeMs": 1712000000000,
  "localHost": "192.168.1.10",
  "localPort": 54321,
  "remoteHost": "192.168.1.100",
  "remotePort": 5201,
  "jitterMs": 0.23,
  "lostPackets": 2,
  "packets": 1000,
  "lostPercent": 0.2
}

Complete JSON example

{
  "Iperf3": [
    {
      "id": "1",
      "title": "TCP upload benchmark",
      "serverHost": "192.168.1.100",
      "serverPort": 5201,
      "protocol": "TCP",
      "direction": "UPLOAD",
      "packetLength": 0,
      "bandwidth": 0,
      "value_output": "$iperf3_result_json"
    }
  ]
}