Michel2/pybricks-api
1
0
Fork 0
mirror of https://github.com/pybricks/pybricks-api.git synced 2026-07-28 04:07:46 +00:00
Code Issues Releases Activity

doc: move snippets to doc

Browse Source 
Example snippets are platform specific.
This commit is contained in:
Laurens Valk
2019-06-03 12:02:16 +02:00
parent 1bf2751daf
commit c43d296511
13 changed files with 302 additions and 168 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/common/robotics.rst
-4
View File
@@ -1,4 +0,0 @@
:mod:`robotics` -- Robotics module
===========================================
.. automodule:: robotics
doc/common/tools.rst
-11
View File
@@ -1,11 +0,0 @@
:mod:`tools` -- Timing and Datalogging
======================================
.. automodule:: tools
:no-members:
.. autofunction:: print
.. autofunction:: wait
.. autoclass:: StopWatch
doc/ev3dev/ev3brick.rst
+67
View File
@@ -10,25 +10,66 @@ Buttons
.. autofunction:: ev3brick.buttons
Examples::
# Do something if the left button is pressed
if Button.LEFT in brick.buttons():
print("The left button is pressed.")
::
# Wait until any of the buttons are pressed
while not any(brick.buttons()):
wait(10)
# Wait until all buttons are released
while any(brick.buttons()):
wait(10)
Light
-----
.. autofunction:: ev3brick.light
Example::
# Make the light red
brick.light(Color.RED)
# Turn the light off
brick.light(None)
Sound
-----
.. automethod:: ev3brick.sound.beep
Example::
# A simple beep
brick.sound.beep()
# A high pitch (1500 Hz) for one second (1000 ms) at 50% volume
brick.sound.beep(1500, 1000, 50)
.. automethod:: ev3brick.sound.beeps
Example::
# Make 5 simple beeps
brick.sound.beeps(5)
.. automethod:: ev3brick.sound.file
Example::
# Play one of the built-in sounds
brick.sound.file(SoundFile.HELLO)
# Play a sound file from your project folder
brick.sound.file('mysound.wav')
Display
-------
@@ -45,12 +86,38 @@ Display
|__________________|
(177, 127)
.. automethod:: ev3brick.display.clear
Example::
# Clear the display
brick.display.clear()
.. automethod:: ev3brick.display.text
Example::
# Print ``Hello`` near the middle of the screen
brick.display.text("Hello", (60, 50))
# Print ``World`` directly underneath it
brick.display.text("World")
.. automethod:: ev3brick.display.image
Example::
# Show a built-in image of two eyes looking upward
brick.display.image(ImageFile.UP)
# Display a custom image from your project folder
brick.display.image('pybricks.png')
# Display a custom image at the top right of the screen, without clearing
# the screen first
brick.display.image('arrow.png', Align.TOP_RIGHT, clear=False)
Battery
-------
doc/ev3dev/ev3devices.rst
+46
View File
@@ -10,10 +10,26 @@ Motors
.. autoclass:: ev3devices.Motor
:no-members:
Example::
# Initialize a motor (by default this means clockwise, without any gears).
example_motor = Motor(Port.A)
# Initialize a motor where positive speed values should go counterclockwise
right_motor = Motor(Port.B, Direction.COUNTERCLOCKWISE)
# Initialize a motor with a gear train
robot_arm = Motor(Port.C, Direction.CLOCKWISE, [12, 36])
.. rubric:: Methods for motors without rotation sensors
.. automethod:: ev3devices.Motor.dc
Example::
# Set the motor duty cycle to 75%.
example_motor.duty(75)
.. rubric:: Methods for motors with rotation sensors
.. automethod:: ev3devices.Motor.angle
@@ -36,6 +52,26 @@ Motors
.. automethod:: ev3devices.Motor.track_target
Example::
# Initialize motor and timer
from math import sin
motor = Motor(Port.A)
watch = StopWatch()
amplitude = 90
# In a fast loop, compute a reference angle
# and make the motor track it.
while True:
# Get the time in seconds
seconds = watch.time()/1000
# Compute a reference angle. This produces
# a sine wave that makes the motor move
# smoothly between -90 and +90 degrees.
angle_now = sin(seconds)*amplitude
# Make the motor track the given angle
motor.track_target(angle_now)
.. automethod:: ev3devices.Motor.stalled
.. automethod:: ev3devices.Motor.run_until_stalled
@@ -44,6 +80,16 @@ Motors
.. automethod:: ev3devices.Motor.set_run_settings
Example::
# Set the maximum speed to 200 deg/s and acceleration to 400 deg/s/s.
example_motor.set_run_settings(200, 400)
# Make the motor run for 5 seconds. Even though the speed argument is 300
# deg/s in this example, the motor will move at only 200 deg/s because of
# the settings above.
example_motor.run_time(300, 5000)
.. automethod:: ev3devices.Motor.set_pid_settings
Sensors
doc/ev3dev/robotics.rst
+46 -1
View File
@@ -1 +1,46 @@
.. include:: ../common/robotics.rst
:mod:`robotics` -- Robotics module
===========================================
.. automodule:: robotics
:no-members:
.. autoclass:: robotics.DriveBase
:no-members:
Example::
# Initialize two motors and a drive base
left = Motor(Port.B)
right = Motor(Port.C)
robot = DriveBase(left, right, 56, 114)
.. automethod:: robotics.DriveBase.drive
Example::
# Initialize two motors and a drive base
left = Motor(Port.B)
right = Motor(Port.C)
robot = DriveBase(left, right, 56, 114)
# Initialize a sensor
sensor = UltrasonicSensor(Port.S4)
# Drive forward until an object is detected
robot.drive(100, 0)
while sensor.distance() > 500:
wait(10)
robot.stop()
.. automethod:: robotics.DriveBase.drive_time
Example::
# Drive forward at 100 mm/s for two seconds
robot.drive_time(100, 0, 2000)
# Turn at 45 deg/s for three seconds
robot.drive_time(0, 45, 3000)
.. automethod:: robotics.DriveBase.stop
doc/ev3dev/tools.rst
+28 -1
View File
@@ -1 +1,28 @@
.. include:: ../common/tools.rst
:mod:`tools` -- Timing and Datalogging
======================================
.. automodule:: tools
:no-members:
.. autofunction:: print
Example::
# Print some text
print("Hello, world")
# Print some text and a number
print("Value:", 5)
.. autofunction:: wait
.. autoclass:: tools.StopWatch
:no-members:
.. automethod:: tools.StopWatch.time
.. automethod:: tools.StopWatch.pause
.. automethod:: tools.StopWatch.resume
.. automethod:: tools.StopWatch.reset
doc/lpf2/lpf2devices.rst
+46
View File
@@ -10,10 +10,26 @@ Motors
.. autoclass:: lpf2devices.Motor
:no-members:
Example::
# Initialize a motor (by default this means clockwise, without any gears).
example_motor = Motor(Port.A)
# Initialize a motor where positive speed values should go counterclockwise
right_motor = Motor(Port.B, Direction.COUNTERCLOCKWISE)
# Initialize a motor with a gear train
robot_arm = Motor(Port.C, Direction.CLOCKWISE, [12, 36])
.. rubric:: Methods for motors without rotation sensors
.. automethod:: lpf2devices.Motor.dc
Example::
# Set the motor duty cycle to 75%.
example_motor.duty(75)
.. rubric:: Methods for motors with rotation sensors
.. automethod:: lpf2devices.Motor.angle
@@ -36,6 +52,26 @@ Motors
.. automethod:: lpf2devices.Motor.track_target
Example::
# Initialize motor and timer
from math import sin
motor = Motor(Port.A)
watch = StopWatch()
amplitude = 90
# In a fast loop, compute a reference angle
# and make the motor track it.
while True:
# Get the time in seconds
seconds = watch.time()/1000
# Compute a reference angle. This produces
# a sine wave that makes the motor move
# smoothly between -90 and +90 degrees.
angle_now = sin(seconds)*amplitude
# Make the motor track the given angle
motor.track_target(angle_now)
.. automethod:: lpf2devices.Motor.stalled
.. automethod:: lpf2devices.Motor.run_until_stalled
@@ -44,6 +80,16 @@ Motors
.. automethod:: lpf2devices.Motor.set_run_settings
Example::
# Set the maximum speed to 200 deg/s and acceleration to 400 deg/s/s.
example_motor.set_run_settings(200, 400)
# Make the motor run for 5 seconds. Even though the speed argument is 300
# deg/s in this example, the motor will move at only 200 deg/s because of
# the settings above.
example_motor.run_time(300, 5000)
.. automethod:: lpf2devices.Motor.set_pid_settings
Sensors
doc/lpf2/robotics.rst
+41 -1
View File
@@ -1 +1,41 @@
.. include:: ../common/robotics.rst
:mod:`robotics` -- Robotics module
===========================================
.. automodule:: robotics
:no-members:
.. autoclass:: robotics.DriveBase
:no-members:
Example::
# Initialize two motors and a drive base
left = Motor(Port.A)
right = Motor(Port.B)
robot = DriveBase(left, right, 56, 114)
.. automethod:: robotics.DriveBase.drive
Example::
# Initialize a sensor
sensor = ColorDistanceSensor(Port.C)
# Drive forward until an object is detected
robot.drive(100, 0)
while sensor.distance() > 30:
wait(10)
robot.stop()
.. automethod:: robotics.DriveBase.drive_time
Example::
# Drive forward at 100 mm/s for two seconds
robot.drive_time(100, 0, 2000)
# Turn at 45 deg/s for three seconds
robot.drive_time(0, 45, 3000)
.. automethod:: robotics.DriveBase.stop
doc/lpf2/tools.rst
+28 -1
View File
@@ -1 +1,28 @@
.. include:: ../common/tools.rst
:mod:`tools` -- Timing and Datalogging
======================================
.. automodule:: tools
:no-members:
.. autofunction:: print
Example::
# Print some text
print("Hello, world")
# Print some text and a number
print("Value:", 5)
.. autofunction:: wait
.. autoclass:: tools.StopWatch
:no-members:
.. automethod:: tools.StopWatch.time
.. automethod:: tools.StopWatch.pause
.. automethod:: tools.StopWatch.resume
.. automethod:: tools.StopWatch.reset
pybricks/_common.py
-88
View File
@@ -25,17 +25,6 @@ class Motor():
The same holds for the documentation below: When it states "motor angle" or "motor speed", you can read this as "mechanism output angle" and "mechanism output speed", and so on, as the gear ratio is automatically accounted for.
The ``gears`` setting is only available for motors with rotation sensors.
Example::
# Initialize a motor (by default this means clockwise, without any gears).
example_motor = Motor(Port.A)
# Initialize a motor where positive speed values should go counterclockwise
right_motor = Motor(Port.B, Direction.COUNTERCLOCKWISE)
# Initialize a motor with a gear train
robot_arm = Motor(Port.C, Direction.CLOCKWISE, [12, 36])
"""
pass
@@ -44,12 +33,6 @@ class Motor():
Arguments:
duty (:ref:`percentage`): The duty cycle (-100.0 to 100).
Example::
# Set the motor duty cycle to 75%.
example_motor.duty(75)
"""
pass
@@ -185,26 +168,6 @@ class Motor():
Arguments:
target_angle (:ref:`angle`): Target angle that the motor should rotate to.
Example::
# Initialize motor and timer
from math import sin
motor = Motor(Port.A)
watch = StopWatch()
amplitude = 90
# In a fast loop, compute a reference angle
# and make the motor track it.
while True:
# Get the time in seconds
seconds = watch.time()/1000
# Compute a reference angle. This produces
# a sine wave that makes the motor move
# smoothly between -90 and +90 degrees.
angle_now = sin(seconds)*amplitude
# Make the motor track the given angle
motor.track_target(angle_now)
"""
pass
@@ -226,15 +189,6 @@ class Motor():
max_speed (:ref:`speed`): Maximum speed of the motor during a motor command.
acceleration (:ref:`acceleration`): Acceleration towards the target speed and deceleration towards standstill. This should be a positive value. The motor will automatically change the sign to decelerate as needed.
Example::
# Set the maximum speed to 200 deg/s and acceleration to 400 deg/s/s.
example_motor.set_run_settings(200, 400)
# Make the motor run for 5 seconds. Even though the speed argument is 300
# deg/s in this example, the motor will move at only 200 deg/s because of
# the settings above.
example_motor.run_time(300, 5000)
"""
pass
@@ -268,17 +222,6 @@ class Display():
text (str): The text to display.
coordinate (tuple): ``(x, y)`` coordinate tuple. It is the top-left corner of the first character. If no coordinate is specified, it is printed on the next line.
Example::
# Clear the display
brick.display.clear()
# Print ``Hello`` near the middle of the screen
brick.display.text("Hello", (60, 50))
# Print ``World`` directly underneath it
brick.display.text("World")
"""
pass
@@ -295,17 +238,6 @@ class Display():
coordinate (tuple): ``(x, y)`` coordinate tuple. It is the top-left corner of the image (*Default*: None).
clear (bool): Whether to clear the screen before showing the image (*Default*: ``True``).
Example::
# Show a built-in image of two eyes looking upward
brick.display.image(ImageFile.UP)
# Display a custom image from your project folder
brick.display.image('pybricks.png')
# Display a custom image at the top right of the screen, without clearing
# the screen first
brick.display.image('arrow.png', Align.TOP_RIGHT, clear=False)
"""
pass
@@ -320,14 +252,6 @@ class Speaker():
frequency (:ref:`frequency`): Frequency of the beep (*Default*: 500).
duration (:ref:`time`): Duration of the beep (*Default*: 100).
volume (:ref:`percentage`): Volume of the beep (*Default*: 30).
Example::
# A simple beep
brick.sound.beep()
# A high pitch (1500 Hz) for one second (1000 ms) at 50% volume
brick.sound.beep(1500, 1000, 50)
"""
pass
@@ -337,10 +261,6 @@ class Speaker():
Arguments:
number (int): Number of beeps.
Example::
# Make 5 simple beeps
brick.sound.beeps(5)
"""
pass
@@ -351,14 +271,6 @@ class Speaker():
file_name (str): Path to the sound file, including extension.
volume (:ref:`percentage`): Volume of the sound (*Default*: 100).
Example::
# Play one of the built-in sounds
brick.sound.file(SoundFile.HELLO)
# Play a sound file from your project folder
brick.sound.file('mysound.wav')
"""
pass
pybricks/ev3brick.py
-24
View File
@@ -10,22 +10,6 @@ def buttons():
:returns: List of pressed buttons.
:rtype: List of :class:`Button <parameters.Button>`
Examples::
# Do something if the left button is pressed
if Button.LEFT in brick.buttons():
print("The left button is pressed.")
::
# Wait until any of the buttons are pressed
while not any(brick.buttons()):
wait(10)
# Wait until all buttons are released
while any(brick.buttons()):
wait(10)
"""
pass
@@ -36,14 +20,6 @@ def light(color):
Arguments:
color (Color): Color of the light. Choose ``Color.BLACK`` or ``None``
to turn the light off.
Example::
# Make the light red
brick.light(Color.RED)
# Turn the light off
brick.light(None)
"""
pass
pybricks/robotics.py
-29
View File
@@ -15,12 +15,6 @@ class DriveBase():
wheel_diameter (:ref:`dimension`): Diameter of the wheels.
axle_track (:ref:`dimension`): Distance between the midpoints of the two wheels.
Example::
# Initialize two motors and a drive base
left = Motor(Port.B)
right = Motor(Port.C)
robot = DriveBase(left, right, 56, 114)
"""
def drive(self, speed, steering):
@@ -29,22 +23,6 @@ class DriveBase():
Arguments:
speed (:ref:`travelspeed`): Forward speed of the robot.
steering (:ref:`speed`): Turn rate of the robot.
Example::
# Initialize two motors and a drive base
left = Motor(Port.B)
right = Motor(Port.C)
robot = DriveBase(left, right, 56, 114)
# Initialize a sensor
sensor = UltrasonicSensor(Port.S4)
# Drive forward until an object is detected
robot.drive(100, 0)
while sensor.distance() > 500:
wait(10)
robot.stop()
"""
pass
@@ -56,13 +34,6 @@ class DriveBase():
steering (:ref:`speed`): Turn rate of the robot.
time (:ref:`time`): Duration of the maneuver.
Example::
# Drive forward at 100 mm/s for two seconds
robot.drive_time(100, 0, 2000)
# Turn at 45 deg/s for three seconds
robot.drive_time(0, 45, 3000)
"""
pass
pybricks/tools.py
-8
View File
@@ -6,14 +6,6 @@ def print():
Print values on the terminal or a stream.
Example::
# Print some text
print("Hello, world")
# Print some text and a number
print("Value:", 5)
"""
pass