Skip to content

Commit 1c66e4b

Browse files
Merge pull request #275 from pioneers/mkdocs-student-documentation
[DOCS] Mkdocs student documentation
2 parents e6b3d18 + 3891a37 commit 1c66e4b

17 files changed

+780
-98
lines changed

docs/.readthedocs.yaml

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Read the Docs configuration file for MkDocs projects
2+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
3+
4+
# Required
5+
version: 2
6+
7+
# Set the version of Python and other tools you might need
8+
build:
9+
os: ubuntu-22.04
10+
tools:
11+
python: "3.12"
12+
13+
mkdocs:
14+
configuration: mkdocs.yml
15+
16+
# Optionally declare the Python requirements required to build your docs
17+
python:
18+
install:
19+
- requirements: docs/requirements.txt

docs/Makefile

-20
This file was deleted.

docs/conf.py

-56
This file was deleted.

docs/docs/api.md

+297
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,297 @@
1+
# API Reference
2+
3+
The Student API is the set of functions available to students to communicate with their robots. The api can be split into two distinct class types. The Robot Class used for getting, setting, and running functions; input classes including the Gamepad Class and the Keyboard Class which are used to take student input to control their robots.
4+
5+
for more information refer to the Student API section of the [Runtime Wiki](https://github.com/pioneers/runtime/wiki)
6+
7+
#
8+
[//]: # (find better word for code periods later)
9+
* [Run Mode](#run-mode)
10+
* [`Teleop` Period](#teleop-period)
11+
* [`Auto` Period](#auto-period)
12+
* [`Robot` Class](#robot-class)
13+
* [`Robot.get_value(device_id, param)`](#robotget_valuedevice_id-param)
14+
* [`Robot.set_value(device_id, param, value)`](#robotset_valuedevice_id-param-value)
15+
* [`Robot.run(function_name, args...)`](#robotrunfunction_name-args)
16+
* [`Robot.is_running(function_name)`](#robotis_runningfunction_name)
17+
* [`Robot.sleep(seconds)`](#robotsleepseconds)
18+
* [Input Classes](#input-classes)
19+
* [`Gamepad.get_value(name_of_input)`](#gamepadget_valuename_of_input)
20+
* [`Keyboard.get_value(name_of_key)`](#keyboardget_valuename_of_key)
21+
22+
# Run Mode
23+
The two run modes, `autonomous` and `teleop` are where a majority of student code will be run. These functions are run in the Autonomous period and Teleoperated period of a PiE competition. Autonomous code restricts student's access to the `Keyboard` and `Gamepad` functions, forcing them to write code that will run without any input. The Teleoperated period allows for control from both, giving students more freedom to control their robot through any of the challenges presented in that phase.
24+
25+
26+
27+
## `AUTO` Period
28+
The autonomous or `AUTO` period is used anytime keyboard or controller input is restricted. Within this period you are encouraged to write code that will be able to run without any user input.
29+
30+
An example of this would be running a robot forward for a set duration within an `AUTO` period
31+
32+
```py
33+
motor = "//INSERT MOTOR ID HERE//"
34+
35+
def autonomous_main():
36+
# keeps motor A running at max speed for 10 seconds
37+
Robot.set_value(motor, velocity_a, 1)
38+
Robot.sleep(10) # stops the execution of any other functions for a specified number of seconds
39+
Robot.set_value(motor, velocity_a, 0)
40+
```
41+
For more recourses please refer to the [Software Hub Autonomous Guide](https://pioneers.berkeley.edu/competition/SoftwareHub/Teleop/)
42+
43+
44+
## `TELEOP` Period
45+
The teleoperated or `TELEOP` period is used anytime remote input via a controller or keyboard is used. The `teleop_main()` function runs in a loop until the teleoperated period has completed.
46+
47+
This code is most useful when a student would like to use controller or keyboard input to control their robot on the game field.
48+
49+
```py
50+
motor = "//INSERT MOTOR ID HERE//"
51+
52+
def teleop_main():
53+
# sets the motor's velocity to max if the button A is pressed
54+
if(Gamepad.get_value(button_a) == True):
55+
Robot.set_value(motor, velocity_a, 1)
56+
```
57+
58+
For more recources please refer to the [Software Hub Teleop Guide](https://pioneers.berkeley.edu/competition/SoftwareHub/Teleop/)
59+
## `SETUP` Phase
60+
The `SETUP` phase prepares for either the `AUTO` or `TELEOP` function to be run. In this phase a student can set or get the value of any lowcar device (any device connected to the robot that can be controlled with the PiE api).
61+
62+
This function is useful when a student would want to turn off the CURRENTLY BROKEN PiD control on a motor controller
63+
```py
64+
motor = "//INSERT MOTOR ID HERE//"
65+
66+
def teleop_setup(): # code segment run before the teleop_main() function
67+
Robot.set_value(motor, pid_enabled_a, False)
68+
Robot.set_value(motor, pid_enabled_b, False)
69+
70+
def autonomous_setup(): # code segment run before the autonomous_main() function
71+
Robot.set_value(motor, pid_enabled_a, False)
72+
Robot.set_value(motor, pid_enabled_b, False)
73+
```
74+
75+
# `Robot` Class
76+
The robot class holds all methods for interacting with various arduino devices connected to a student’s robot. These devices include servos, motors, and sensors.
77+
78+
## `Robot.get_value(device_id, param)`
79+
The get_value function returns the current value of a specified `param` of the device with the specified device_id.
80+
81+
* `device_id`: the ID that specifies which PiE device will be read
82+
* `param`: identifies which parameter on the specified PiE device will be read. Possible param values depend on the specified device. Find a list of params for each device on the device get page
83+
84+
The function is useful for checking the current state of devices. For example, getting the current state of the limit switch using its device_id and the param “switch0” will return the value True when pressed down and False if not.
85+
86+
```py
87+
# first segment of code ran in the teleop process
88+
limit_switch = "//INSERT SWITCH ID HERE//"
89+
90+
def teleop_setup():
91+
print("Tele-operated mode has started!")
92+
pass
93+
94+
def teleop_main():
95+
# example code for getting the value of a limit switch
96+
97+
# first parameter is the limit switch's id
98+
# second parameter tells which switch to get the value from
99+
100+
# in this case the method will return True or False depending on if the switch is pressed down or not
101+
102+
Robot.get_value(limit_switch, switch0)
103+
pass
104+
105+
```
106+
For more examples and devices refer to the devices page in the reference
107+
108+
109+
## `Robot.set_value(device_id, param, value)`
110+
The `set_value` function sets a specified value to a device’s parameter
111+
112+
* `device_id`: the ID that specifies which PiE device will have its parameter set
113+
* `param`: determines which parameter should be set. The parameters depend on the specified Lowcar device and can be found at INCLUDE LINK TO LOWCAR DEVICE PAGE
114+
* `value` <int, bool, float> - the value to set the parameter to
115+
116+
This function is useful for setting the state of parts of your robot while driving. For example calling the set_value param `“velocity_a”` with a KoalaBear device (motor controller) with a value of `1` results in the attached motor spinning forwards at full power
117+
118+
119+
[//]: <> (MAKE CODE SEGMENTS COLLAPSIBLE)
120+
```py
121+
# first segment of code ran in the teleop process
122+
motor = "//INSERT MOTOR ID HERE//"
123+
124+
def teleop_setup():
125+
print("Tele-operated mode has started!")
126+
pass
127+
128+
def teleop_main():
129+
# example code for turning a motor forward at full speed
130+
# first parameter is the motor controller's id set as a variable
131+
# second parameter 'velocity_a' tells a motor controller which motor to drive
132+
# third parameter sets the value
133+
134+
Robot.set_value(motor, velocity_a, 1)
135+
pass
136+
137+
```
138+
139+
## `Robot.run(function_name, args)`
140+
The `Robot.run()` runs another function, passing the `args` fed into the function. The `function_name` is run in parallel to any other code run following the `Robot.run()` function.
141+
142+
* `function_name`: the name of a function in the student code which will be run simultaneously with the main loop
143+
144+
* `args`: this is a list of zero or more inputs, which will be passed to the function_name specified previously as arguments (inputs)
145+
146+
[//]: <> (I want to separate the code example and this line of text. Not exactly sure how to do it so adding this comment to come back to it)
147+
An example of this would if a student would want to run a process alongside the teleop_main loop. Using the Robot.sleep class to define the amount of time a motor should rotate for without stopping the teleop_main loop.
148+
149+
150+
[//]: <> (FULL CODE WITHOUT ANY REMOVED CODE SEGMENTS //REMOVE//)
151+
```py
152+
ARM_MOTOR = "INSERT MOTOR_ID HERE"
153+
DRIVE_MOTOR = "INSERT MOTOR_ID HERE"
154+
155+
156+
def arm_movement():
157+
# moves arm up for 1 second and then moves it down for 1 second
158+
# assumes arm is attached to motor A of MC "ARM_MOTOR"
159+
if(Gamepad.get_value("button_a")):
160+
Robot.set_value(ARM_MOTOR, "velocity_a", 0.5)
161+
Robot.sleep(1)
162+
Robot.set_value(ARM_MOTOR, "velocity_a", -0.5)
163+
Robot.sleep(1)
164+
165+
def teleop_setup():
166+
# starts the arm_movement subroutine in parallel to the main thread
167+
Robot.run(arm_movement)
168+
pass
169+
170+
def teleop_main():
171+
# put your teleop code here and it will run along side the arm_movement thread
172+
if(Gamepad.get_value("button_b")):
173+
Robot.set_value(DRIVE_MOTOR, "velocity_a", 1)
174+
175+
```
176+
177+
178+
## `Robot.is_running(function_name)`
179+
The `Robot.is_running()` function returns a boolean value (`True` or `False`) for whether or not the specified function is still running.
180+
181+
`function_name`: the name of a function defined by the student. If run through `Robot.run()` it will be the same inputted `function_name`
182+
183+
An example usage of this would be to wait for a `Robot.run()` process to finish before allowing user input for another process.
184+
185+
```py
186+
187+
def robot_actions():
188+
# series of actions from the Robot.set_value().
189+
190+
def teleop_setup():
191+
pass
192+
193+
# if the button A is pressed down and robot_actions are not running. Then the robot will be able to run robot_actions again. Will not run if the button A is not pressed or if robot_actions is running
194+
def teleop_main():
195+
if Gamepad.get_value(button_a) and not Robot.is_running(robot_actions):
196+
Robot.run(robot_actions)
197+
198+
199+
```
200+
201+
202+
203+
## `Robot.sleep(seconds)`
204+
Pauses the execution of the current function for the specified number of `seconds`.
205+
206+
`seconds`: the number of `seconds` to pause the execution of the current function for.
207+
It should be emphasized that calling `Robot.sleep` in one function does not cause any other function that is being run by `Robot.run()` or the main loop function to pause. Only the instance of the function that is executing the call to `Robot.sleep` will pause execution. It is highly recommended to not use this function in the setup functions or main loop functions--only in functions executed by `Robot.run()`.
208+
209+
a great place to use `Robot.sleep()` would be to make a robot go to a specific spot using set motor velocities and ammount of time each function should run.
210+
[//]: <> (could go further and say that `Robot.sleep()` combined with encoder ticks per revolution could allow you to specify a distance your robot could go)
211+
212+
```py
213+
MOTOR_ID = "INSERT MOTOR_ID HERE"
214+
215+
def autonomous_setup():
216+
print("Autonomous mode has started!")
217+
robot.run(autonomous_actions) # runs the autonomous_actions function in parallel to autonomous main
218+
219+
220+
def autonomous_main():
221+
pass
222+
223+
def autonomous_actions():
224+
print("Action 1") # action one sets the motor velocities to 1
225+
Robot.set_value(MOTOR_ID, "velocity_b", 1.0)
226+
Robot.set_value(MOTOR_ID, "velocity_a", 1.0)
227+
Robot.sleep(1.0) # holds the function for one second before running the next lines
228+
print("Action 2") # the following code sets the motor velocities to 0
229+
Robot.set_value(KOALA_BEAR, "velocity_b", 0)
230+
Robot.set_value(KOALA_BEAR, "velocity_a", 0)
231+
232+
```
233+
234+
# Input Classes
235+
The input classes are both of the input classes that can only be run during the teleoperated game phase. These two classes allow a student to receive a boolean value for whether or not a button is pressed down or not. Most students will use these classes to
236+
237+
## `Gamepad.get_value(input)`
238+
The `Gamepad` class receives input for when there is a change to a controller. This class is only usable during the teleop phase.
239+
240+
`input`: identifies which button or joystick will be returned. This function is useful for checking the state of a button or joystick
241+
242+
For example, if you wanted to print `"hello world"` when the `"button_a"` is pressed and false when it isn't you would use the function as a condition in an if statement
243+
244+
```py
245+
# segment of code will print "hello world" into the console when button_a is pressed
246+
def teleop_main():
247+
if Gamepad.get_value("button_a"):
248+
print("hello world")
249+
```
250+
This function is essential for controlling your robot with the game pad.
251+
252+
The possible button inputs are:
253+
* "button_a"
254+
* "button_b"
255+
* "button_x"
256+
* "button_y"
257+
* "l_bumper"
258+
* "r_bumper"
259+
* "l_trigger"
260+
* "r_trigger"
261+
* "button_back"
262+
* "button_start"
263+
* "l_stick"
264+
* "r_stick"
265+
* "dpad_up"
266+
* "dpad_down"
267+
* "dpad_left"
268+
* "dpad_right"
269+
* "button_xbox"
270+
271+
The possible joystick inputs are:
272+
* "joystick_left_x"
273+
* "joystick_left_y"
274+
* "joystick_right_x"
275+
* "joystick_right_y"
276+
277+
Note that the joysticks function differently from the button inputs. Rather then returning a Boolean `[True or False]`, they return a floating point value ranging from `-1.0 `and` 1.0` (inclusive)
278+
279+
## `Keyboard.get_value(input)`
280+
The `Keyboard` class allows a student to receive keyboard input. Like the `Gamepad` class, it is only usable during the teleop game phase.
281+
282+
`input`: identifies which key is being read. When pressed the `get_value` will return a `True` boolean and `False` when not.
283+
284+
possible keyboard inputs are:
285+
* The letters on the keyboard, lowercase and no spaces `"a"`-`"z"`
286+
* The numbers on the keyboard, no spaces `"0"`-`"9"`
287+
* The punctuation keys `","`, `"."`, `"/"`, `";"`, `"'"`, `"["`, `"]"`
288+
* The four arrow keys `"left_arrow"`, `"right_arrow"`, `"up_arrow"`, `"down_arrow"`
289+
290+
For example, if you wanted to print `"hello world"` when the `"w"` is pressed and false when it isn't you would use the function as a condition in an if statement
291+
292+
```py
293+
# segment of code will print "hello world" into the console when the w key is pressed
294+
def teleop_main():
295+
if Keyboard.get_value("w"):
296+
print("hello world")
297+
```

docs/docs/dawn.png

41.6 KB
Loading

0 commit comments

Comments
 (0)