UARTService: add stream operations; make advertising start/stop explicit

Author: dhalbert

adafruit_ble/uart.py

@@ -32,7 +32,13 @@
 
 
 class UARTService:
-    """Provide UART-like functionality via the Nordic NUS service.
+    """
+    Provide UART-like functionality via the Nordic NUS service.
+
+    :param int timeout:  the timeout in seconds to wait
+      for the first character and between subsequent characters.
+    :param int buffer_size: buffer up to this many bytes.
+      If more bytes are received, older bytes will be discarded.
 
     Example::
 
@@ -44,7 +50,7 @@ class UARTService:
     NUS_RX_CHAR_UUID = UUID("6E400002-B5A3-F393-E0A9-E50E24DCCA9E")
     NUS_TX_CHAR_UUID = UUID("6E400003-B5A3-F393-E0A9-E50E24DCCA9E")
 
-    def __init__(self):
+    def __init__(self, timeout=1.0, buffer_size=64):
         """Define the NUS service and start advertising it."""
         self._nus_tx_char = Characteristic(self.NUS_TX_CHAR_UUID, notify=True)
         self._nus_rx_char = Characteristic(self.NUS_RX_CHAR_UUID,
@@ -53,21 +59,65 @@ def __init__(self):
         nus_uart_service = Service(self.NUS_SERVICE_UUID, (self._nus_tx_char, self._nus_rx_char))
 
         self._periph = Peripheral((nus_uart_service,))
-        self._rx_buffer = CharacteristicBuffer(self._nus_rx_char, 64)
+        self._rx_buffer = CharacteristicBuffer(self._nus_rx_char,
+                                               timeout=timeout, buffer_size=buffer_size)
 
         self._periph.start_advertising()
 
+    def start_advertising(self):
+        """Start advertising the service. When a client connects, advertising will stop.
+        When the client disconnects, restart advertising by calling ``start_advertising()`` again.
+        """
+        self._periph.start_advertising()
+
+    def stop_advertising(self):
+        """Stop advertising the service."""
+        self._periph.stop_advertising()
+
     @property
     def connected(self):
-        """Has someone connected to the service?"""
+        """True if someone connected to the service."""
         return self._periph.connected
 
-    def read(self):
-        """Read the next available byte from the buffered input.
-        Return None if nothing is available.
+    def read(self, nbytes=None):
+        """
+        Read characters. If ``nbytes`` is specified then read at most that many bytes.
+        Otherwise, read everything that arrives until the connection times out.
+        Providing the number of bytes expected is highly recommended because it will be faster.
+
+        :return: Data read
+        :rtype: bytes or None
+        """
+        return self._rx_buffer.read(nbytes)
+
+    def readinto(self, buf, nbytes=None):
         """
-        return self._rx_buffer.read()
+        Read bytes into the ``buf``. If ``nbytes`` is specified then read at most
+        that many bytes. Otherwise, read at most ``len(buf)`` bytes.
+
+        :return: number of bytes read and stored into ``buf``
+        :rtype: int or None (on a non-blocking error)
+        """
+        return self._rx_buffer.readinto(buf, nbytes)
+
+    def readline(self):
+        """
+        Read a line, ending in a newline character.
+
+        :return: the line read
+        :rtype: int or None
+        """
+        return self._rx_buffer.readline()
+
+    @property
+    def in_waiting(self):
+        """The number of bytes in the input buffer, available to be read."""
+        return self._rx_buffer.in_waiting
+
+    def reset_input_buffer(self):
+        """Discard any unread characters in the input buffer."""
+        self._rx_buffer.reset_input_buffer()
 
-    def write(self, bytes_to_write):
+    def write(self, buf):
         """Write a buffer of bytes."""
-        self._nus_tx_char.value = bytes_to_write
+        self._nus_tx_char.value = buf