From 826b06dce0364112f8d8329d591d4817f6394970 Mon Sep 17 00:00:00 2001
From: rbaron <rbaron@rbaron.net>
Date: Mon, 8 Aug 2022 03:00:00 +0200
Subject: [PATCH] Adds docs for the new ble_client.ble_write Action (#2024)

Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
---
 components/ble_client.rst | 28 ++++++++++++++++++++++++++++
 guides/automations.rst    |  1 +
 2 files changed, 29 insertions(+)

diff --git a/components/ble_client.rst b/components/ble_client.rst
index a846ed24e..00e4b385e 100644
--- a/components/ble_client.rst
+++ b/components/ble_client.rst
@@ -91,6 +91,34 @@ This automation is triggered when the client disconnects from a BLE device.
             - lambda: |-
                 ESP_LOGD("ble_client_lambda", "Disconnected from BLE device");
 
+.. _ble_client-ble_write_action:
+
+``ble_client.ble_write`` Action
+-------------------------------
+
+This action triggers a write to a specified BLE characteristic. The write is attempted in
+a best-effort fashion and will only succeed if the `ble_client`'s  connection has been
+established and the peripheral exposes the expected BLE service and characteristic.
+
+Example usage:
+
+.. code-block:: yaml
+
+    ble_client:
+      - mac_address: 11:22:33:44:55:66
+        id: my_ble_client
+
+    switch:
+      - platform: template
+        name: "My Switch"
+        turn_on_action:
+          - ble_client.ble_write:
+              id: my_ble_client
+              service_uuid: F61E3BE9-2826-A81B-970A-4D4DECFABBAE
+              characteristic_uuid: 6490FAFE-0734-732C-8705-91B653A081FC
+              # List of bytes to write.
+              value: [0x01, 0xab, 0xff]
+
 BLE Overview
 ------------
 This section gives a brief overview of the Bluetooth LE architecture
diff --git a/guides/automations.rst b/guides/automations.rst
index fb457796b..5062b0da1 100644
--- a/guides/automations.rst
+++ b/guides/automations.rst
@@ -394,6 +394,7 @@ All Actions
 - :ref:`select.set <select-set_action>` / :ref:`select.set_index <select-set_index_action>` / :ref:`select.first <select-first_action>` / :ref:`select.last <select-last_action>` / :ref:`select.previous <select-previous_action>`  / :ref:`select.next <select-next_action>`  / :ref:`select.operation <select-operation_action>`
 - :ref:`media_player.play <media_player-play>` / :ref:`media_player.pause <media_player-pause>` / :ref:`media_player.stop <media_player-stop>` / :ref:`media_player.toggle <media_player-toggle>`
   / :ref:`media_player.volume_up <media_player-volume_up>` / :ref:`media_player.volume_down <media_player-volume_down>` / :ref:`media_player.volume_set <media_player-volume_set>`
+- :ref:`ble_client.ble_write <ble_client-ble_write_action>`
 
 .. _config-condition: