Micropython API reference

The following figures show the main components offered by the e-puck2 robot and where they are physically placed:

1 Functions Summary

epuck2 Module Functions

Method	Parameters	Description	Returns
epuck2.get_api_version()	None	Returns the current e-puck2 API version.	str
epuck2.set_rgb()	led, r, g, b	Set a single RGB LED (LED 2, 4, 6, or 8).	None
epuck2.set_all_rgb()	r2, g2, b2 ... r8, g8, b8	Set all four RGB LEDs at once (12 params).	None
epuck2.set_leds()	bitmask: int	Set the standard Red LEDs using a bitmask.	None
epuck2.play_sound()	sound_id: int	Play an onboard sound effect.	None
epuck2.set_motors_speed()	left, right	Set motor speeds (-1000 to 1000).	None
epuck2.set_all_actuators()	list	Set all actuators (motors, LEDs, sound) at once.	None
epuck2.get_proximity()	None	Get values from the 8 IR proximity sensors.	list[8]
epuck2.get_distance()	None	Get ToF distance in mm.	int
epuck2.get_mic_volume()	None	Get volume from the 4 microphones.	list[4]
epuck2.get_acc_raw()	None	Get accelerometer raw axes (X, Y, Z).	list[3]
epuck2.get_gyro_raw()	None	Get gyroscope raw axes (X, Y, Z).	list[3]
epuck2.get_battery()	None	Get raw battery level.	int
epuck2.get_selector()	None	Get rotary selector position (0-15).	int
epuck2.button_pressed()	None	Get user button state.	bool
epuck2.sd_available()	None	Check if Micro SD card is present.	bool
epuck2.get_tv_remote()	None	Get IR remote data (RC5).	int
epuck2.get_all_sensors()	None	Get all sensor data in one call.	list[49]

2 General System

2.1 epuck2.get_api_version()

Returns the API version as a string (e.g., "XX.XX").

import epuck2
print(epuck2.get_api_version())

2.2 epuck2.get_battery()

Get the raw battery voltage value.

Returns: Integer representing the raw battery level.

2.3 epuck2.get_selector()

Get the position of the physical rotary selector switch on top of the robot.

Returns: Integer between 0 and 15.

2.4 epuck2.button_pressed()

Check the state of the user button.

Returns: True if pressed, False otherwise.

2.5 epuck2.sd_available()

Check if a Micro SD card is inserted and mountable.

Returns: True if available, False otherwise.

3 Actuators (Motors, LEDs, Sound)

3.1 epuck2.set_motors_speed(left, right)

Set the speed of the left and right motors.

Parameters:

• left (int): Speed of left motor (-1000 to 1000).
• right (int): Speed of right motor (-1000 to 1000).

import epuck2
epuck2.set_motors_speed(500, -500) # Spin in place

3.2 epuck2.set_leds(value)

Set the state (on, off) of the standard red LEDs using a bitmask integer.

Parameters:

• value (int):
  • Bit 0: LED 1
  • Bit 1: LED 3
  • Bit 2: LED 5
  • Bit 3: LED 7
  • Bit 4: Body LED
  • Bit 5: Front LED

# Turn on LED 1 (1) and Front LED (32) -> 1 + 32 = 33 (0x21)
epuck2.set_leds(33)

3.3 epuck2.set_rgb(led, red, green, blue)

Set the intensity of a specific RGB LED.

Parameters:

• led (int): 0=LED2, 1=LED4, 2=LED6, 3=LED8.
• red, green, blue (int): Intensity 0-100.

# Set LED 2 (Index 0) to half-intensity blue
import epuck2
epuck2.set_rgb(0, 0, 0, 50)

3.4 epuck2.set_all_rgb(r2, g2, b2, ... r8, g8, b8)

Set all four RGB LEDs simultaneously.

Parameters: 12 integers (0-100) representing R, G, B for LED 2, 4, 6, and 8 respectively.

# Set LED 2 to Red (100, 0, 0) and LED 4 to Green (0, 100, 0). Other LEDs are off.
import epuck2
epuck2.set_all_rgb(100, 0, 0,  # LED 2
                   0, 100, 0,  # LED 4
                   0, 0, 0,    # LED 6
                   0, 0, 0)    # LED 8

3.5 epuck2.play_sound(id)

Play onboard sound.

Parameters:

• id (int):
  • 1: Mario
  • 2: Underworld
  • 4: Star Wars
  • 8: 4KHz Tone
  • 16: 10KHz Tone
  • 32: Stop Sound

4 Sensors

4.1 epuck2.get_proximity()

Get the proximity sensor values. Higher value = closer object.

Returns: List of 8 integers (Prox0 to Prox7).

import epuck2
prox_values = epuck2.get_proximity()
# prox_values[0] is sensor Prox0, prox_values[7] is sensor Prox7
print(prox_values)

4.2 epuck2.get_distance()

Get distance from the front Time of Flight (ToF) sensor.

Returns: Integer in millimeters (0 to 2000).

4.3 epuck2.get_mic_volume()

Get microphone volume levels [0..4095].

Returns: List of 4 integers: [Mic0 (right), Mic1 (left), Mic2 (back), Mic3 (front)].

4.4 epuck2.get_acc_raw()

Get raw accelerometer values (±2g).

Returns: List of 3 integers: [X, Y, Z]. Range [-1500..1500].

4.5 epuck2.get_gyro_raw()

Get raw gyroscope values (±250dps).

Returns: List of 3 integers: [X, Y, Z]. Range [-32768..32767].

4.6 epuck2.get_tv_remote()

Get the TV remote data (RC5 protocol).

Returns: Integer data field.

5 Advanced bulk functions

5.1 epuck2.set_all_actuators(args...)

Set all actuators in one call. Requires 17 arguments.

• Arg 0: Settings:
  • bit0: 1=calibrate IR proximity sensors
  • bit1: 0=disable onboard obstacle avoidance; 1=enable onboard obstacle avoidance (not implemented yet)
  • bit2: 0=set motors speed; 1=set motors steps (position)
• Arg 1-2: Left Motor, Right Motor
• Arg 3: Standard LEDs bitmask
  • Bit 0: LED 1
  • Bit 1: LED 3
  • Bit 2: LED 5
  • Bit 3: LED 7
  • Bit 4: Body LED
  • Bit 5: Front LED
• Arg 4-15: RGB LEDs (R,G,B for LED 2,4,6,8)
• Arg 16: Sound ID
  • 1: Mario
  • 2: Underworld
  • 4: Star Wars
  • 8: 4KHz Tone
  • 16: 10KHz Tone
  • 32: Stop Sound

5.2 epuck2.get_all_sensors()

Get all sensors values at once. Returns a list of 49 elements:

Idx	Name	Description
0-2	Accel X, Y, Z	Raw values between -1500 and 1500, resolution is +-2g
3	Acceleration magnitude	Between 0.0 and about 2600.0 (~3.46 g)
4	Orientation	between 0.0 and 360.0 degrees
5	Inclination	between 0.0 and 90.0 degrees (when tilted in any direction)
6-8	Gyro X, Y, Z	Raw values between -32768 and 32767, resolution is +-250dps
9-11	Magnetometer	X, Y, Z, range is +-4912.0 uT (magnetic flux density expressed in micro Tesla)
12	Temperature	Celsius
13-20	Proximity	Proximity IR sensors 0-7, between 0 (no objects detected) and 4095 (object near the sensor)
21-28	Ambient	Ambient Light 0-7, between 0 (strong light) and 4095 (dark)
29	Distance	ToF (mm)
30-33	Mics	Volume 0-3 between 0 and 4095
34-35	Motors steps	Left, Right Motor steps (1000 steps per wheel revolution)
36	Battery	Raw value
37	Micro SD	State, 1 if the micro SD is present and can be read/write, 0 otherwise
38-40	Remote	Toggle, Address, Data (RC5 protocol)
41	Selector	Position 0-15
42-44	Ground Proximity (extension)	Sensors 0-2 between 0 (no surface at all or not reflective surface e.g. black) and 1023 (very reflective surface e.g. white)
45-47	Ground Ambient (extension)	Ambient 0-2 between 0 (strong light) and 1023 (dark)
48	Button	1=pressed, 0=released