Skip to content

Commit ffe8603

Browse files
rhempelrhempel
committed
Fixes #104 - Expand the README for this project
- Split Resources into User and Developer Sections - Add Usage section - Fix broken links - this is a GitHub rst rendering issue - Fixed up the code-block directives
1 parent caa11d8 commit ffe8603

File tree

1 file changed

+165
-3
lines changed

1 file changed

+165
-3
lines changed

‎README.rst‎

Lines changed: 165 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,171 @@ Python language bindings for ev3dev
55
:target: https://travis-ci.org/rhempel/ev3dev-lang-python
66
.. image:: https://readthedocs.org/projects/python-ev3dev/badge/?version=latest
77
:target: http://python-ev3dev.readthedocs.org/en/latest/?badge=latest
8-
:alt: Documentation Statu
8+
:alt: Documentation Status
99

10-
This is a python library implementing unified interface for ev3dev_ devices.
10+
A Python library implementing unified interface for ev3dev_ devices.
1111

12-
.. _ev3dev: http://ev3dev.org
12+
Example Code
13+
------------
14+
15+
To run these minimal examples, run the Python interpreter from
16+
the terminal like this:
17+
18+
.. code-block:: bash
19+
20+
robot@ev3dev:~$ python
21+
Python 2.7.9 (default, Mar 1 2015, 13:52:09)
22+
[GCC 4.9.2] on linux2
23+
Type "help", "copyright", "credits" or "license" for more information.
24+
>>>
25+
26+
The ``>>>`` characters are the default prompt for Python. In the examples
27+
below, we have removed these characters so it's easier to cut and
28+
paste the code into your session.
29+
30+
Load the ev3dev-lang_ bindings:
31+
32+
.. code-block:: python
33+
34+
import ev3dev.ev3 as ev3
35+
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.
41+
42+
.. code-block:: python
43+
44+
ts = ev3.TouchSensor()
45+
while True:
46+
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 75% power for 3 seconds.
50+
51+
.. code-block:: python
52+
53+
m = ev3.LargeMotor('outA')
54+
m.run_timed(time_sp=3000, duty_cycle_sp=75)
55+
56+
If you want to make your robot speak, then paste this code into the terminal:
57+
58+
.. code-block:: python
59+
60+
ev3.Sound.speak('Welcome to the EV3DEV project!').wait()
61+
62+
To quit Python, just type ``exit()`` or ``Ctrl-D``.
63+
64+
User Resources
65+
--------------
66+
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!
73+
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.
79+
80+
Demo Robot
81+
Laurens Valk of robot-square_ has been kind enough to allow us to
82+
reference his excellent `EXPLOR3R`_ robot. Consider building the
83+
`EXPLOR3R`_ and running the demo programs referenced below to get
84+
familiar with what Python programs using this binding look like.
85+
86+
Demo Code
87+
There are `demo programs`_ that you can run to get acquainted with
88+
this language binding. The programs are designed to work with the
89+
`EXPLOR3R`_ robot.
1390

91+
Developer Resources
92+
-------------------
93+
94+
Python Package Index
95+
The Python language has a `package repository`_ where you can find
96+
libraries that others have written, including the `latest version of
97+
this package`_.
98+
99+
The ev3dev Binding Specification
100+
Like all of the language bindings for ev3dev_ supported hardware, the
101+
Python binding follows the minimal API that must be provided per
102+
`this document`_.
103+
104+
The ev3dev-lang Project on GitHub
105+
The `source repository for the generic API`_ and the scripts to automatically
106+
generate the binding. Only developers of the ev3dev-lang-python_ binding
107+
would normally need to access this information.
108+
109+
Python2.x and Python3.x Compatibility
110+
-------------------------------------
111+
112+
The ev3dev_ distribution comes with both python2_ and python3_ installed and
113+
this library is compatible with both versions.
114+
115+
Note that currently, the source is only installed in the default
116+
`Python 2.x`_ location - this will be addressed in the next package we
117+
release.
118+
119+
For `Python 2.x`_ programs, you import the binding like this:
120+
121+
.. code-block:: python
122+
123+
from ev3dev.auto import *
124+
125+
For `Python 3.x`_ the easiest way to work around the problem is
126+
to get your EV3 connected to the Internet and then:
127+
128+
#. Update the package lists
129+
#. Install the ``python3-pil`` package
130+
#. Use ``easy-install`` install ``python-ev3dev``
131+
132+
.. code-block:: bash
133+
134+
sudo apt-get update
135+
sudo apt-get install python3-pil
136+
sudo python3 -m easy_install python-ev3dev
137+
138+
You will be asked for the ``robot`` user's password to get ``sudo`` access
139+
to the system - the default password is ``maker``.
140+
141+
Please be patient - a typical ``apt-get update`` will take about
142+
10 minutes - there's a LOT going on under the hood to sort out
143+
package dependencies.
144+
145+
And now you can use ev3dev-lang-python_ under `Python 3.x`_.
146+
147+
.. code-block:: python
148+
149+
from ev3dev.auto import *
150+
151+
----
152+
153+
.. _ev3dev: http://ev3dev.org
154+
.. _Getting Started: ev3dev-getting-started_
155+
.. _ev3dev-getting-started: http://www.ev3dev.org/docs/getting-started/
156+
.. _detailed instructions for USB connections: ev3dev-usb-internet_
157+
.. _ev3dev-usb-internet: http://www.ev3dev.org/docs/tutorials/connecting-to-the-internet-via-usb/
158+
.. _source repository for the generic API: ev3dev-lang_
159+
.. _ev3dev-lang: https://github.com/ev3dev/ev3dev-lang
160+
.. _ev3dev-lang-python: https://github.com/rhempel/ev3dev-lang-python
161+
.. _this document: wrapper-specification_
162+
.. _wrapper-specification: https://github.com/ev3dev/ev3dev-lang/blob/develop/wrapper-specification.md
163+
.. _EXPLOR3R: demo-robot_
164+
.. _demo-robot: http://robotsquare.com/2015/10/06/explor3r-building-instructions/
165+
.. _demo programs: demo-code_
166+
.. _demo-code: https://github.com/rhempel/ev3dev-lang-python/tree/master/demo
167+
.. _robot-square: http://robotsquare.com/
168+
.. _Python 2.x: python2_
169+
.. _python2: https://docs.python.org/2/
170+
.. _Python 3.x: python3_
171+
.. _python3: https://docs.python.org/3/
172+
.. _package repository: pypi_
173+
.. _pypi: https://pypi.python.org/pypi
174+
.. _latest version of this package: pypi-python-ev3dev_
175+
.. _pypi-python-ev3dev: https://pypi.python.org/pypi/python-ev3dev

0 commit comments

Comments
 (0)