Skip to content

Commit 164aeaf

Browse files
dwalton76dwalton76
authored
Merge pull request #201 from WasabiFan/overhaul-readme
Overhaul README with relevant links and step-by-step intro
2 parents cff6cda + 498f168 commit 164aeaf

File tree

2 files changed

+113
-54
lines changed

2 files changed

+113
-54
lines changed

‎ISSUE_TEMPLATE.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
<!--
2+
Before we can help you, we need some information about what you are trying to do and what software you are using.
3+
If you are reporting a bug or asking a usage question, please fill out the information below; otherwise you can delete this template.
4+
-->
5+
6+
- **ev3dev version:** PASTE THE OUTPUT OF `uname -r` HERE
7+
- **ev3dev-lang-python version:**
8+
9+
<!-- Now tell us about what you were trying to do, and include any error messages you received. Be specific and include any involved code, please! -->
10+

‎README.rst‎

Lines changed: 103 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -7,17 +7,52 @@ Python language bindings for ev3dev
77
:target: http://python-ev3dev.readthedocs.org/en/latest/?badge=latest
88
:alt: Documentation Status
99

10-
A Python3 library implementing unified interface for ev3dev_ devices.
10+
A Python3 library implementing an interface for ev3dev_ devices,
11+
letting you control motors, sensors, hardware buttons, LCD
12+
displays and more from Python code.
1113

12-
Example Code
14+
If you haven't written code in Python before, you'll need to learn the language
15+
before you can use this library. **TODO: INSERT RESOURCES HERE**
16+
17+
Getting Started
18+
---------------
19+
20+
This library runs on ev3dev_. Before continuing, make sure that you have set up
21+
your EV3 or other ev3dev device as explained in the `ev3dev Getting Started guide`_.
22+
Make sure that you have a kernel version that includes `-10-ev3dev` or higher (a
23+
larger number). You can check the kernel version by selecting "About" in Brickman
24+
and scrolling down to the "kernel version". If you don't have a compatible version,
25+
upgrade the kernel first. **TODO: INSERT LINK HERE**
26+
27+
Once you have booted ev3dev and connected to your EV3 (or Raspberry Pi / BeagleBone)
28+
via SSH, you will need to install the latest version of this library.
29+
30+
To do so, run the following commands, which could take ten minutes or longer
31+
(you may be prompted to type the password; the default is `maker`):
32+
33+
.. code-block:: bash
34+
35+
sudo apt-get update
36+
sudo apt-get install python3-ev3dev
37+
38+
Now that you have the latest version installed, you should be ready to start
39+
using ev3dev with Python. If you want to go through some basic usage examples,
40+
check out the `Usage Examples`_ section to try out motors, sensors and LEDs.
41+
Then look at `Writing Python Programs for Ev3dev`_ to see how you can save
42+
your Python code to a file.
43+
44+
Make sure that you look at the `User Resources`_ section as well for links
45+
to documentation and larger examples.
46+
47+
Usage Examples
1348
------------
1449

1550
To run these minimal examples, run the Python3 interpreter from
16-
the terminal like this:
51+
the terminal using the `python3` command:
1752

18-
.. code-block:: bash
53+
.. code-block::
1954
20-
robot@ev3dev:~/ev3dev-lang-python$ python3
55+
$ python3
2156
Python 3.4.2 (default, Oct 8 2014, 14:47:30)
2257
[GCC 4.9.1] on linux
2358
Type "help", "copyright", "credits" or "license" for more information.
@@ -27,55 +62,90 @@ The ``>>>`` characters are the default prompt for Python. In the examples
2762
below, we have removed these characters so it's easier to cut and
2863
paste the code into your session.
2964

30-
Load the ev3dev-lang_ bindings:
65+
Required: Import the library
66+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3167

3268
.. code-block:: python
3369
3470
import ev3dev.ev3 as ev3
3571
36-
Now let's try our first program. This code will turn the left LED red
37-
whenever the touch sensor is pressed, and back to green when it's
38-
released. Plug a touch sensor into any sensor port and then paste in this
39-
code - you'll need to hit ``Enter`` after pasting to complete the
40-
loop and start the program. Hit ``Ctrl-C`` to exit the loop.
72+
Controlling the LEDs with a touch sensor
73+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
74+
75+
This code will turn the left LED red whenever the touch sensor is pressed, and
76+
back to green when it's released. Plug a touch sensor into any sensor port and
77+
then paste in this code - you'll need to hit ``Enter`` after pasting to complete
78+
the loop and start the program. Hit ``Ctrl-C`` to exit the loop.
4179

4280
.. code-block:: python
4381
4482
ts = ev3.TouchSensor()
4583
while True:
4684
ev3.Leds.set_color(ev3.Leds.LEFT, (ev3.Leds.GREEN, ev3.Leds.RED)[ts.value()])
47-
48-
Now plug a motor into the ``A`` port and paste this code into the terminal. This
49-
little program will run the motor at 500 RPM for 3 seconds.
85+
86+
Running a motor
87+
~~~~~~~~~~~~~~~
88+
89+
Now plug a motor into the ``A`` port and paste this code into the Python prompt.
90+
This little program will run the motor at 500 ticks per second (around 0.4
91+
rotations per second) for three seconds.
5092

5193
.. code-block:: python
5294
5395
m = ev3.LargeMotor('outA')
5496
m.run_timed(time_sp=3000, speed_sp=500)
5597
56-
If you want to make your robot speak, then paste this code into the terminal:
98+
Using text-to-speech
99+
~~~~~~~~~~~~~~~~~~~~
100+
101+
If you want to make your robot speak, you can use the `Sound.speak` method:
57102

58103
.. code-block:: python
59104
60105
ev3.Sound.speak('Welcome to the E V 3 dev project!').wait()
61106
62-
To quit Python, just type ``exit()`` or ``Ctrl-D``.
107+
**To quit the Python REPL, just type** ``exit()`` **or press** ``Ctrl-D`` **.**
108+
109+
Make sure to check out the `User Resources`_ section for more detailed
110+
information on these features and many others.
111+
112+
Writing Python Programs for Ev3dev
113+
----------------------------------
114+
115+
Every Python program should have a few basic parts. Use this template
116+
to get started:
117+
118+
.. code-block:: python
119+
120+
#!/usr/bin/env python3
121+
from ev3dev.ev3 import *
122+
123+
# TODO: Add code here
124+
125+
The first two lines should be included in every Python program you write
126+
for ev3dev. The first allows you to run this program from Brickman, while the
127+
second imports this library.
128+
129+
When saving Python files, it is best to use the ``.py`` extension, e.g. ``my-file.py``.
63130

64131
User Resources
65132
--------------
66133

67-
Getting Started with ev3dev
68-
If you got here as the result of looking for "how to program
69-
LEGO MINDSTORMS EV3 using Python" then you might not be aware that
70-
this is part of a much larger project called ev3dev_. Make sure
71-
you read the `Getting Started`_ page
72-
to become familiar with ev3dev_ first!
134+
Library Documentation
135+
**Class documentation for this library can be found on** `our Read the Docs page`_ **.**
136+
You can always go there to get information on how you can use this
137+
library's functionality.
73138

74-
Connecting the EV3 to the Internet
75-
You can connect to an EV3 running ev3dev_ using USB, Wifi or
76-
Bluetooth. The USB connection is a good starting point, and
77-
the ev3dev_ site has `detailed instructions for USB connections`_
78-
for Linux, Windows, and Mac computers.
139+
ev3dev.org
140+
`ev3dev.org`_ is a great resource for finding guides and tutoials on
141+
using ev3dev.
142+
143+
Support
144+
If you are having trouble using this library, please open an issue
145+
at `our Issues tracker`_ so that we can help you. When opening an
146+
issue, make sure to include as much information as possible about
147+
what you are trying to do and what you have tried. The issue template
148+
is in place to guide you through this process.
79149

80150
Demo Robot
81151
Laurens Valk of robot-square_ has been kind enough to allow us to
@@ -116,42 +186,21 @@ Note that currently, the Python3 binding for ev3dev_ is not installed
116186
by default - this will be addressed in the next package we
117187
release.
118188

119-
The easiest way to work around the problem is
120-
to get your EV3 connected to the Internet and then:
121-
122-
#. Update the package lists
123-
#. Install the ``python3-pil`` package
124-
#. Use ``easy-install`` install ``python-ev3dev``
125-
126-
.. code-block:: bash
127-
128-
sudo apt-get update
129-
sudo apt-get install python3-pil
130-
sudo python3 -m easy_install python-ev3dev
131-
132-
You will be asked for the ``robot`` user's password to get ``sudo`` access
133-
to the system - the default password is ``maker``.
134-
135-
Please be patient - a typical ``apt-get update`` will take about
136-
10 minutes - there's a LOT going on under the hood to sort out
137-
package dependencies.
138-
139-
And now you can use ev3dev-lang-python_ under `Python 3.x`_.
140-
141-
.. code-block:: python
142-
143-
from ev3dev.auto import *
144-
145-
----
189+
Until then, you must follow the instructions at the top of this README to make
190+
sure that you have installed the newest version of the Python 3-based library.
146191

147192
.. _ev3dev: http://ev3dev.org
193+
.. _ev3dev.org: ev3dev_
148194
.. _Getting Started: ev3dev-getting-started_
195+
.. _ev3dev Getting Started guide: ev3dev-getting-started_
149196
.. _ev3dev-getting-started: http://www.ev3dev.org/docs/getting-started/
150197
.. _detailed instructions for USB connections: ev3dev-usb-internet_
151198
.. _ev3dev-usb-internet: http://www.ev3dev.org/docs/tutorials/connecting-to-the-internet-via-usb/
199+
.. _our Read the Docs page: http://python-ev3dev.readthedocs.org/en/latest/
152200
.. _source repository for the generic API: ev3dev-lang_
153201
.. _ev3dev-lang: https://github.com/ev3dev/ev3dev-lang
154202
.. _ev3dev-lang-python: https://github.com/rhempel/ev3dev-lang-python
203+
.. _our Issues tracker: https://github.com/rhempel/ev3dev-lang-python/issues
155204
.. _this document: wrapper-specification_
156205
.. _wrapper-specification: https://github.com/ev3dev/ev3dev-lang/blob/develop/wrapper-specification.md
157206
.. _EXPLOR3R: demo-robot_

0 commit comments

Comments
 (0)