Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Minimum viable SR2024 docs #521

Merged
merged 108 commits into from
Sep 20, 2023
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
108 commits
Select commit Hold shift + click to select a range
deeafb7
slight tweak to power board
8BitJosh Aug 26, 2023
3754776
Update servo numbers for new FW, rewrite for ease of understanding
8BitJosh Aug 26, 2023
10d110c
Specify L2 is reserved
8BitJosh Aug 26, 2023
187f0b8
Update power board image to label brain port (L2)
8BitJosh Aug 26, 2023
7f85080
Update diagram to label status leds
8BitJosh Aug 26, 2023
6e282c6
motor board - talk about status LEDs now in FW
8BitJosh Aug 26, 2023
6df90bc
SR2024 - Update Section - Servo board
8BitJosh Aug 27, 2023
f7d9cc8
Merge pull request #486 from srobo/jp-motor-board
8BitJosh Aug 27, 2023
6eaf212
Remove power board note stating individual outputs
8BitJosh Aug 27, 2023
f8090ce
Add notes about the fan
8BitJosh Aug 27, 2023
5842f26
Merge pull request #484 from srobo/jp-power-board
8BitJosh Aug 27, 2023
7802bb7
sidebar rules
8BitJosh Aug 27, 2023
00e4023
sidebar kit section
8BitJosh Aug 27, 2023
e7bcdd6
sidebar programming section
8BitJosh Aug 27, 2023
2e6431d
sidebar - simulator and resources
8BitJosh Aug 27, 2023
40d9846
Fix links in interactive troubleshooter
8BitJosh Aug 27, 2023
1da26c0
Fix broken links
8BitJosh Aug 27, 2023
10e01b9
Sidebar Shuffle
8BitJosh Aug 27, 2023
5807727
Update content for ease of reading and clarity
8BitJosh Aug 28, 2023
b6777d9
KCH board API page update
8BitJosh Aug 28, 2023
0442894
standardize on robot. rather than R.
8BitJosh Aug 28, 2023
a6d0fef
SR2024 - Update Section - Brain board LEDs
8BitJosh Aug 28, 2023
b3a0a47
First parse at top level vision page
8BitJosh Aug 30, 2023
2623a65
Add images to orientation page
8BitJosh Aug 30, 2023
fa8ad3e
Merge pull request #490 from srobo/jdp-arduino-update
8BitJosh Aug 31, 2023
860d1dc
Update power board API
8BitJosh Aug 31, 2023
eac0ae9
Update servo board content
8BitJosh Aug 31, 2023
ea96370
fix servo board code typo
8BitJosh Aug 31, 2023
d3deba0
Motor board page update - simplify for clarity
8BitJosh Aug 31, 2023
0d216db
Updates for style consistency
8BitJosh Aug 31, 2023
6c0ee29
Style consistency
8BitJosh Aug 31, 2023
a40db43
Review comments
8BitJosh Sep 1, 2023
b3e9be8
Review fixes
8BitJosh Sep 1, 2023
6657f59
Remove explicit Note import
8BitJosh Sep 1, 2023
a98f278
Jekyll auto creates internal links to headers
8BitJosh Sep 1, 2023
9f2bb46
Jekyll auto creates internal links to headers
8BitJosh Sep 1, 2023
21bf83d
Servo extended servo range
8BitJosh Sep 1, 2023
e8b0ee9
remove !
8BitJosh Sep 1, 2023
61ebb2c
Duplicate log line for consistency
8BitJosh Sep 1, 2023
e96a2a5
SR2024 - Update Section - Power board API
8BitJosh Sep 2, 2023
7e4fcac
SR2024 - Update Section - Motor board API
8BitJosh Sep 2, 2023
82988bd
Update brain board pages
8BitJosh Sep 2, 2023
67d1412
robot instead of R
8BitJosh Sep 2, 2023
05f7e1f
vision orientation page
8BitJosh Sep 3, 2023
a4aa897
review comments - brain board
8BitJosh Sep 4, 2023
613f909
Review tweaks
8BitJosh Sep 4, 2023
28399ee
SR2024 - Update Section - Brain board
8BitJosh Sep 4, 2023
4843684
Review tweaks - servo API
8BitJosh Sep 4, 2023
d02d1ff
SR2024 - Update Section - Servo board API
8BitJosh Sep 4, 2023
cb8f759
Update vision pages
8BitJosh Sep 4, 2023
bac4f7c
review tweaks
8BitJosh Sep 4, 2023
b702522
SR2024 - Update Section - Vision
8BitJosh Sep 4, 2023
9647235
Fix vision code typo
8BitJosh Sep 6, 2023
d396e0a
Merge pull request #501 from srobo/jdp-tweak-vision
8BitJosh Sep 6, 2023
a045a99
Update top level kit page
8BitJosh Sep 7, 2023
41f0f40
SR2024 - Update Section - Kit
8BitJosh Sep 8, 2023
f14575e
Update intro page
8BitJosh Sep 9, 2023
9ddbebe
Update warning box to be less passive
8BitJosh Sep 9, 2023
77dc7ad
SR2024 - Update Section - Introduction
8BitJosh Sep 9, 2023
0b09b9a
Update robot API page - Add comp mode page
8BitJosh Sep 9, 2023
7d76b11
remove references to print wifi creds
8BitJosh Sep 9, 2023
4514f16
Merge pull request #505 from srobo/jdp-web-details
8BitJosh Sep 9, 2023
ff294f7
Update page on python libraries
8BitJosh Sep 9, 2023
20f052f
Fix broken link on simulator page
8BitJosh Sep 9, 2023
df73f21
opencv is not in the simulator
8BitJosh Sep 9, 2023
52c1b81
Update Python & Webots versions the simulator uses
PeterJCLaw Sep 9, 2023
c850300
Review comments
8BitJosh Sep 9, 2023
f27c4b2
Merge pull request #506 from srobo/jdp-python-libs
8BitJosh Sep 9, 2023
3426014
First parse at updating arduino API pages
8BitJosh Sep 10, 2023
c229fc7
battery page formatting
8BitJosh Sep 10, 2023
1e11100
Fix incorrect links and details on path
8BitJosh Sep 11, 2023
0aacf26
battery page markdown formatting
8BitJosh Sep 11, 2023
0dc3f3a
Talk about list_ports()
8BitJosh Sep 11, 2023
1bbabbe
update programming page
8BitJosh Sep 11, 2023
fa122a7
SR2024 - Update Section - Robot API
8BitJosh Sep 12, 2023
8ac64fc
SR2024 - Update Section - Programming
8BitJosh Sep 12, 2023
33a3875
Review comments
8BitJosh Sep 12, 2023
5121c6c
review tweak arduino
8BitJosh Sep 13, 2023
95a659f
SR2024 - Update Section - Arduino API
8BitJosh Sep 13, 2023
5b4b72e
Update cheat sheet
8BitJosh Sep 13, 2023
a91deb9
Update battery page
8BitJosh Sep 15, 2023
7558777
page formatting
8BitJosh Sep 15, 2023
ec1cf5f
Update img release for this years initial image release (#513)
8BitJosh Sep 16, 2023
ca0874f
Kit assembly page, minor tweaks
8BitJosh Sep 17, 2023
f39defe
an intro to python page
8BitJosh Sep 17, 2023
dc1df78
tutorial - getting code on your robot
8BitJosh Sep 17, 2023
be99a1c
Tutorial - basic movement
8BitJosh Sep 17, 2023
bf1e30a
SR2024 - Update Section - Batteries
8BitJosh Sep 17, 2023
b0b73fa
Review tweaks
8BitJosh Sep 17, 2023
0e461b3
SR2024 - Update Section - API Quick Reference
8BitJosh Sep 17, 2023
f749325
vision tweaks for clarity
8BitJosh Sep 17, 2023
26a2a98
Merge pull request #516 from srobo/jdp-vision-page-tweaks
8BitJosh Sep 17, 2023
3b52165
Merge branch 'simulator-versions' into sr2024
PeterJCLaw Sep 17, 2023
dcf378d
Document battery charger barrel size (#512)
RealOrangeOne Sep 18, 2023
afac331
top level tutorial page
8BitJosh Sep 18, 2023
ed31277
tweak sidebar
8BitJosh Sep 18, 2023
37ad6ad
Merge remote-tracking branch 'origin/main' into sr2024
8BitJosh Sep 18, 2023
c0d75bd
change to use jpg instead of png (#518)
8BitJosh Sep 18, 2023
2f77c3f
review tweaks
8BitJosh Sep 18, 2023
da1c123
review comments
8BitJosh Sep 18, 2023
835a06a
Some code
8BitJosh Sep 18, 2023
f8dad10
Merge pull request #517 from srobo/Tutorials-update
8BitJosh Sep 18, 2023
4738184
Change wifi -> web interface
8BitJosh Sep 19, 2023
46309f5
Move simulator to its own section
8BitJosh Sep 19, 2023
7a1bc1a
Move discord to tutorials section
8BitJosh Sep 19, 2023
db546ef
Create placeholder info for the resources pages
8BitJosh Sep 19, 2023
c0a40ab
Fix broken links
8BitJosh Sep 19, 2023
e15503b
Merge pull request #520 from srobo/jdp-multipage-tweaks
8BitJosh Sep 20, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 34 additions & 1 deletion programming/robot_api/comp_mode.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,37 @@ title: Competition Mode

# Competition Mode

TODO

## What is Comp Mode

During a competition match a Competition Mode USB is inserted into a spare USB port on your robot (See the [kit assembly guide]({{ site.baseurl }}/tutorials/assembly) for details on the spare USB port you need to leave).
This will instruct your robot that it is in competition mode and will have a number of effects, which are detailed below.


## Effects of Comp Mode

* Enabling Game timeout

When in competition mode the robot will automatically stop at the end of a match, where the duration of a match is defined in the [rules]({{ site.baseurl }}/rules).
The duration of the match is defined from when the start button is pressed.

* Disabling of WiFi and Web interface

During competition matches remote control of robots is forbidden ([rules]({{ site.baseurl }}/rules)), so the WiFi and web interface are disabled to ensure a fair game.

* Updating of match-specific `robot` attributes

Certain robot attributes will change when in comp mode, these can be used to change your robot's behaviour.
The affected attributes are:

mode
: Whether the robot is running in competition mode.
When in a competition match, this will be `COMP`, and at all other times this will be `DEV`.

zone
: The number of the scoring zone that the robot is associated with.
Between `0` and `3`.

The zone you are in defines which arena markers are near your scoring zone.
You can use the knowledge of your zone to compensate for this, so your robot behaves correctly in all starting positions.
See the [rules]({{ site.baseurl }}/rules) for where the scoring zones and arena markers are positioned.
119 changes: 56 additions & 63 deletions programming/robot_api/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,126 +3,119 @@ layout: page
title: Robot API
---

Robot API
=========
# Robot API

Student Robotics has written a module — `sr.robot3` — which is used to interface with the hardware.
It handles all the low-level interactions so you don't have to.
To set the output power of output 0 of the first motor board to -30%, for example, you would simply write:

~~~~~ python
R.motor_board.motors[0].power = -0.3
~~~~~

`-0.3` would be backwards (depending upon which way you wired up the motor) — 30% power in reverse.

To gain access to all of this functionality, all you need to do is write:
For example, to set the power of output 0 on a Motor Board to 30%, you would simply write:

~~~~~ python
from sr.robot3 import *
robot.motor_board.motors[0].power = 0.3
~~~~~

...at the top of your code (before you use any of its functionality, basically).
This imports the Student Robotics module that we've written to interface with our hardware.
<div class="info" markdown="1">
See the [Motor Board]({{ site.baseurl }}/programming/motors) page for more details about this example.
</div>

Then, within the `sr.robot3` module, there is a `Robot` class that should be instantiated, as follows:
To gain access to all of this functionality, all you need to do at the top of your code is the following:

~~~~~ python
from sr.robot3 import *
R = Robot()
robot = Robot()
~~~~~

Within your `Robot` (`R` in this case), you then have access to the following attributes:
This imports the Student Robotics module that we've written to interface with our hardware.
We then use the `Robot` class from within the `sr.robot3` module, to create a `robot` object that sets up and gives you access to your robot's hardware.

* [motors](/docs/programming/motors)
* [power](/docs/programming/power)
* [servos](/docs/programming/servos)
* [ruggeduinos](/docs/programming/arduino/)
* [vision](/docs/programming/vision/)
<div class="info" markdown="1">
Most examples in the documentation will assume you have created a `robot` object from the `Robot` class.
If you see `robot` in a code example, it is assumed you have run the two lines above.
</div>

They can be used in your code just like the example above.
Note that `motors`, `ruggeduinos`, and `servos` are Python lists, and so should be accessed as such.
Here are some examples:
Then, within your `robot` you can use the following attributes to access to the robot's hardware:

~~~~~ python
R.motor_board.motors[0].power = 0.5 # WILL work, if motor 0 exists
R.motor_board.motors[1].power = -0.2 # WILL work, if motor 1 exists
R.motor_board.motors.power = 0.42 # WON'T WORK
* [kch]({{ site.baseurl }}/programming/leds)
* [motor_board]({{ site.baseurl }}/programming/motors)
* [power_board]({{ site.baseurl }}/programming/power)
* [servo_board]({{ site.baseurl }}/programming/servos)
* [arduino]({{ site.baseurl }}/programming/arduino/)
* [camera]({{ site.baseurl }}/programming/vision/)

# the above is similar to the situation for 'ruggeduinos' and 'servos'
~~~~~
The functions of each board are described on their respective pages.

A number of examples in the documentation will assume you've instantiated the required `Robot` class and have called it `R`.
From here in, if you see a `R.something`, the requirement of the `sr.robot3` import line and the instantiation of `Robot` as `R` is implicit.

[Other Robot Attributes](#OtherRobotAttributes) {#OtherRobotAttributes}
----------------------
## Other Robot Attributes

As well as the attributes listed above, the Robot class also has the following attributes, which you may find useful:
As well as the attributes listed above, the `Robot` class also has the following attributes, which you may find useful:

zone
: The number of the zone that the robot is associated with. Between `0` and `3`.
: The number of the scoring zone that the robot is associated with.
Between `0` and `3`.

This attribute is only available after the start button is pressed and will throw an error if accessed before.
See the [competition mode](./comp_mode) page for more information about this attribute.

mode
: Whether the robot is running in competition mode.
When in a competition match, this will be `RobotMode.COMP`, and at all other times this will be `RobotMode.DEV`.
When in a competition match, this will be `COMP`, and at all other times this will be `DEV`.

This attribute is only available after the start button is pressed and will throw an error if accessed before.
See the [competition mode](./comp_mode) page for more information about this attribute.

~~~~~ python
from sr.robot3 import *

R = Robot()
robot = Robot()

if R.mode == RobotMode.COMP:
print("This is the competition!")
if robot.mode == COMP:
print("This is the competition!")
elif robot.mode == DEV:
print("This is development")
~~~~~

usbkey
: The path to the USB memory stick.
Your code is unzipped and run from a temporary directory, therefore files you create will be lost when the kit is turned off.
You can use this to easily read from and write to files on the stick itself.
Note that the USB memory stick is mounted synchronously, so any writes to it will block until complete and may slow down your code.
: A [`Path`](https://docs.python.org/3/library/pathlib.html#basic-use) object containing the path to the USB stick.
You can use this to easily read and write files on the USB stick itself.

An example of how the `usbkey` attribute might be used:
An example of how the `usbkey` attribute might be used to read a file called `my-file.txt` which is stored on the USB stick:

~~~~~ python
from sr.robot3 import *
import os

R = Robot()
print("The path to the USB key is:", R.usbkey)
robot = Robot()
print("The path to the USB stick is:", robot.usbkey)
print("My file on the USB contains:")
with open(os.path.join(R.usbkey, 'my-file.txt'), 'r') as f:
print(f.read())
with open(os.path.join(robot.usbkey, 'my-file.txt')) as file:
print(file.read())
~~~~~

is_simulated
: A boolean value indicating whether or not the code is running in the simulator.
This value is `True` when in the simulator and `False` when on the robot.


[Custom Robot Object Initialisation](#CustomRobotInit) {#CustomRobotInit}
----------------------
## Custom Robot Object Initialisation

Normally the Robot object is initialised with the following:

~~~~~ python
R = Robot()
from sr.robot3 import *
robot = Robot()
~~~~~

However if you want to:

* customise your Ruggeduino firmware
* initialise some hardware or software before the start button is pressed

Then Robot initialisation can be broken up as follows (this example is equivalent to the previous code excerpt):
By default your robot will pause on this line waiting for the start button to be pressed.
However if you want to initialise some hardware or software before the start button is pressed then Robot initialisation can be broken up as follows.

~~~~~ python
R = Robot(auto_start=True)
from sr.robot3 import *
robot = Robot(wait_for_start=False)

# Initialisation phase.
# Here you can perform hardware/software initialisation before start

R.wait_start()
robot.wait_start()
~~~~~

During the initialisation phase, all hardware is accessible.
If you have any hardware which must be initialised before the start button is pressed,
the initialisation phase is the time to do so.
This will not pause on the line which creates the `robot` but will instead pause on the `robot.wait_start()` line, until the start button is pressed.