home

Documentation Robotics

Module imports:

from simrobot import *
from nxtrobot import *
from ev3robot import *

LegoRobot

Method Action
LegoRobot()

creates a robot (without motors/sensors) and establishes a communication link
[Simulation: displays the simulation window]

addPart(part) adds a part to the robot (motor, sensor, etc.)
clearDisplay() erases the display [Simulation: status bar]
drawString(text, x, y) draws text at position x, y [Simulation: in status bar, (x, y) irrelevant]
isEnterHit() True, if ENTER button was hit [NXT and simulation: keyboard key Enter]
isEscapeHit() True, if ESCAPE button was hit [NXT and simulation: keyboard key Escape]
isLeftHit() True, if LEFT button was hit [NXT and simulation: keyboard key Cursor-left]
isRightHit() True, if RIGHT button was hit [NXT and simulation: keyboard key Cursor-right]
isUpHit() True, if UP button was hit [NXT and simulation: keyboard key Cursor-up]
isDownHit() True, if DOWN button was hit [NXT and simulation: keyboard key Cursor-down]
playTone(frequency, duration) plays a tone with given frequency (in Hz) and duration (ms)
setVolume(volume) sets the sound volume for all sound emissions (0..100)
playSample(tag, volume) plays a WAV file using the given volume (0..100) from folder /home/root/music with file name song<tag>.wav (tag: integer) (non blocking). WAV format: mono, 8 bit unsigned or 16 bit signed with maximum sampling rate 11025 Hz [not available in sim]
playSampleWait(tag, volume) same, but blocking until play is finished [not available in sim]
setAlarm(on) with on = 1 starts a sound alarm signal until the function is called with on = 0
setLED(pattern) sets the EV3 LEDS: 0: off, 1: green, 2: red, 3: red bright, 4: green blinking, 5: red blinking, 6: red blinking bright, 7: green double blinking , 8: red double blinking, 9: red double blinking brightl
exit() stops all motors and terminates the communication link
isConnected() returns True, if the communication link is established [Simulation: Window not closed]
reset() Simulation: sets the robot to the starting position/direction


Gear

Gear() creates a vehicle with motors at port A and B
backward() moves backward (non-blocking method)
backward(ms) moves backward during given time (in ms) (blocking method)
isMoving() returns True, if the vehicle is not at rest
forward() starts moving forward (non-blocking method)
forward(ms) moves forward during given time (in ms) (blocking method)
left() starts turning left (non-blocking method)
left(ms) turns left during given time (in ms) (blocking method)
leftArc(radius) starts turning on left arc with given radius (approx. in m) left (non-blocking method)
leftArc(radius, ms) turns on left arc during given time (in ms) with given radius (approx. in m) left (blocking method)
right() starts turning right (non-blocking method)
right(ms) turns right during given time (in ms) (blocking method)
rightArc(radius) starts turning on right arc with given radius (approx. in m) left (non-blocking method)
rightArc(radius, ms) turns on right arc during given time (in ms) with given radius (approx. in m) left (blocking method)
setSpeed(speed) sets the vehicle speed (0..100). Default speed = 30.
stop() stops the vehicle
getLeftMotorCount() returns current value of left motor counter [not available in sim]
getRightMotorCount() returns current value of right motor counter [not available in sim]
resetLeftMotorCount() sets left motor counter to 0 [not available in sim]
resetRightMotorCount() sets right motor counter to 0 [not available in sim]


TurtleRobot

TurtleRobot() creates a vehicle with motors at port A and B
backward() starts moving backward (non-blocking method)
backward(step) moves backward for the given number of steps (blocking method)
forward() starts moving forward (non-blocking method)
forward(step) moves forward for the given number of steps (blocking method)
left() starts turning left (non-blocking method)
left(angle) turns left for the given angel (approx. degrees) (blocking method)
right() starts turning right (non-blocking method)
right(angle) turns right for the given angel (approx. degrees) (blocking method)
setTurtleSpeed(speed) sets the vehicle speed (0..100)


Motor

Motor(MotorPort.port) creates a motor at Motorport A, B, C or D
backward() starts rotating forward
forward() starts rotating backward
setSpeed(speed) sets the motor speed (0..100)
isMoving() returns True, if the motor is not at rest
stop() stops the motor
getMotorCount() returns current value of motor counter
resetMotorCount() sets motor counter to 0
rotateTo(count) sets counter to 0, moves motor until count and stops (blocking)
rotateTo(count, blocking) same as rotateTo(count), but not blocking for blocking = False
continueTo(count) same as rotateTo(count), but counter is not set to 0
continueTo(count, blocking) same as rotateTo(count, blocking), but counter is not set to 0
continueRelativeTo(count) same as continueTo(count), but count is increment
continueRelativeTo(count, blocking) same as continueTo(count, blocking), but count is increment
setAcceleration(acc) sets starting acceleration (in degrees/sec/sec. Default:: 6000) [not available in sim]


Light Sensor

LightSensor(SensorPort.port)

creates a light sensor at SensorPort S1, S2, S3 or S4
Simulation mode: Port S1: front right, S2: front left, S3: front center, S4: rear center

LightSensor(SensorPort.port, bright = onBright, dark = onDark) same with registered event callbacks onBright(port, value), onDark(port, value) while crossing the trigger level
LightSensor(SensorPort.port, True) Simulationsmode only: creates an upward directed light sensor at SensorPort S1, S2, S3 or S4. Port S1: front right, S2: front left, S3: rear right, S4: rear left
LightSensor(SensorPort.port, True, bright = onBright, dark = onDark) same with registered event callbacks onBright(port, value), onDark(port, value) while crossing the trigger level
getValue() returns the measured light level value (0...1000 approx.)
activate(bool) turns on/off the LED of a NXT LightSensor
setTriggerLevel(level) sets the trigger level (default: 500)


ColorSensor

ColorSensor(SensorPort.port) creates a color sensor at SensorPort S1, S2, S3 or S4
Simulation mode: Port S1: front right, S2: front left, S3: front center, S4: rear center
getColor() returns the measured color as Color object with methods getRed(), getGreen(), getBlue() (RGB value 0..255)
getColorID() returns a color identifier: 0: undefined, 1: black, 2: blue, 3:green, 4: yellow, 5: red, 6: white
getColorStr() returns the measured color as string ("UNDEFINED", "BLACK", "BLUE", "GREEN", "YELLOW", "RED", "WHITE")
getLightValue() returns the luminosity (in HSG model) of the measured color


TouchSensor

TouchSensor(SensorPort.port)

creates a touch sensor at SensorPort S1, S2, S3 or S4
Simulation mode: Port S1: front right, S2: front left, S3: front center, S4: rear center

TouchSensor(SensorPort.port, pressed = onPressed, released = onReleased) same with registered event callbacks onPressed(port), onReleased(port)
isPressed() returns True, if the button is pressed


SoundSensor

SoundSensor(SensorPort.port)

creates a sound sensor at SensorPort S1, S2, S3 or S4
Simulation mode: Sound card input. For EV3, use the NXT sound sensor: NxtSoundSensor(SensorPort.port)

SoundSensor(SensorPort.port, loud = onLoud, quiet = onQuiet) same with registered event callbacks onLoud(port, value), onQuiet(port, value) while crossing the trigger level
getValue() returns the measured sound level value (0...100 approx.)
setTriggerLevel(level) sets the trigger level (default: 50)


UltrasonicSensor

UltrasonicSensor(SensorPort.port) creates an ultrasonic sensor at SensorPort S1, S2, S3 or S4
Simulation mode: S1: forward; S2: left, S3: backward

UltrasonicSensor(SensorPort.port, far = onFar, near = onNear)

same with registered event callbacks onFar(port, value), onNear(port, value) while crossing the trigger level
getDistance() returns the measured distance (in cm approx.; 255, if measurement fails; for simulation mode: -1)
setTriggerLevel(level) sets the trigger level (default: 10)
far(port, level), near(port, level) callback functions that may be registered by named parameters
setProximityCircleColor(color) Simulation: sets the color of the proximity circle
setMeshTriangleColor(color) Simulation: sets the color of the mesh triangles
setBeamAreaColor(color) Simulation: sets the color of the beam area boundaries
eraseBeamArea() Simulation: erases the beam area boundaries

 

GyroRateSensor (only EV3)

GyroRateSensor(SensorPort.port)

creates a GyroRateSensor at SensorPort S1, S2, S3, S4

getValue() returns the angle velocity (degrees per second, positive anit-clockwise)

 

GyroAngleSensor (only EV3)

GyroAngleSensor(SensorPort.port)

creates a GyroAngleSensor at SensorPort S1, S2, S3, S4

getValue() returns the current orientation relative to the start position (degrees anti-clockwise)
reset() sets the start position


InfraredSensor (only EV3)

IRRemoteSensor(SensorPort.port) creates an infrared sensor for remote control at SensorPort S1, S2, S3 or S4
getCommand() returns the current command ID: 0:Nothing,1: TopLeft,2:BottomLeft,3:TopRight, 4:bottomRight
5:TopLeft&TopRight, 6:TopLeft&BottomRight,7:BottomLeft&TopRight,
8:bottomLeft&BottomRight, 9:Centre,10:BottomLeft&TopLeft,11:TopRight&BottomRight
The channel is selected by the red slider switch: 1: top, 4: bottom. It corresponds to the port number, where the sensor is attached.
actionPerformed(port, command)

callback function that may be registered by a named parameter


IRSeekSensor(SensorPort.port)

creates tn infrared search sensor at SensorPort S1, S2, S3 or S4 .
The active IR source of the remote control must be switched on (centre button)

v = getValue() v.bearing returns the direction (-12..12) and v.distance the distance (in cm) to the source.
The channel is selected by the red slider switch: 1: top, 4: bottom. It corresponds to the port number, where the sensor is attached.

IRDistanceSensor(SensorPort.port) creates a infrared distance sensorer at SensorPort S1, S2, S3 or S4 (reflecting target).
getDistance() returns the distance to the target (in cm)


ArduinoLink (only EV3)

ArduinoLink(SensorPort.port) creates an I2C master for the connection to the Arduino at SensorPort S1, S2, S3, S4

getReply(request, reply)

sends the request (integer 0..255) to the Arduino and returns the answer in the given list reply (max.16 integers 0..255)
getReplyInt(request) sends the request (integer 0..255) to the Arduino und returns the answer as integer 0..255
getReplyString(request)

sends the request (integer 0..255) to the Arduino und returns the answer as string (max. 15 ASCII-characters)


TemperatureSensor (only EV3)

TemperatureSensor(SensorPort.port) creates a temperature sensor at SensorPort S1, S2, S3, S4 (Lego NXT Temperature Sensor 9749)
getTemperature() returns the temperature in range -55..128 degrees Celsius


I2CExpander (only EV3)

I2CExpander(SensorPort.port, deviceType, slaveAddress) creates an I2C expander at SensorPort S1, S2, S3, S4. deviceType = 0: PCF8574, 1: PCF8574A, 2: PCF8591; slaveAddress: 8-bit I2C address
I2CExpander(SensorPort.port, deviceType, inputMode, slaveAddress) same, but defines inputMode: 0: single ended, 2: three differential, 3: mixed, 4: two differential (see data sheet PCF8591)

writeDigital(out)

sets the digital input/output (8 bits) and returns the current value. To define a pin as input, the port bit is set to 1. (Only for PCF8574/PCF8574A)
writeAnalog(out) sets the analog ouput (8 bits). (Only for PCF8591)
readAnalog(channel)

returns the current value of channel 0..3 (0..255 for single ended, -128..127 for differential). (Only for PCF8591)

readAnalog() returns list of currenet values of all channels. (Only for PCF8591)


For simulation mode only: RobotContext

setStartDirection(angle) sets the starting direction (0 to east, positive clockwise)
setStartPosition(x, y) sets the starting position (in pixels, zero at upper-left vertex)
showStatusBar(height) adds a status bar with given height at the bottom of the window
setStatusText(text) inserts text into the status bar (old text is erased)
useBackground(filename) inserts the given image into the background to be used by a light or color sensor
useObstacle(filename, x, y) inserts an obstacle at given position to be used by a the touch sensor
useTarget(filename, mesh, x, y) inserts a target at given position to be used by the ultrasonic sensor
useTorch(power, x, y, z) insert ein spot light source with given power at position (x, y, z) (draggable, z: height over floor). The light is detected by light sensors pointing upwards
useShadow(ulx, ul.y, lrx, lry) inserts a rectangle shadow area with upper left vertex (ulx, uly) and lower right vertex (lrx, lry). The shadow absorbs the light from all spot lights.

 

EV3Copy (only EV3, Direct Mode)

EV3Copy.copyFile(ipAddress, sourcePath, targetPath) copies local file sourcePath to targetPath of EV3 with given IP address (e.g. copyFile("10.0.1.1", "c:/test.wav", "/home/root/music/song1.wav")

 


TCP Client/Server Library (only EV3, autonomous mode)

Class TCPServer

server = TCPServer(port, stateChanged, isVerbose = False) creates a TCP socket server that listens on TCP port for a connecting client. State changes are notified by the callback stateChanged(). For isVerbose = True, debug messages are written to output window
stateChanged(state, msg)

Callback called at state change events.
state: TCPServer.PORT_IN_USE, msg: port
state: TCPServer.CONNECTED, msg: IP address of client
state: TCPServer.LISTENING, msg: port
state: TCPSever.TERMINATED, msg: empty
state: TCPServer.MESSAGE, msg: message received from client (string)

server.disconnect() closes the connection with the client and enters the LISTENING state
server.isConnected() True, if a client is connected to the server
server.terminate() closes the connection and terminates the LISTENING state. Releases the IP port
server.isTerminated() True, if the server has been terminated
server.sendMessage(msg) sends the information msg to the client (as string, the character \0 (ASCII 0) serves as end of string indicator, it is transparently added and removed)
TCPServer.getVersion() returns the module version as string

 

Class TCPClient

client = TCPClient(ipAddress, port, stateChanged, isVerbose = False)

creates a TCP socket client prepared for a connection with a TCPServer at given address (string) and port (integer). State changes are notified by the callback stateChanged(). For isVerbose = True, debug messages are written to the output window

stateChanged(state, msg) Callback called at state change events.
state: TCPClient.CONNECTING, msg: IP address:port of server
state: TCPClient.CONNECTION_FAILED, msg: IP address:port of server
state: TCPClient.CONNECTED, msg: IP address:port of server
state: TCPClient.SERVER_OCCUPIED, msg: IP address:port of server
state: TCPClient.DISCONNECTED, msg: empty
state: TCPClient.MESSAGE, msg: message received from server (string)
client.connect() creates a connection to the server (blocking until timeout). Returns True, if the connection is established; otherwise returns False
client.connect(timeout) same, but with timeout (in s) to establish the connection
client.isConnecting() True during a connection trial
client.isConnected() True, if the client is connected to a server
client.disconnect() closes the connection with the server
client.sendMessage(msg, responseTime) sends the information msg to the server (as string, the character \0 (ASCII 0) serves as end of string indicator, it is transparently added and removed). For responseTime > 0 the method blocks and waits for maximum responseTime seconds for a server reply. Returns the message or None, if a timeout occured
TCPClient.getVersion() returns the module version as string

 

Class HTTPServer (inherited from TCPServer)

server = HTTPServer(requestHandler, serverName = "EV3", port = 80, isVerbose = False)

creates and starts a simple HTTP server with the given name listening on HTTP GET requests on the given port. When a request is received, the requestHandler callback function is called with the following parameters:

clientIP: IP address of the client
filename: Filename of the GET query (string)
params: key-value pairs of GET parameters (dictionary)

The return value (string) is sent to the client as a message part of the HTTP-Respose. With Verbose = true debug information are printed.

To stop the server and release the port, terminate() should be called

getClientIP() returns the dotted IP of a connected client. If no client is connected, returns empty string
getServerIP() returns the server's IP address (static method)
(all methods of TCPServer)  


Class HTTPClient

Function Action
HTTPClient.getRequest(url, data = None)

sends a GET request to the server. url is either "http://serveraddress?key1 = value1&key2 = value2 ..." or just "http://serveraddress" and data is a directory {key1: value1, key2: value2, ..}. In this case, key and value are automatically URL encoded. For SSL (port: 443) http: is replaced by https:.
The return value is the HTTP response (without header). If an error occurs, the error description is returned

HTTPClient.postRequest(url, data = None) sends a POST request to the server. url is either "http://serveraddress?key1 = value1 & key2 = value2 ..." or just "http://serveraddress" and data is a directory {key1: value1, key2: value2, ..}. In this case, key and value are automatically URL encoded. For SSL (port: 443) http: is replaced by https:.
The return value is the HTTP response (without header). If an error occurs, the error description is returned. If an error occurs, the error description is returned
HTTPClient.deletetRequest(url, data = "") sends a DELETE request to the server. url is "http://serveraddress" and data is a string containing the file path of the file to delete. For SSL (port: 443), http: is replaced by https:.
The return value is the HTTP response (without header). If an error occurs, the error description is returned
HTTPClient.pushover(token_key, user_key, title, message)

sends a push request to the pushover server api.pushover.net with given token key, user key, title and message. For verbose = True, debug information is printed. The return value is the HTTP response (without header). If an error occurs, the error description is returned

class ThingSpeakChannel

Function Action
chn = ThingSpeakChannel(channelId, readKey, writeKey, userKey, verbose = False)

creates an instance of the ThinkSpeakChannel class for communication with an existing channel on the cloud server www.thingspeak.com. The parameters correspond to the values received from the server during the channel definition. With verbose = True, debug informationen are written to the console. userKey is assigned to the user account and not to the channel (User API Key)

chn.getData(nbEntries = -1, includeDate = True)

returns the last nbEntries records as list of dictionaries [{fieldId: value} ...] (fieldId = 1..8). For nbEntries = -1, all records are returned. For includeDate = True, the field 'data', which contains the date-time of the record's creation, is also returned. All values are strings. In case of error, None is returned

chn.getTable(nbEntries = -1, includeDate = True)

the same, but returns an instance of DbTable with the table values. In case of error, an empty table is returned

 

chn.show(nbEntries = -1, includeDate = True) the same, but shows the table contents in the console
chn.getLastValue(fieldId = 1)

returns the value of the last record with given fieldId (1..8). In case of error or if the table is empty, None is returned

chn.getFields()

returns a dictionary with the fields defined in the channel and their names: {'field1': <field name 1>, 'field2' :, <field name 2> ..}. In case of error, None is returned

chn.insert(data, timeout = 20)

makes a new table entry and returns True, if successful. data is either a single value (number or string) or a dictionary {fieldId: value, ...} for an entry in multiple fields. Fields that have no value are set to None. For free accounts, a new entry is only allowed every 15 seconds, for payed accounts every second; if the server is not yet ready to accept new data, the insertion trial is repeated every second until the timeout (in s) is reached and False is returned

chn.clear()
clears all table entries. If successful returns True

 

Weather data (only EV3, autonomous mode)

Function Action
info = weather.request(ssid, password, city, key = defaultKey, lang = 'en')

makes a weather data request at http://openweathermap.org for the given location. The given authorization key is used. This can be obtained free of charge on this host. (If the parameter is omitted, a default key is used, which allows a maximum of 60 requests / min for all users.)

Return value: Dictionary with the fields:

"status" "OK" or error string describing the error, e.g. "City not found"
"temp" Temperature in °C (float)
"pressure" Air pressure in hPa (mbar) (float)
"humidity" Humitiy in % (int)
"temp_min" Minimum daily temperature in °C (float)
"temp_max" Maximum daily temperature in °C (float)
"description" Weather description (string, language defined by parameter lang)
"sunrise" Sunrise in Universal Time (UTC) (string)
"sunset" Sunset in Universal Time (UTC) (string)
"datetime" Date-Time of weather recording (UTC) (string)

 

 

Temperature/Humitidy sensor (Sensirion SHT31 over I2C) (only EV3)

sht = SHTSensor(SensorPort.port) creates a sensor instance at SensorPort S1, S2, S3, S4
sht.getValues() returns temperature (deg C) and humidity (%) in a tuple (floats)

 

Environment sensor (temperature, humidity, air pressure) (Bosch BME280 over I2C) (only EV3)

bme = BMESensor(SensorPort.port) creates a sensor instance at SensorPort S1, S2, S3, S4
bme.getValues() returns temperature (deg C), humidity (%) and air pressure (hPa) in a tuple (floats)


3-axes acceleration sensor (ADXL345 over I2C) (nur EV3)

adxl = ADXLSensor(SensorPort.port) creates a sensor instance at SensorPort S1, S2, S3, S4
adxl.getValues() returns accelerations in x-, y- and z-direction (m/s^2 in range -2g .. 2g) in a tuple (floats)

 

 

Complete Online-JavaDoc : EV3JLibA (Autonomous mode)
  EV3JLib (Direct mode)
  NxtJLib (Direct mode)
  RobotSim (Simulation)

home