Benchmark Iperf3

Résumé

Nom interne : Iperf3
Catégorie : Communication
Objectif : Exécuter un test de débit réseau iperf3 contre un serveur distant et stocker les métriques de performance mesurées sous forme de chaîne JSON.
Type de tâche : Normale

Compatibilité

Version AndroMate minimale : 1.1.0
Version AndroMate maximale : 1.1.0
Android minimum : Android 13 (API 33)
Android maximum testé : Android 16 (API 36)
Fabricants supportés :
- ✅ Samsung (One UI 6.x / 7.x / 8.x)
- ✅ Google Pixel (Android Stock)
- ⚠️ Autres fabricants — non testés
Permissions requises :
- INTERNET
- ACCESS_NETWORK_STATE

Description détaillée

La tâche Benchmark Iperf3 exécute le client iperf3 sur l'appareil Android via JNI (Iperf3Runner.run()) pour mesurer le débit réseau entre l'appareil et un serveur iperf3 distant. Elle supporte les protocoles TCP et UDP ainsi que les deux directions (envoi et réception).

La tâche construit un objet Iperf3Options à partir des paramètres fournis et invoque la couche JNI iperf3 avec json=true et oneOff=true. La sortie JSON brute d'iperf3 est analysée et stockée sous forme de chaîne unique dans value_output. Aucun code d'exception n'est défini dans AndromateExceptionTypes pour cette tâche — les erreurs de connexion et d'exécution remontent comme des exceptions runtime depuis la couche JNI.

Remarque : packetLength n'est appliqué que s'il est supérieur à 0. bandwidth n'est appliqué que s'il est supérieur à 0 (ajouté sous la forme "<valeur>M" pour cibler un débit en Mbit/s).

Paramètres d'entrée

Paramètre	Type	Obligatoire	Valeurs possibles	Compatibilité Android	Compatibilité AndroMate	Défaut
`serverHost`	Chaîne	Oui	Adresse IP ou nom d'hôte du serveur iperf3 — supporte les références `$variable`	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`""`
`serverPort`	Entier	Non	Numéro de port valide (1–65535)	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`5201`
`packetLength`	Entier	Non	Longueur du tampon/paquet en octets ; `0` = utiliser le défaut iperf3	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`0`
`bandwidth`	Entier	Non	Débit cible en Mbit/s pour UDP ; `0` = utiliser le défaut iperf3	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`0`
`protocol`	Chaîne	Non	`"TCP"` ou `"UDP"`	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`"TCP"`
`direction`	Chaîne	Non	`"UPLOAD"` (client→serveur) ou `"DOWNLOAD"` (serveur→client, reverse `-R`)	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`"UPLOAD"`

Paramètres de sortie

Champ	Type	Condition de déclenchement	Compatibilité Android	Compatibilité AndroMate	Défaut
`value_output`	Chaîne	Toujours en cas de succès — résultat iperf3 sous forme de chaîne JSON	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`<ANDROMATE_NULL_VALUE>`

La chaîne JSON de value_output contient les champs suivants :

Champ JSON	Présence	Description
`exitCode`	Toujours	Code de sortie du processus iperf3
`sentBps`	Toujours	Débit envoyé en bits/seconde
`receivedBps`	Toujours	Débit reçu en bits/seconde
`seconds`	Toujours	Durée du test en secondes
`startTimeMs`	Toujours	Horodatage de début du test en millisecondes
`localHost`	Toujours	Hôte du point de terminaison local
`localPort`	Toujours	Port du point de terminaison local
`remoteHost`	Toujours	Hôte du serveur distant
`remotePort`	Toujours	Port du serveur distant
`jitterMs`	UDP uniquement	Gigue mesurée en millisecondes
`lostPackets`	UDP uniquement	Nombre de paquets perdus
`packets`	UDP uniquement	Nombre total de paquets envoyés
`lostPercent`	UDP uniquement	Pourcentage de perte de paquets

Exceptions

Aucun code d'exception n'est défini dans AndromateExceptionTypes pour Iperf3. Les échecs de connexion, les erreurs d'hôte inaccessible et les autres problèmes d'exécution remontent comme des exceptions runtime depuis la couche JNI.

Diagramme d'exécution

flowchart TD
    Start([▶ Iperf3]) --> ResolveParams[🔄 Résoudre serverHost + paramètres]

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

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

    RunJNI -->|Erreur de connexion/exécution| ERuntime[❌ Exception runtime\ndepuis la couche JNI]
    RunJNI -->|Succès| ParseJSON[📊 Analyser la sortie JSON iperf3]

    ParseJSON --> WriteOutput[💾 Définir value_output\nchaîne JSON résultat iperf3]

    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

Fonctionnement :

Résoudre les paramètres : serverHost et tous les autres paramètres sont résolus depuis le contexte workflow
Construire Iperf3Options : crée l'objet options avec le protocole, la direction, serverHost, serverPort ; applique packetLength uniquement si > 0 ; applique bandwidth sous la forme "<valeur>M" uniquement si > 0 ; définit toujours json=true et oneOff=true
Exécuter via JNI : appelle Iperf3Runner.run() via la couche JNI — les erreurs de connexion et d'exécution remontent comme des exceptions runtime
Analyser la sortie : analyse le résultat JSON d'iperf3
Définir la sortie : stocke la chaîne JSON du résultat iperf3 dans value_output
Résultat : retourne StrTaskResult

Exemples de code

Exemple 1 — Test TCP envoi (par défaut)

{
  "Iperf3": [
    {
      "id": "1",
      "title": "Test TCP envoi",
      "serverHost": "192.168.1.100",
      "protocol": "TCP",
      "direction": "UPLOAD",
      "value_output": "$resultat_iperf3"
    }
  ]
}

Exemple 2 — Test TCP réception (mode reverse)

{
  "Iperf3": [
    {
      "id": "2",
      "title": "Test TCP réception",
      "serverHost": "192.168.1.100",
      "serverPort": 5201,
      "protocol": "TCP",
      "direction": "DOWNLOAD",
      "value_output": "$resultat_iperf3"
    }
  ]
}

Exemple 3 — Test UDP avec débit cible

{
  "Iperf3": [
    {
      "id": "3",
      "title": "Test qualité UDP à 10 Mbit/s",
      "serverHost": "$serveur_iperf3",
      "protocol": "UDP",
      "direction": "UPLOAD",
      "bandwidth": 10,
      "value_output": "$resultat_udp"
    }
  ]
}

Test UDP — le JSON de value_output inclura jitterMs, lostPackets, packets et lostPercent.

Exemple 4 — Port personnalisé et longueur de paquet

{
  "Iperf3": [
    {
      "id": "4",
      "title": "Port personnalisé iperf3",
      "serverHost": "10.0.0.5",
      "serverPort": 5210,
      "packetLength": 1400,
      "protocol": "TCP",
      "direction": "UPLOAD",
      "value_output": "$json_brut"
    }
  ]
}

Détails des paramètres d'entrée

1. `serverHost` — Adresse du serveur

L'adresse IP ou le nom d'hôte du serveur iperf3 distant. Le serveur doit fonctionner en mode serveur (iperf3 -s). Supporte les références $variable_workflow.

Défaut : ""
Supporte les variables : Oui

2. `serverPort` — Port du serveur

Le port sur lequel le serveur iperf3 distant écoute.

Défaut : 5201 (port par défaut d'iperf3)

3. `packetLength` — Longueur du tampon/paquet

La longueur du tampon ou du paquet en octets passée à iperf3. La valeur 0 signifie qu'iperf3 utilise son propre défaut. Appliqué uniquement lorsqu'il est supérieur à 0.

Défaut : 0 (utiliser le défaut iperf3)

4. `bandwidth` — Débit cible (UDP)

Débit cible en Mbit/s pour les tests UDP. La valeur 0 signifie qu'iperf3 utilise son propre défaut. Appliqué uniquement lorsqu'il est supérieur à 0 — passé à iperf3 sous la forme "<valeur>M".

Défaut : 0 (utiliser le défaut iperf3)
S'applique à : protocole UDP principalement

5. `protocol` — Protocole de transport

Sélectionne le protocole de couche transport pour le test.

Valeur	Protocole	Remarques
`"TCP"`	TCP	Mesure le débit avec contrôle de congestion
`"UDP"`	UDP	Mesure le débit, la gigue et la perte de paquets

Défaut : "TCP"

6. `direction` — Direction du trafic

Contrôle le sens du flux de trafic du test.

Valeur	Direction	Option iperf3
`"UPLOAD"`	Envoi — l'appareil envoie vers le serveur	(défaut, sans option supplémentaire)
`"DOWNLOAD"`	Réception — le serveur envoie vers l'appareil	`-R` (mode reverse)

Défaut : "UPLOAD"

Détails des paramètres de sortie

`value_output` — Chaîne JSON résultat iperf3

Stocke le résultat complet d'iperf3 sous forme de chaîne JSON (depuis StrTaskResult). Le JSON contient les champs de débit pour TCP et UDP, et en plus jitterMs, lostPackets, packets et lostPercent pour les tests UDP.

Exemple du contenu JSON pour un test UDP :

{
  "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
}

Exemple JSON complet

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