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 ------------------------