README.md 5.86 KB
Newer Older
1
# RWTH - Mindstorms EV3 Toolbox for MATLAB
Tim Stadtmann's avatar
Tim Stadtmann committed
2

Tim Stadtmann's avatar
Tim Stadtmann committed
3
4
Hello, fellow LEGO constructors and MATLAB programmers, welcome to the RWTH - 
Mindstorms EV3 Toolbox for MATLAB! 
5

Tim Stadtmann's avatar
Tim Stadtmann committed
6
7
8
This toolbox was designed to simplify controlling LEGO MINDSTORMS EV3 
robots live using MATLAB. Via Bluetooth or USB you can easily read sensor values 
or control your robots’ motors. You can choose to either work on a high level, 
Tim Stadtmann's avatar
Tim Stadtmann committed
9
with a virtual twin of your EV3, or follow the EV3's firmware specification 
Tim Stadtmann's avatar
Tim Stadtmann committed
10
by sending commands directly. 
Tim Stadtmann's avatar
Tim Stadtmann committed
11

12
13
This toolbox is being developed at RWTH Aachen University, Germany. It is the 
successor of the 
Linus Atorf's avatar
Linus Atorf committed
14
[RWTH - Mindstorms NXT Toolbox](http://www.mindstorms.rwth-aachen.de/). Amongst other applications,
15
16
17
18
19
20
21
22
23
24
it is used in the yearly lab exercise ["MATLAB meets LEGO Mindstorms"](https://mindstorms.lfb.rwth-aachen.de)
by more than 400 students in the first year of their Eletrical Engineering curriculum at RWTH Aachen University


To get started, take a look at the installation instructions and examples below. 


## License

This software is distributed under the Lesser GNU Plublic License v2.1 (LGPL 2.1).
Tim Stadtmann's avatar
Tim Stadtmann committed
25

26
This software is based on the [QUT EV3 MATLAB Toolkit](https://wiki.qut.edu.au/display/cyphy/QUT+EV3+MATLAB+toolkit) 
Linus Atorf's avatar
Linus Atorf committed
27
28
29
30
31
32
by Peter Corke et al. of Queensland University.  
Source: <https://github.com/petercorke/robotics-toolbox-matlab/tree/master/interfaces/EV3>  

*The QUT EV3 MATLAB Toolkit is part of the Robotics Toolbox for MATLAB, see:*  
*<https://github.com/petercorke/robotics-toolbox-matlab/>*  
*P. Corke, "Robotics, Vision \& Control: Fundamental Algorithms in Matlab", Springer, 2011, ISBN 978-3-642-20143*
33
34
35
36
37

This software uses the HIDAPI library by Alan Ott, Signal 11 Software, see <https://github.com/signal11/hidapi>

## How to quote

Linus Atorf's avatar
Linus Atorf committed
38
If you want to cite this software, you can use the following bibtex snippet:
39
40
41
42
43
44
45
46
47
48
49
50

 
```bibtex
@Misc{rwthmindstormsev3toolbox,
  author       = {Atorf, L. and Sondermann, B. and Stadtmann, T. and Rossmann, J.},
  title        = {RWTH - Mindstorms EV3 Toolbox},
  year         = {2018},
  version      = {1.0},
  organization = {Institute for Man-Machine Interaction, RWTH Aachen University},
  url          = {https://git.rwth-aachen.de/mindstorms/ev3-toolbox-matlab}
}
```
Tim Stadtmann's avatar
Tim Stadtmann committed
51
52


Tim Stadtmann's avatar
Tim Stadtmann committed
53
54
55
## Prerequisites 
If you use Windows, you will need to have the Instrument Control Toolbox 
installed for USB to work properly. 
Tim Stadtmann's avatar
Tim Stadtmann committed
56

Tim Stadtmann's avatar
Tim Stadtmann committed
57
58
59
This toolbox has been developed and tested on MATLAB 2014a/2016a, on Windows 
7/10 and Ubuntu 14.04/16.04. If you encounter problems using other 
configurations, feel free to contact us.
Tim Stadtmann's avatar
Tim Stadtmann committed
60

Tim Stadtmann's avatar
Tim Stadtmann committed
61
The EV3's firmware version needs to be updated to 1.09, bugs and unsuspected 
Tim Stadtmann's avatar
Tim Stadtmann committed
62
behaviour have been encountered when we used older versions.
Tim Stadtmann's avatar
Tim Stadtmann committed
63

Tim Stadtmann's avatar
Tim Stadtmann committed
64
65
66
## Installation 
In most cases, you will only need to download the toolbox and add its path to 
your MATLAB search path. ('Set path' -> 'Add with subfolders')
Tim Stadtmann's avatar
Tim Stadtmann committed
67
68
69

If you use a Linux system and connecting via Bluetooth does not work,
you can try to manually install the *HIDAPI*, an API for communication with
Tim Stadtmann's avatar
Tim Stadtmann committed
70
71
HID devices, which this toolbox uses for Bluetooth connection on Linux - a 
prebuilt version is delivered with the toolbox. HIDAPI can be installed using the 
Tim Stadtmann's avatar
Tim Stadtmann committed
72
[official repositories of your distribution](https://packages.ubuntu.com/de/source/trusty/hidapi/) 
Tim Stadtmann's avatar
Tim Stadtmann committed
73
or [built](https://github.com/signal11/hidapi/) on your own.
Tim Stadtmann's avatar
Tim Stadtmann committed
74
75


Tim Stadtmann's avatar
Tim Stadtmann committed
76
## Examples 
Tim Stadtmann's avatar
Tim Stadtmann committed
77
78
79
Before you can try out the following example, you will need to have your EV3
connected to your PC via Bluetooth or USB. If you use a Linux system and want
to try out Bluetooth, we suggest you use the 'btconnect'-script you find
Tim Stadtmann's avatar
Tim Stadtmann committed
80
81
82
in 'Tools'. It is a commandline script which aims to make pairing with the
brick more easy. The syntax is 'btconnect *brickName*' (you can read the 
name of your EV3 at the top of its display - it should be *EV3* by default).
Tim Stadtmann's avatar
Tim Stadtmann committed
83
84
85
86
87
88
89
90
91
92
93
94
95
96

```
% This example expects a motor at port A and a (random) sensor at port 1
b = EV3();
b.connect('usb'); % OR: b.connect('bt');
ma = b.motorA;
ma.setProperties('power', 50, 'limitValue', 720);
ma.start();
% fun
ma.waitFor();
disp(b.sensor1.value);
b.beep();
b.disconnect();
```
Tim Stadtmann's avatar
Tim Stadtmann committed
97
You can find more information on the toolbox functions/classes either by using 
Tim Stadtmann's avatar
Tim Stadtmann committed
98
99
100
*help classname.functionname* and *doc classname.functionname* in your MATLAB
editor (the *.functionname* is optional), or in the PDF/HTML documentation 
inside the subfolder *docs*.
Tim Stadtmann's avatar
Tim Stadtmann committed
101
102


103
## Building the documentation
Tim Stadtmann's avatar
Tim Stadtmann committed
104
105
106
107
108
109
110
111
112
113
114
115
116
117
The documentation is built using [Sphinx](http://www.sphinx-doc.org/en/stable/) and several
extensions: [matlabdomain](https://pypi.python.org/pypi/sphinxcontrib-matlabdomain), 
[Napoleon](https://pypi.python.org/pypi/sphinxcontrib-napoleon) and 
[Sphinx Bootstrap Theme](https://pypi.python.org/pypi/sphinx-bootstrap-theme/).

In order to setup your PC for building the documentation from the comments, you need to install these. 
Using Ubuntu, you can use the following instructions (for other distros/OS's checkout the websites above):
```
sudo apt-get install python-sphinx
pip install sphinxcontrib-napoleon
pip install -U sphinxcontrib-matlabdomain
pip install sphinx_bootstrap_theme
```

Tim Stadtmann's avatar
Tim Stadtmann committed
118
119
120
Note: If you get 'permission-denied' errors on the pip install lines, try adding 
'--user *your_username*' to each pip install line.

Tim Stadtmann's avatar
Tim Stadtmann committed
121
122
123
124
125
126
127
128
129
130
131
132
133
134
You also need to setup your latex parser if you want Sphinx to generate pdfs:
```
sudo apt install texlive-latex-base
sudo apt install texlive-latex-extra
```

The build process for different outputs/platforms is controlled with a Makefile.
In the doc-directory, use the following commands to generate html or pdf files. 
Other targets have not been tested.
```
make html
make latexpdf
```

135
136
137
## Acknowledgement

Special thanks to Tim Stadtmann for his effort and perseverance.
Tim Stadtmann's avatar
Tim Stadtmann committed
138
139


Linus Atorf's avatar
Linus Atorf committed
140
## Contact
Tim Stadtmann's avatar
Tim Stadtmann committed
141

Linus Atorf's avatar
Linus Atorf committed
142
143
144
145
146
Dipl.-Phys. Linus Atorf  
Institute for Man-Machine Interaction  
RWTH Aachen University  
Ahornstr. 55  
52074 Aachen, Germany   
Linus Atorf's avatar
Linus Atorf committed
147

148
149
150
151
152
153
Mail: atorf at mmi.rwth-aachen.de


## Disclaimer

This site is neither affiliated with nor endorsed by the LEGO Group. LEGO, MINDSTORMS, NXT, and EV3 are registered trademarks of the LEGO Group.