Micropython API reference: Difference between revisions

From GCtronic wiki
Jump to navigation Jump to search
No edit summary
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>None</code>
|-
|-
| <code>epuck2_set_leds()</code>
| <code>epuck2.set_leds()</code>
| <code>led1,led3,led5,led7,body,front</code>
| <code>bitmask: int</code>
| Set the LEDs state (on, off).
| Set the standard Red LEDs using a bitmask.
| <code>None</code>
| <code>None</code>
|-
|-
| <code>epuck2.play_sound()</code>
| <code>epuck2.play_sound()</code>
| <code>sound id</code>
| <code>sound_id: int</code>
| Play onboard sound.
| Play an onboard sound effect.
| <code>None</code>
| <code>None</code>
|-
|-
| <code>epuck2.set_motors_speed()</code>
| <code>epuck2.set_motors_speed()</code>
| <code>left: int</code>, <code>right: int</code>
| <code>left, right</code>
| Set the speed for the left and right motors.
| Set motor speeds (-1000 to 1000).
| <code>None</code>
| <code>None</code>
|-
|-
| <code>epuck2.set_all_actuators()</code>
| <code>epuck2.set_all_actuators()</code>
| <code>actuators list</code> (17 arguments total)
| <code>list</code>
| Set all actuators at once.
| 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.get_mic_volume()</code>
| None
| Get volume from the 4 microphones.
| <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>
| <code>epuck2.button_pressed()</code>
| None
| None
| Get button state.
| Get user button state.
| <code>True if pressed</code>
| <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>
</syntaxhighlight>


= LEDs =
== <code>epuck2.get_battery()</code> ==
== <code>epuck2.set_rgb(led, red, green, blue)</code> ==
Get the raw battery voltage value.
Set the intensity of one of the four RGB LEDs.
 
'''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:'''
'''Parameters:'''
    * <code>led</code> (<code>int</code>): The index of the LED to control:
* <code>left</code> (<code>int</code>): Speed of left motor ('''-1000''' to '''1000''').
        * <code>0</code>: LED 2 (Front Right)
* <code>right</code> (<code>int</code>): Speed of right motor ('''-1000''' to '''1000''').
        * <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
import epuck2
import epuck2
epuck2.set_rgb(0, 0, 0, 50)
epuck2.set_motors_speed(500, -500) # Spin in place
</syntaxhighlight>
</syntaxhighlight>


== <code>epuck2.set_all_rgb(red2, green2, blue2, red4, green4, blue4, red6, green6, blue6, red8, green8, blue8)</code> ==
== <code>epuck2.set_leds(value)</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 the state (on, off) of the standard red LEDs using a bitmask integer.


'''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'''.
'''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


'''Example:'''
<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.
# Turn on LED 1 (1) and Front LED (32) -> 1 + 32 = 33
import epuck2
epuck2.set_leds(33)
epuck2.set_all_rgb(100, 0, 0,  # LED 2
                  0, 100, 0,  # LED 4
                  0, 0, 0,    # LED 6
                  0, 0, 0)   # LED 8
</syntaxhighlight>
</syntaxhighlight>


= Proximity sensors =
== <code>epuck2.set_rgb(led, red, green, blue)</code> ==
Set the intensity of a specific RGB LED.
 
'''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.
 
== <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.
 
== <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:''' List of 8 integers (Sensor 0 to Sensor 7).
 
== <code>epuck2.get_distance()</code> ==
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>[MicRight, MicLeft, MicBack, MicFront]</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].


'''Returns:''' A list of 8 integers.
== <code>epuck2.get_tv_remote()</code> ==
Get the TV remote data (RC5 protocol).


'''Example:'''
'''Returns:''' Integer data field.
<syntaxhighlight lang="python">
import epuck2
prox_values = epuck2.get_proximity()
# prox_values[0] is sensor S0, prox_values[7] is sensor S7
print(prox_values)
</syntaxhighlight>


= Motors =
= Advanced Bulk Functions =
== <code>epuck2.set_motors_speed(left, right)</code> ==
Set the speed of the left and right motors.


'''Parameters:'''
== <code>epuck2.set_all_actuators(args...)</code> ==
    * <code>left</code> (<code>int</code>): Speed of the left motor. Range is **-1000** (reverse) to **1000** (forward).
Set all actuators in one call. Requires 17 arguments.
    * <code>right</code> (<code>int</code>): Speed of the right motor. Range is **-1000** (reverse) to **1000** (forward).
* <code>Arg 0</code>: Settings (Mic sensitivity, etc)
* <code>Arg 1-2</code>: Left Motor, Right Motor
* <code>Arg 3</code>: Standard LEDs bitmask
* <code>Arg 4-15</code>: RGB LEDs (R,G,B for LED 2,4,6,8)
* <code>Arg 16</code>: Sound ID


'''Example:'''
== <code>epuck2.get_all_sensors()</code> ==
<syntaxhighlight lang="python">
Get all sensors values at once. Returns a list of 49 elements:
# Move forward at full speed
import epuck2
epuck2.set_motors_speed(1000, 1000)


# Turn right in place
{| class="wikitable"
import epuck2
! Idx !! Name !! Description
epuck2.set_motors_speed(500, -500)
|-
</syntaxhighlight>
| 0-2 || Accel X, Y, Z || Raw values
|-
| 3-5 || Orientation || Acc Mag, Orientation, Inclination (Floats)
|-
| 6-8 || Gyro X, Y, Z || Raw values
|-
| 9-11 || Magnetometer || X, Y, Z (Floats, uT)
|-
| 12 || Temp || Celsius
|-
| 13-20 || Proximity || IR Sensors 0-7
|-
| 21-28 || Ambient || Ambient Light 0-7
|-
| 29 || Distance || ToF (mm)
|-
| 30-33 || Mics || Volume 0-3
|-
| 34-35 || Steps || Left, Right Motor steps
|-
| 36 || Battery || Raw value
|-
| 37 || Micro SD || State (1=OK)
|-
| 38-40 || Remote || Toggle, Address, Data
|-
| 41 || Selector || Position 0-15
|-
| 42-44 || Ground Prox || Sensors 0-2
|-
| 45-47 || Ground Amb || Ambient 0-2
|-
| 48 || Button || 1=Pressed
|}

Revision as of 09:12, 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
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.

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.

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 (Sensor 0 to Sensor 7).

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: [MicRight, MicLeft, MicBack, MicFront].

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 (Mic sensitivity, etc)
  • Arg 1-2: Left Motor, Right Motor
  • Arg 3: Standard LEDs bitmask
  • Arg 4-15: RGB LEDs (R,G,B for LED 2,4,6,8)
  • Arg 16: Sound ID

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
3-5 Orientation Acc Mag, Orientation, Inclination (Floats)
6-8 Gyro X, Y, Z Raw values
9-11 Magnetometer X, Y, Z (Floats, uT)
12 Temp Celsius
13-20 Proximity IR Sensors 0-7
21-28 Ambient Ambient Light 0-7
29 Distance ToF (mm)
30-33 Mics Volume 0-3
34-35 Steps Left, Right Motor steps
36 Battery Raw value
37 Micro SD State (1=OK)
38-40 Remote Toggle, Address, Data
41 Selector Position 0-15
42-44 Ground Prox Sensors 0-2
45-47 Ground Amb Ambient 0-2
48 Button 1=Pressed
Retrieved from "http://www.gctronic.com/doc/index.php?title=Micropython_API_reference&oldid=2687"