update docs

Author: b3b

README.rst

@@ -27,23 +27,12 @@ PythonHere
 - *Here* is a server part with the GUI interface. It could be Android, Raspberry Pi, some other remote device that being debugged.
 - And *%there* is a client - Jupyter magic command to run code interactively on remote device.
 
-Project documentation: https://herethere.me
-
-.. |jupyter| image:: https://raw.githubusercontent.com/b3b/pythonhere/master/docs/left_jupyter.png
-   :align: middle
-   :height: 400
-.. |android| image:: https://raw.githubusercontent.com/b3b/pythonhere/master/docs/right_android.png
-   :align: middle
-   :height: 400
+This app could serve as a Python Kivy playground, for dynamic code execution from the PC.
 
-.. list-table::
-   :widths: 50 50
-   :header-rows: 1
+Project documentation: https://herethere.me
 
-   * - Jupyter on PC
-     - Android app
-   * - |jupyter|
-     - |android|
+.. image:: https://raw.githubusercontent.com/b3b/pythonhere/master/docs/description.png
+  :alt: Project description
 
 
 Install on Android
@@ -104,7 +93,7 @@ To build with `Buildozer <https://github.com/kivy/buildozer>`_, run in the sourc
 Related resources
 -----------------
 
-* `Kivy Remote Shell <https://github.com/kivy/kivy-remote-shell>`_: Remote SSH+Python interactive shell application
+* `Kivy Remote Shell <https://github.com/kivy/kivy-remote-shell>`_ : Remote SSH+Python interactive shell application
 * `herethere <https://github.com/b3b/herethere>`_ : Library for interactive code execution, based on AsyncSSH
 * `AsyncSSH <https://github.com/ronf/asyncssh>`_ : Asynchronous SSH for Python
 * `Buildozer action <https://github.com/ArtemSBulgakov/buildozer-action>`_ : GitHub action that is used to build Android APK with Buildozer

buildozer.spec

@@ -58,6 +58,9 @@ android.api = 29
 android.minapi = 22
 android.ndk = 20b
 
+# (str) The Android arch to build for, choices: armeabi-v7a, arm64-v8a, x86, x86_64
+android.arch = armeabi-v7a
+
 android.permissions =
                     WAKE_LOCK,
                     ACCESS_NETWORK_STATE,

docs/description.png

@@ -22,11 +22,16 @@ Android platform features could be used with [PyJNIus](https://github.com/kivy/p
 
 ```python
 %%there
+from pathlib import Path
 from kivy.logger import Logger
 from android.permissions import Permission, check_permission, request_permission
 import plyer
 ```
 
+```python
+%there -b log
+```
+
 ## Show notification
 
 ```python
@@ -73,24 +78,24 @@ touch /sdcard/test_python_here
 
 ### Request runtime permission
 
-```python
-%there -bl 1 log
-```
-
 ```python
 %%there
-
 def permissions_callback(permissions, grant_results):
     if permissions and all(grant_results):
-        Logger.info("Runtime permissions: granted")
+        Logger.info("Runtime permissions: granted %s", permissions)
     else:
-        Logger.error("Runtime permissions: not granted")
+        Logger.error("Runtime permissions: not granted, %s", permissions)
 
-permission = Permission.WRITE_EXTERNAL_STORAGE
-if check_permission(permission):
-    print(f"{permission} is already granted")
-else:
-    request_permission(permission, callback=permissions_callback)
+def ask_permission(permission):
+    if check_permission(permission):
+        print(f"{permission} is already granted")
+    else:
+        request_permission(permission, callback=permissions_callback)
+```
+
+```python
+%%there
+ask_permission(Permission.WRITE_EXTERNAL_STORAGE)
 ```
 
 The system permission prompt should appear at this point.
@@ -112,3 +117,29 @@ touch /sdcard/test_python_here.txt
 cat /sdcard/test_python_here.txt
 rm /sdcard/test_python_here.txt
 ```
+
+## Take picture with a camera
+Camera could be displayed and captured with the Kivy [Camera](https://kivy.org/doc/stable/api-kivy.uix.camera.html) widget.
+
+```python
+%%there
+ask_permission(Permission.CAMERA)
+```
+
+```python
+%%there kv
+Camera:
+    play: True
+```
+
+```python
+%%there
+root.export_to_png(filename=str(Path("camera.png").resolve()))
+root.play = False
+```
+
+```python
+%%there  shell
+file camera.png
+rm camera.png
+```

docs/left_jupyter.png

@@ -0,0 +1,118 @@
+---
+jupyter:
+  jupytext:
+    text_representation:
+      extension: .md
+      format_name: markdown
+      format_version: '1.2'
+      jupytext_version: 1.7.1
+  kernelspec:
+    display_name: Python 3
+    language: python
+    name: python3
+---
+
+# Android Bluetooth Low Energy functions
+BLE functions could be used with the [able](https://github.com/b3b/able) library.
+
+```python
+%load_ext pythonhere
+%connect-there
+```
+
+```python
+%%there
+from kivy.logger import Logger
+from able import BluetoothDispatcher, GATT_SUCCESS
+```
+
+BLE dispatcher callbacks results should be printed in logs:
+
+```python
+%there -b log
+```
+
+## Setup BLE interface
+with logging callbacks
+
+```python
+%%there
+class BLE(BluetoothDispatcher):
+
+    def on_connection_state_change(self, status, state):
+        Logger.info("on_connection_state_change: status=%s, state=%s", status, state)
+        if status == GATT_SUCCESS and state:
+            Logger.info("Connection: succeed")
+
+    def on_services(self, status, services):
+        Logger.info("on_services: status=%s", status)
+        if status == GATT_SUCCESS:
+            Logger.info("services discovered: %s", list(services.keys()))
+            # save discovered services object
+            self.services = services
+
+    def on_characteristic_read(self, characteristic, status):
+        Logger.info("on_characteristic_read: status=%s, characteristic=%s", status,
+                    characteristic.getUuid().toString())
+        if status == GATT_SUCCESS:
+            Logger.info("Characteristic read: succeed")
+
+
+ble = BLE()
+print(ble)
+```
+
+## Connect to remote device by a hardware address
+In this example device hardware address address is known.
+
+```python
+%%there
+if not getattr(app, "device_address", None):
+    app.device_address = "FF:FF:FF:FF:FF:FF"
+
+ble.connect_by_device_address(app.device_address)
+```
+
+## Discover device services and characteristics
+Wait a while, while device is connected. Start services discovery:
+
+```python
+%%there -d 5
+ble.discover_services()
+```
+
+Wait a while, while services discovered. Print connected device characteristics:
+
+```python
+%%there -d 2
+print(type(ble.services))
+for service, characteristics in ble.services.items():
+    print(f"Service {service} characteristics:")
+    for characteristic in characteristics:
+        print(f"\t*{characteristic}")
+```
+
+## Read characteristic
+In this example, it is known that target device has characteristic
+with UUID = 16fe**0d01**-c111-11e3-b8c8-0002a5d5c51b  
+This characteristic is readable, and always returns a string value: "test".
+
+```python
+%%there
+characteristic = ble.services.search("0d01")  
+print(f"Characteristic UUID found: {characteristic.getUuid().toString()}")
+print(f"Characteristic object: {characteristic}")
+# https://developer.android.com/reference/android/bluetooth/BluetoothGattCharacteristic#getStringValue(int)
+print(f"Characteristic value is not available yet: {characteristic.getStringValue(0)}")
+
+ble.read_characteristic(characteristic)
+```
+
+Wait a while, and check characteristic value.  
+**on_characteristic_read** message should appear in logs
+
+```python
+%%there -d 2
+# https://developer.android.com/reference/android/bluetooth/BluetoothGattCharacteristic#getStringValue(int)
+print(characteristic.getStringValue(0))
+```