deploy: cbabaae

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 125d1183e421262ae167d669c878281c
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_downloads/df14896bba634131bee7f870285c5b8c/main.py

@@ -0,0 +1,4 @@
+from nanonav import BLE 
+
+# TODO: Add code to use a feature or two from the nanonav module
+# to ensure that MicroPython installation worked properly

_downloads/e6ffb4613247059f19b76a508c48412c/nanonav.py

@@ -0,0 +1,108 @@
+
+from ble_advertising import advertising_payload
+import bluetooth
+from machine import Pin, PWM, ADC, freq
+import machine
+from micropython import const
+import rp2
+
+import time
+
+# Define BLE constants (these are not packaged in bluetooth for space efficiency)
+_IO_CAPABILITY_DISPLAY_ONLY = const(0)
+_FLAG_READ = const(0x0002)
+_FLAG_WRITE = const(0x0008)
+_IRQ_CENTRAL_CONNECT = const(1)
+_IRQ_CENTRAL_DISCONNECT = const(2)
+_IRQ_GATTS_WRITE = const(3)
+
+class BLE:
+    """
+    A helpful wraper around the BLE service functions needed for the Wumpus World project
+    """
+    def __init__(self, ble=bluetooth.BLE(), name="NANO RP2040"):
+        # Setup bluetooth low energy communication service
+        _SERVICE_UUID = bluetooth.UUID(0x1523) # unique service id for the communication
+        _NanoBot_CHAR_UUID = (bluetooth.UUID(0x1525), _FLAG_WRITE | _FLAG_READ) # characteristic
+        _NanoBot_SERVICE = (_SERVICE_UUID, (_NanoBot_CHAR_UUID,),) # service to provide the characteristic
+
+        self._ble = ble
+        self._ble.active(True)
+        self._ble.config(
+            bond=True,
+            mitm=True,
+            le_secure=True,
+            io=_IO_CAPABILITY_DISPLAY_ONLY
+        )
+        self._ble.irq(self._irq)
+        ((self._handle,),) = self._ble.gatts_register_services((_NanoBot_SERVICE,))
+        self._connections = set()
+        self._payload = advertising_payload(name=name, services=[_SERVICE_UUID])
+        self._advertise()
+        self.value = b'a'
+
+    def _advertise(self, interval_us=500000):
+        self._ble.gap_advertise(interval_us, adv_data=self._payload)
+
+    def _irq(self, event, data):
+        # handle bluetooth event
+        if event == _IRQ_CENTRAL_CONNECT:
+            # handle succesfull connection
+            conn_handle, addr_type, addr = data
+            self._connections.add(conn_handle)
+
+        elif event == _IRQ_CENTRAL_DISCONNECT:
+            # handle disconnect
+            conn_handle, _, _ = data
+            self._connections.remove(conn_handle)
+            self._advertise()
+
+        elif event == _IRQ_GATTS_WRITE:
+            conn_handle, value_handle = data
+            if conn_handle in self._connections:
+                # Value has been written to the characteristic
+                self.value = self._ble.gatts_read(value_handle)
+
+
+    def send(self, value):
+        """
+        Send value to the bluetooth characteristic.
+
+        :param value: The value to send.
+        :type value: bytes, int, str
+        :raise ValueError: If the value is not bytes, int, or str.
+
+        """
+        if not isinstance(value, bytes):
+            if isinstance(value, int):
+                value = value.to_bytes(1, "big")
+            elif isinstance(value, str):
+                value = value.encode('utf-8')
+            else:
+                raise ValueError("send value should be type bytes, int, or string")
+        self.value = value
+        self._ble.gatts_write(self._handle, value)
+
+    def read(self, as_type="bytes"):
+        """
+        Return the current value of the bluetooth characteristic, or None if an error occurred.
+
+        :param as_type: The type to return the value as. Must be one of 'bytes', 'str', or 'int'.
+        :type as_type: str
+        :return: The value of the characteristic.
+        :rtype: bytes, str, int, None
+        :raise ValueError: If as_type is not 'bytes', 'str', or 'int'.
+        """
+        value = self.value  # try using the last value written to characteristic
+        try:
+            if as_type == "bytes":
+                return value
+            elif as_type == "str":
+                return value.decode("utf-8")
+            elif as_type == "int":
+                print(f'read {value}')
+                return int.from_bytes(value, "big")
+        except Exception as e:
+            return None
+
+        raise ValueError("as_type must be one of 'bytes', 'str', or 'int'")

_sources/bluetooth.rst.txt

@@ -0,0 +1,61 @@
+Bluetooth
+=========
+Using Bluetooth Low Energy (BLE) to communicate with the NanoNav.
+
+Quick Example
+-------------
+
+.. code-block:: python
+
+    from nanonav import BLE
+
+    # Create a Bluetooth object
+    ble = BLE(name="NanoNav")  
+
+    ble.send(43)
+    response = ble.read()
+
+Usage
+-----
+
+.. autoclass:: nanonav.BLE     
+    :members: 
+    :special-members: __init__,
+
+
+
+Connecting from Mobile
+----------------------
+
+Various mobile apps are available for communicating with Bluetooth Low Energy. We recommend LightBlue which is available for both iOS and Android.
+After downloading and installing it, you will need to turn your phone's Bluetooth on and open the app (no pairing is needed for Bluetooth Low Energy).
+
+If the NanoNav is waiting for a BLE connection, you will see it as one of the connection options in LightBlue. You may need to scroll down to find it.
+
+.. note::
+    On some versions of iOS, the BLE devices are automatically renamed, and NanoNav's connection may show up as "Arduino" or something else. If you find yourself in this 
+    situation, it can be helpful to search for the service id instead. TODO: link to explanation for how this can be done.
+
+.. image:: images/lightblue_devices_view.png
+  :width: 400
+  :alt: LightBlue Application with Bluetooth connections available
+
+After clicking the connect button, you will see a screen like this, which gives information about the connection.
+
+.. image:: images/lightblue_connected_view.png
+  :width: 400
+  :alt: LightBlue Application after connecting to device
+
+It is possible to configure the BLE for more complex behavior, but with this kit we only need to send small numbers back and forth with the Arduino. Click on the 
+option at the bottom (highlighted in red in the above screenshot) to open the portal where you can perform this simplified communication with NanoNav. 
+
+.. image:: images/lightblue_characteristic_view.png
+  :width: 400
+  :alt: LightBlue display of BLE characteristic, with options to read or write values to it
+
+You can think of a BLE connection as a secret whiteboard that you and your friend share. There is always some number written on it, and each of you 
+can look at (read) whatever is on it whenever you like, and can also change (write to) it whenever you like. Inside the LightBlue app, as shown in the 
+above picture, you can click the :blue:`Read Again` button as often as you would like, but the value will only
+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. You will not need to do this,
+but if interested, see `here <https://docs.micropython.org/en/latest/library/bluetooth.html>`_ for advanced uses).

_sources/faq.rst.txt

@@ -0,0 +1,10 @@
+FAQ
+===
+
+No questions yet.
+
+Issues
+------
+
+Found a bug? Create an issue on GitHub. Submit `Link here <https://github.com/Bram-Hub/NanoNav/issues>`_ with as much information as you can provide
+about the context of the bug.

_sources/index.rst.txt

@@ -0,0 +1,20 @@
+.. NanoNav documentation master file, created by
+   sphinx-quickstart on Mon Apr 15 12:52:38 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to NanoNav's documentation.
+===================================
+
+Check out the :doc:`usage` section to get started.
+
+Contents
+--------
+
+.. toctree::
+
+   usage
+   bluetooth 
+   movement
+   faq
+

_sources/movement.rst.txt

@@ -0,0 +1,12 @@
+Movement
+=========
+Working with NanoNav's motors.
+
+Quick Example
+-------------
+
+.. code-block:: python
+
+    from nanonav import ...
+
+    # TODO

_sources/usage.rst.txt

@@ -0,0 +1,65 @@
+Quick Start
+===========
+
+Installation
+------------
+You will need to download `OpenMV IDE <https://openmv.io/pages/download>`_ to transfer your MicroPython code onto the arduino. See :ref:`Workflow` for more information about this process.
+
+Your Arduino Nano RP2040 can run either C++ or MicroPython, but not both at the same time. So before moving on, it is important that the Arduino is configured for MicroPython mode.
+`Link this guide <https://docs.arduino.cc/tutorials/nano-rp2040-connect/rp2040-openmv-setup/>` from Arduino will walk you through the process of "bootloading" the Nano RP2040 so that 
+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, either download :download:`nanonav.py </../../nanonav.py>` to your project directory
+
+Or copy the code below into a file called nanonav.py
+
+.. raw:: html
+
+   <div style="max-height: 50vh; overflow-y: scroll;">
+
+.. literalinclude:: /../../nanonav.py
+    :language: python
+    :linenos:
+
+.. raw:: html
+
+   </div>
+
+..  _Workflow:
+
+Workflow
+--------
+Here is how you can program your Arduino. You will need a file called `main.py` that contains your MicroPython code - you can create other files 
+and import them as usual, but `main.py` is the one that will be run on the Arduino. For getting started quickly, we recommend downloading this installation check 
+:download:`main.py </../../tests/installation_check/main.py>` to verify that everything is working correctly so far. Alternatively, copy the following into a file called `main.py`:
+
+.. raw:: html
+
+   <div style="max-height: 50vh; overflow-y: scroll;">
+
+.. literalinclude:: /../../tests/installation_check/main.py
+    :language: python
+    :linenos:
+
+.. raw:: html
+
+   </div>
+
+We recommend creating a folder that you will use for your MicroPython code - put both `nanonav.py` and `main.py` in that folder. Open the OpenMV IDE application. Use the File -> Open Files menu to select the `main.py` file that you downloaded.
+Connect your Arduino to your computer using a USB cable. Click the "Connect" button in the bottom left of OpenMV IDE. The arrow below it should turn green when connected. Click that arrow to run
+your code on the Arduino. If all worked well, you should see :red:`TODO`.
+
+.. note::
+   We recommend testing your
+
+..  _MicroPython:
+
+MicroPython
+-----------
+
+In general, MicroPython is very similar to regular Python, but there are some difference we would like to point you to before you begin. MicroPython has its own library of 
+packages, which are different from the PyPi packages you may be used to (if you ever ```pip install``` anything). We provide helper functions for the ways we think you'll need to 
+interact with the Arduino, Bluetooth, and peripherals, and just about anything you can do in Python 3.11 can also be done in MicroPython, but note that you will not have access to the full standard Python library. For instance, you can import `time` since this has been added to
+MicroPython's library, but you cannot import `Queue` or other familiar packages. If ever in doubt about whether MicroPython supports a particular package, simply google "MicroPython [package name]", 
+and you will likely find the information you need.
+You can find the MicroPython documentation `here <https://docs.micropython.org/en/latest/>`_.