deploy: 3d011d0

.buildinfo

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

_downloads/051422046cba6049b278a5cebcee1f0c/blink_LED.py

@@ -0,0 +1,9 @@
+from machine import Pin
+import time
+
+LED = Pin(6, Pin.OUT)
+
+while True:
+    LED.off()
+    time.sleep(2)
+    LED.on()

_sources/bluetooth.rst.txt

@@ -0,0 +1,113 @@
+.. _Bluetooth:
+
+Bluetooth
+=========
+Using Bluetooth Low Energy (BLE) to communicate with the NanoNav.
+
+Quick Example
+-------------
+
+.. code-block:: python
+
+    from nanonav import BLE
+    import time
+
+    # Create a Bluetooth object
+    ble = BLE(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)
+
+Usage
+-----
+
+.. autoclass:: nanonav.BLE     
+    :members: 
+
+.. note::
+  Just as a heads up, we've noticed that occasionally the value stored on the BLE characteristic gets corrupted. Wherever you call the `read` method, it's a good idea to verify that 
+  the value is within the range you expect (and not ``None``), and if not, consider requesting the value again.   
+
+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 Arduino's MAC address instead, which means identifying the device once in LightBlue and keeping track of its MAC address for future connections.
+
+.. 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, 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).
+
+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>`_.

_sources/faq.rst.txt

@@ -0,0 +1,64 @@
+FAQ
+===
+
+No questions yet.
+
+Troubleshooting
+===============
+
+Why are the wheels of my robot spinning at full speed after I stop my program?
+-------------------------------------------------------------------------------
+
+This behavior is expected because of `how Pulse Width Modulation (PWM) works <https://learn.sparkfun.com/tutorials/pulse-width-modulation/all>`_. If you stop your program with your motors on at any speed, there is a chance that the program will terminate with your motor spinning HIGH. The Arduino will continue its last instruction, making the motor spin at full speed until the next time you run code. To avoid this, call `robot.stop()`` before the program ends, or flip the "Driver Enable" switch off to disable the motor hardware (remember to turn it back on when you want to spin the motors again!).
+
+
+Arduino not connecting to OpenMV
+--------------------------------
+
+If your Arduino is not connecting to OpenMV, either because OpenMV is loading forever, or because the cursor is flickering between loading and a pointer, you should reset your board. Do this by double tapping the button on top of the Arduino. This will reset the board.
+
+.. image:: images/rp2040_white_button.jpeg
+   :height: 80
+   :alt: RP2040 white button
+
+Wait for OpenMV to update. When OpenMV updates, it should offer to load the latest firmware. Agree and load the firmware, and hopefully the Arduino will connect.
+
+If this doesn't work, it's probably because your code has a frequently repeating while loop which keeps the Arduino occupied. Keep trying to reset the board by double pressing the top button, or open Finder or FileExplorer, open the board's external drive, and replace its main.py (your code) with a basic main.py such as :download:`blink_LED.py <../../tests/installation_check/blink_LED.py>`. This should enable the Arduino to connect.
+
+If you still cannot get the Arduino to connect, it could be a problem on your computer. Try changing the port you're using to connect to the Arduino.
+
+IR sensor has both LEDs lit regardless of sensor state
+------------------------------------------------------
+
+We've noticed a problem with some of the boards where the right IR sensor has both LEDs on, regardless of whether the sensor is in front of a white or black surface:
+
+.. image:: images/ir_2_lights_on.jpeg
+    :height: 80
+    :alt: IR sensor with 2 lights on
+
+If you're noticing this, add
+
+.. code-block:: python
+
+    from machine import Pin
+
+to your import statements and add the line 
+
+.. code-block:: python
+
+    Pin(28, Pin.OUT).on()
+
+after your imports and before `robot = NanoBot()`.
+
+Strange problems with code which was just working
+-------------------------------------------------
+
+When you run in laptop mode from OpenMV, sometimes the code gives you errors the first 2 times you try to run. We're not sure why this happens, but these errors always go away after the third attempt.
+
+If when running in solo mode, the Arduino behaves strangely when running code which you know works, it could be because you are out of storage. This will not happen until your code files are at least 30 KB in total!!! If your code files are not 30 KB or larger in total, what you're experiencing is an ordinary bug. If you suspect that you make be out of storage, try to shrink your code by removing comments and making functions more efficient. Every character counts, because it's the storage of your .py files which is running out. Try removing excess newlines or whitespace.
+
+Issues
+------
+
+Found a bug? Create an issue on GitHub. Submit `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,21 @@
+.. 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
+   sensors
+   faq
+

_sources/movement.rst.txt

@@ -0,0 +1,51 @@
+.. _Movement:
+
+Movement
+=========
+Working with NanoNav's motors.
+
+Introduction
+------------
+
+To complete the Wumpus challenge, NanoBot will have to navigate the board by moving and turning. It does this by sending power to the motors, which then turn the wheels. Speed of the motors is controlled by the amount of power you send. However, because most microcontrollers can only send LOW or HIGH voltage (0V or 3.3V in the Arduino's case), power is controlled by a process called Pulse Width Modulation (PWM), which is explained in more detail `here <https://learn.sparkfun.com/tutorials/pulse-width-modulation/all>`_ if you're interested.
+
+Sensors called encoders are used to track the rotation of the motors accurately. Encoders track rotation in ticks. You can read more `here <https://howtomechatronics.com/tutorials/arduino/rotary-encoder-works-use-arduino/>`_ if you're interested, but all you have to know is that a positive change in ticks corresponds to a forward rotation of the motor, and a negative change to a backward rotation of the motor.
+
+You don't have to use encoders in your solution, though they do provide greater accuracy.
+
+
+Quick Example
+-------------
+
+.. code-block:: python
+
+    from nanonav import NanoBot
+    import time
+
+    # Create a NanoBot object
+    robot = NanoBot()
+
+    # Move forward for 2 seconds
+    robot.m1_forward(30)
+    robot.m2_forward(30)
+    time.sleep(2)
+
+    # Stop
+    robot.stop()
+    time.sleep(2)
+
+    # Move backward for 2 seconds
+    robot.m1_backward(30)
+    robot.m2_backward(30)
+    time.sleep(2)
+
+    # Stop
+    robot.stop()
+    
+Usage
+-----
+
+.. autoclass:: nanonav.NanoBot
+    :members:
+    :exclude-members: ir_left, ir_right
+

_sources/sensors.rst.txt

@@ -0,0 +1,44 @@
+.. _Sensors:
+
+Sensors
+=======
+Using the IR sensors on NanoNav.
+
+Introduction
+------------
+To best interact with its environment, your NanoNav kit comes with infrared sensors that can be used for detecting how reflective the surface under it is.
+
+Quick Example
+-------------
+
+.. code-block:: python
+
+    from nanonav import NanoBot
+    import time
+
+    # Create a NanoBot object
+    robot = NanoBot()
+
+    while True:
+        # Repeatedly print the IR sensor values
+        print(f'left: {robot.ir_left()}    right: {robot.ir_right()}')
+        time.sleep(0.5)
+
+Note that this code snippet uses `print` which means it will only
+work while connected to a computer.
+
+Calibration
+-----------
+Initially, and if you ever notice the IR sensors not detecting the white line correctly,
+you may need to calibrate the sensors. The below video (for a very similar IR sensor model)
+shows how to do this.
+
+.. raw:: html
+
+    <iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/fHBPYWRgEH8?si=n_tW8sT_w2ZMGEE9" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+
+Usage
+-----
+
+.. automethod:: nanonav.NanoBot.ir_left
+.. automethod:: nanonav.NanoBot.ir_right