Micropython API reference: Difference between revisions
| (31 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
The following figures show the main components offered by the e-puck2 robot and where they are physically placed:<br/> | |||
<span class="plainlinks">[https://projects.gctronic.com/epuck2/wiki_images/epuck2-components-position.png <img width=800 src="https://projects.gctronic.com/epuck2/wiki_images/epuck2-components-position_small.png">]</span><br/> | |||
= Functions | = Functions Summary = | ||
{| class="wikitable sortable" | {| class="wikitable sortable" | ||
|+ epuck2 Module Functions | |+ epuck2 Module Functions | ||
| Line 7: | Line 9: | ||
| <code>epuck2.get_api_version()</code> | | <code>epuck2.get_api_version()</code> | ||
| None | | None | ||
| Returns the current e-puck2 API version | | Returns the current e-puck2 API version. | ||
| <code>str</code> | | <code>str</code> | ||
|- | |- | ||
| <code>epuck2.set_rgb()</code> | | <code>epuck2.set_rgb()</code> | ||
| <code>led | | <code>led, r, g, b</code> | ||
| Set | | Set a single RGB LED (LED 2, 4, 6, or 8). | ||
| <code>None</code> | | <code>None</code> | ||
|- | |- | ||
| <code>epuck2.set_all_rgb()</code> | | <code>epuck2.set_all_rgb()</code> | ||
| <code> | | <code>r2, g2, b2 ... r8, g8, b8</code> | ||
| Set the | | Set all four RGB LEDs at once (12 params). | ||
| <code>None</code> | |||
|- | |||
| <code>epuck2.set_leds()</code> | |||
| <code>bitmask: int</code> | |||
| Set the standard Red LEDs using a bitmask. | |||
| <code>None</code> | |||
|- | |||
| <code>epuck2.play_sound()</code> | |||
| <code>sound_id: int</code> | |||
| Play an onboard sound effect. | |||
| <code>None</code> | |||
|- | |||
| <code>epuck2.set_motors_speed()</code> | |||
| <code>left, right</code> | |||
| Set motor speeds (-1000 to 1000). | |||
| <code>None</code> | |||
|- | |||
| <code>epuck2.set_all_actuators()</code> | |||
| <code>list</code> | |||
| Set all actuators (motors, LEDs, sound) at once. | |||
| <code>None</code> | | <code>None</code> | ||
|- | |- | ||
| <code>epuck2.get_proximity()</code> | | <code>epuck2.get_proximity()</code> | ||
| None | | None | ||
| Get | | Get values from the 8 IR proximity sensors. | ||
| <code>list</code> ( | | <code>list[8]</code> | ||
|- | |||
| <code>epuck2.get_distance()</code> | |||
| None | |||
| Get ToF distance in mm. | |||
| <code>int</code> | |||
|- | |- | ||
| <code>epuck2. | | <code>epuck2.get_mic_volume()</code> | ||
| <code> | | None | ||
| | | Get volume from the 4 microphones. | ||
| <code>None</code> | | <code>list[4]</code> | ||
|- | |||
| <code>epuck2.get_acc_raw()</code> | |||
| None | |||
| Get accelerometer raw axes (X, Y, Z). | |||
| <code>list[3]</code> | |||
|- | |||
| <code>epuck2.get_gyro_raw()</code> | |||
| None | |||
| Get gyroscope raw axes (X, Y, Z). | |||
| <code>list[3]</code> | |||
|- | |||
| <code>epuck2.get_battery()</code> | |||
| None | |||
| Get raw battery level. | |||
| <code>int</code> | |||
|- | |||
| <code>epuck2.get_selector()</code> | |||
| None | |||
| Get rotary selector position (0-15). | |||
| <code>int</code> | |||
|- | |||
| <code>epuck2.button_pressed()</code> | |||
| None | |||
| Get user button state. | |||
| <code>bool</code> | |||
|- | |||
| <code>epuck2.sd_available()</code> | |||
| None | |||
| Check if Micro SD card is present. | |||
| <code>bool</code> | |||
|- | |||
| <code>epuck2.get_tv_remote()</code> | |||
| None | |||
| Get IR remote data (RC5). | |||
| <code>int</code> | |||
|- | |||
| <code>epuck2.get_all_sensors()</code> | |||
| None | |||
| Get all sensor data in one call. | |||
| <code>list[49]</code> | |||
|} | |} | ||
= | = General System = | ||
== <code>epuck2.get_api_version()</code> == | == <code>epuck2.get_api_version()</code> == | ||
Returns the API version as a string (e.g., " | Returns the API version as a string (e.g., "XX.XX"). | ||
<syntaxhighlight lang="Python"> | <syntaxhighlight lang="Python"> | ||
import epuck2 | import epuck2 | ||
print(epuck2.get_api_version()) | |||
</syntaxhighlight> | |||
== <code>epuck2.get_battery()</code> == | |||
Get the raw battery voltage value. | |||
'''Returns:''' Integer representing the raw battery level. | |||
== <code>epuck2.get_selector()</code> == | |||
Get the position of the physical rotary selector switch on top of the robot. | |||
'''Returns:''' Integer between '''0''' and '''15'''. | |||
== <code>epuck2.button_pressed()</code> == | |||
Check the state of the user button. | |||
'''Returns:''' <code>True</code> if pressed, <code>False</code> otherwise. | |||
== <code>epuck2.sd_available()</code> == | |||
Check if a Micro SD card is inserted and mountable. | |||
'''Returns:''' <code>True</code> if available, <code>False</code> otherwise. | |||
= Actuators (Motors, LEDs, Sound) = | |||
== <code>epuck2.set_motors_speed(left, right)</code> == | |||
Set the speed of the left and right motors. | |||
'''Parameters:''' | |||
* <code>left</code> (<code>int</code>): Speed of left motor ('''-1000''' to '''1000'''). | |||
* <code>right</code> (<code>int</code>): Speed of right motor ('''-1000''' to '''1000'''). | |||
<syntaxhighlight lang="python"> | |||
import epuck2 | |||
epuck2.set_motors_speed(500, -500) # Spin in place | |||
</syntaxhighlight> | |||
== <code>epuck2.set_leds(value)</code> == | |||
Set the state (on, off) of the standard red LEDs using a bitmask integer. | |||
'''Parameters:''' | |||
* <code>value</code> (<code>int</code>): | |||
** Bit 0: LED 1 | |||
** Bit 1: LED 3 | |||
** Bit 2: LED 5 | |||
** Bit 3: LED 7 | |||
** Bit 4: Body LED | |||
** Bit 5: Front LED | |||
<syntaxhighlight lang="python"> | |||
# Turn on LED 1 (1) and Front LED (32) -> 1 + 32 = 33 (0x21) | |||
epuck2.set_leds(33) | |||
</syntaxhighlight> | </syntaxhighlight> | ||
== <code>epuck2.set_rgb(led, red, green, blue)</code> == | == <code>epuck2.set_rgb(led, red, green, blue)</code> == | ||
Set the intensity of | Set the intensity of a specific RGB LED. | ||
'''Parameters:''' | '''Parameters:''' | ||
* <code>led</code> (<code>int</code>): 0=LED2, 1=LED4, 2=LED6, 3=LED8. | |||
* <code>red, green, blue</code> (<code>int</code>): Intensity 0-100. | |||
<syntaxhighlight lang="python"> | <syntaxhighlight lang="python"> | ||
# Set LED | # Set LED 2 (Index 0) to half-intensity blue | ||
import epuck2 | import epuck2 | ||
epuck2.set_rgb(0, 0, 0, 50) | epuck2.set_rgb(0, 0, 0, 50) | ||
</syntaxhighlight> | </syntaxhighlight> | ||
== <code>epuck2.set_all_rgb( | == <code>epuck2.set_all_rgb(r2, g2, b2, ... r8, g8, b8)</code> == | ||
Set all four RGB LEDs simultaneously. | |||
''' | '''Parameters:''' 12 integers (0-100) representing R, G, B for LED 2, 4, 6, and 8 respectively. | ||
<syntaxhighlight lang="python"> | <syntaxhighlight lang="python"> | ||
# Set LED 2 to Red (100, 0, 0) and LED 4 to Green (0, 100, 0). Other LEDs are off. | # Set LED 2 to Red (100, 0, 0) and LED 4 to Green (0, 100, 0). Other LEDs are off. | ||
| Line 76: | Line 184: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
= | == <code>epuck2.play_sound(id)</code> == | ||
Play onboard sound. | |||
'''Parameters:''' | |||
* <code>id</code> (<code>int</code>): | |||
** 1: Mario | |||
** 2: Underworld | |||
** 4: Star Wars | |||
** 8: 4KHz Tone | |||
** 16: 10KHz Tone | |||
** 32: Stop Sound | |||
= Sensors = | |||
== <code>epuck2.get_proximity()</code> == | == <code>epuck2.get_proximity()</code> == | ||
Get the proximity sensor values. Higher value = closer object. | |||
''' | '''Returns:''' List of 8 integers (Prox0 to Prox7). | ||
<syntaxhighlight lang="python"> | <syntaxhighlight lang="python"> | ||
import epuck2 | import epuck2 | ||
prox_values = epuck2.get_proximity() | prox_values = epuck2.get_proximity() | ||
# prox_values[0] is sensor | # prox_values[0] is sensor Prox0, prox_values[7] is sensor Prox7 | ||
print(prox_values) | print(prox_values) | ||
</syntaxhighlight> | </syntaxhighlight> | ||
= | == <code>epuck2.get_distance()</code> == | ||
== <code>epuck2. | Get distance from the front Time of Flight (ToF) sensor. | ||
'''Returns:''' Integer in millimeters (0 to 2000). | |||
== <code>epuck2.get_mic_volume()</code> == | |||
Get microphone volume levels [0..4095]. | |||
'''Returns:''' List of 4 integers: <code>[Mic0 (right), Mic1 (left), Mic2 (back), Mic3 (front)]</code>. | |||
== <code>epuck2.get_acc_raw()</code> == | |||
Get raw accelerometer values (±2g). | |||
'''Returns:''' List of 3 integers: <code>[X, Y, Z]</code>. Range [-1500..1500]. | |||
== <code>epuck2.get_gyro_raw()</code> == | |||
Get raw gyroscope values (±250dps). | |||
'''Returns:''' List of 3 integers: <code>[X, Y, Z]</code>. Range [-32768..32767]. | |||
== <code>epuck2.get_tv_remote()</code> == | |||
Get the TV remote data (RC5 protocol). | |||
'''Returns:''' Integer data field. | |||
= Advanced bulk functions = | |||
== <code>epuck2.set_all_actuators(args...)</code> == | |||
< | Set all actuators in one call. Requires 17 arguments. | ||
* <code>Arg 0</code>: 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) | |||
* <code>Arg 1-2</code>: Left Motor, Right Motor | |||
* <code>Arg 3</code>: 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 | |||
* <code>Arg 4-15</code>: RGB LEDs (R,G,B for LED 2,4,6,8) | |||
* <code>Arg 16</code>: Sound ID | |||
** 1: Mario | |||
** 2: Underworld | |||
** 4: Star Wars | |||
** 8: 4KHz Tone | |||
** 16: 10KHz Tone | |||
** 32: Stop Sound | |||
== <code>epuck2.get_all_sensors()</code> == | |||
Get all sensors values at once. Returns a list of 49 elements: | |||
{| class="wikitable" | |||
! Idx !! Name !! Description | |||
|- | |||
| 0-2 || Accel X, Y, Z || Raw values between -1500 and 1500, resolution is +-2g | |||
|- | |||
| 3 || Acceleration magnitude <img width=70 src="https://projects.gctronic.com/epuck2/wiki_images/3dvector-magnitude.png"> || 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 | |||
|} | |||
Latest revision as of 11:02, 27 November 2025
The following figures show the main components offered by the e-puck2 robot and where they are physically placed:

1 Functions Summary
| 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 place3.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 83.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 MotorArg 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 |
