From 7aeafe2ae9f16af74d22604b3090641a664b2da2 Mon Sep 17 00:00:00 2001
From: Damien George
Date: Fri, 29 Nov 2019 12:48:38 +1100
Subject: extmod/modbluetooth: Add optional 4th arg to gattc_write for write
 mode.

This allows the user to explicitly select the behaviour of the write to the
remote peripheral.  This is needed for peripherals that have
characteristics with WRITE_NO_RESPONSE set (instead of normal WRITE).  The
function's signature is now:

    BLE.gattc_write(conn_handle, value_handle, data, mode=0)

mode=0 means write without response, while mode=1 means write with
response.  The latter was the original behaviour so this commit is a change
in behaviour of this method, and one should specify 1 as the 4th argument
to get back the old behaviour.

In the future there could be more modes supported, such as long writes.
---
 docs/library/ubluetooth.rst | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/library/ubluetooth.rst b/docs/library/ubluetooth.rst
index 2d3af1bb6..fd4c012d2 100644
--- a/docs/library/ubluetooth.rst
+++ b/docs/library/ubluetooth.rst
@@ -310,12 +310,23 @@ Central Role (GATT Client)
 
     On success, the ``_IRQ_GATTC_READ_RESULT`` event will be raised.
 
-.. method:: BLE.gattc_write(conn_handle, value_handle, data)
+.. method:: BLE.gattc_write(conn_handle, value_handle, data, mode=0)
 
     Issue a remote write to a connected peripheral for the specified
     characteristic or descriptor handle.
 
-    On success, the ``_IRQ_GATTC_WRITE_STATUS`` event will be raised.
+    The argument *mode* specifies the write behaviour, with the currently
+    supported values being:
+
+        * ``mode=0`` (default) is a write-without-response: the write will
+          be sent to the remote peripheral but no confirmation will be
+          returned, and no event will be raised.
+        * ``mode=1`` is a write-with-response: the remote peripheral is
+          requested to send a response/acknowledgement that it received the
+          data.
+
+    If a response is received from the remote peripheral the
+    ``_IRQ_GATTC_WRITE_STATUS`` event will be raised.
 
 
 class UUID
-- 
cgit v1.2.3