Micropython API reference: Difference between revisions

From GCtronic wiki
Jump to navigation Jump to search
No edit summary
 
(30 intermediate revisions by the same user not shown)
Line 2: Line 2:
<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/>
<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 list=
= Functions Summary =
{| class="wikitable sortable"
{| class="wikitable sortable"
|+ epuck2 Module Functions
|+ epuck2 Module Functions
Line 9: Line 9:
| <code>epuck2.get_api_version()</code>
| <code>epuck2.get_api_version()</code>
| None
| None
| Returns the current e-puck2 API version as a string.
| 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: int</code>, <code>red: int</code>, <code>green: int</code>, <code>blue: int</code>
| <code>led, r, g, b</code>
| Set the intensity of a single RGB LED. Intensity ranges between '''0''' (off) and '''100''' (full on).
| 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>red2..blue8: int</code> (12 arguments total)
| <code>r2, g2, b2 ... r8, g8, b8</code>
| Set the intensity for all four RGB LEDs (LED 2, 4, 6, 8) simultaneously. Intensity ranges between '''0''' and '''100'''.
| 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 the values from the 8 proximity sensors. Higher values indicate a closer object.
| Get values from the 8 IR proximity sensors.
| <code>list</code> (of 8 integers)
| <code>list[8]</code>
|-
| <code>epuck2.get_distance()</code>
| None
| Get ToF distance in mm.
| <code>int</code>
|-
|-
| <code>epuck2.set_motors_speed()</code>
| <code>epuck2.get_mic_volume()</code>
| <code>left: int</code>, <code>right: int</code>
| None
| Set the speed for the left and right motors.
| 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>
|}
|}


= Various =
= General System =


== <code>epuck2.get_api_version()</code> ==
== <code>epuck2.get_api_version()</code> ==
Returns the API version as a string (e.g., "02.01").
Returns the API version as a string (e.g., "XX.XX").


<syntaxhighlight lang="Python">
<syntaxhighlight lang="Python">
import epuck2
import epuck2
version = epuck2.get_api_version()
print(epuck2.get_api_version())
print(version) # Example output: "XX.XX"
</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>


= LEDs =
== <code>epuck2.set_rgb(led, red, green, blue)</code> ==
== <code>epuck2.set_rgb(led, red, green, blue)</code> ==
Set the intensity of one of the four RGB LEDs.
Set the intensity of a specific RGB LED.


'''Parameters:'''
'''Parameters:'''
    * <code>led</code> (<code>int</code>): The index of the LED to control:
* <code>led</code> (<code>int</code>): 0=LED2, 1=LED4, 2=LED6, 3=LED8.
        * <code>0</code>: LED 2 (Front Right)
* <code>red, green, blue</code> (<code>int</code>): Intensity 0-100.
        * <code>1</code>: LED 4 (Back Right)
        * <code>2</code>: LED 6 (Back Left)
        * <code>3</code>: LED 8 (Front Left)
    * <code>red</code>, <code>green</code>, <code>blue</code> (<code>int</code>): Intensity from '''0''' (off) to '''100''' (full brightness).
 
'''Example:'''
<syntaxhighlight lang="python">
<syntaxhighlight lang="python">
# Set LED 1 (Index 0, LED 2) to half-intensity Blue
# 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(red2, green2, blue2, red4, green4, blue4, red6, green6, blue6, red8, green8, blue8)</code> ==
== <code>epuck2.set_all_rgb(r2, g2, b2, ... r8, g8, b8)</code> ==
Sets all four RGB LEDs simultaneously. The arguments are grouped in R, G, B for LEDs 2, 4, 6, and 8 in that order.
Set all four RGB LEDs simultaneously.  
 
'''Parameters:''' 12 integers representing the R, G, B values for LED 2, LED 4, LED 6, and LED 8, respectively. All values are in the range '''0''' to '''100'''.


'''Example:'''
'''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 78: Line 184:
</syntaxhighlight>
</syntaxhighlight>


= Proximity sensors =
== <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> ==
Retrieves the proximity sensor readings.
Get the proximity sensor values. Higher value = closer object.
 
'''Returns:''' A list of 8 integers.


'''Example:'''
'''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 S0, prox_values[7] is sensor S7
# prox_values[0] is sensor Prox0, prox_values[7] is sensor Prox7
print(prox_values)
print(prox_values)
</syntaxhighlight>
</syntaxhighlight>


= Motors =
== <code>epuck2.get_distance()</code> ==
== <code>epuck2.set_motors_speed(left, right)</code> ==
Get distance from the front Time of Flight (ToF) sensor.
Set the speed of the left and right motors.
 
'''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.


'''Parameters:'''
= Advanced bulk functions =
    * <code>left</code> (<code>int</code>): Speed of the left motor. Range is **-1000** (reverse) to **1000** (forward).
    * <code>right</code> (<code>int</code>): Speed of the right motor. Range is **-1000** (reverse) to **1000** (forward).


'''Example:'''
== <code>epuck2.set_all_actuators(args...)</code> ==
<syntaxhighlight lang="python">
Set all actuators in one call. Requires 17 arguments.
# Move forward at full speed
* <code>Arg 0</code>: Settings:
import epuck2
** bit0: 1=calibrate IR proximity sensors
epuck2.set_motors_speed(1000, 1000)
** 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


# Turn right in place
== <code>epuck2.get_all_sensors()</code> ==
import epuck2
Get all sensors values at once. Returns a list of 49 elements:
epuck2.set_motors_speed(500, -500)
{| class="wikitable"
</syntaxhighlight>
! 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

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