diff --git a/README.md b/README.md index 6a8b0de..a78e006 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,3 @@ # NanoBot Educational micropython robotics kit +See documentation and start guides [here](https://bram-hub.github.io/NanoNav/) diff --git a/docs/source/__pycache__/nanonav.cpython-312.pyc b/docs/source/__pycache__/nanonav.cpython-312.pyc new file mode 100644 index 0000000..ce01bf1 Binary files /dev/null and b/docs/source/__pycache__/nanonav.cpython-312.pyc differ diff --git a/docs/source/_static/css/s4defs-roles.css b/docs/source/_static/css/s4defs-roles.css new file mode 100644 index 0000000..b77bbaa --- /dev/null +++ b/docs/source/_static/css/s4defs-roles.css @@ -0,0 +1,56 @@ +/* Colors and Sizes for sphinx documentation +use like :red `text in red` or :large `large text` +see https://stackoverflow.com/questions/3702865/sphinx-restructuredtext-set-color-for-a-single-word for more info +*/ +.black { + color: black; +} + +.red { + color: red; +} + +.green { + color: green; +} + +.blue { + color: blue; +} + +.yellow { + color: yellow; +} + +.orange { + color: orange; +} + +.purple { + color: purple; +} + +.grey { + color: grey; +} + +/* Sizes */ +.small { + font-size: small; +} + +.medium { + font-size: medium; +} + +.large { + font-size: large; +} + +.x-large { + font-size: x-large; +} + +.xx-large { + font-size: xx-large; +} \ No newline at end of file diff --git a/docs/source/bluetooth.rst b/docs/source/bluetooth.rst index adc364e..561cb74 100644 --- a/docs/source/bluetooth.rst +++ b/docs/source/bluetooth.rst @@ -17,14 +17,45 @@ Quick Example 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. -TODO: Add screenshots and instructions for connecting to the NanoNav using LightBlue. +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 `Link here `_ for advanced uses). \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index cdc8ce9..1abf94c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -10,7 +10,7 @@ import sys # Add the project root to the path to allow autofunction for nanonav.py -sys.path.insert(0, os.path.abspath('../../')) +sys.path.insert(0, os.path.abspath('./')) project = 'NanoNav' copyright = '2024, Erik Umble, Joel McCandless, & Chris Kurbiel' @@ -20,6 +20,7 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration extensions = [ + 'sphinx_rtd_theme', 'sphinx.ext.autodoc', 'sphinx_copybutton', ] @@ -34,5 +35,14 @@ # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = 'alabaster' +html_theme = 'sphinx_rtd_theme' html_static_path = ['_static'] + +# below is used for css roles (to set a phrase with in color, for instance) +rst_prolog = """ +.. include:: + +""" + +def setup(app): + app.add_css_file('css/s4defs-roles.css') diff --git a/docs/source/images/lightblue_characteristic_view.png b/docs/source/images/lightblue_characteristic_view.png new file mode 100755 index 0000000..160bdf8 Binary files /dev/null and b/docs/source/images/lightblue_characteristic_view.png differ diff --git a/docs/source/images/lightblue_connected_view.png b/docs/source/images/lightblue_connected_view.png new file mode 100755 index 0000000..0f3a37a Binary files /dev/null and b/docs/source/images/lightblue_connected_view.png differ diff --git a/docs/source/images/lightblue_devices_view.png b/docs/source/images/lightblue_devices_view.png new file mode 100755 index 0000000..c839511 Binary files /dev/null and b/docs/source/images/lightblue_devices_view.png differ diff --git a/docs/source/nanonav.py b/docs/source/nanonav.py new file mode 100644 index 0000000..54ce641 --- /dev/null +++ b/docs/source/nanonav.py @@ -0,0 +1,45 @@ + +""" +Skeleton file for documentation docstrings +""" + +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 + + + +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"): + pass + + 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. + + """ + pass + + 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'. + """ + pass \ No newline at end of file diff --git a/docs/source/usage.rst b/docs/source/usage.rst index f371617..a0f68dc 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -3,7 +3,7 @@ Quick Start Installation ------------ - +You will need to download `Link OpenMV `_ to transfer your micropython code onto the arduino. See `:ref Workflow` for more information about this process. To use the NanoNav supplementary code, either download :download:`nanonav.py ` to your project directory Or copy the code below into a file called nanonav.py @@ -20,3 +20,8 @@ Or copy the code below into a file called nanonav.py +.. _Workflow: + +Workflow +-------- +