diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index c9b31e5..db24ac2 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -6,10 +6,10 @@ This repository holds the Python bindings for ev3dev_, ev3dev-lang-python.
Opening issues
--------------
-Please make sure you have read the FAQ_. If you are still encountering your
-problem, open an issue, and ensure that the questions asked by the issue
-template are completely answered with correct info. This will make it much
-easier for us to help you!
+Please make sure you have read the FAQ_ and `Common Issues`_. If you are still
+encountering your problem, open an issue, and ensure that the questions asked
+by the issue template are completely answered with correct info. This will make
+it much easier for us to help you!
Submitting Pull Requests
------------------------
@@ -105,3 +105,4 @@ following commands:
.. _ev3dev: http://ev3dev.org
.. _FAQ: https://python-ev3dev.readthedocs.io/en/ev3dev-stretch/faq.html
+.. _Common Issues: http://python-ev3dev.readthedocs.io/en/ev3dev-stretch/common-issues.html
diff --git a/README.rst b/README.rst
index 9403883..c29b375 100644
--- a/README.rst
+++ b/README.rst
@@ -70,7 +70,7 @@ If you encounter an error such as
``/usr/bin/env: 'python3\r': No such file or directory``,
you must switch your editor's "line endings" setting for the file from
"CRLF" to just "LF". This is usually in the status bar at the bottom.
-For help, see `our FAQ page`_.
+For help, see our `Common Issues page`_.
Important: Make your script executable (non-Visual Studio Code only)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -202,7 +202,8 @@ Frequently-Asked Questions
--------------------------
Experiencing an odd error or unsure of how to do something that seems
-simple? Check our our `FAQ`_ to see if there's an existing answer.
+simple? Check our our `FAQ`_ and `Common Issues page`_ to see if there's an
+existing answer.
.. _ev3dev: http://ev3dev.org
@@ -218,6 +219,7 @@ simple? Check our our `FAQ`_ to see if there's an existing answer.
.. _ev3python.com: http://ev3python.com/
.. _FAQ: http://python-ev3dev.readthedocs.io/en/ev3dev-stretch/faq.html
.. _our FAQ page: FAQ_
+.. _Common Issues page: http://python-ev3dev.readthedocs.io/en/ev3dev-stretch/common-issues.html
.. _our Issues tracker: https://github.com/ev3dev/ev3dev-lang-python/issues
.. _EXPLOR3R: demo-robot_
.. _demo-robot: http://robotsquare.com/2015/10/06/explor3r-building-instructions/
diff --git a/docs/_static/vscode-crlf.png b/docs/_static/vscode-crlf.png
new file mode 100644
index 0000000..84d6bc6
Binary files /dev/null and b/docs/_static/vscode-crlf.png differ
diff --git a/docs/_static/vscode-debug.png b/docs/_static/vscode-debug.png
new file mode 100644
index 0000000..7caf1b8
Binary files /dev/null and b/docs/_static/vscode-debug.png differ
diff --git a/docs/common-issues.rst b/docs/common-issues.rst
new file mode 100644
index 0000000..156cb36
--- /dev/null
+++ b/docs/common-issues.rst
@@ -0,0 +1,55 @@
+Common Issues with ev3dev-lang-python
+=====================================
+
+``ImportError: No module named ev3dev2``
+----------------------------------------
+
+This likely means you are running the script on your computer rather than on the
+EV3 (or other ev3dev platform). You can run it using our
+`Visual Studio Code extension`_ by connecting to a device from the "Explore" tab
+on the left and then going to the debug tab, selecting "Run and Debug", and
+choosing the ev3dev option.
+
+.. image:: _static/vscode-debug.png
+
+``/usr/bin/env: 'python3\r': No such file or directory``
+--------------------------------------------------------
+
+This means your file includes Windows-style line endings
+(CRLF--carriage-return line-feed), which are often inserted by editors on
+Windows. To resolve this issue, open an SSH session and run the following
+command, replacing ```` with the name of the Python file you're
+using:
+
+.. code:: shell
+
+ sed -i 's/\r//g'
+
+This will fix it for the copy of the file on the brick, but if you plan to edit
+it again from Windows, you should configure your editor to use Unix-style
+line endings (LF/line-feed). In Visual Studio Code, there is an option in the
+lower-right corner.
+
+.. image:: _static/vscode-crlf.png
+
+For PyCharm, you can find a guide on doing this
+`here `_.
+Most other editors have similar options; there may be an option for it in the
+status bar at the bottom of the window or in the menu bar at the top.
+
+
+``Exception: Unsupported platform 'None'``
+------------------------------------------
+
+If you are on a Raspberry Pi, you probably forgot to `update config.txt`_.
+
+
+Using BrickPi 3: sensors aren't found
+-------------------------------------
+
+The BrickPi can't automatically detect what sensors are plugged in, so you need
+to tell it. See the `BrickPi 3 demo`_.
+
+.. _update config.txt: https://www.ev3dev.org/docs/getting-started/#step-3a-raspberry-pi-only-update-options-in-configtxt
+.. _Visual Studio Code extension: https://github.com/ev3dev/vscode-ev3dev-browser
+.. _BrickPi 3 demo: https://github.com/ev3dev/ev3dev-lang-python-demo/blob/stretch/platform/brickpi3-motor-and-sensor.py
\ No newline at end of file
diff --git a/docs/faq.rst b/docs/faq.rst
index 2033729..84b2cd8 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -1,23 +1,7 @@
Frequently-Asked Questions
==========================
-Q: Why does my Python program exit quickly or immediately throw an error?
- A: This may occur if your file includes Windows-style line endings
- (CRLF--carriage-return line-feed), which are often inserted by editors on
- Windows. To resolve this issue, open an SSH session and run the following
- command, replacing ```` with the name of the Python file you're
- using:
-
- .. code:: shell
-
- sed -i 's/\r//g'
-
- This will fix it for the copy of the file on the brick, but if you plan to edit
- it again from Windows, you should configure your editor to use Unix-style
- line endings (LF--line-feed). For PyCharm, you can find a guide on doing this
- `here `_.
- Most other editors have similar options; there may be an option for it in the
- status bar at the bottom of the window or in the menu bar at the top.
+See also `Common Issues`_.
Q: Where can I learn more about the ev3dev operating system?
A: `ev3dev.org`_ is a great resource for finding guides and tutorials on
@@ -63,6 +47,7 @@ Q: What compatibility issues are there with the different versions of Python?
.. _ev3python.com: http://ev3python.com/
.. _FAQ: http://python-ev3dev.readthedocs.io/en/ev3dev-stretch/faq.html
.. _our FAQ page: FAQ_
+.. _Common Issues: http://python-ev3dev.readthedocs.io/en/ev3dev-stretch/common-issues.html
.. _our Issues tracker: https://github.com/ev3dev/ev3dev-lang-python/issues
.. _EXPLOR3R: demo-robot_
.. _demo-robot: http://robotsquare.com/2015/10/06/explor3r-building-instructions/
diff --git a/docs/index.rst b/docs/index.rst
index 1d13ed6..cdd3076 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -10,3 +10,4 @@
spec
rpyc
faq
+ common-issues
diff --git a/docs/sensors.rst b/docs/sensors.rst
index 0c86881..7c70728 100644
--- a/docs/sensors.rst
+++ b/docs/sensors.rst
@@ -6,7 +6,9 @@ Sensor classes
*Note:* If you are using a BrickPi rather than an EV3, you will need to manually
configure the ports before interacting with your sensors. See the example
`here `_.
+There are other common issues specific to the BrickPi; check out `Common Issues`_.
+.. _Common Issues: http://python-ev3dev.readthedocs.io/en/ev3dev-stretch/common-issues.html
Dedicated sensor classes
------------------------