Skip to content

Commit 516dc38

Browse files
dlechdlech
committed
add docs for latest test release
1 parent bb89b55 commit 516dc38

94 files changed

Lines changed: 845 additions & 18 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎_config.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,12 @@ defaults:
1313
type: "pages"
1414
values:
1515
layout: "docs"
16+
-
17+
scope:
18+
path: "docs/tutorials"
19+
type: "pages"
20+
values:
21+
category: "tutorials"
1622
-
1723
scope:
1824
path: "docs/sensors"

‎_includes/screenshot.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
<span class="screenshot"><a href="{{ include.source }}"><img height="{{ include.scale }}%" width="{{ include.scale }}%" src="{{ include.source }}" /></a></span>

‎_layouts/docs.html‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22
layout: page
33
---
44

5+
<div class="edit-on-github">
6+
<a href="{{ site.github.repository_url }}/edit/master/{{ page.path }}">Edit on Github</a>
7+
</div>
58
<div class="breadcrumbs">
69
{% assign parent_dirs=page.url | replace_first: '/', '' | split: '/' %}
710
{% assign link='/' %}

‎contributing/index.md‎

Lines changed: 22 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5,23 +5,33 @@ title: Contributing
55
* Table of Contents
66
{:toc}
77

8-
ev3dev is a HUGE project and we are always happy to receive help.
8+
ev3dev is a **HUGE** project and we are always happy to receive help.
99
Here are some of the many ways you can contribute to the project.
1010

1111
## Write some documentation
1212

13-
All of our documentation (including this website) is maintained through GitHub
14-
via [pull requests]. If you find an error or would like to add new
15-
documentation to the [wiki], you can find instructions on how to contribute
16-
[here][contribute-to-wiki]. If you have an idea or correction for this website,
17-
you can submit it [here][this-website].
13+
All of our documentation (including this entire website) is maintained through
14+
GitHub via [pull requests] (so you will need a GitHub account if you don't
15+
already have one). All of the *docs* pages have a link that says "Edit on
16+
Github". Just follow the link and make your changes - and be sure to preview
17+
before saving changes. Github will automatically create a pull request. We will
18+
review your changes before incorporating them into the site.
19+
20+
Even if a page doesn't have the edit link, you can actually still make changes.
21+
Just find it [here][this-website].
22+
23+
We are also in the process of migrating the [wiki] documentation to this site.
24+
It would be nice to get some help with this. Pick a page and figure out where
25+
it should go (probably under *docs* somewhere). But be sure to ask first,
26+
though, in case we don't actually want that particular page migrated.
1827

1928
## Write some software
2029

21-
As the hardware drivers are being finalized, development will be shifting to software that can interface
22-
with the hardware. There are many <a href="https://github.com/ev3dev">packages on GitHub</a> that you can
23-
hack on. Additionally, there are some language bindings listed on the <a href="/">home page</a> that are
24-
not part of the ev3dev GitHub organization (yet).
30+
As the hardware drivers are being finalized, development will be shifting to
31+
software that can interface with the hardware. There are many [packages on
32+
GitHub][ev3dev-github-org] that you can hack on. Additionally, there are some
33+
language bindings listed on the [home page](/) that are not part of the ev3dev
34+
GitHub organization (yet).
2535

2636
If you have never used GitHub before, it's super-easy. [Read about it][GitHub Help],
2737
then send a pull request.
@@ -61,4 +71,5 @@ hardware and we will make it work for you. See this
6171
[issue]: https://github.com/ev3dev/ev3dev/issues
6272
[ev3-creating-a-console-cable]: http://botbench.com/blog/2013/08/15/ev3-creating-console-cable
6373
[Saleae referral]: http://go.referralcandy.com/share/8LP4Z9L
64-
[will-work-for-sensors]: http://lechnology.com/2014/08/will-work-for-sensors
74+
[will-work-for-sensors]: http://lechnology.com/2014/08/will-work-for-sensors
75+
[ev3dev-github-org]: https://github.com/ev3dev

‎docs/getting-started.md‎

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
---
2+
title: Getting Started with ev3dev
3+
---
4+
5+
* Table of Contents
6+
{:toc}
7+
8+
So you are ready to try out ev3dev. Great!. Here are step-by-step instructions
9+
to get ev3dev up and running on your EV3.
10+
11+
First, here are the things you need before starting:
12+
13+
* A LEGO MINDSTORMS EV3 Intelligent Brick (obviously).
14+
* A [microSD] or [microSDHC] card. [microSDXC] is not supported (you
15+
might be able to get it to work, but it will operate at reduced capacity and
16+
speed). Also look at the [speed class rating]. Class 10 is the fastest, but
17+
slower speeds will work just fine. Ultra High Speed (UHS) classes are not
18+
supported (again, they should work, but not at the rated speed).
19+
* A computer with an adapter for the SD card. You will need administrator user
20+
permissions on this computer.
21+
* A way to communicate with the EV3. This can be one of the following:
22+
* USB cable (the one that comes with the EV3)
23+
* USB WiFi dongle
24+
* USB Ethernet (wired) dongle
25+
* Bluetooth
26+
27+
---
28+
29+
**IMPORTANT:** The instructions on this page only apply to releases dated Oct.
30+
2014 or later. For earlier releases (i.e. wheesy "Latest Release"), see
31+
[Getting Started v2] on the old wiki. These older releases are no longer
32+
supported.
33+
34+
---
35+
36+
## Step 1: Download the latest ev3dev image file
37+
38+
Releases are posted [on GitHub][releases]. Follow the link and download the latest
39+
**Test Release** image file. Downloading the `.zip` file is recommended for
40+
Windows/Mac and the `.xz` file is recommended for Linux. The `.xz` is smaller,
41+
but it requires that you have additional software installed on Windows/Mac to
42+
decompress it (such as [7-Zip] on Windows).
43+
44+
## Step 2: Copy the image on to the SD card
45+
46+
---
47+
48+
**IMPORTANT:** THIS WILL ERASE EVERYTHING ON YOUR SD CARD! BACKUP YOUR FILES
49+
IF YOU DO NOT WANT TO LOOSE THEM!
50+
51+
---
52+
53+
There are a vast number of ways to do this, so pick the one from the list that
54+
sounds the easiest to you:
55+
56+
* **Linux**
57+
* [Command Line](../tutorials/writing-sd-card-image-linux-command-line)
58+
* [Ubuntu (graphical interface)](../tutorials/writing-sd-card-image-ubuntu-disk-image-writer)
59+
* **Mac OS X**
60+
* [Command Line](../tutorials/writing-sd-card-image-mac-command-line)
61+
* **Windows**
62+
* [Win32DiskImager (graphical interface)](../tutorials/writing-sd-card-image-win32diskimager)
63+
64+
**TIP:** For more detailed information and more alternatives, check out
65+
[this page for RaspberryPi](http://elinux.org/RPi_Easy_SD_Card_Setup). Much
66+
of the information there is applicable to ev3dev.
67+
68+
## Step 3: Boot ev3dev
69+
70+
Put the SD Card in your EV3 and power it on. At first, you will see the
71+
MINDSTORMS boot splash and the red LEDs will be on. This is immediately
72+
followed by the ev3dev boot splash and the LEDs changing to orange. The left
73+
LED indicates CPU activity and the right LED indicates disk (SD card) activity.
74+
75+
Shortly after the ev3dev boot splash, the screen will go blank <s>and then
76+
eventually say `"Debian GNU/Linux 7 (wheezy)"`. Any time after the screen goes
77+
blank, you can press any of the directional buttons (up, down, left, right)
78+
to toggle displaying boot messages.</s> (Plymouth is currently broken, so no
79+
boot messages for now.)
80+
81+
The first boot will take a little longer that subsequent boots because the EV3
82+
has to create a unique SSH host ids and take care of a few other housekeeping
83+
items.
84+
85+
When the boot is complete, the LEDs will turn green and you will see something
86+
like this on the screen:
87+
88+
{% include screenshot.html source="/images/brickman/main-menu.png" %}
89+
90+
**Troubleshooting tips if your EV3 won't boot:**
91+
92+
* Make sure nothing is plugged into the EV3 (USB/sensors/motors/etc.)
93+
* Try writing the image to the SD card again.
94+
* You may have a bad/incompatible SD card - try a different SD card.
95+
96+
## Step 4: Setup a network connection
97+
98+
There are lots of choices here. Your choice depends on what type of connection
99+
you want to use and on the OS of your host computer, so pick the one that applies:
100+
101+
* Ethernet over USB (just requires the USB cable that comes with the EV3)
102+
* [Linux (NetworkManager)](../tutorials/setting-up-ethernet-over-usb-on-linux-networkmanager)
103+
* [Mac OS X](../tutorials/setting-up-ethernet-over-usb-on-mac)
104+
* [Windows](../tutorials/setting-up-ethernet-over-usb-on-windows)
105+
* USB Ethernet dongle (as in the kind with an RJ45 connector)
106+
* If your network has a DHCP server, this will "just work". See brickman
107+
docs for more info.
108+
* USB WiFi Dongle
109+
* Hopefully you can figure it out. I'm putting off writing detailed docs
110+
until brickman is a bit more stable.
111+
* Bluetooth
112+
* Can someone figure this out and write up some documentation please?
113+
114+
## Step 5: First things to do with ev3dev
115+
116+
Here are some suggestions of some things you should do to get your EV3 setup.
117+
118+
### Change your root password
119+
120+
root@ev3dev:~# passwd
121+
Enter new UNIX password:
122+
Retype new UNIX password:
123+
passwd: password updated successfully
124+
125+
### Set up a new user
126+
127+
Replace `user` with your actual user name and `First Last` with your real name
128+
(if you want it on the EV3 - you can leave it blank too). Don't miss the
129+
command to assign groups hiding at the end.
130+
131+
root@ev3dev:~# adduser user
132+
Adding user `user' ...
133+
Adding new group `user' (1001) ...
134+
Adding new user `user' (1001) with group `user' ...
135+
Creating home directory `/home/user' ...
136+
Copying files from `/etc/skel' ...
137+
Enter new UNIX password:
138+
Retype new UNIX password:
139+
passwd: password updated successfully
140+
Changing the user information for user
141+
Enter the new value, or press ENTER for the default
142+
Full Name []: First Last
143+
Room Number []:
144+
Work Phone []:
145+
Home Phone []:
146+
Other []:
147+
Is the information correct? [Y/n] y
148+
root@ev3dev:~# usermod -a -G sudo,ev3dev,plugdev,audio,video user
149+
150+
### Set the time zone
151+
152+
root@ev3dev:~# dpkg-reconfigure tzdata
153+
154+
Then just follow the instructions on the screen.
155+
156+
**NOTE:** The EV3 does not have a battery backup for the realtime clock.
157+
Whenever you remove the batteries, the clock will be reset. If the EV3 is
158+
connected to the Internet, the clock will be automatically set via NTP,
159+
otherwise, you can manually set the date/time with the `date` command.
160+
161+
162+
### Set the locale
163+
164+
You can skip this if en-US is OK.
165+
166+
root@ev3dev:~# dpkg-reconfigure locales
167+
168+
### Grow your root file system
169+
170+
The ev3dev image is only ~900MB so that you don't have to wait so long while
171+
writing the image to the SD card (and also so it will fit on a 1GB card). This
172+
means that you have some unused space on your SD card that you can reclaim.
173+
This command will expand the root file system partition to use the rest of the
174+
free space on your SD card.
175+
176+
root@ev3dev:~# lvextend --extents +100%FREE --resizefs /dev/ev3devVG/root /dev/mmcblk0p3
177+
178+
**IMPORTANT**: Don't wait until you get an error that your disk is full before
179+
doing this. You need some free disk space available in order to run this command.
180+
181+
### Update packages
182+
183+
Make sure your EV3 is connected to the Internet first. Updating the package
184+
list the first time will take a few minutes.
185+
186+
root@ev3dev:~# apt-get update
187+
root@ev3dev:~# apt-get upgrade
188+
root@ev3dev:~# apt-get dist-upgrade
189+
190+
If a new kernel package is installed, you will need to reboot.
191+
192+
root@ev3dev:~# reboot
193+
194+
## Step 6: Do something awesome
195+
196+
This will be where we tell you how to use the EV3's main functions, and how
197+
to write programs. We are still learning, so everything here should be
198+
considered experimental and subject to major changes.
199+
200+
### Using the EV3 hardware drivers
201+
202+
Here are some guides for using each of the major components.
203+
204+
* [Sensors](/docs/sensors)
205+
* [Motors](https://github.com/ev3dev/ev3dev/wiki/Using-Motors)
206+
* [Sound](https://github.com/ev3dev/ev3dev/wiki/Using-Sound)
207+
* [LCD](https://github.com/ev3dev/ev3dev/wiki/Using-the-LCD)
208+
* [Buttons](https://github.com/ev3dev/ev3dev/wiki/Using-the-Buttons)
209+
* [LEDs](https://github.com/ev3dev/ev3dev/wiki/Using-the-LEDs)
210+
* [Bluetooth](https://github.com/ev3dev/ev3dev/wiki/Using-Bluetooth)
211+
212+
### Writing programs
213+
214+
There are a number of programming languages available to use. The brick can
215+
run almost all languages that any other Linux distro can, so your favorite
216+
language is probably supported. Language bindings have already been written
217+
for some languages:
218+
219+
- [Using brickstrap to cross compile and debug](https://github.com/ev3dev/ev3dev/wiki/Using-brickstrap-to-cross-compile-and-debug)
220+
- [C++, Lua and Vala language bindings/samples](https://github.com/ev3dev/ev3dev-lang)
221+
- [Google Go](https://github.com/ldmberman/GoEV3)
222+
- [Node.js](https://github.com/WasabiFan/ev3dev-NodeJS)
223+
- [Python](https://github.com/topikachu/python-ev3)
224+
225+
If the language you want isn't listed, you still can use it, but you'll have to
226+
do more of the heavy lifting yourself using the guides above. Once you get the
227+
hang of it, you can even write your own interface library and have it listed here!
228+
229+
## Step 7: Calling it a day
230+
231+
When you are ready to wish your EV3 goodnight, turn if off by pressing the
232+
*back* button from the main menu in brickman and selecting *Power Off*.
233+
234+
{% include screenshot.html source="/images/brickman/shutdown-menu.png" %}
235+
236+
[microSD]: https://en.wikipedia.org/wiki/Secure_Digital#SD
237+
[microSDHC]: https://en.wikipedia.org/wiki/Secure_Digital#SDHC
238+
[microSDXC]: https://en.wikipedia.org/wiki/Secure_Digital#SDXC
239+
[speed class rating]: https://en.wikipedia.org/wiki/Secure_Digital#Speed_class_rating
240+
[releases]:https://github.com/mindboards/ev3dev/releases
241+
[7-Zip]: http://www.7-zip.org/
242+
[Getting Started v2]: https://github.com/ev3dev/ev3dev/wiki/Getting-started-v2

‎docs/index.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,15 @@ layout: page
55

66
We are in the process of moving documentation from the [wiki] to here.
77

8-
* Getting Started
9-
* Tutorials
8+
* [Getting Started]
9+
* [Tutorials]
1010
* Libraries (Programming Languages)
1111
* [Supported Sensors and Other Input Devices][sensors]
1212
* Supported Motors and Other Output Devices
1313
* sysfs ABI
1414
* ev3dev Developer Tools
1515

16+
[Getting Started]: getting-started
17+
[Tutorials]: tutorials
1618
[wiki]: https://github.com/ev3dev/ev3dev/wiki
1719
[sensors]: sensors

‎docs/tutorials/index.html‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: Tutorials
3+
---
4+
5+
{% assign tutorials=site.pages | where: "category", "tutorials" | groupby: "subject" %}
6+
<ul>
7+
{% for other_page in tutorials %}
8+
{% if other_page.subject != last_subject %}
9+
{% if !last_subject %}
10+
</ul>
11+
{% endif %}
12+
<li>{{ other_page.subject }}</li>
13+
<ul>
14+
{% assign last_subject=other_page.subject %}
15+
{% endif %}
16+
{% if other_page.url != page.url %}
17+
<li><a href="{{ other_page.url }}">{{ other_page.title }}</a></li>
18+
{% endif %}
19+
{% endfor %}
20+
</ul>
21+
</ul>

0 commit comments

Comments
 (0)