From cbabaae92b0c91853127a2f1d7b1b2f57b890870 Mon Sep 17 00:00:00 2001 From: Erik Umble Date: Tue, 30 Apr 2024 21:30:49 -0400 Subject: [PATCH] Add installation guide and other improvements --- README.md | 2 +- docs/source/bluetooth.rst | 2 +- docs/source/faq.rst | 10 ++++++++ docs/source/index.rst | 1 + docs/source/usage.rst | 40 +++++++++++++++++++++++++++++++- run-dev | 4 ++++ tests/installation_check/main.py | 4 ++++ 7 files changed, 60 insertions(+), 3 deletions(-) create mode 100644 docs/source/faq.rst create mode 100755 run-dev create mode 100644 tests/installation_check/main.py diff --git a/README.md b/README.md index a78e006..6ac6cc1 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,3 @@ # NanoBot -Educational micropython robotics kit +Educational MicroPython robotics kit See documentation and start guides [here](https://bram-hub.github.io/NanoNav/) diff --git a/docs/source/bluetooth.rst b/docs/source/bluetooth.rst index 561cb74..cb8c6ca 100644 --- a/docs/source/bluetooth.rst +++ b/docs/source/bluetooth.rst @@ -58,4 +58,4 @@ can look at (read) whatever is on it whenever you like, and can also change (wri 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 +but if interested, see `here `_ for advanced uses). \ No newline at end of file diff --git a/docs/source/faq.rst b/docs/source/faq.rst new file mode 100644 index 0000000..65ce061 --- /dev/null +++ b/docs/source/faq.rst @@ -0,0 +1,10 @@ +FAQ +=== + +No questions yet. + +Issues +------ + +Found a bug? Create an issue on GitHub. Submit `Link here `_ with as much information as you can provide +about the context of the bug. \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 0393474..4a3ec66 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -16,4 +16,5 @@ Contents usage bluetooth movement + faq diff --git a/docs/source/usage.rst b/docs/source/usage.rst index a0f68dc..4979f72 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -3,7 +3,12 @@ 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. +You will need to download `OpenMV IDE `_ 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 ` 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 ` to your project directory Or copy the code below into a file called nanonav.py @@ -24,4 +29,37 @@ Or copy the code below into a file called nanonav.py 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 ` to verify that everything is working correctly so far. Alternatively, copy the following into a file called `main.py`: + +.. raw:: html + +
+ +.. literalinclude:: /../../tests/installation_check/main.py + :language: python + :linenos: + +.. raw:: html + +
+ +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 `_. \ No newline at end of file diff --git a/run-dev b/run-dev new file mode 100755 index 0000000..4dca8e3 --- /dev/null +++ b/run-dev @@ -0,0 +1,4 @@ +#! /bin/sh +pip install -r requirements.txt +sphinx-build -M html docs/source docs/_build +open docs/_build/html/index.html \ No newline at end of file diff --git a/tests/installation_check/main.py b/tests/installation_check/main.py new file mode 100644 index 0000000..ffda45e --- /dev/null +++ b/tests/installation_check/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 \ No newline at end of file