Home
Welcome to the ev3dev2simulator wiki! This page contains the user manual, showing how the simulator can be used. For information on how the simulator internally works, please consult: https://github.com/ev3dev-python-tools/ev3dev2simulator/wiki/Technical-Specification.
The ev3dev2simulator allows code designed for Lego Mindstorms EV3 robots to be executed in a virtual environment without any modifications to the code. After running the simulator, a user can run multiple Python applications as if they run on a Lego Mindstorms EV3 Brick[1]. The simulator is designed specifically to simulate bricks running the operating system ev3dev[2] and its corresponding ev3dev Python library[3]. The second version of this library is called 'ev3dev2'.
As the image below shows, the simulator can be configured to simulate multiple robots that each consist of multiple bricks. Multiple bricks on a robot are useful to allow for additional sensors and actuators to be connected. The software created by the user that would be run on a brick, now does not connect to the normal ev3dev API/library that is installed on an actual brick, but uses a fake ev3dev API that is provided with the simulator. This fake API automatically connects to the simulator.
The only prerequisites for the simulator are python 3.7 and pip. Installation instructions can be found here. Simulating robot sound works out of the box for Windows and macOS users. Linux user need to install espeak.
The simulator is installed with pip using:
pip install ev3dev2simulatorThen you can just run the simulator by running the executable:
ev3dev2simulatorBased on the configuration of the simulator, it will tell which brick should be connected, e.g, which script should be run. Run the python script that would normally be run on the brick. An example that work with the default configuration is shown below. The fake ev3dev2 module will handle the connection with the simulator.
#!/usr/bin/env python3
from ev3dev2.motor import MoveTank, OUTPUT_A, OUTPUT_D, SpeedPercent
def drive():
tank_drive.on(SpeedPercent(30), SpeedPercent(30))
tank_drive = MoveTank(OUTPUT_A, OUTPUT_D)
drive()The simulator is configured with command line options. The most import option is the desired playing field. The playing field configuration describes the dimensions of the playing field, the robots and additional obstacles that are in the virtual world. By starting the simulator with ev3dev2simulator -t config_large a playground with a bigger robot is opened. All included playing fields are:
- 'config_small', a small playing field with a small mars rover, three lakes and a bottle.
- 'config_small2', same as 'config_small', but with two small mars rovers.
- 'config_large', a big playing field with a large mars rover (one with two bricks), three lakes with holes, and two rocks, of which one can be pushed and one is too heavy to be pushed.
- 'config_large2', same as 'config_large', but with two big mars rovers.
Using your own playing field is also possible. A playing field is described by a '.yaml' file. Start the simulator with ev3dev2simulator -t <relative path to your .yaml file>. An example file can be found here. The two standard playing fields are shown below.
All possible command line options are shown below.
usage: ev3dev2simulator [-h] [-V] [-t SIMULATION_FILE] [-2] [-f] [-m]
optional arguments:
-h, --help show this help message and exit
-V, --version Show version info
-t SIMULATION_FILE, --simulation_file SIMULATION_FILE
Path to the configuration file. Defaults to
config_small
-2, --show-on-second-monitor
Show simulator window on second monitor instead,
default is first monitor
-f, --fullscreen Show simulator fullscreen
-m, --maximized Show simulator maximized
After settings up the simulator and starting the brick scripts there are several ways to influence the simulator. The following key binding are available:
- q : quit the simulator
- m : maximize simulator window
- f : show simulator fullscreen (toggle)
- t : toggle screen on which to show simulator in fullscreen mode.
The cursor can be used to drag robots and obstacles or to resize the playing field. Left-click dragging, moves objects to a different position, right-mouse dragging rotates objects. Dragging the outer border of the window rescales the window.
To reset the playing field, all scripts controlling bricks should be stopped. If you want to change the script of a brick, stop the current script. The simulator will request the start of a script for the brick that was stopped.
To support communication between bricks, the PyBluez BluetoothSocket is also simulated by the ev3dev2simulator. The Bluetooth connection is simulated using a regular TCP/IP socket as shown in the figure below. To use Bluetooth, import the globally available module using import bluetooth. An example on how to use Bluetooth can be found here.
