Skip to content

Home

Jump to bottom
Harco Kuppens edited this page Dec 6, 2022 · 26 revisions

Welcome to the ev3dev2simulator wiki! 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 with the exact same scripts. The simulator will request a script to be run for each brick that is configured in the simulator. This page contains the user manual showing how the simulator can be used. For information on how the simulator internally works, please consult the technical specification.

User manual

The simulator is designed specifically to simulate bricks running the operating system ev3dev and its corresponding ev3dev Python library. The second version of this library is called 'ev3dev2'. The simulator is currently developed to support version 2.0.0b5 of the ev3dev2 library. The simulator is tested with version 3.8 of Python, but should work also for newer versions.

The simulator can be configured to simulate multiple robots that each consist of multiple bricks. Multiple bricks on a robot are useful to allow additional sensors and actuators to be connected. The software created by the user that would be run on a brick 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. There are two predefined playing fields included with the simulator, a small field with a small robot, and a big playing field with a big robot. It is also possible to create your own playing field and robots.

To support communication between bricks, the PyBluez BluetoothSocket is also simulated by the ev3dev2simulator. To use Bluetooth, import the globally available module using import bluetooth.

Getting started

The only prerequisites for the simulator are python 3.8.10 and pip. Simulating robot sound works out of the box for Windows and macOS users. Linux user need to install espeak.

First, for windows users it is strongly adviced to install python 3.8.10. For this python version the installation goes smoothly because there are precompiled binary wheels available for all dependencies. Newer versions of python will also work, but then you need a c build environment installed to build the c-code of the simpleaudio package. For macos and linux a c build environment is standard available and install with compiling c-code will not be a problem.

The only prerequisites for the simulator are python 3.8.10 and pip. Simulating robot sound works out of the box for Windows and macOS users. Linux user need to install espeak.

First, for windows users it is strongly adviced to install python 3.8.10. For this python version the installation goes smoothly because there are precompiled binary wheels available for all dependencies. Newer versions of python will also work, but then you need a c build environment installed to build the c-code of the simpleaudio package. For macos and linux a c build environment is standard available and install with compiling c-code will not be a problem.

First install python3

 Download Python 3.8.10 from the Python website (https://www.python.org/downloads/). 
 Note: 3.8.10 is the latest 3.8 version with installers.

The simulator is installed with pip using the following command:

pip install ev3dev2simulator

After installation, the simulator can be run with the command:

ev3dev2simulator

Based 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 in a terminal on your own computer. After starting one script, the simulator will tell which script should be started next (if the configuration consists of multiple bricks). An example of a scripts that works 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
from ev3dev2._platform.ev3 import INPUT_2
from ev3dev2.sensor.lego import ColorSensor

def drive():
    tank_drive.on(SpeedPercent(30), SpeedPercent(30))


tank_drive = MoveTank(OUTPUT_A, OUTPUT_D)
cs = ColorSensor(INPUT_2)

drive()
while True:
    if cs.color != 6:
        tank_drive.stop()
        tank_drive.on_for_rotations(SpeedPercent(-35), SpeedPercent(-35), 1)
        tank_drive.on_for_degrees(SpeedPercent(40), SpeedPercent(0), 300)
        drive()

Configuring the simulator

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. See the image below on the left.
  • '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. See the image below on the right, but ignore one of the two robots.
  • 'config_large2', same as 'config_large', but with two big mars rovers. See the image below on the right.

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. Two standard playing fields are shown below. The robots can either be configured by describing its parts in the playing field file or seperately described and referenced in the configuration file by describing the robot type. The two included types are: large_robot and small_robot. Use a relative path to your files instead of the predefined types to include your own robot type.

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

Please note that the exact behaviour of the last 3 options are highly dependant on the used graphics card and operating system. If they seem to fail, see the section below to adjust the size of the screen while the simulator is running.

Using the simulator

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 in fullscreen mode; toggle only works at 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 of that brick. The simulator will request the start of the script for the brick that was stopped.

Single instance

The ev3dev2simulator enforces that only one instance of the simulator can be run.

When a simulator is running, and you then startup a new simulator window:

  • the new simulator sees that another simulator is already running and exits
  • the already simulator's window is raised so that it becomes visible again.

Features not yet supported

The simulator does not yet support the full ev3dev2 API. When looking at the ev3dev2 API's source files, the below listed functions, classes, or specific class methods are not yet supported.

We list what is NO supported, so the rest is supported. Meaning:

  • if only a specific python file is listed, then that whole file is not supported. Python files not listed ARE fully supported.
  • if within a python file a specific class/function is listed, then that class/function is not supported but all other class/functions in that file ARE supported.
  • if specific for a class a set of methods are listed, those methods are not supported, but the class itself and the other methods in the class ARE supported.

The current not supported listing is:

button.py
console.py

control/init.py
control/GyroBalance.py
control/rc_tank.py
control//webserver.py

display.py

motor.py

  • class ActuonixL1250Motor
  • class ActuonixL12100Motor
  • class DcMotor
  • class ServoMotor
  • class MoveJoystick

port.py
power.py

sensor/init.py

  • def list_sensors

  • class Sensor

    • def bin_data()

  • class I2cSensor

sensor/lego.py

  • class ColorSensor

    • def ambient_light_intensity()

  • class UltrasonicSensor

    • def other_sensor_present()

  • class GyroSensor

  • class InfraredSensor

  • class SoundSensor

  • class LightSensor

sound.py

  • def get_command_processes()

  • Class Sound

    • def get_volume()
    • def set_volume()
    • def get_channel()
Clone this wiki locally