Aller au contenu

BLE Write Characteristic

Résumé

  • Nom interne : Ble_writeChar
  • Catégorie : Bluetooth
  • Objectif : Encoder une valeur et l'écrire dans une caractéristique GATT sur un appareil BLE déjà connecté.
  • 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 Write Characteristic encode value_to_write selon le type decoder choisi et écrit les octets résultants dans une caractéristique GATT (identifiée par UUID de service + UUID de caractéristique) sur un appareil BLE qui doit déjà être connecté via Ble_connect.

La caractéristique cible doit supporter la propriété WRITE ou WRITE_NO_RESPONSE, sinon la tâche échoue immédiatement.

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 ""
value_to_write String Oui La valeur à encoder et écrire — format dépend de decoder 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 l'accusé de réception de l'écriture Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 5000

Types de décodeur (utilisés pour ENCODER value_to_write en octets)

Code Décodeur Format attendu de value_to_write
1 AUTO Texte brut, encodé en UTF-8
2 UTF8 Texte brut
3 ASCII Texte brut (ASCII uniquement)
10 INT8 / 11 UINT8 / 31 BITMASK Chaîne d'entier décimal ou préfixée 0x
12 INT16 / 13 UINT16 Chaîne d'entier décimal ou préfixée 0x
14 INT32 / 15 UINT32 Chaîne d'entier décimal ou préfixée 0x
20 FLOAT32 Chaîne décimale, ex. "3.14"
21 FLOAT64 Chaîne décimale, ex. "3.14159265"
30 BOOL "true" ou "false"
40 HEX / 41 HEX_COMPACT Chaîne hex, espaces optionnels, ex. "AF 01 3C" ou "AF013C"
42 BASE64 Chaîne encodée en Base64
43 BYTES Octets entre crochets séparés par des virgules, ex. "[12, -1, 3]"

Tout code non listé ci-dessus (ou omis) résout en UNKNOWN, que cette tâche traite comme HEX. Si l'encodage échoue pour une raison quelconque (mauvais format pour le décodeur choisi), un tableau d'octets vide est écrit plutôt que de faire planter la tâche.

Paramètres de sortie

La tâche BLE Write Characteristic ne produit aucune sortie.

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é, ou la caractéristique ne supporte pas l'écriture.
BLE-TASK-015 Écriture impossible L'appel d'écriture n'a pas pu démarrer, ou le serveur GATT a retourné un statut d'échec.
BLE-TASK-012 Timeout lecture/écriture Aucun accusé de réception dans le délai read_timeout (pendant la découverte de services ou l'écriture elle-même).

Diagramme d'exécution

flowchart TD
    Start([▶ Ble_writeChar]) --> 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 --> FindChar{Service + caractéristique trouvés,\ninscriptibles ?}
    FindChar -->|Non| E3[❌ BLE-TASK-008/009]
    FindChar -->|Oui| Encode[🔄 Encoder value_to_write selon decoder]
    Encode --> Write[✍️ writeCharacteristic]
    Write --> CheckStart{Écriture\ndémarrée OK ?}
    CheckStart -->|Non| E4[❌ BLE-TASK-015\nCANNOT_WRITE]
    CheckStart -->|Oui| WaitAck{Accusé dans\nread_timeout ?}
    WaitAck -->|Non| E5[❌ BLE-TASK-012\nTIMEOUT]
    WaitAck -->|GATT_SUCCESS| Success1[✅ Écrit]
    WaitAck -->|Statut d'erreur| E4

    Success1 --> Success([✅ VoidResult])
    E1 --> Error([❌ Exception])
    E2 --> Error
    E3 --> Error
    E4 --> Error
    E5 --> Error

    style Start fill:#e3f2fd
    style Success fill:#c8e6c9
    style Error fill:#ffcdd2
    style Write fill:#fff9c4

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 + localiser : trouve le service et la caractéristique ; échoue si introuvables ou non inscriptibles.
  4. Encoder : convertit value_to_write en octets selon decoder (repli sur HEX si non défini/inconnu).
  5. Écrire : lance l'écriture GATT et attend l'accusé de réception du serveur.
  6. Résultat : succès sur GATT_SUCCESS ; sinon BLE-TASK-015 ou BLE-TASK-012 en cas de timeout.

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é à écrire.

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 à écrire.

Exemple

"service_uid": "0000ffe0-0000-1000-8000-00805f9b34fb",
"char_uid": "0000ffe1-0000-1000-8000-00805f9b34fb"

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

La valeur à encoder et envoyer — son format attendu dépend du decoder choisi (voir tableau ci-dessus).

Exemple — texte

"value_to_write": "ON",
"decoder": 2

Exemple — entier

"value_to_write": "1",
"decoder": 11

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

Comment encoder value_to_write en octets avant l'écriture — voir le tableau Types de décodeur ci-dessus.

Détails

  • Optionnel — les codes non définis ou non reconnus se replient sur HEX.

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

Millisecondes à attendre à la fois la découverte de services et l'accusé de réception de l'écriture.

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_writeChar": [
    {
      "id": "2",
      "title": "Activer le relais",
      "mac_ble": "AA:BB:CC:DD:EE:FF",
      "service_uid": "0000ffe0-0000-1000-8000-00805f9b34fb",
      "char_uid": "0000ffe1-0000-1000-8000-00805f9b34fb",
      "value_to_write": "1",
      "decoder": 11
    }
  ]
}