Merge remote-tracking branch 'origin/master' into install_with_pip

# Conflicts:
#	docs/guide/robot_sbc/setup_raspberry_pi.md

docs/guide/build_hardware.md

@@ -20,7 +20,13 @@ The latest version of the software installation instructions are maintained in t
 
 ## Choosing a Car
 
-There are 4 fully supported chassis all made under the "Exceed" Brand, all are very similar and should be considered equivalent.  Note, often some of these are out of stock, so go through the links to find one that is in stock.  If they are out of stock on Amazon, you can find the cars at the [Exceed Website](https://www.nitrorcx.com/1rcelca.html).   The HSP-94186 is identical to the Exceed Magnet 1/16 Truck; it can be found on AliExpress but takes about a month to get to the US, there are local options that charge a premium.
+There are two main options for cars.  One is the WL Toys brand and the second is the exceed brand.  
+
+*NOTE: only the WL Toys 144010 and HSP-94186 are readily avilable rignt now* 
+
+The [WL Toys 144010](https://www.banggood.com/custlink/vvKtByVPZn) is probably the easiest car to get right now.  It has a brushless motor, which makes it fast, but takes some getting used to for beginners.  There are brushed motor versions of theis car the 144011 and 144001 but both require the user to replace both the steering servo and ESC.  Only do this if you are familiar with RC or enjoy tinkering.  [Here is a short video](https://www.youtube.com/watch?v=4LKDjoTKlaE) explaining how to assemble the car.  You can find the adapters in [Thingiverse](https://www.thingiverse.com/thing:2566276) or if you would like to buy them you can do so one the [donkey car store](https://store.donkeycar.com/products/donkey-adapter-for-wl-toys-144010?variant=40161156562979)
+
+The alterate car, which often has slighly less availability is the HSP 94186 and the "Exceed" brand cars.  There are 5 supported cars, all are very similar and should be considered equivalent.  Note, often some of these are out of stock, so go through the links to find one that is in stock.  If they are out of stock on Amazon, you can find the cars at the [Exceed Website](https://www.nitrorcx.com/1rcelca.html).   The HSP-94186 is identical to the Exceed Magnet 1/16 Truck; it can be found on AliExpress but takes about a month to get to the US, there are local options that charge a premium.
 
 *  Exceed Magnet [Blue](https://amzn.to/2BkBRka), [Red](https://amzn.to/3qKksIC)
 *  HSP-94186 [1/16 electric Truck](https://www.aliexpress.us/item/2255799890095973.html)
@@ -30,7 +36,7 @@ There are 4 fully supported chassis all made under the "Exceed" Brand, all are v
 
 These cars are electrically identical but have different tires, mounting and other details.  It is worth noting that the Desert Monster, Short Course Truck and Blaze all require adapters which can be easily printed or purchased from the donkey store.  These are the standard build cars because they are mostly plug and play, both have a brushed motor which makes training easier, they handle rough driving surfaces well and are inexpensive.
 
-Here is a [video](https://youtu.be/UucnCmCAGTI) overview of the different cars and how to assemble them.
+Here is a [video](https://youtu.be/UucnCmCAGTI) overview of the different cars (Excluding the WL Toys car) and how to assemble them.
 
 For advanced users there are 2 more cars supported under the "Donkey Pro" name.  These are 1/10 scale cars which means that they are bigger, perform a little better and are slightly more expensive.  They can be found here:
 
@@ -67,7 +73,7 @@ If you are in Asia, the DIYRobocars community in Hong Kong also sells car kits a
 
 | Part Description                                                                    | Link                                                                                  | Approximate Cost |
 |-------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------|------------------|
-| Exceed Magnet, Desert Monster, Blaze, or Short Course Truck                                                                       | See links above                                     | ~$90              |
+| WL Toys 144010, Exceed Magnet, Desert Monster, Blaze, or Short Course Truck                                                                       | See links above                                     | $100-130              |
 | USB Battery with microUSB cable (any battery capable of 2A 5V output is sufficient) | [Anker 10,000 mAh](https://amzn.to/3BOqqND)                                          | $39              |
 | Raspberry Pi 3b+                                                                      | [Pi 3b+](https://amzn.to/3gCUcZL)                                          | $42              |
 | MicroSD Card (many will work, we strongly recommend this one)             | 64GB [https://amzn.to/2XP7UAa](https://www.amazon.com/SanDisk-128GB-Extreme-microSD-Adapter/dp/B07FCMKK5X?tag=donkeycar-20)                            | $11.99           |

docs/guide/computer_vision/computer_vision.md

@@ -17,6 +17,20 @@ What if your track does not have a center line; what if it just has a left and r
 
 >> IMPORTANT: The computer vision template requires that opencv is installed.  Opencv is pre-installed on the Jetson Nano, but it must be explicitly installed on the Raspberry Pi. See Raspberry Pi installation [Step 9](/guide/robot_sbc/setup_raspberry_pi/#step-9-optional-install-opencv-dependencies) and [Step 11](/guide/robot_sbc/setup_raspberry_pi/#step-11-install-donkeycar-python-code).  
 
+## Create a computer vision Application
+
+You can create a computer vision application similarly to the how we create a deep learning application; we just tell it to use the **cv_control** template instead of the default template.  First, make sure your donkeycar python environment is activated, then use the **createcar** command to create your application folder.
+
+```bash
+donkey createcar --template=cv_control --path=~/mycar
+```
+
+When updating to a new version of donkeycar, you will want to refresh your application folder.  You can do this with the same command, but add `--overwrite` so that it does not erase your **myconfig.py** file.
+
+```bash
+donkey createcar --template=cv_control --path=~/mycar --overwrite
+```
+
 ## The Line Follower
 
 The built-in algorithm can follow a line using the camera.  By default it is tuned for a yellow line, but the color that it tracks can be configured.  Many other aspects of the algorithm can be tuned.  Below is as description of the algorithm and how it uses the configuraton values.  The values themselves are listed and described afterwards.

docs/guide/create_application.md

@@ -163,31 +163,11 @@ If you plan to use a joystick, take a side track over to [here](/parts/controlle
 
 ## Camera Setup
 
-If you are using the default deep learning template then you will need a camera.  By default __myconfig.py__ assumes a RaspberryPi camera.  You can change this by editing the __myconfig.py__ file in your `~/mycar` folder.  
+If you are using the default deep learning template or the computer vision template then you will need a camera.  By default __myconfig.py__ assumes a RaspberryPi camera.  You can change this by editing the `CAMERA_TYPE` value in the __myconfig.py__ file in your `~/mycar` folder.  
 
 If you are using the gps path follow template then you do not need, and may not want, a camera.  In this case you can change the camera type to mock; `CAMERA_TYPE = "MOCK"`.
 
-**Raspberry Pi**:
-
-If you are on a raspberry pi and using the recommended pi camera ("PICAM"), then no changes are needed to your __myconfg.py__.
-
-**Jetson Nano**:
-
-When using a Sony IMX219 based camera, and you are using the default car template, then you will want edit your __myconfg.py__ to have:
-`CAMERA_TYPE = "CSIC"`.
-For flipping the image vertically set `CSIC_CAM_GSTREAMER_FLIP_PARM = 6` - this is helpful if you have to mount the camera in a rotated position.
-
-`CAMERA_TYPE = CVCAM` is a camera type that has worked for USB cameras when OpenCV is setup. This requires additional setup for [OpenCV for Nano](/guide/robot_sbc/setup_jetson_nano/#step-4-install-opencv) or [OpenCV for Raspberry Pi](https://www.learnopencv.com/install-opencv-4-on-raspberry-pi/).
-
-**USB Cameras**
-
-You can also use a USB camera if you prefer.  If you have installed the optional OpenCV dependencies then you can use OpenCV to connect to the camera by editing the camera type to `CAMERA_TYPE = "CVCAM"`. If you have installed the optional pygame library then you can connect to the camera by editing the camera type to `CAMERA_TYPE = "WEBCAM"`.  See the required additional setup for [pygame](https://www.pygame.org/wiki/GettingStarted).
-
-We are adding other cameras over time, so read the camera section in __myconfig.py__ to see what options are available.
-
-## Troubleshooting
-
-If you are having troubles with your camera, check out our [Discord hardware channel](https://discord.gg/zcyzK69S) for more help.
+See [Cameras](/parts/cameras) for details on the various cameras and configuration.
 
 ## Upgrade Donkey Car Software
 

docs/guide/robot_sbc/setup_jetson_nano.md

@@ -149,9 +149,8 @@ cd ~/projects
 git clone https://github.com/autorope/donkeycar
 cd donkeycar
 git fetch --all --tags -f
-latestTag=$(git describe --tags `git rev-list --tags --max-count=1`)
-git checkout $latestTag
-pip install -e .[nano45]
+git checkout 4.5.0
+pip install -e .[nano]
 
 ```
 

docs/guide/robot_sbc/setup_raspberry_pi.md

@@ -78,9 +78,10 @@ Doing it in the shell through:
 sudo raspi-config
 ```
 
-* enable `Interfacing Options` - `I2C`
-* select `Advanced Options` - `Expand Filesystem` so you can use your whole
+* Enable `Interfacing Options` - `I2C`
+* Select `Advanced Options` - `Expand Filesystem` so you can use your whole
   sd-card storage
+* Do *not* enable the legacy camera (it's disabled by default, so don't change anything)
 
 Choose `<Finish>` and hit enter.
 
@@ -99,7 +100,7 @@ and apply the settings there.
 
 To create a virtual environmnet run the following from your home directory:
 ```bash
-python3 -m virtualenv -p python3 env --system-site-packages
+python3 -m venv env --system-site-packages
 echo "source ~/env/bin/activate" >> ~/.bashrc
 source ~/.bashrc
 ```

docs/guide/train_autopilot.md

@@ -1,4 +1,4 @@
-# Train an Autopilot
+# Create an Autopilot
 
 Donkey supports three kinds of autopilots; a deep-learning autopilot, a path follow autopilot and a computer vision autopilot.  
 
@@ -22,7 +22,7 @@ Because the deep learning autopilot depends on a camera image, lighting conditio
 [Train a deep learning autopilot](./deep_learning/train_autopilot.md)
 
 
-## Path Follow Autopilot
+## Path Follow Autopilot (using GPS, wheel encoders, etc)
 The path follow template is an alternative to the deep learning template.  Outside we have access to GPS; the path follow template allows you to record a path using a GPS receiver and then configure an autopilot that can follow that path.  The overall process looks like this;
 
 - A **human drives** the car to **gather data**. The data is aquired from a GPS receiver and represents and (x,y) position in meters.  Each (x,y) position is called a waypoint.  The user will drive the course once to collect waypoints.  The complete set of waypoints is called a path.

docs/index.md

@@ -25,7 +25,7 @@ Donkey is the standard car that most people build first. The parts cost about $2
 3. [Create Donkey App.](guide/create_application)
 4. [Calibrate your car.](guide/calibrate)
 5. [Start driving.](guide/get_driving)
-6. [Train an autopilot.](guide/train_autopilot)
+6. [Create an autopilot.](guide/train_autopilot)
 7. [Experiment with simulator.](guide/deep_learning/simulator)
 
 ---------------

docs/parts/cameras.md

@@ -0,0 +1,55 @@
+# Cameras
+
+Donkeycar supports a large number of cameras via the `CAMERA_TYPE` configuration.  For most applications a wide field of vision is important, so your camera should use a 120 degree wide angle lens or better.  A 160 degree wide angle lense is recommended.
+
+## Camera Setup
+
+If you are using the default deep learning template or the computer vision template then you will need a camera.  By default __myconfig.py__ assumes a RaspberryPi camera.  You can change this by editing the `CAMERA_TYPE` value in the __myconfig.py__ file in your `~/mycar` folder.  
+
+If you are using the gps path follow template then you do not need, and may not want, a camera.  In this case you can change the camera type to mock; `CAMERA_TYPE = "MOCK"`.
+
+### Raspberry Pi:
+
+If you are on a raspberry pi and using the recommended pi camera ("PICAM"), then no changes are needed to your __myconfg.py__.
+
+This works with all Raspberry Pi cameras, including the original Raspberry Pi Camera Module based on the 5 megapixel OV5647 chipset and the Raspberry Pi Camera Module v2 based on the Sony IMX219 chip.  These cameras are easily obtainable and are offered in generic (clone) versions by many vendors.
+
+### Jetson Nano:
+
+The Jetson does not have a driver for the original 5 megapixels OV5647 based Raspberry Pi Camera, but it does have a driver for the v2 camera based on the IMX219 chip.  Indeed the recommended camera is based on the IMX219 chip.
+
+The default setting `CAMERA_TYPE = "PICAM"` does **not** work on the Jetson, even if you are using an 8mp RaspberryPi camera or a camera based on a Sony IMX219 based camera  In either of these cases you will want edit your __myconfg.py__ to have: `CAMERA_TYPE = "CSIC"`.
+
+For flipping the image vertically set `CSIC_CAM_GSTREAMER_FLIP_PARM = 6` - this is helpful if you have to mount the camera in a rotated position.
+
+### USB Cameras
+
+`CAMERA_TYPE = CVCAM` is a camera type that has worked for USB cameras when OpenCV is setup. This requires additional setup for [OpenCV for Nano](/guide/robot_sbc/setup_jetson_nano/#step-4-install-opencv) or [OpenCV for Raspberry Pi](https://www.learnopencv.com/install-opencv-4-on-raspberry-pi/).  
+
+If you have installed the optional pygame library then you can connect to the camera by editing the camera type to `CAMERA_TYPE = "WEBCAM"`.  See the required additional setup for [pygame](https://www.pygame.org/wiki/GettingStarted).
+
+If you have more than one camera then you made need to the `CAMERA_INDEX` configuration value.  By default it is zero.
+
+>> NOTE: `CAMERA_TYPE = CVCAM` depends upon a version of OpenCV that has GStreamer support compiled in.  This is the default on the Jetson computers and is supported in the recommended version of OpenCV for that Raspberry Pi.
+
+### Intel Realsense D435
+
+The Intel Realsense cameras are RGBD cameras; they provide RGB images and Depth.  You can use them as an RGB camera to provide images for the Deep Learning template or the Computer Vision template by setting `CAMERA_TYPE = "D435"` in your __myconfig.py__ settings.  You will also want to review the settings that are specific to the Intel Realsense cameras;
+
+```
+# Intel Realsense D435 and D435i depth sensing camera
+REALSENSE_D435_RGB = True       # True to capture RGB image
+REALSENSE_D435_DEPTH = True     # True to capture depth as image array
+REALSENSE_D435_IMU = False      # True to capture IMU data (D435i only)
+REALSENSE_D435_ID = None        # serial number of camera or None if you only have one camera (it will autodetect)
+```
+
+If you are not using depth then you will want to set `REALSENSE_D435_DEPTH = False` so it does not save the depth data.
+
+## Troubleshooting
+
+If the colors look wrong it may be that the camera is outputting BGR colors rather than RGB.  You can set `BGR2RGB = True` to convert from BGR to RGB.
+
+We are adding other cameras over time, so read the camera section in __myconfig.py__ to see what options are available.
+
+If you are having troubles with your camera, check out our [Discord hardware channel](https://discord.gg/zcyzK69S) for more help.

mkdocs.yml

@@ -23,14 +23,15 @@ nav:
     - Create Donkeycar App.: guide/create_application.md
     - Calibrate steering and throttle.: guide/calibrate.md
     - Get driving.: guide/get_driving.md
-    - Train an autopilot.: guide/train_autopilot.md
+    - Create an autopilot.: guide/train_autopilot.md
     - Donkey UI.: utility/ui.md
     - Donkey Simulator.: guide/deep_learning/simulator.md
     - Virtual Race League.: guide/deep_learning/virtual_race_league.md
     - Mobile app: guide/deep_learning/mobile_app.md
   - Parts:
     - About: parts/about.md
     - Actuators: parts/actuators.md
+    - Cameras: parts/cameras.md
     - Controllers: parts/controllers.md
     - Odometry/encoders: parts/odometry.md
     - RC: parts/rc.md