Aller au contenu

Cmd Stage

Résumé

  • Nom interne : CmdStage
  • Catégorie : Système
  • But : Exécuter une commande shell sur l’appareil Android, avec gestion facultative des privilèges root.
  • 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)

  • Constructeurs supportés :

  • ✅ Samsung (One UI 6.x / 7.x / 8.x)
  • ✅ Google Pixel (Android Stock)

  • ⚠️ Autres constructeurs : non testés ou partiellement supportés

  • Permissions nécessaires :

  • INTERNET (si la commande effectue un accès réseau)
  • MANAGE_EXTERNAL_STORAGE (si la commande lit certains fichiers dans le mobile)
  • ⚠️ Root requis pour certaines commandes (selon la valeur de root)

Description détaillée

La tâche Cmd Stage permet d’exécuter une commande shell directement sur l’appareil Android.
Elle est utilisée pour :

  • Tester la connectivité réseau (ping, curl, traceroute, etc.)
  • Collecter des informations système (CPU, mémoire, interfaces réseau, radio…)
  • Modifier la configuration (si root : ip, ifconfig, tc, etc.)
  • Automatiser des diagnostics techniques ou des actions système répétitives.

Détails d'implémentation

  • Détection automatique du shell : Détecte les caractères spéciaux et les espaces pour décider si un shell est nécessaire
  • Échappement des caractères : Échappe les guillemets et caractères spéciaux (; | & < > * ( ) { } [ ])
  • Timeout fixe : 5 minutes (300 secondes) maximum pour l'exécution
  • Gestion du root : Utilise su -c pour les commandes root, vérifie que l'appareil est rooté
  • Capture stdout/stderr : Les deux flux sont capturés séparément et concaténés
  • Limite de taille : Maximum 10.000 caractères pour la sortie (les excédents sont tronqués)
  • Nettoyage des ressources : Ferme proprement les flux et le processus en cas d'erreur

Paramètres d’entrée

Paramètre Type Obligatoire Valeurs possibles Compatibilité Android Compatibilité AndroMate Défaut
cmd_text String Oui Toute commande shell valide Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 —
root Boolean Non true / false Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 false

Paramètres de sortie

Champ Type Condition de déclenchement Compatibilité Android Compatibilité AndroMate Défaut
cmd_result_output String Si la commande principale réussit Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 <ANDROMATE_NULL_VALUE>
cmd_error_output String Si la commande principale échoue Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 <ANDROMATE_NULL_VALUE>

Diagramme d'exécution

flowchart TD
    Start([Démarrer CmdTask]) --> ResolveParams[🔄 Résoudre paramètres<br/>cmd_text, root]

    ResolveParams --> CheckRoot{root = true?}

    CheckRoot -->|Oui| ExecRoot[⚙️ Exécuter avec root<br/>su -c commande]
    CheckRoot -->|Non| ExecCmd[⚙️ Exécuter commande<br/>sh -c commande]

    ExecRoot --> ReadOutput[📤 Lire stdout et stderr<br/>Max 10000 caractères]
    ExecCmd --> ReadOutput

    ReadOutput --> CheckError{stderr present?}

    CheckError -->|Oui| StoreError[💾 Stocker dans cmd_error_output<br/>Message d'erreur]
    CheckError -->|Non| StoreSuccess[💾 Stocker dans cmd_result_output<br/>Sortie de la commande]

    StoreError --> LogReport[📋 Logger rapport<br/>ReportSection]
    StoreSuccess --> LogReport

    LogReport --> Success([✅ Succès<br/>CmdTaskResult])

    style Start fill:#e3f2fd
    style Success fill:#c8e6c9
    style ExecRoot fill:#f3e5f5
    style ExecCmd fill:#f3e5f5
    style ReadOutput fill:#fff9c4
    style StoreError fill:#ffe0e0
    style StoreSuccess fill:#e0f0e0

Comment ça fonctionne :

  1. Résoudre paramètres : Charge cmd_text et root depuis la configuration
  2. Vérifier root : Détermine si la commande doit être exécutée avec les privilèges root
  3. Exécuter commande : Lance via /system/bin/sh -c (ou su -c si root=true)
  4. Lire sortie : Capture stdout et stderr, limité à 10.000 caractères max
  5. Vérifier erreur : Si stderr n'est pas vide, capture le message d'erreur
  6. Stocker résultat : Stocke dans cmd_result_output (succès) ou cmd_error_output (erreur)
  7. Logger : Enregistre le rapport d'exécution
  8. Résultat : Retourne CmdTaskResult (succès toujours, les erreurs sont dans les variables)

Note : Cette tâche ne lève PAS d'exception. Les erreurs sont capturées dans la variable cmd_error_output.

Messages d'erreur possibles

La tâche capture les messages d'erreur générés par la commande dans cmd_error_output. Ces messages proviennent de :

  1. Erreurs d'exécution (stderr du processus)
  2. Erreurs au niveau système (timeout processus, appareil non rooté, etc.)

Catégories de messages d'erreur

Erreurs réseau

Message d'erreur Cause Exemple de commande
Network is unreachable Pas de connectivité réseau ping 8.8.8.8
Temporary failure in name resolution Échec résolution DNS ping google.com
Connection refused Port cible fermé curl http://localhost:9999
Connection timeout Serveur n'répond pas curl http://192.0.2.1
Operation timed out Latence réseau trop élevée ping 8.8.8.8 -c 10

Erreurs système de fichiers

Message d'erreur Cause Exemple de commande
No such file or directory Fichier n'existe pas cat /data/nonexistent.txt
Permission denied Permissions insuffisantes cat /root/private.txt (sans root)
Is a directory Lecture d'un répertoire comme fichier cat /data/
Device or resource busy Fichier/périphérique verrouillé rm /data/locked_file

Erreurs root/privilèges

Message d'erreur Cause Exemple de commande
Permission Denied (no rooted Device) root=true mais appareil non rooté Toute commande avec root: true
su: not found Binaire su non disponible Commande root sur appareil non rooté
Operation not permitted Action nécessite root ip route add sans root

Erreurs d'exécution

Message d'erreur Cause Exemple de commande
command not found Binaire/exécutable n'existe pas iperf3 (non installé)
Process timed out and was killed Timeout dépassé (300s) Commande longue
Exec error: ... IOException lors de l'exécution Commande corrompue ou problème système

Erreurs d'information système

Message d'erreur Cause Exemple de commande
cannot read ... Impossible accéder fichier système cat /proc/cpuinfo (permission refusée)
unknown option Argument commande invalide ping --invalid-option
Bad syntax Commande malformée sh -c "echo unclosed

Structure des messages d'erreur

Les messages d'erreur dans cmd_error_output suivent cette structure :

[Timestamp] [Error Type]: [Error Description]
Ligne 1 de la sortie stderr
Ligne 2 de la sortie stderr
... (max 10.000 caractères total)

Gestion des erreurs dans les workflows

Exemple 1 : Vérifier une erreur réseau

{
  "CmdStage": [
    {
      "id": "1",
      "title": "Tester réseau",
      "cmd_text": "ping -c 1 8.8.8.8",
      "root": false,
      "cmd_result_output": "$PING_RESULT",
      "cmd_error_output": "$PING_ERROR"
    }
  ],
  "Condition": [
    {
      "id": "2",
      "condition": "$PING_ERROR contains 'unreachable'",
      "then": "NetworkDownTask",
      "else": "ContinueTask"
    }
  ]
}

Exemple 2 : Réessayer avec root si permission refusée

{
  "CmdStage": [
    {
      "id": "1",
      "title": "Première tentative sans root",
      "cmd_text": "cat /system/build.prop",
      "root": false,
      "cmd_result_output": "$BUILD_PROP",
      "cmd_error_output": "$ERROR_1"
    }
  ],
  "Condition": [
    {
      "id": "2",
      "condition": "$ERROR_1 contains 'Permission denied'",
      "then": "RetryWithRootTask",
      "else": "SuccessTask"
    }
  ]
}

Caractères spéciaux et limites

Détection du shell

La tâche détecte automatiquement si un shell est nécessaire selon les conditions :

  • La commande contient des espaces (ex: ping -c 1 8.8.8.8)
  • La commande contient des caractères spéciaux : ; | & < > * ( ) { } [ ]

Si l'une de ces conditions est vraie, la commande est exécutée via /system/bin/sh -c "commande".

Exemples

Commande Nécessite shell ? Raison
ping ❌ Non Pas d'espace, pas de caractères spéciaux
ping -c 1 8.8.8.8 ✅ Oui Contient des espaces
ping 8.8.8.8 \| grep ✅ Oui Contient le pipe \|
curl http://example.com && echo ok ✅ Oui Contient &&
cat /data/file > /tmp/out ✅ Oui Contient > (redirection)

Limites

Limite Valeur Description
Timeout 300 secondes (5 min) Délai maximum avant terminaison du processus
Taille de sortie 10.000 caractères Maximum pour stdout + stderr combinés
Caractères échappés " → \" Les guillemets sont échappés dans les commandes root

Dépassement des limites

  • Timeout dépassé : Le processus est tué et l'erreur CMD_PROCESS_TIMEOUT est levée
  • Sortie trop grande : Le texte est tronqué avec ... output truncated ... ajouté à la fin

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

1. Paramètre d’entrée : cmd_text

La commande principale à exécuter sur l’appareil.

Exemple

"cmd_text": "ping -c 1 www.google.com"

Détails

  • Exécutée via le shell Android (/system/bin/sh).
  • Doit être compatible avec la version Android et les binaires disponibles sur le device.
  • Sa sortie standard est transmise au cmd_result_output via une variable andromate (ex. $RESULT).

2. Paramètre d’entrée : root

Indique si la commande doit être exécutée avec les privilèges root.

Exemple

"root": true

Détails

  • Si root = true, la commande est généralement exécutée via su -c "<cmd_text>".
  • Si l’appareil n’est pas rooté ou si su n’est pas disponible, la tâche peut échouer.
  • À utiliser uniquement pour des actions nécessitant des permissions élevées (réseau bas niveau, fichiers système, etc.).

Détails des paramètres de sortie

3. Variable de résultat : cmd_error_output

cmd_error_output est une variable interne utilisée pour sauvegarder la sortie d’erreur (stderr) produite par la commande principale (cmd_text) lorsqu’elle échoue.

Exemple

"cmd_error_output": "$CMD_ERROR"

Déclenchement

cmd_error_output est alimentée lorsque la commande principale :

  • retourne un code de sortie ≠ 0,
  • dépasse un timeout,
  • ou lorsque la commande est introuvable ou non exécutable.

Dans tous ces cas, la sortie d’erreur (stderr) est copiée dans la variable.

Cas d’usage

  • Sauvegarder l’erreur générée par une commande (ex : ping, iperf, twamp, curl…)
  • Enregistrer des logs spécifiques (logcat, traces internes…)
  • Transmettre l’erreur à un backend pour analyse ou monitoring
  • Exploiter l’erreur dans une autre task (condition, fallback, rapport…)

4. Variable de résultat : cmd_result_output

cmd_result_output est une variable interne utilisée pour sauvegarder la sortie standard (stdout) produite par la commande exécutée dans la task.

Exemple

"cmd_result_output" : "$RESULT"

Détails

  • $RESULT contient la sortie standard de la commande principale.
  • Le workflow peut :
  • analyser la sortie,
  • extraire une valeur (temps de réponse, code, état…),
  • transformer ou normaliser le résultat,
  • l’envoyer à un backend (via curl ou Http request.).

Cas d’usage

  • Envoi de métriques vers un serveur de collecte
  • Chaine d’exécution de plusieurs commandes dépendantes

Exemple JSON complet

{
  "CmdStage": [
    {
      "id": "-1",
      "title": "Cmd Stage",
      "cmd_text": "ping -c 1 www.google.com",
      "root": true,
      "cmd_error_output":  "$PING_GOOGLE_CMD_ERROR",
      "cmd_result_output": "$PING_GOOGLE_CMD_RESULT"
    }
  ]
}