Improve documentation

docs/source/bluetooth.rst

@@ -69,4 +69,45 @@ above picture, you can click the :blue:`Read Again` button as often as you would
 change when you (or NanoNav) writes to it. And you can send a number as often as you want in LightBlue, but NanoNav will not know unless you program it to 
 read the value periodically. (Actually, you can setup BLE interrupts for NanoNav to run code when something changes in the BLE connection, similar to the :py:meth:`~nanonav.BLE.on_connected` and :py:meth:`~nanonav.BLE.on_disconnected`, but we think 
 you'll have an easier time getting your code to work as expected by avoiding that kind of programming for now).
-If interested in learning about other bluetooth capabilities beyond the scope of NanoNav, see `here <https://docs.micropython.org/en/latest/library/bluetooth.html>`_.
+
+Event Handlers (Optional)
+-------------------------
+MicroPython enables a variety of event handlers to be used with Bluetooth. Unless you want to explore the details of the BLE object,
+the two most accessible event handlers are for when a device connects or disconnects from your NanoNav.
+
+.. code-block:: python
+
+    from nanonav import BLE
+    import time
+
+    _IRQ_GATTC_WRITE_DONE = const(17)
+
+    class MyBLE(BLE):
+      # Don't override the __init__ method, unless you know what you're doing
+
+      # You can create these methods to handle connection and disconnection events
+      def on_connected(self):
+        print("Connected established with NanoNav")
+
+      def on_disconnected(self):
+        print("Disconnected from NanoNav")
+
+      # For advanced event handling use cases:
+      def _irq(self, event, data):
+        if event == _IRQ_GATTC_WRITE_DONE:
+            print("Data written successfully to Bluetooth characteristic")
+        super()._irq(event, data)
+
+    # Create an instance of your subclass
+    ble = MyBLE(name="NanoNav")  
+
+    ble.send(43)
+    response = ble.read()
+    # wait until something changes, indicating a response
+    while response == 43:
+        response = ble.read()
+	      time.sleep(0.5)
+
+    print("Received: ", response)
+
+If interested in learning about other Bluetooth events or capabilities beyond the scope of NanoNav, see `here <https://docs.micropython.org/en/latest/library/bluetooth.html>`_.

docs/source/nanonav.py

@@ -48,13 +48,13 @@ def read(self):
 
     def on_connected(self):
         """
-        You may specify this method to be called once the BLE connection is established.
+        You may create this method in a subclass of BLE to be called once the BLE connection is established.
         """
         pass
 
     def on_disconnected(self):
         """
-        You may specify this method to be called once the BLE connection is lost.
+        You may create this method in a subclass of BLE to be called once the BLE connection is lost.
         """
         pass
 

docs/source/usage.rst

@@ -47,7 +47,7 @@ Your Arduino Nano RP2040 can run either C++ or MicroPython, but not both at the
 you can run MicroPython code on it. After you have done this once, you should not need to do it again.
 
 To use the NanoNav supplementary code, download this starter zip folder :download:`nanonav_starter.zip </../../tests/installation_check/nanonav_starter.zip>`.
-You will need the `nanonav.py` file as well as the `ble_advertising.py` file for any projects you use NanoNav with. Extract the files from the zip folder; you will need them for the next steps.
+You will need the `nanonav.py` file as well as the `ble_advertising.py` file for any projects you use NanoNav with. Extract the files from the zip folder; you will use them for the next steps.
 
 The `ble_advertising.py` file comes from `MicroPython's github repository <https://github.com/micropython/micropython/tree/master>`_. If you're interested, you can check out the latest Open Source developments in MicroPython!
 
@@ -68,10 +68,6 @@ Connecting to the Arduino over USB
 
 Connect your Arduino to your computer using a USB cable. 
 
-.. image:: images/rp2040_white_button.jpeg
-   :height: 80
-   :alt: RP2040 white button
-
 In the bottom left of the OpenMV IDE, you should see this:
 
 .. image:: images/openmv_unconnected.png
@@ -83,7 +79,11 @@ You can wait for a little and try messing with your USB conection (different cab
 
 If this still does not work, try putting the Arduino in bootloader mode by double clicking the white button on the top of the board.
 
-Once you see this, click the "Connect" button (the USB connection, or upper button of the two in the image).
+.. image:: images/rp2040_white_button.jpeg
+   :height: 80
+   :alt: RP2040 white button
+
+Once you see the "Connect" button, click it (the USB connection, or upper button of the two in the image).
 
 When you try to connect, you may see a popup requesting to load the latest firmware. If you see this, click OK.
 
@@ -97,9 +97,9 @@ The arrow below it should turn green when connected.
    :height: 100
    :alt: OpenMV connected symbols
 
-After you can see the green arrow, you should be able to see the Arduino as an external drive in FileExplorer (Windows), Finder (Mac), 
+When the Arduino is connected (as indicated by the green arrow), you should be able to find the Arduino as an external drive in FileExplorer (Windows), Finder (Mac), 
 or the equivalent for your Operating System. 
-It will likely be named "NO NAME" and should contain a `main.py` and `README.txt` file. 
+It will likely be named "NO NAME" or "USB Drive" and should contain a `main.py` and `README.txt` file. 
 
 .. note::
    You must copy the the files (not the folder) from :download:`nanonav_starter.zip </../../tests/installation_check/nanonav_starter.zip>` 
@@ -113,7 +113,7 @@ You have two options for running your code on the Arduino: laptop mode and solo
 
 **Laptop mode**: Click the arrow to run the code in conjunction with the laptop. Running in laptop mode is optimal for debugging. You can run and stop your code without touching the Arduino or USB cable. While in laptop mode, you can use print statements to print to the Serial Terminal in the OpenMV IDE. You can expand this terminal by pressing its corresponding button in the bottom left of the IDE. Note that when running in laptop mode, you must have the Arduino connected to the laptop. Once you disconnect the Arduino, your code will no longer be running.
 
-**Solo mode**: To run code without the laptop connected, you need to run in solo mode. Connect to the Arduino but don't hit the green play. Instead, go to Tools > Save open script to OpenMV Cam (as main.py). This will write the file you have open to the Arduino under the name "main.py". An alternative way to do this would be to copy the file over in FileExplorer/Finder like we did for nanonav.py. If you copy the file using FileExplorer/Finder, make sure it's named main.py, as the Arduino looks for and executes only the main.py file. In solo mode, you won't have access to any print statements or Python exceptions, so only use solo mode after you've tested your code in laptop mode.
+**Solo mode**: To run code without the laptop connected, you need to run in solo mode. Connect to the Arduino but don't hit the green play. Instead, go to Tools > Save open script to OpenMV Cam (as main.py). This will write the file you have open to the Arduino under the name "main.py". An alternative way to do this would be to copy the file over in FileExplorer/Finder like we did for the starter files. If you copy the file using FileExplorer/Finder, make sure it's named main.py, as the Arduino looks for and executes only the main.py file. In solo mode, you won't have access to any print statements or Python exceptions, so only use solo mode after you've tested your code in laptop mode.
 
 We recognize that OpenMV IDE is not a very nice editor to write code in, so feel free to open `main.py` in your favorite editor (such as VS Code) for editing and run it from OpenMV IDE.
 
@@ -122,7 +122,7 @@ We recognize that OpenMV IDE is not a very nice editor to write code in, so feel
 Running our test code
 ^^^^^^^^^^^^^^^^^^^^^
 
-When you have doubts about whether your Arduino is functioning properly, try running our test code! Use the `main.py`, `nanonav.py`, and `ble_advertising.py` files from above.
+When you have doubts about whether your Arduino is functioning properly, try running our test code! Use the `main.py`, `nanonav.py`, and `ble_advertising.py` files from :download:`nanonav_starter.zip </../../tests/installation_check/nanonav_starter.zip>`.
 
 This tests all of the features of the kit: motors, encoders, IR sensors and Bluetooth.
 
@@ -134,7 +134,6 @@ After writing over Bluetooth, the IR sensor values should be printed out in the
 
 If all of this works, you've verified that your kit works correctly! If not, try our `Troubleshooting <https://bram-hub.github.io/NanoNav/faq.html#troubleshooting>`_. Happy coding!
 
-
 MicroPython
 -----------