Merge remote-tracking branch 'refs/remotes/origin/main'

docs/source/ble_advertising.py

@@ -0,0 +1,102 @@
+# Helpers for generating BLE advertising payloads.
+
+# A more fully-featured (and easier to use) version of this is implemented in
+# aioble. This code is provided just as a basic example. See
+# https://github.com/micropython/micropython-lib/tree/master/micropython/bluetooth/aioble
+
+from micropython import const
+import struct
+import bluetooth
+
+# Advertising payloads are repeated packets of the following form:
+#   1 byte data length (N + 1)
+#   1 byte type (see constants below)
+#   N bytes type-specific data
+
+_ADV_TYPE_FLAGS = const(0x01)
+_ADV_TYPE_NAME = const(0x09)
+_ADV_TYPE_UUID16_COMPLETE = const(0x3)
+_ADV_TYPE_UUID32_COMPLETE = const(0x5)
+_ADV_TYPE_UUID128_COMPLETE = const(0x7)
+_ADV_TYPE_UUID16_MORE = const(0x2)
+_ADV_TYPE_UUID32_MORE = const(0x4)
+_ADV_TYPE_UUID128_MORE = const(0x6)
+_ADV_TYPE_APPEARANCE = const(0x19)
+
+_ADV_MAX_PAYLOAD = const(31)
+
+
+# Generate a payload to be passed to gap_advertise(adv_data=...).
+def advertising_payload(limited_disc=False, br_edr=False, name=None, services=None, appearance=0):
+    payload = bytearray()
+
+    def _append(adv_type, value):
+        nonlocal payload
+        payload += struct.pack("BB", len(value) + 1, adv_type) + value
+
+    _append(
+        _ADV_TYPE_FLAGS,
+        struct.pack("B", (0x01 if limited_disc else 0x02) + (0x18 if br_edr else 0x04)),
+    )
+
+    if name:
+        _append(_ADV_TYPE_NAME, name)
+
+    if services:
+        for uuid in services:
+            b = bytes(uuid)
+            if len(b) == 2:
+                _append(_ADV_TYPE_UUID16_COMPLETE, b)
+            elif len(b) == 4:
+                _append(_ADV_TYPE_UUID32_COMPLETE, b)
+            elif len(b) == 16:
+                _append(_ADV_TYPE_UUID128_COMPLETE, b)
+
+    # See org.bluetooth.characteristic.gap.appearance.xml
+    if appearance:
+        _append(_ADV_TYPE_APPEARANCE, struct.pack("<h", appearance))
+
+    if len(payload) > _ADV_MAX_PAYLOAD:
+        raise ValueError("advertising payload too large")
+
+    return payload
+
+
+def decode_field(payload, adv_type):
+    i = 0
+    result = []
+    while i + 1 < len(payload):
+        if payload[i + 1] == adv_type:
+            result.append(payload[i + 2 : i + payload[i] + 1])
+        i += 1 + payload[i]
+    return result
+
+
+def decode_name(payload):
+    n = decode_field(payload, _ADV_TYPE_NAME)
+    return str(n[0], "utf-8") if n else ""
+
+
+def decode_services(payload):
+    services = []
+    for u in decode_field(payload, _ADV_TYPE_UUID16_COMPLETE):
+        services.append(bluetooth.UUID(struct.unpack("<h", u)[0]))
+    for u in decode_field(payload, _ADV_TYPE_UUID32_COMPLETE):
+        services.append(bluetooth.UUID(struct.unpack("<d", u)[0]))
+    for u in decode_field(payload, _ADV_TYPE_UUID128_COMPLETE):
+        services.append(bluetooth.UUID(u))
+    return services
+
+
+def demo():
+    payload = advertising_payload(
+        name="micropython",
+        services=[bluetooth.UUID(0x181A), bluetooth.UUID("6E400001-B5A3-F393-E0A9-E50E24DCCA9E")],
+    )
+    print(payload)
+    print(decode_name(payload))
+    print(decode_services(payload))
+
+
+if __name__ == "__main__":
+    demo()

docs/source/usage.rst

@@ -40,26 +40,15 @@ 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.
 
+You will also need to install LightBlue on your mobile device for Bluetooth communication. You can download it from the App Store or Google Play Store.
+
 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.
 `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>
+To use the NanoNav supplementary code, download :download:`nanonav.py </../../nanonav.py>` and :download:`ble_advertising.py </../../ble_advertising.py>` to your project directory. This is highly recommended!
 
+This `ble_advertising` 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!
 
 ..  _Workflow:
 
@@ -87,13 +76,27 @@ We recommend creating a folder that you will use for your MicroPython code - put
 Connecting to the Arduino over USB
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Connect your Arduino to your computer using a USB cable. In the bottom left of the OpenMV IDE, you should see this:
+Connect your Arduino to your computer using a USB cable. Double click the small white button on the top of the Arduino to put the Arduino in bootloader mode.
+
+.. 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
    :height: 100
    :alt: OpenMV unconnected symbols
 
-If you don't see this, it means that OpenMV doesn't recognize the board. You can wait for a little and try messing with your USB conection (different cable, different port, unplug/replug, etc.). Once you see this, click the "Connect" button (the USB connection, or upper button of the two in the image).
+If you don't see this, it means that OpenMV doesn't recognize the board. You can wait for a little and try messing with your USB conection (different cable, different port, unplug/replug, etc.).
+
+Once you see this, click the "Connect" button (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.
+
+.. image:: images/bootload.png
+   :height: 80
+   :alt: Bootloading
 
 The arrow below it should turn green when connected.
 
@@ -106,6 +109,8 @@ After you can see the green arrow, you should be able to see the Arduino as an e
 Running your code on the Arduino
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+You have two options for running your code on the Arduino: laptop mode and solo mode.
+
 **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.
@@ -114,6 +119,22 @@ We recognize that OpenMV IDE is not a very nice editor to write code in, so feel
 
 ..  _MicroPython:
 
+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.
+
+This tests all of the features of the kit: motors, encoders, IR sensors and Bluetooth.
+
+When you run it, you should see the wheels spin forwards first, then backwards after a few seconds. On the Serial Terminal in the OpenMV IDE, you should see the encoder values printed out.
+
+Using your phone, look on LightBlue for a peripheral named something related to Arduino (names may vary). Some examples are: "NanoNav", "Arduino", "MPY Nimble", etc. See `Connecting from Mobile <https://bram-hub.github.io/NanoNav/bluetooth.html#connecting-from-mobile>`_ for more detailed information. Connect to the peripheral and write 0 to the Read/Write characteristic. You should see 0 printed on the Serial Terminal.
+
+After writing over Bluetooth, the IR sensor values should be printed out in the Serial Terminal.
+
+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
 -----------