Aller au contenu

BLE Read Characteristic

Résumé

  • Nom interne : Ble_readChar
  • Catégorie : Bluetooth
  • Objectif : Lire la valeur d'une caractéristique GATT depuis un appareil BLE déjà connecté et la décoder dans une variable de workflow.
  • Type de tâche : Normale

Compatibilité

  • Version minimale AndroMate : 1.1.0

  • Version maximale AndroMate : 1.1.0

  • Android minimum : Android 13 (API 33)

  • Android maximum testé : Android 16 (API 36)

  • Constructeurs supportés :

    • ✅ Tous les constructeurs

  • Permissions requises :

    • BLUETOOTH_SCAN
    • BLUETOOTH_CONNECT
    • Localisation de l'appareil activée (exigence Android pour les opérations BLE)

Description détaillée

La tâche BLE Read Characteristic lit la valeur d'une caractéristique GATT (identifiée par son UUID de service + UUID de caractéristique) depuis un appareil BLE qui doit déjà être connecté via Ble_connect. Les octets bruts sont décodés selon le type decoder choisi et stockés sous forme de chaîne dans value_output.

Avant la lecture, la tâche découvre les services GATT de l'appareil et localise le service/caractéristique demandé — les deux doivent exister sur l'appareil, sinon la tâche échoue.

Paramètres d'entrée

Paramètre Type Obligatoire Valeurs possibles Compatibilité Android Compatibilité AndroMate Défaut
mac_ble String Oui Une adresse MAC Bluetooth valide, doit déjà être connectée Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 ""
service_uid String Oui Un UUID de service GATT valide Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 ""
char_uid String Oui Un UUID de caractéristique GATT valide Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 ""
decoder Integer Non Voir le tableau Types de décodeur ci-dessous Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 -1 (UNKNOWN → repli sur HEX)
read_timeout Integer Non Millisecondes à attendre la réponse de lecture Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 5000

Types de décodeur

Code Décodeur Remarques
1 AUTO UTF-8 si tous les octets sont imprimables, sinon repli sur hex espacé
2 UTF8 Décoder les octets en texte UTF-8
3 ASCII Décoder les octets en texte ASCII
10 INT8 Entier signé 8 bits
11 UINT8 Entier non signé 8 bits
12 INT16 Entier signé 16 bits, little-endian
13 UINT16 Entier non signé 16 bits, little-endian
14 INT32 Entier signé 32 bits, little-endian
15 UINT32 Entier non signé 32 bits, little-endian
20 FLOAT32 Flottant IEEE-754 32 bits, little-endian
21 FLOAT64 Flottant IEEE-754 64 bits, little-endian
30 BOOL Premier octet : 0 = false, non-zéro = true
31 BITMASK Premier octet comme entier non signé (bitmask)
40 HEX Hex espacé en majuscules, ex. "AF 01 3C"
41 HEX_COMPACT Hex sans espace en majuscules, ex. "AF013C"
42 BASE64 Chaîne encodée en Base64
43 BYTES toString() de tableau d'octets Java, ex. "[12, -1, 3]"

Tout code non listé ci-dessus (ou omis) résout en UNKNOWN, que cette tâche traite comme HEX.

Paramètres de sortie

Paramètre Type Condition Compatibilité Android Compatibilité AndroMate Défaut
value_output String Toujours, en cas de succès Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 <ANDROMATE_NULL_VALUE>

value_output

La valeur de la caractéristique, décodée selon le paramètre decoder (voir tableau ci-dessus).

Exceptions

Code Nom de l'exception Description
BLE-TASK-001 Bluetooth désactivé Le Bluetooth est désactivé sur l'appareil.
BLE-TASK-002 Bluetooth non supporté Cet appareil ne supporte pas le Bluetooth.
ERROR-001 Permission non accordée BLUETOOTH_SCAN ou BLUETOOTH_CONNECT n'a pas été accordée.
GPS-ERROR-003 Localisation désactivée La localisation de l'appareil est désactivée — requise par Android pour le BLE.
BLE-TASK-003 Format MAC invalide mac_ble n'est pas une adresse MAC Bluetooth valide.
BLE-TASK-005 MAC BLE déconnectée L'appareil n'est pas actuellement connecté.
BLE-TASK-006 MAC BLE non enregistrée L'appareil n'a jamais été connecté via Ble_connect dans cette session.
BLE-TASK-011 Aucune connexion GATT active Aucune connexion GATT active disponible pour cet appareil.
BLE-TASK-007 UUID invalide service_uid ou char_uid n'est pas un format UUID valide.
BLE-TASK-008 Service introuvable Aucun service GATT correspondant à service_uid sur cet appareil.
BLE-TASK-009 Caractéristique introuvable Aucune caractéristique correspondant à char_uid dans le service donné.
BLE-TASK-010 Lecture impossible Le serveur GATT a retourné un statut d'échec pour la lecture.
BLE-TASK-012 Timeout lecture/écriture Aucune réponse dans le délai read_timeout (pendant la découverte de services ou la lecture elle-même).

Diagramme d'exécution

flowchart TD
    Start([▶ Ble_readChar]) --> Prereq{BLE activé, connecté,\nenregistré, permissions OK ?}
    Prereq -->|Non| E1[❌ BLE-TASK-001/002/005/006/011\nERROR-001/GPS-ERROR-003]
    Prereq -->|Oui| CheckUuid{service_uid, char_uid\nUUID valides ?}
    CheckUuid -->|Non| E2[❌ BLE-TASK-007\nINVALID_UUID]
    CheckUuid -->|Oui| Discover[🔍 discoverServices]
    Discover --> WaitDisc{Découvert dans\nread_timeout ?}
    WaitDisc -->|Non| E3[❌ BLE-TASK-012\nTIMEOUT]
    WaitDisc -->|Oui| FindService{Service\ntrouvé ?}
    FindService -->|Non| E4[❌ BLE-TASK-008\nSERVICE_NOT_FOUND]
    FindService -->|Oui| FindChar{Caractéristique\ntrouvée ?}
    FindChar -->|Non| E5[❌ BLE-TASK-009\nCHAR_NOT_FOUND]
    FindChar -->|Oui| Read[📖 readCharacteristic]
    Read --> WaitRead{Réponse dans\nread_timeout ?}
    WaitRead -->|Non| E3
    WaitRead -->|GATT_SUCCESS| Decode[🔄 Décoder les octets selon decoder]
    WaitRead -->|Statut d'erreur| E6[❌ BLE-TASK-010\nCANNOT_READ]
    Decode --> StoreResult[💾 Stocker value_output]
    StoreResult --> Success([✅ StrTaskResult])

    E1 --> Error([❌ Exception])
    E2 --> Error
    E3 --> Error
    E4 --> Error
    E5 --> Error
    E6 --> Error

    style Start fill:#e3f2fd
    style Success fill:#c8e6c9
    style Error fill:#ffcdd2
    style Read fill:#fff9c4
    style StoreResult fill:#c8e6c9

Comment ça fonctionne :

  1. Vérifications préalables + connexion : Bluetooth prêt, mac_ble connectée et enregistrée.
  2. Validation des UUID : service_uid/char_uid doivent être des UUID valides.
  3. Découvrir les services : attend la table des services GATT (bornée par read_timeout).
  4. Localiser le service et la caractéristique : échoue si l'un des deux est introuvable sur l'appareil.
  5. Lire : lance la lecture GATT et attend la réponse du serveur.
  6. Décoder : convertit les octets bruts selon le type decoder (repli sur HEX si non défini/inconnu).
  7. Stocker : écrit la chaîne décodée dans value_output.

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

1. Paramètre d'entrée : mac_ble

L'adresse MAC de l'appareil déjà connecté à lire.

Exemple

"mac_ble": "AA:BB:CC:DD:EE:FF"

2. Paramètre d'entrée : service_uid / char_uid

Les UUID de service et de caractéristique GATT à lire.

Exemple

"service_uid": "0000180f-0000-1000-8000-00805f9b34fb",
"char_uid": "00002a19-0000-1000-8000-00805f9b34fb"

3. Paramètre d'entrée : decoder

Comment décoder les octets bruts lus depuis la caractéristique — voir le tableau Types de décodeur ci-dessus.

Exemple

"decoder": 11

Détails

  • Optionnel — les codes non définis ou non reconnus se replient sur HEX (chaîne hex espacée).

4. Paramètre d'entrée : read_timeout

Millisecondes à attendre à la fois la découverte de services et la réponse de lecture.

Exemple

"read_timeout": 8000

Détails

  • Optionnel — vaut 5000 (5 secondes) par défaut.

Exemple JSON complet

{
  "Ble_connect": [
    { "id": "1", "mac_ble": "AA:BB:CC:DD:EE:FF" }
  ],
  "Ble_readChar": [
    {
      "id": "2",
      "title": "Lire le niveau de batterie de la caractéristique",
      "mac_ble": "AA:BB:CC:DD:EE:FF",
      "service_uid": "0000180f-0000-1000-8000-00805f9b34fb",
      "char_uid": "00002a19-0000-1000-8000-00805f9b34fb",
      "decoder": 11,
      "value_output": "$BLE_BATTERY_LEVEL"
    }
  ]
}