Skip to content

Commit

Permalink
Add BLE screenshots, css roles, and new theme
Browse files Browse the repository at this point in the history
  • Loading branch information
ErikUmble committed Apr 29, 2024
1 parent 364444d commit 7dc2e0e
Show file tree
Hide file tree
Showing 10 changed files with 152 additions and 4 deletions.
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,2 +1,3 @@
# NanoBot
Educational micropython robotics kit
See documentation and start guides [here](https://bram-hub.github.io/NanoNav/)
Binary file added docs/source/__pycache__/nanonav.cpython-312.pyc
Binary file not shown.
56 changes: 56 additions & 0 deletions docs/source/_static/css/s4defs-roles.css
Original file line number Diff line number Diff line change
@@ -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;
}
33 changes: 32 additions & 1 deletion docs/source/bluetooth.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://docs.micropython.org/en/latest/library/bluetooth.html>`_ for advanced uses).
14 changes: 12 additions & 2 deletions docs/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand All @@ -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',
]
Expand All @@ -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:: <s5defs.txt>
"""

def setup(app):
app.add_css_file('css/s4defs-roles.css')
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/source/images/lightblue_connected_view.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/source/images/lightblue_devices_view.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
45 changes: 45 additions & 0 deletions docs/source/nanonav.py
Original file line number Diff line number Diff line change
@@ -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
7 changes: 6 additions & 1 deletion docs/source/usage.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ Quick Start

Installation
------------

You will need to download `Link OpenMV <https://openmv.io/pages/download>`_ 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 </../../nanonav.py>` to your project directory

Or copy the code below into a file called nanonav.py
Expand All @@ -20,3 +20,8 @@ Or copy the code below into a file called nanonav.py

</div>

.. _Workflow:

Workflow
--------

0 comments on commit 7dc2e0e

Please sign in to comment.