API documentation

LEGO EV3 direct commands

Static methods

LCX

Translates an integer into a direct command compatible number with identification byte. It is used for input arguments of operations, which are not read from global or local memory. Dependent from the value an LCX will be a byte string of one, two, three or 5 bytes length.

ev3_dc.LCX(value: int) → bytes

create a LC0, LC1, LC2, LC4, dependent from the value

Positional Argument

value

integer value as argument of a direct command

LCS

Adds a leading identification byte and an ending zero terminator to an ascii string and returns a byte string.

ev3_dc.LCS(value: str) → bytes

pack a string into a LCS by adding a leading and a trailing byte

Positional Argument

value

string as argument of a direct command

LVX

Translates a local memory adress into a direct command compatible format with identification byte. This can be used for input or output arguments of operations.

ev3_dc.LVX(value: int) → bytes

create a LV0, LV1, LV2, LV4, dependent from the value

Positional Argument

value

position (bytes address) in the local memory

GVX

Translates a global memory adress into a direct command compatible format with identification byte. This can be used for input or output arguments of operations.

ev3_dc.GVX(value: int) → bytes

create a GV0, GV1, GV2, GV4, dependent from the value

Positional Argument

value

position (bytes address) in the global memory

port_motor_input

Allows to use well known motor ports of output commands for input commands too.

ev3_dc.port_motor_input(port_output: int) → bytes

get corresponding input motor port (from output motor port)

Positional Argument

port_output

motor port number

pid

pid is a PID controller. It continuously adjusts a system by periodically calculating a signal value from a measured variable. Function pid() does the setup and returns the controller, which is a function (with this signature: signal(value: float) -> float).

ev3_dc.pid(setpoint: float, gain: float, *, time_int: float = None, time_der: float = None) → Callable

Parametrize a new PID controller (standard form)

A PID controller derives a control signal from a measurement value

Mandatory positional arguments

setpoint

target value of the measurement

gain

proportional gain, high values result in fast adaption, but too high values produce oscillations or instabilities

Optional keyword only arguments

time_int

time of the integrative term [s] (approx. the time for elimination), compensates errors from the past (e.g. steady-state error) small values produce oscillations or instabilities and increase settling time

time_der

time of the derivative term [s] (approx. the forecast time), damps oszillations, decreases overshooting and reduces settling time but reacts sensitive on noise

Returns

function signal(value: float) -> float

Classes

EV3

EV3 establishes a connection between your computer and the EV3 device. It allows to send direct and system commands and receive their replies.

class ev3_dc.EV3(*, protocol: str = None, host: str = None, ev3_obj: Optional[ev3_dc.ev3.EV3] = None, sync_mode: str = None, verbosity=0)

communicates with a LEGO EV3 using direct or system commands

Establish a connection to a LEGO EV3 device

Keyword arguments (either protocol and host or ev3_obj)

protocol

‘Bluetooth’, ‘USB’ or ‘WiFi’

host

MAC-address of the LEGO EV3 (e.g. ‘00:16:53:42:2B:99’)

ev3_obj

existing EV3 object (its connections will be used)

sync mode (standard, asynchronous, synchronous)

STD - if reply then use DIRECT_COMMAND_REPLY and wait for reply.

ASYNC - if reply then use DIRECT_COMMAND_REPLY, but never wait for reply (it’s the task of the calling program).

SYNC - Always use DIRECT_COMMAND_REPLY and wait for reply, which may be empty.

verbosity

level (0, 1, 2) of verbosity (prints on stdout).

send_direct_cmd(ops: bytes, *, local_mem: int = 0, global_mem: int = 0, sync_mode: str = None, verbosity: int = None) → bytes

Send a direct command to the LEGO EV3

Mandatory positional arguments

ops

holds netto data only (operations), these fields are added:

length: 2 bytes, little endian

msg_cnt: 2 bytes, little endian

type: 1 byte, DIRECT_COMMAND_REPLY or DIRECT_COMMAND_NO_REPLY

header: 2 bytes, holds sizes of local and global memory

Optional keyword only arguments

local_mem

size of the local memory

global_mem

size of the global memory

sync_mode

synchronization mode (STD, SYNC, ASYNC)

verbosity

level (0, 1, 2) of verbosity (prints on stdout).

Returns

STD (sync_mode)

if global_mem > 0 then reply else message counter

ASYNC (sync_mode)

message counter

SYNC (sync_mode)

reply of the LEGO EV3

send_system_cmd(cmd: bytes, *, reply: bool = True, verbosity: int = None) → bytes

Send a system command to the LEGO EV3

Mandatory positional arguments

cmd

holds netto data only (cmd and arguments), these fields are added:

length: 2 bytes, little endian

msg_cnt: 2 bytes, little endian

type: 1 byte, SYSTEM_COMMAND_REPLY or SYSTEM_COMMAND_NO_REPLY

Optional keyword only arguments

reply

flag if with reply

verbosity

level (0, 1, 2) of verbosity (prints on stdout).

Returns

reply (in case of SYSTEM_COMMAND_NO_REPLY: msg_cnt)

wait_for_reply(msg_cnt: bytes, *, verbosity: int = None) → bytes

Ask the LEGO EV3 for a reply and wait until it is received

Mandatory positional arguments

msg_cnt

is the message counter of the corresponding send_direct_cmd

Optional keyword only arguments

verbosity

level (0, 1, 2) of verbosity (prints on stdout).

Returns

reply to the direct command (without len, msg_cnt and return status)

battery

battery voltage [V], current [A] and percentage (as named tuple)

host

mac address of EV3 device

memory

total and free memory [kB] (as named tuple)

name

name of EV3 device

network

name, ip_adr and mac_adr of the EV3 device (as named tuple)

available only for WiFi connected devices, mac_adr is the address of the WiFi dongle

protocol

connection type

sensors

all connected sensors and motors at all ports (as named tuple Sensors)

You can address a single one by e.g.: ev3_dc.EV3.sensors.Port_3 or ev3_dc.EV3.sensors.Port_C

sensors_as_dict

all connected sensors and motors at all ports (as dict)

You can address a single one by e.g.: ev3_dc.EV3.sensors_as_dict[ev3_dc.PORT_1] or ev3_dc.EV3.sensors_as_dict[ev3_dc.PORT_A_SENSOR]

sleep

idle minutes until EV3 shuts down, values from 0 to 120

value 0 says: never shut down

sync_mode

sync mode (standard, asynchronous, synchronous)

STD

use DIRECT_COMMAND_REPLY only if global_mem > 0, wait for reply if there is one.

ASYNC

use DIRECT_COMMAND_REPLY only if global_mem > 0, never wait for reply (it’s the task of the calling program).

SYNC

always use DIRECT_COMMAND_REPLY and wait for reply.

The idea is

ASYNC - if there is a reply, it must explicitly be asked for. Control directly comes back.

SYNC - EV3 device is blocked and control comes back, when direct command is finished, which means synchronicity of program and EV3 device.

STD - direct commands with no reply are handled like ASYNC, direct commands with reply are handled like SYNC.

system

system versions and build numbers (as named tuple System)

os_version

operating system version

os_build

operating system build number

fw_version

firmware version

fw_build

firmware build number

hw_version

hardware version

verbosity

level of verbosity (prints on stdout), values 0, 1 or 2

volume

sound volume [%], values from 0 to 100

Touch

Touch is a subclass of EV3 and allows to read data from a touch sensor, which may be an EV3-Touch or a NXT-Touch.

class ev3_dc.Touch(port: bytes, *, protocol: str = None, host: str = None, ev3_obj: ev3_dc.ev3.EV3 = None, sync_mode: str = None, verbosity=0)

EV3 touch, controls a single touch sensor

Positional Arguments

port

port of touch sensor (PORT_1, PORT_2, PORT_3 or PORT_4)

Keyword only Arguments (either protocol and host or ev3_obj)

protocol

either ev3_dc.BLUETOOTH, ev3_dc.USB or ev3_dc.WIFI

host

mac-address of the LEGO EV3 (e.g. ‘00:16:53:42:2B:99’)

ev3_obj

an existing EV3 object (its connections will be used)

sync mode (standard, asynchronous, synchronous)

STD - if reply then use DIRECT_COMMAND_REPLY and wait for reply.

ASYNC - if reply then use DIRECT_COMMAND_REPLY, but never wait for reply (it’s the task of the calling program).

SYNC - Always use DIRECT_COMMAND_REPLY and wait for reply, which may be empty.

verbosity

level (0, 1, 2) of verbosity (prints on stdout).

clear() → None

clears bump counter of touch sensor

bumps

number of bumps since last clearing of bump counter

port

port, where touch sensor is connected (PORT_1, PORT_2, PORT_3 or PORT_4)

sensor_type

type of sensor

touched

flag, that tells if sensor is currently touched

Infrared

Infrared is a subclass of EV3 and allows to read data from an infrared sensor. It uses three modes of the infrared sensor:

• proximity mode, which measures the distance between the sensor an a surface in front of the sensor.
• seeker mode, which measures the position (heading and distance) of up to four beacons.
• remode mode, which reads the currently pressed buttons of up to four beacons.

class ev3_dc.Infrared(port: bytes, *, protocol: str = None, host: str = None, ev3_obj: ev3_dc.ev3.EV3 = None, channel: int = None, verbosity=0)

controls a single infrared sensor

Positional Arguments

port

port of infrared sensor (PORT_1, PORT_2, PORT_3 or PORT_4)

Keyword only Arguments (either protocol and host or ev3_obj)

protocol

either ev3_dc.BLUETOOTH, ev3_dc.USB or ev3_dc.WIFI

host

mac-address of the LEGO EV3 (e.g. ‘00:16:53:42:2B:99’)

ev3_obj

an existing EV3 object (its already established connection will be used)

channel

beacon sends on this channel (1, 2, 3, 4)

verbosity

level (0, 1, 2) of verbosity (prints on stdout).

beacon

heading and distance [m] of detected the beacon (seeker mode). returned heading is between -25 and 25.

-25 stands for far left

0 stands for straight forward

25 stands for far right

returned distance is between 0.01 and 1.00 m.

returns either None or namedtuple Beacon with heading and distance

beacons

headings and distances [m] of detected beacons (seeker mode). returned headings are between -25 and 25:

-25 stands for far left

0 stands for straight forward

25 stands for far right

returned distances are between 0.01 and 1.00 m.

returns a tuple of four items, one per channel. Each of them is either None or a namedtuple Beacon with heading and distance

channel

selected channel, on which the beacon sends

distance

distance [m], where the sensor detected something (proximity mode). returned distances are between 0.01 and 1.00 m. None stands for ‘seen nothing’.

port

port, where sensor is connected (PORT_1, PORT_2, PORT_3 or PORT_4)

remote

heading and distance [m] of detected beacon (remote mode) returned heading is between -25 and 25:

-25 stands for far left

0 stands for straight forward

25 stands for far right

returned distance is between 0.01 and 1.00 m.

returns either None or namedtuple Beacon with heading and distance

remotes

headings and distances [m] of detected beacons (remote mode). returned headings are between -25 and 25:

-25 stands for far left

0 stands for straight forward

25 stands for far right

returned distances are between 0.01 and 1.00 m.

returns a tuple of four items, each of them is either None or a namedtuple Beacon with heading and distance

Ultrasonic

Ultrasonic is a subclass of EV3 and allows to read data from an ultrasonic sensor, which may be an EV3-Ultrasonic or a NXT-Ultrasonic. It uses mode EV3-Ultrasonic-Cm (resp. NXT-Ultrasonic-Cm).

class ev3_dc.Ultrasonic(port: bytes, *, protocol: str = None, host: str = None, ev3_obj: ev3_dc.ev3.EV3 = None, verbosity=0)

controls a single ultrasonic sensor in cm mode

Positional Arguments

port

port of ultrasonic sensor (PORT_1, PORT_2, PORT_3 or PORT_4)

Keyword only Arguments (either protocol and host or ev3_obj)

protocol

either ev3_dc.BLUETOOTH, ev3_dc.USB or ev3_dc.WIFI

host

mac-address of the LEGO EV3 (e.g. ‘00:16:53:42:2B:99’)

ev3_obj

an existing EV3 object (its already established connection will be used)

verbosity

level (0, 1, 2) of verbosity (prints on stdout).

distance

distance [m] ahead, where the sensor detected something

distances are between 0.01 and 2.55 m. None stands for ‘seen nothing’

port

port, where sensor is connected (PORT_1, PORT_2, PORT_3 or PORT_4)

sensor_type

type of sensor

Color

Color is a subclass of EV3 and allows to read data from a color sensor, which may be an EV3-Color or a NXT-Color. It uses modes EV3-Color-Reflected, (resp. NXT-Color-Reflected).

class ev3_dc.Color(port: bytes, *, protocol: str = None, host: str = None, ev3_obj: ev3_dc.ev3.EV3 = None, channel: int = None, verbosity=0)

controls a single color sensor

Mandatory positional Arguments

port

port of color sensor (PORT_1, PORT_2, PORT_3 or PORT_4)

Keyword only Arguments (either protocol and host or ev3_obj)

protocol

either ev3_dc.BLUETOOTH, ev3_dc.USB or ev3_dc.WIFI

host

mac-address of the LEGO EV3 (e.g. ‘00:16:53:42:2B:99’)

ev3_obj

an existing EV3 object (its already established connection will be used)

verbosity

level (0, 1, 2) of verbosity (prints on stdout).

ambient

intensity of ambient light in percent [0 - 100]

uses modes EV3-Color-Ambient or NXT-Color-Ambient

color

surface color in front of the sensor

0: none, 1: black, 2: blue, 3: green, 4: yellow, 5: red, 6: white, 7: brown

uses modes EV3-Color-Color or NXT-Color-Color

port

port, where sensor is connected (PORT_1, PORT_2, PORT_3 or PORT_4)

reflected

intensity of the reflected (red) light in percent [0 - 100]

uses modes EV3-Color-Reflected or NXT-Color-Reflected

rgb

surface color in front of the sensor as red, green, blue intensities

intensities are white balanced reflected light intensities [0 - 255]

uses mode EV3-Color-Color, does not work with NXT-Color-Color

rgb_raw

surface color in front of the sensor as red, green, blue intensities

intensities are reflected light intensities [0 - 1024]

uses mode EV3-Color-Color, does not work with NXT-Color-Color

rgb_white_balance

perfect white surface in front of the sensor for calibration

returned intensities are raw reflected light intensities [0 - 1024]

uses mode EV3-Color-Color, does not work with NXT-Color-Color

Gyro

Gyro is a subclass of EV3 and allows to read data from a gyro sensor (EV3-Gyro). It uses mode EV3-Gyro-Rate & Angle.

class ev3_dc.Gyro(port: bytes, *, protocol: str = None, host: str = None, ev3_obj: ev3_dc.ev3.EV3 = None, verbosity=0)

controls a single gyro sensor

Positional Arguments

port

port of gyro sensor (PORT_1, PORT_2, PORT_3 or PORT_4)

Keyword only Arguments (either protocol and host or ev3_obj)

protocol

either ev3_dc.BLUETOOTH, ev3_dc.USB or ev3_dc.WIFI

host

mac-address of the LEGO EV3 (e.g. ‘00:16:53:42:2B:99’)

ev3_obj

an existing EV3 object (its already established connection will be used)

verbosity

level (0, 1, 2) of verbosity (prints on stdout).

reset(angle=0) → int

define current angle to be angle 0 (or another given value)

Optional keyword only arguments

angle

sets the current angle to this value

Returns

current angle in previous normalization

angle

angle [degree] measured by gyro sensor

port

port, where sensor is connected (PORT_1, PORT_2, PORT_3 or PORT_4)

rate

rate [degree/second] measured by gyro sensor

sensor_type

type of sensor

state

angle [degree] and rate [degree/second] measured by gyro sensor

Sound

Sound is a subclass of EV3 and provides higher order methods for the EV3 sound.

class ev3_dc.Sound(*, protocol: str = None, host: str = None, ev3_obj: ev3_dc.ev3.EV3 = None, verbosity: int = 0, volume: int = None)

basic sound functionality

Keyword only arguments (either protocol and host or ev3_obj)

protocol

either ev3_dc.BLUETOOTH, ev3_dc.USB or ev3_dc.WIFI

host

mac-address of the LEGO EV3 (e.g. ‘00:16:53:42:2B:99’)

ev3_obj

an existing EV3 object (its already established connection will be used)

verbosity

level (0, 1, 2) of verbosity (prints on stdout).

volume

sound volume [%], values from 0 to 100

duration(path: str, *, local: bool = False) → float

detemines duration of a sound file by reading its header

Mandatory positional arguments

path

name of the sound file (may be without extension “.rsf”) as absolute path, or relative to /home/root/lms2012/sys/

Optional keyword only arguments

local

flag, if path is a location on the local host

play_sound(path: str, *, volume: int = None, repeat: bool = False, local: bool = False) → None

plays a sound file

Mandatory positional arguments

path

name of the sound file (may be without extension “.rsf”) as absolute path, or relative to /home/root/lms2012/sys/

Keyword only arguments

volume

volume [0 - 100] of tone (defaults to attribute volume)

repeat

flag, if repeatedly playing

local

flag, if path is a location on the local host (PC)

sound(path: str, *, volume: int = None, duration: float = None, repeat: bool = False, local: bool = False) → thread_task.task.Task

returns a Task object, which plays a sound file

Mandatory positional arguments

path

name of the sound file (may be without extension “.rsf”) as absolute path, or relative to /home/root/lms2012/sys/

Optional keyword only arguments

volume

volume [0 - 100] of tone (defaults to attribute volume)

duration

total duration in sec., in combination with repeat, this means interruption,

repeat

flag, if repeatedly playing (unlimited if no duration is set)

local

flag, if path is a location on the local host

stop_sound() → None

stops the sound

tone(freq: int, *, duration: numbers.Number = None, volume: int = None) → None

plays a tone

Mandatory positional arguments

freq

frequency of tone, range [250 - 10000]

Optional keyword only arguments

duration

duration (sec.) of the tone (no duration means forever)

volume

volume [0 - 100] of tone

Jukebox

Jukebox is a subclass of Sound and provides higher order methods for tones and LEDs.

class ev3_dc.Jukebox(*, protocol: str = None, host: str = None, ev3_obj: ev3_dc.ev3.EV3 = None, volume: int = None, temperament: int = 440, verbosity: int = 0)

plays songs and uses LEDs

Keyword only arguments (either protocol and host or ev3_obj)

protocol

either ev3_dc.BLUETOOTH, ev3_dc.USB or ev3_dc.WIFI

host

mac-address of the LEGO EV3 (e.g. ‘00:16:53:42:2B:99’)

ev3_obj

an existing EV3 object (its already established connection will be used)

volume

sound volume [%], values from 0 to 100

temperament

temperament of the tones (default: 440 Hz)

verbosity

level (0, 1, 2) of verbosity (prints on stdout).

change_color(led_pattern: bytes) → None

changes LED color

Positional arguments:

led_pattern:

color of LEDs, f.i. ev3.LED_RED

play_tone(tone: str, *, duration: numbers.Number = None, volume: int = None) → None

plays a tone

Mandatory positional arguments

tone

name of tone f.i. “c’”, “cb’’”, “c#”

Optional keyword only arguments

duration

length (sec.) of the tone (no duration means forever)

volume

volume [0 - 100] of tone (defaults to attribute volume)

song(song: dict, *, volume: int = None) → thread_task.task.Task

returns a Task object, that plays a song

Mandatory positional arguments

song

dict with song data (e.g. ev3.HAPPY_BIRTHDAY)

Keyword only arguments

volume

volume [0 - 100] of tone (defaults to attribute volume)

temperament

temperament of the tones (default: 440 Hz)

Voice

Voice is a subclass of Sound and provides higher order methods for speaking. It supports text to speech and calls gTTS, which needs an internet connection. Voice allows to select the language, the top level domain and a slower reading speed by supporting gTTS’s attributes lang, tld and slow.

gTTS answers with mp3 data, therefore Voice calls ffmpeg to convert mp3 to pcm. If ffmpeg is not installed on your system, Voice will not work.

class ev3_dc.Voice(*, protocol: str = None, host: str = None, ev3_obj: ev3_dc.ev3.EV3 = None, volume: int = None, lang: str = 'en', tld: str = 'com', slow: bool = False, verbosity: int = 0)

lets the EV3 device speak tts (text to sound)

Keyword only arguments (either protocol and host or ev3_obj)

protocol

either ev3_dc.BLUETOOTH, ev3_dc.USB or ev3_dc.WIFI

host

mac-address of the LEGO EV3 (e.g. ‘00:16:53:42:2B:99’)

ev3_obj

an existing EV3 object (its already established connection will be used)

filesystem

already existing FileSystem object

volume

sound volume [%], values from 0 to 100

lang

language, e.g. ‘it’, ‘fr, ‘de’, ‘en’ (default)

verbosity

level (0, 1, 2) of verbosity (prints on stdout).

speak(txt: str, *, lang: str = None, tld: str = None, slow: bool = None, duration: numbers.Number = None, volume: int = None) → thread_task.task.Task

let the EV3 device speak some text

Mandatory positional arguments

txt

text to speak

Optional keyword only arguments

lang

language, e.g. ‘it’, ‘fr, ‘de’, ‘en’ (default)

tld

top level domain of google server, e.g. ‘de’, ‘co.jp’, ‘com’ (default)

slow

reads text more slowly. Defaults to False

duration

length (sec.) of the tone (no duration means forever)

volume

volume [0 - 100] of tone (defaults to attribute volume)

Motor

Motor is a subclass of EV3 and provides higher order methods for motor movements.

class ev3_dc.Motor(port: int, *, protocol: str = None, host: str = None, ev3_obj: ev3_dc.ev3.EV3 = None, speed: int = 10, ramp_up: int = 15, ramp_up_time: float = 0.15, ramp_down: int = 15, ramp_down_time: float = 0.15, delta_time: numbers.Number = None, verbosity: int = 0)

EV3 motor, moves a single motor

Mandatory positional arguments

port

port of motor (PORT_A, PORT_B, PORT_C or PORT_D)

Keyword only arguments (either protocol and host or ev3_obj)

protocol

BLUETOOTH == ‘Bluetooth’ USB == ‘Usb’ WIFI == ‘WiFi’

host

mac-address of the LEGO EV3 (f.i. ‘00:16:53:42:2B:99’)

ev3_obj

an existing EV3 object (its connections will be used)

speed

percentage of maximum speed [1 - 100] (default is 10)

ramp_up

degrees for ramp-up (default is 15)

ramp_up_time

duration of ramp-up (used by move_for, default is 0.1 sec.)

ramp_down

degrees for ramp-down (default is 15)

ramp_down_time

duration of ramp-down (used by move_for, default is 0.1 sec.)

delta_time

timespan between introspections [s] (default depends on protocol, USB: 0.2 sec., WIFI: 0.1 sec., USB: 0.05 sec.)

verbosity

level (0, 1, 2) of verbosity (prints on stdout).

cont() → None

continues a stopped movement

cont_as_task() → thread_task.task.Task

continues a stopped movement

Returns

thread_task.Task object, which does the continuing

move_by(degrees: int, *, speed: int = None, ramp_up: int = None, ramp_down: int = None, brake: bool = False, duration: numbers.Number = None) → thread_task.task.Task

exact and smooth movement of the motor by a given angle.

Positional Arguments

degrees

direction (sign) and angle (degrees) of movement

Keyword Arguments

speed

percentage of maximum speed [1 - 100]

ramp_up

degrees for ramp-up

ramp_down

degrees for ramp-down

brake

Flag if ending with floating motor (False) or active brake (True).

duration

duration of Task execution [s] (waits if movement lasts shorter)

Returns

Task object, that can be started, stopped and continued.

move_for(duration: float, *, speed: int = None, direction: int = 1, ramp_up_time: float = None, ramp_down_time: float = None, brake: bool = False) → thread_task.task.Task

start moving the motor for a given duration.

Mandatory positional arguments

duration

duration of the movement [sec.]

Optional keyword only arguments

speed

percentage of maximum speed [1 - 100]

direction

direction of movement (-1 or 1)

ramp_up_time

duration time for ramp-up [sec.]

ramp_down_time

duration time for ramp-down [sec.]

brake

flag if ending with floating motor (False) or active brake (True).

Returns

Task object, which can be started, stopped and continued.

move_to(position: int, *, speed: int = None, ramp_up: int = None, ramp_down: int = None, brake: bool = False, duration: numbers.Number = None) → thread_task.task.Task

move the motor to a given position.

Mandatory positional arguments

position

target position (degrees)

Optional keyword only arguments

speed

percentage of maximum speed [1 - 100]

ramp_up

degrees for ramp-up

ramp_down

degrees for ramp-down

brake

flag if ending with floating motor (False) or active brake (True).

duration

duration of Task execution [s] (waits if movement lasts shorter)

Returns

Task object, which can be started, stopped and continued.

start_move(*, speed: int = None, direction: int = 1, ramp_up_time: float = None) → None

starts unlimited movement of the motor.

Optional keyword only arguments

speed

percentage of maximum speed [1 - 100]

direction

direction of movement (-1 or 1)

ramp_up_time

duration time for ramp-up [sec.]

start_move_by(degrees: int, *, speed: int = None, ramp_up: int = None, ramp_down: int = None, brake: bool = False, _control: bool = False) → None

starts moving the motor by a given angle (without time control).

Positional Arguments

degrees

direction (sign) and angle (degrees) of movement

Keyword Arguments

speed

percentage of maximum speed [1 - 100]

ramp_up

degrees for ramp-up

ramp_down

degrees for ramp-down

brake

Flag if ending with floating motor (False) or active brake (True).

start_move_for(duration: float, *, speed: int = None, direction: int = 1, ramp_up_time: float = None, ramp_down_time: float = None, brake: bool = False, _control: bool = False) → None

start moving the motor for a given duration.

Mandatory positional arguments

duration

duration of the movement [sec.]

Optional keyword only arguments

speed

percentage of maximum speed [1 - 100]

direction

direction of movement (-1 or 1)

ramp_up_time

duration time for ramp-up [sec.]

ramp_down_time

duration time for ramp-down [sec.]

brake

flag if ending with floating motor (False) or active brake (True).

start_move_to(position: int, *, speed: int = None, ramp_up: int = None, ramp_down: int = None, brake: bool = False, _control: bool = False)

start moving the motor to a given position (without time control).

Mandatory positional arguments

position

target position (degrees)

Optional keyword only arguments

speed

percentage of maximum speed [1 - 100]

ramp_up

degrees for ramp-up

ramp_down

degrees for ramp-down

brake

flag if ending with floating motor (False) or active brake (True).

stop(*, brake: bool = False) → None

stops the current motor movement, sets or releases brake

Keyword Arguments

brake

flag if stopping with active brake

stop_as_task(*, brake: bool = False) → thread_task.task.Task

stops the current motor movement, with or without brake (can be used to release brake)

Optional keyword only arguments

brake

flag if stopping with active brake

Returns

thread_task.Task object, which does the stopping

busy

Flag if motor is currently busy

delta_time

timespan between introspections [s]

motor_type

type of motor (7: EV3-Large, 8: EV3-Medium, )

port

port of motor (default: PORT_A)

position

current position of motor [degree]

ramp_down

degrees for ramp-down (default is 15)

ramp_down_time

seconds for ramp-down of timed movements (default is 0.1)

ramp_up

degrees for ramp-up (default is 15)

ramp_up_time

seconds for ramp-up of timed movements (default is 0.1)

speed

speed of movements in percentage of maximum speed [1 - 100] (default is 10)

TwoWheelVehicle

TwoWheelVehicle is a subclass of EV3 and provides higher order methods for moving or driving a vehicle with two drived wheels. It tracks the position of the vehicle.

class ev3_dc.TwoWheelVehicle(radius_wheel: numbers.Number, tread: numbers.Number, *, protocol: str = None, host: str = None, ev3_obj: ev3_dc.ev3.EV3 = None, speed: int = 10, ramp_up: int = 30, ramp_down: int = 30, delta_time: numbers.Number = None, port_left: bytes = 1, port_right: bytes = 8, polarity_left: int = 1, polarity_right: int = 1, tracking_callback: Callable = None, verbosity: int = 0)

EV3 vehicle with two drived wheels

Establishes a connection to a LEGO EV3 device

Mandatory positional arguments

radius_wheel

radius of the wheels [m]

tread:

the vehicles tread [m]

Keyword only arguments (either protocol and host or ev3_obj)

protocol

BLUETOOTH == ‘Bluetooth’, USB == ‘Usb’, WIFI == ‘WiFi’

host

mac-address of the LEGO EV3 (e.g. ‘00:16:53:42:2B:99’)

ev3_obj

an existing EV3 object (its connections will be used)

speed

percentage of maximum speed [1 - 100] (default is 10)

ramp_up

degrees for ramp-up (default is 30)

ramp_down

degrees for ramp-down (default is 30)

delta_time

timespan between introspections [s] (default depends on protocol, USB: 0.2 sec., WIFI: 0.1 sec., USB: 0.05 sec.)

port_left

port of left motor (PORT_A, PORT_B, PORT_C or PORT_D)

port_right

port of right motor (PORT_A, PORT_B, PORT_C or PORT_D)

polarity_left

polarity of left motor rotation, values: -1, 1 (default)

polarity_right

polarity of right motor rotation, values: -1, 1 (default)

tracking_callback

callable, which frequently tells current position, its single argument must be of type VehiclePosition

verbosity

level (0, 1, 2) of verbosity (prints on stdout)

cont() → None

continues stopped movement

drive_straight(distance: numbers.Number, *, speed: int = None, ramp_up: int = None, ramp_down: int = None, brake: bool = False) → thread_task.task.Task

drives the vehicle straight by a given distance

Mandatory positional arguments

distance

direction (sign) and distance (meters) of straight movement

Optional keyword only arguments

speed

percentage of maximum speed [1 - 100]

ramp_up

degrees for ramp-up

ramp_down

degrees for ramp-down

brake

flag if ending with floating motors (False) or active brake (True).

Returns

Task object, which can be started, stopped and continued.

drive_turn(angle: numbers.Number, radius: numbers.Number, *, speed: int = None, back: bool = False, ramp_up: int = None, ramp_down: int = None, brake: bool = False) → thread_task.task.Task

starts driving the vehicle a turn by given angle and radius

Mandatory positional arguments

angle

angle of turn (degrees), positive sign: to the left, negative sign: to the right

radius

radius of turn (meters)

Optional keyword only arguments

speed

percentage of maximum speed [1 - 100]

back

flag if backwards

ramp_up

degrees for ramp-up

ramp_down

degrees for ramp-down

brake

Flag if ending with floating motors (False) or active brake (True).

Returns

Task object, which can be started, stopped and continued.

move(speed: int, turn: int) → None

Starts unlimited synchronized movement of the vehicle

Mandatory positional arguments

speed

direction (sign) and speed of movement as percentage of maximum speed [-100 - 100]

turn

type of turn [-200 - 200]

-200: circle right on place

-100: turn right with unmoved right wheel

0 : straight

100: turn left with unmoved left wheel

200: circle left on place

stop(brake: bool = False) → None

stops the current motor movements, sets or releases brake

Keyword Arguments

brake

flag if stopping with active brake

busy

Flag if motors are currently busy

motor_pos

current positions of left and right motor [degree] (as named tuple)

polarity_left

polarity of left motor rotation (values: -1, 1, default: 1)

polarity_right

polarity of left motor rotation (values: -1, 1, default: 1)

port_left

port of left wheel (default: PORT_D)

port_right

port of right wheel (default: PORT_A)

position

current vehicle position (as named tuple)

x and x-coordinates are in meter, orientation is in degree [-180 - 180]

ramp_down

degrees for ramp-down

ramp_up

degrees for ramp-up

speed

speed as percentage of maximum speed [1 - 100]

tracking_callback

callable, which frequently tells current vehicle position, its single argument must be of type VehiclePosition

FileSystem

FileSystem is a subclass of EV3 and provides higher order methods for the filesystem of an EV3 device. It allows to read and write EV3’s files or directories.

class ev3_dc.FileSystem(*, protocol: str = None, host: str = None, ev3_obj: Optional[ev3_dc.ev3.EV3] = None, sync_mode: str = None, verbosity=0)

Access to EV3’s filesystem

Establish a connection to a LEGO EV3 device

Keyword arguments (either protocol and host or ev3_obj)

protocol

‘Bluetooth’, ‘USB’ or ‘WiFi’

host

MAC-address of the LEGO EV3 (e.g. ‘00:16:53:42:2B:99’)

ev3_obj

existing EV3 object (its connections will be used)

sync mode (standard, asynchronous, synchronous)

STD - if reply then use DIRECT_COMMAND_REPLY and wait for reply.

ASYNC - if reply then use DIRECT_COMMAND_REPLY, but never wait for reply (it’s the task of the calling program).

SYNC - Always use DIRECT_COMMAND_REPLY and wait for reply, which may be empty.

verbosity

level (0, 1, 2) of verbosity (prints on stdout).

copy_file(path_source: str, path_dest: str) → None

Copies a file in EV3’s file system from its old location to a new one (no error if the file doesn’t exist)

Mandatory positional arguments

path_source

absolute or relative path (from “/home/root/lms2012/sys/”) of the existing file

path_dest

absolute or relative path of the new file

create_dir(path: str) → None

Create a directory in EV3’s file system

Mandatory positional arguments

path

absolute or relative path (from “/home/root/lms2012/sys/”)

del_dir(path: str, *, secure: bool = True) → None

Delete a directory in EV3’s file system

Mandatory positional arguments

path

absolute or relative path (from “/home/root/lms2012/sys/”)

Optional keyword only arguments

secure

flag, if the directory must be empty

del_file(path: str) → None

Delete a file in EV3’s file system

Mandatory positional arguments

path

absolute or relative path (from “/home/root/lms2012/sys/”) of the file

list_dir(path: str) → dict

Read one EV3 directory’s content

Mandatory positional arguments

path

absolute or relative path (from “/home/root/lms2012/sys/”) to the directory (f.i. “/bin”)

Returns

subfolders

tuple of strings (names)

files

tuple of tuples (name:str, size:int, md5:str)

load_file(path_source: str, path_dest: str, *, check: bool = True) → None

Copy a local file to EV3’s file system

Mandatory positional arguments

path_source

absolute or relative path of the existing file in the local file system

path_dest

absolute or relative path (from “/home/root/lms2012/sys/”) in EV3’s file system

Optional keyword only aguments

check

flag for check if file already exists with identical MD5 checksum

read_file(path: str) → bytes

Read one of EV3’s files

Mandatory positional arguments

path

absolute or relative path to file (f.i. “/bin/sh”)

write_file(path: str, data: bytes, *, check: bool = True) → None

Create a file in EV3’s file system and write data into it

Mandatory positional arguments

path

absolute or relative path (from “/home/root/lms2012/sys/”) of the file

data

data to write into the file

Optional keyword only arguments

check

flag for check if file already exists with identical MD5 checksum