Flashing red and green when the battery is low | Green | | 5V | Green when 5V is being supplied | Green | | H0–1, L0–3 | Green when the corresponding output is on [^1]
Red when the output's current limit is reached | Off | -| RUN\|ERROR | Orange on power-up, or USB reset
Flashing green when ready to run
Solid green when running or booting | Orange | +| RUN\|ERROR | Orange on power-up, or USB disconnection
Flashing green when ready to run
Solid green when running or booting | Orange | [^1]: The outputs only turn on when your program runs (specifically, when the `Robot` object is created). -On power-up, the Power Board will emit some beeps, which are related to the version of the firmware it has installed. +On power-up and when waiting for the start button, the Power Board will beep once. If the Power Board starts beeping (and all the outputs turn off) then this means that the whole board's current limit has been triggered. @@ -69,6 +69,6 @@ The case measures 83x99x24mm. Don’t forget that the cables will stick out. ## Designs You can access the schematics and source code of the firmware for the power board in the following places. You do not need this information to use the board but it may be of interest to some people. -- [Full Schematics](/docs/power-schematic.pdf) -- [Firmware Source](https://github.com/sourcebots/power-v4-fw) +- [Full Schematics](../assets/docs/power-schematic.pdf) +- [Firmware Source](https://github.com/srobo/power-v4-fw) - [Hardware Source](https://github.com/sourcebots/power-v4-hw) diff --git a/docs/kit/servo-board.md b/docs/kit/servo-board.md new file mode 100644 index 00000000..58d33b82 --- /dev/null +++ b/docs/kit/servo-board.md @@ -0,0 +1,61 @@ +# Servo Board + +The Servo Board can be used to control up to 12 RC servos. Many devices +are available that can be controlled as servos, such as RC motor speed +controllers, and these can also be used with the board. + +## Board Diagram + + + +## Indicators + +| LED | Meaning | Initial power-up state | +|-------|----------------------|------------------------| +| Power | The board is powered | On + +## Connectors + +There are 8 servo connections on the left-side of the board, and 4 on +the right. Servo cables are connected vertically, with 0V (the black or +brown wire) at the bottom of the board. + +For the servo board to operate correctly, you must connect it to the 12V +power rail from the power board. A green LED will light next to the +servo board 12V connector when it is correctly powered and the 8 outputs +on the left-side of the board can be used. + +To use the 4 auxillary outputs on the right-side of the board, 5V needs to be connected to the auxillary input. + +## Case Dimensions + +The case measures 68x68x21mm. Don't forget that the cables will stick +out. + +## Range of servos + +When using the majority of servos that we supply, you will find that the +servo will only turn about 90 degrees. + +## Specification + +| Parameter | Value | +|----------------------------------|-------------| +| Number of servo channels | 12 | +| Nominal input voltage | 11.1V ± 15% | +| Output voltage | 5.5V | +| Maximum total output current[^1] | 10A | + +## Designs +------- + +You can access the schematics and source code of the firmware on the +servo board in the following places. You do not need this information to +use the board but it may be of interest to some people. + +- [Full Schematics](../assets/docs/servo-schematic.pdf) +- [Firmware Source](https://github.com/srobo/servo-v4-fw/) +- [Hardware designs](https://github.com/sourcebots/servo-v4-hw) + +[^1]: If the auxiliary input is connected, outputs 8-11 have an independent + maximum current. diff --git a/docs/programming/arduino.md b/docs/programming/arduino.md new file mode 100644 index 00000000..6f0a92dd --- /dev/null +++ b/docs/programming/arduino.md @@ -0,0 +1,119 @@ +# Arduino API + +The [Arduino](https://store.arduino.cc/arduino-uno-rev3) provides a +total of 18 pins for either digital input or output (labelled 2 to 13 +and A0 to A5), including 6 for analogue input (labelled A0 to A5). + +!!! warning + Digital pins 0 and 1 are reserved and cannot be used. + +## Accessing the Arduino + +The Arduino can be accessed using the `arduino` property of the `Robot` +object. + +``` python +my_arduino = robot.arduino +``` + +You can use the GPIO *(General Purpose Input/Output)* pins for anything, +from microswitches to LEDs. GPIO is only available on pins 2 to 13 and +A0 to A5 because pins 0 and 1 are reserved for communication with the +rest of our kit. + +## Pin Mode + +GPIO pins have four different modes. A pin can only have one mode at a +time, and some pins aren't compatible with certain modes. These pin +modes are represented by an +[enum](https://docs.python.org/3/library/enum.html) which needs to be +imported before they can be used. + +``` python +from sbot import GPIOPinMode +``` + +!!! tip + The input modes closely resemble those of an Arduino. More information on them can be found in [their docs](https://www.arduino.cc/en/Tutorial/DigitalPins). + +### Setting the pin mode + +You will need to ensure that the pin is in the correct pin mode before +performing an action with that pin. You can read about the possible pin +modes below. + +``` python +robot.arduino.pins[3].mode = GPIOPinMode.DIGITAL_INPUT_PULLUP +``` + +### `GPIOPinMode.DIGITAL_INPUT` + +In this mode, the digital state of the pin (whether it is high or low) +can be read. + +``` python +robot.arduino.pins[4].mode = GPIOPinMode.DIGITAL_INPUT + +pin_value = robot.arduino.pins[4].digital_state +``` + +### `GPIOPinMode.DIGITAL_INPUT_PULLUP` + +Same as `GPIOPinMode.DIGITAL_INPUT`, but with an internal [pull-up +resistor](https://learn.sparkfun.com/tutorials/pull-up-resistors) +enabled. + +``` python +robot.arduino.pins[4].mode = GPIOPinMode.DIGITAL_INPUT_PULLUP + +pin_value = robot.arduino.pins[4].digital_state +``` + +### `GPIOPinMode.DIGITAL_OUTPUT` + +In this mode, we can set binary values of `0V` or `5V` to the pin. + +``` python +robot.arduino.pins[4].mode = GPIOPinMode.DIGITAL_OUTPUT +robot.arduino.pins[6].mode = GPIOPinMode.DIGITAL_OUTPUT + +robot.arduino.pins[4].digital_state = True +robot.arduino.pins[6].digital_state = False +``` + +### `GPIOPinMode.ANALOGUE_INPUT` + +Certain sensors output analogue signals rather than digital ones, and so +have to be read differently. The Arduino has six analogue inputs, which +are labelled `A0` to `A5`; however pins `A4` and `A5` are reserved and +cannot be used. + +!!! tip + Analogue signals can have any voltage, while digital signals can only + take on one of two voltages. You can read more about digital vs analogue + signals [here](https://learn.sparkfun.com/tutorials/analog-vs-digital). + +``` python +from sbot import AnaloguePin + +robot.arduino.pins[AnaloguePin.A0].mode = GPIOPinMode.ANALOGUE_INPUT + +pin_value = robot.arduino.pins[AnaloguePin.A0].analogue_value +``` + +!!! tip + The values are the voltages read on the pins, between 0 and 5. + +## Ultrasound Sensors + +You can also measure distance using an ultrasound sensor from the arduino. + +```python +# Trigger pin: 4 +# Echo pin: 5 + +distance_metres = robot.arduino.ultrasound_measure(4, 5) +``` + +!!! warning + The ultrasound sensor can measure distances up to 2 metres. If the ultrasound signal has to travel further than 2m, the sensor will timeout and return `None`. diff --git a/content/api/game-state.md b/docs/programming/game-state.md similarity index 96% rename from content/api/game-state.md rename to docs/programming/game-state.md index e7d629b8..280e885d 100644 --- a/content/api/game-state.md +++ b/docs/programming/game-state.md @@ -15,7 +15,7 @@ Your robot can be in 1 of 2 modes: `DEVELOPMENT` and `COMPETITION`. By default, your robot will be in `DEVELOPMENT` mode: ``` python -r.is_competition +robot.is_competition >> False ``` @@ -29,9 +29,9 @@ zone. The number of zones depends on the game. Each zone is given a number, which you can access with the `zone` property: ``` python -r.zone +robot.zone >> 1 ``` During a competition match, a USB drive will be used to tell your robot -which corner it's in. By default during development, this is `0`. \ No newline at end of file +which corner it's in. By default during development, this is `0`. diff --git a/docs/programming/index.md b/docs/programming/index.md new file mode 100644 index 00000000..3d286f9e --- /dev/null +++ b/docs/programming/index.md @@ -0,0 +1,89 @@ +# Programming + +Programming your robot is done in [Python](https://www.python.org/), +specifically version 3.9.6. You can learn more about Python from their +[docs](https://docs.python.org/3/), and our [whirlwind tour](../tutorials/python-whirlwind-tour.md). + +Each board has an API which allows its various functionality to be controlled. + +## Setup + +The following two lines are required to complete initialisation of the +kit: + +``` python +from sbot import Robot + +robot = Robot() +``` + +Once this has been done, this `Robot` object can be used to control the +robot's functions. + +The remainder of the tutorials pages will assume your `Robot` object is +defined as `robot`. + +!!! note + In Python, variables are case-sensitive. `robot` is an instance of `Robot`. + +## Running your code + +Your code needs to be put on a USB drive in a file called `robot.py`. When connected to the robot, this file will be executed. The file is directly executed off your USB drive, with your drive as the working directory. + +!!! tip + If this file is missing or incorrectly named, your robot won't do anything. No log file will be created. + +To stop your code running, you can just remove the USB drive. This will also stop the motors and any other peripherals connected to the kit. + +You can then reinsert the USB drive into the robot, and it will run your `main.py` again (from the start). This allows you to make changes and test them quickly. + +## Logs + +A log file is saved to your USB so you can see what your robot did, +what it didn't do, and any errors it raised. The file is saved to log.txt in the top-level directory of the USB drive. + +!!! warning + The previous log file is deleted at the start of each run, so copy it elsewhere if you need to keep hold of it! + +## Running Code before pressing the start button + +If you want to do things before the start button press, such as setting up servos or motors, you can pass `wait_for_start` to the `Robot` constructor. You will then need to wait for the start button manually using `robot.wait_start()`. + +```python +robot = Robot(wait_for_start=False) + +# Do your setup here + +robot.wait_start() +``` + +## Debug mode + +It is possible to run your robot in "Debug Mode". + +In "Debug Mode", your robot will print more information about what it is doing. + +```python +from sbot import Robot + +robot = Robot(debug=True) +``` + +!!! info + Debug mode is very verbose. It will print a lot of information that you may not need. + +## Included Libraries + +Python comes with plenty of [built-in +libraries](https://docs.python.org/3.9/py-modindex.html) to use. We +install some extra ones which may be of use: + +- [numpy 1.25.0](https://pypi.org/project/numpy/1.25.0/) +- [matplotlib 3.7.1](https://pypi.org/project/matplotlib/3.7.1/) +- [pandas 2.0.3](https://pypi.org/project/pandas/2.0.3/) +- [scipy 1.11.1](https://pypi.org/project/scipy/1.11.1/) + +!!! tip + If you would like an extra library installed, go and ask a volunteer to see if we can help. + +*[API]: Application Programming Interface diff --git a/content/api/motor-board.md b/docs/programming/motor-board.md similarity index 69% rename from content/api/motor-board.md rename to docs/programming/motor-board.md index dbea54b8..dd2b7c13 100644 --- a/content/api/motor-board.md +++ b/docs/programming/motor-board.md @@ -1,6 +1,4 @@ ---- -title: Motor Board API ---- +# Motor Board API The kit can control multiple motors simultaneously. One Motor Board can control up to two motors. @@ -11,22 +9,19 @@ If there is exactly one motor board attached to your robot, it can be accessed using the `motor_board` property of the `Robot` object. ``` python -my_motor_board = r.motor_board +my_motor_board = robot.motor_board ``` -{{% notice warning %}} -If there is more than one motor board on your kit, you *must* use the -`motor_boards` property. `r.motor_board` *will cause an error*. This is -because the kit doesn't know which motor board you want to access. -{{% /notice %}} +!!! warning + If there is more than one motor board on your kit, you *must* use the `motor_boards` property. `robot.motor_board` *will cause an error*. This is because the kit doesn't know which motor board you want to access. Motor boards attached to your robot can be accessed under the `motor_boards` property of the `Robot`. The boards are indexed by their serial number, which is written on the board. ``` python -my_motor_board = r.motor_boards["SRO-AAD-GBH"] -my_other_motor_board = r.motor_boards["SR08U6"] +my_motor_board = robot.motor_boards["SRO-AAD-GBH"] +my_other_motor_board = robot.motor_boards["SR08U6"] ``` ## Controlling the Motor Board @@ -63,17 +58,11 @@ my_motor_board.motors[1].power >>> -1 ``` -{{% notice warning %}} -Setting a value outside of the range `-1` to `1` will raise an exception -and your code will crash. -{{% /notice %}} +!!! warning + Setting a value outside of the range `-1` to `1` will raise an exception and your code will crash. -{{% notice warning %}} -Sudden large changes in the motor speed setting (e.g. `-1` to `0`, `1` -to `-1` etc.) will likely trigger the over-current protection and your -robot will shut down with a distinct beeping noise and/or a red light -next to the power board output that is powering the motor board. -{{% /notice %}} +!!! danger + Sudden large changes in the motor speed setting (e.g. `-1` to `0`, `1` to `-1` etc.) will likely trigger the over-current protection and your robot will shut down with a distinct beeping noise and/or a red light next to the power board output that is powering the motor board. ### Special values @@ -90,9 +79,8 @@ from sbot import BRAKE, COAST `BRAKE` will stop the motors from turning, and thus stop your robot as quick as possible. -{{% notice tip %}} -`BRAKE` does the same as setting the power to `0`. -{{% /notice %}} +!!! note + `BRAKE` does the same as setting the power to `0`. ``` python from sbot import BRAKE diff --git a/docs/programming/power-board.md b/docs/programming/power-board.md new file mode 100644 index 00000000..07c031f8 --- /dev/null +++ b/docs/programming/power-board.md @@ -0,0 +1,99 @@ +# Power Board API + +The power board can be accessed using the `power_board` property of +the `Robot` object. + +```python +my_power_board = robot.power_board +``` + +## Power outputs + +The six outputs of the power board are grouped together as `power_board.outputs`. + +The power board's six outputs can be turned on and off using the +`power_on` and `power_off` functions of the group respectively. + +!!! tip + `power_on` is called when you set up your robot, so + this doesn't need to be called manually. The ports will come on + automatically as soon as your robot is ready, before the start button is + pressed. + +```python +robot.power_board.outputs.power_off() +robot.power_board.outputs.power_on() +``` + +You can also get information about and control each output in the group. +An output is indexed using the appropriate `PowerOutputPosition`. + +```python +from sbot import PowerOutputPosition + +robot.power_board.outputs[PowerOutputPosition.H0].is_enabled = True +robot.power_board.outputs[PowerOutputPosition.L3].is_enabled = False + +boolean_value = robot.power_board.outputs[PowerOutputPosition.L2].is_enabled + +current_amps = robot.power_board.outputs[PowerOutputPosition.H1].current +``` + +!!! warning + The motor and servo boards are powered through these + power outputs, whilst the power is off, you won't be able to control + your motors or servos. They will register as a missing board and your code will + break if you try and control them. + +## Battery Sensor + +The power board has some sensors that can monitor the status of your battery. +This can be useful for checking the charge status of your battery. + +```python +battery_voltage = robot.power_board.battery_sensor.voltage +battery_current_amps = robot.power_board.battery_sensor.current +``` + +## Buzzing 🐝 + +The power board has a piezo sounder which can buzz. + +The `buzz` function accepts two parameters. The first argument is the duration of the beep, in seconds. +The second argument is either the note you want to play, or the frequency of the buzzer (in Hertz). + +Theoretically, the piezo buzzer will buzz at any provided frequency, +however humans can only hear between [20Hz and +20000Hz](https://en.wikipedia.org/wiki/Hearing_range#Humans). + +The `Note` enum provides notes in [scientific pitch notation](https://en.wikipedia.org/wiki/Scientific_pitch_notation) between +`C6` and `C8`. You can play other tones by providing a frequency. + +!!! tip + Calling `buzz` is non-blocking, which means it doesn't + actually wait for the piezo to stop buzzing before continuing with your + code. If you want to wait for the buzzing to stop, add a + `sleep` afterwards! If you send more than 32 beeps to the robot too + quickly, your power board will crash! + +```python +from sbot import Note + +# Buzz for half a second in D6. +robot.power_board.piezo.buzz(0.5, Note.D6) + +# Buzz for 2 seconds at 400Hz +robot.power_board.piezo.buzz(2, 400) +``` + +## Start Button + +You can manually wait for the start button to be pressed, not only at +the start. + +```python +robot.wait_start() +``` + +This may be useful for debugging, but be sure to remove it in the +competition, as you won't be allowed to touch the start button after a match has begun! diff --git a/docs/programming/servo-board.md b/docs/programming/servo-board.md new file mode 100644 index 00000000..17e0337f --- /dev/null +++ b/docs/programming/servo-board.md @@ -0,0 +1,56 @@ +# Servo Board API + +The kit can control multiple servos simultaneously. One Servo Board can +control up to twelve servos. + +## Accessing the Servo Board + +The servo board can be accessed using the `servo_board` property of +the `Robot` object. + +```python +my_servo_board = robot.servo_board +``` + +This board object has an array containing the servos connected to it, +which can be accessed as `servos[0]`, `servos[1]`, `servos[2]`, etc. +The servo board is labelled so you know which servo is which. + +!!! tip + Remember that lists start counting at 0. + +## Setting servo positions + +The position of servos can range from `-1` to `1` inclusive: + +```python +# set servo 1's position to 0.2 +robot.servo_board.servos[1].position = 0.2 + +# Set servo 2's position to -0.55 +robot.servo_board.servos[2].position = -0.55 +``` + +You can read the last value a servo was set to using similar code: + +```python +last_position = robot.servo_board.servos[11].position +``` + +!!! warning + While it is possible to retrieve the last position a servo was set to, this does not guarantee that the servo is currently in that position. + +## How the set position relates to the servo angle + +!!! danger + You should be careful about forcing a servo to drive past its end stops. Some servos are very strong and it could damage the internal gears. + +The angle of an RC servo is controlled by the width of a pulse supplied +to it periodically. There is no standard for the width of this pulse and +there are differences between manufacturers as to what angle the servo +will turn to for a given pulse width. To be able to handle the widest +range of all servos our hardware outputs a very wide range of pulse +widths which in some cases will force the servo to try and turn past its +internal end-stops. You should experiment and find what the actual limit +of your servos are (it almost certainly won't be -1 and 1) and not +drive them past that. diff --git a/docs/programming/vision/index.md b/docs/programming/vision/index.md new file mode 100644 index 00000000..9c0734ae --- /dev/null +++ b/docs/programming/vision/index.md @@ -0,0 +1,108 @@ +# Vision + + + + +Your robot is able to use a webcam to detect [Fiducial Markers](https://en.wikipedia.org/wiki/Fiducial_marker). +Specifically it will detect [AprilTags](https://april.eecs.umich.edu/software/apriltag), using the `36H11` marker set. + +Using [Pose Estimation](https://en.wikipedia.org/wiki/3D_pose_estimation), it can calculate the orientation and position of +the marker relative to the webcam. Using this data, it is possible to determine the location of your robot and other objects around it. + +You can download the markers from the [resources page](../../resources/index.md). + +## Searching for markers + +Assuming you have a webcam connected, you can use `robot.camera.see()` to take a picture. The software will process the picture +and returns a list of the markers it sees. + +```python +markers = robot.camera.see() +``` + +!!! tip + Your camera will be able to process images better if they are not blurred. + +## Saving camera output + +You can also save a snapshot of what your webcam is currently seeing. This can be useful to debug your code. +Every marker that your robot can see will have a square annotated around it, with a red dot indicating the bottom right +corner of the marker. The ID of every marker is also written next to it. + +Snapshots are saved to your USB drive, and can be viewed on another computer. + +```python +robot.camera.save("snapshot.jpg") +``` + +{ width="50%" } + +## Markers + +The marker objects in the list expose data that may be useful to your robot. + +### Marker ID + +Every marker has a numeric identifier that can be used to determine what object it represents. + +```python +markers = robot.camera.see() + +for m in markers: + print(m.id) +``` + +### Position + +Each marker has a position in 3D space, relative to your webcam. + +You can access the position using `m.distance`, `m.cartesian` and `m.spherical`. + +```python +markers = robot.camera.see() + +for m in markers: + print(m.distance) # Distance to the marker from the webcam, in metres + print(m.spherical.rot_y) # Bearing to the marker from the webcam, in radians +``` + +!!! note + `m.distance` is equivalent to `m.cartesian.z` or `m.spherical.dist`. + +For more information on position, including how to use `m.cartesian`, `m.spherical`, and the coordinate systems, +see [Position](./position.md). + +It is also possible to look at the [Orientation](./orientation.md) of the marker. + +!!! tip + You can use the [`math.degrees`](https://docs.python.org/3/library/math.html#math.degrees) function to convert from radians to degrees. + +### Size + +Markers can come in different sizes. +You can access the size of a marker using `m.size`. +Check the rules to find out how big the different marker types are. + +```python +markers = robot.camera.see() + +for m in markers: + print(m.size) +``` + +### Pixel Positions + +The positions of various points on the marker within the image are exposed over the API. This is useful +if you would like to perform your own Computer Vision calculations. + +The corners are specified in clockwise order, starting from the top left corner of the +marker. Pixels are counted from the origin of the image, which +conventionally is in the top left corner of the image. + +```python +markers = robot.camera.see() + +for m in markers: + print(m.pixel_corners) # Pixel positions of the marker corners within the image. + print(m.pixel_centre) # Pixel positions of the centre of the marker within the image. +``` diff --git a/docs/programming/vision/orientation.md b/docs/programming/vision/orientation.md new file mode 100644 index 00000000..8fb47627 --- /dev/null +++ b/docs/programming/vision/orientation.md @@ -0,0 +1,47 @@ +# Orientation + + + +Orientation represents the rotation of a marker around the x, y, and z axes. These can be accessed as follows: + +* `rot_x` / `pitch` - the angle of rotation in radians counter-clockwise about the Cartesian x axis. +* `rot_y` / `yaw` - the angle of rotation in radians counter-clockwise about the Cartesian y axis. +* `rot_z` / `roll` - the angle of rotation in radians counter-clockwise about the Cartesian z axis. + +Rotations are applied in order of z, y, x. + +```python +markers = robot.camera.see() + +for marker in markers: + print(marker.orientation.rot_x) # Angle of rotation about x axis. + print(marker.orientation.rot_y) # Angle of rotation about y axis. + print(marker.orientation.rot_z) # Angle of rotation about z axis. +``` + +!!! note + In our use case the z axis always faces the camera, and thus will appear as a clockwise rotation + +## Examples + +The following table visually explains what positive and negative rotations represent. + +!!! example + 0 in all axes: + + ![m0x0y0z]{ width="35%" } + +| | π/4 | -π/4 | +|---:|:---:|:---:| +| **`rot_x`** | ![m45x0y0z] | ![m-45x0y0z] | +| **`rot_y`** | ![m0x45y0z] | ![m0x-45y0z] | +| **`rot_z`** | ![m0x0y45z] | ![m0x0y-45z] | + +[m0x0y0z]: ../../assets/img/api/vision/m0x0y0z.png +[m-45x0y0z]: ../../assets/img/api/vision/m-45x0y0z.png +[m0x-45y0z]: ../../assets/img/api/vision/m0x-45y0z.png +[m0x0y-45z]: ../../assets/img/api/vision/m0x0y-45z.png +[m0x0y0z]: ../../assets/img/api/vision/m0x0y0z.png +[m0x0y45z]: ../../assets/img/api/vision/m0x0y45z.png +[m0x45y0z]: ../../assets/img/api/vision/m0x45y0z.png +[m45x0y0z]: ../../assets/img/api/vision/m45x0y0z.png diff --git a/docs/programming/vision/position.md b/docs/programming/vision/position.md new file mode 100644 index 00000000..61c7c22a --- /dev/null +++ b/docs/programming/vision/position.md @@ -0,0 +1,56 @@ +# Position + +Your robot supports two different coordinates systems for position: + +* Cartesian +* Spherical + +The latter is a [Polar Coordinates system](https://en.wikipedia.org/wiki/Polar_coordinate_system). + +## Cartesian + +{ width="40%" } + +The [cartesian coordinates system](https://en.wikipedia.org/wiki/Cartesian_coordinate_system) has three +_principal axes_ that are perpendicular to each other. + +The value of each coordinate indicates the distance travelled along the axis to the point. + +The camera is located at the origin, where the coordinates are ``(0, 0, 0)``. + +```python +markers = robot.camera.see() + +for m in markers: + print(m.cartesian.x) # Displacement from the origin in millimetres, along x axis. + print(m.cartesian.y) # Displacement from the origin in millimetres, along y axis. + print(m.cartesian.z) # Displacement from the origin in millimetres, along z axis. +``` + +!!! tip + The `y` axis decreases as you go up. This matches convention for computer vision systems. + +## Spherical + +{ width="40%" } + +The [spherical coordinates system](https://en.wikipedia.org/wiki/Spherical_coordinate_system) has +three values to specify a specific point in space. + +* `distance` - The _radial distance_, the distance from the origin to the point, in millimetres. +* `rot_x` - Rotation around the X-axis, in radians, corresponding to "theta" on the diagram. +* `rot_y` - Rotation around the Y-axis, in radians, corresponding to "phi" on the diagram. + +The camera is located at the origin, where the coordinates are `(0, 0, 0)`. + +```python +markers = robot.camera.see() + +for m in markers: + print(m.spherical.distance) # Distance from the origin in millimetres + print(m.spherical.rot_x) # The angle from the azimuth to the point, in radians. + print(m.spherical.rot_y) # The polar angle from the plane of the camera to the point, in radians. +``` + +!!! tip + You can use the [`math.degrees`](https://docs.python.org/3/library/math.html#math.degrees) function to convert from radians to degrees. diff --git a/docs/resources/index.md b/docs/resources/index.md new file mode 100644 index 00000000..f3b31163 --- /dev/null +++ b/docs/resources/index.md @@ -0,0 +1,24 @@ +--- +hide: + - navigation +--- + +# Resources + +Here you can find links to some useful resources. + +## Game Rules + +The game rules can be found on the [Rules](../rules/index.md) page. + +## Markers + +Some parts of the arena are labelled with markers. These can be downloaded below: + +[Download markers :fontawesome-solid-download:](https://drive.google.com/file/d/1OoQpvLmXecamn488gyRKmpgX-fy5ClpZ/view?usp=drive_link){ .md-button } + +Each PDF contains a single marker, which when printed on a single page will be the correct size. + +## Labs + +- [Python Lab](../tutorials/python-lab.md) diff --git a/docs/rules/index.md b/docs/rules/index.md new file mode 100644 index 00000000..074f4e40 --- /dev/null +++ b/docs/rules/index.md @@ -0,0 +1,7 @@ +--- +title: Rules +--- + +You can find the rules for Smallpeice 2021 competition here!: + +[Download the rules :fontawesome-solid-download:](../assets/rules.pdf){ .md-button .md-button--primary } diff --git a/docs/tutorials/.pages b/docs/tutorials/.pages new file mode 100644 index 00000000..990f2a79 --- /dev/null +++ b/docs/tutorials/.pages @@ -0,0 +1,7 @@ +nav: + - index.md + - python-whirlwind-tour.md + - python-lab.md + - getting-code-on-the-robot.md + - basic-movement.md + - ... diff --git a/docs/tutorials/basic-movement.md b/docs/tutorials/basic-movement.md new file mode 100644 index 00000000..c0752cf9 --- /dev/null +++ b/docs/tutorials/basic-movement.md @@ -0,0 +1,115 @@ +# Basic movement + +The example program we'll write will do a number of things with the motor: forwards and backwards, and different power settings, for example. Let's begin. To start off, we'll just make a motor move forwards, then backwards, and then repeat. + +## Forwards & backwards + +Doing this is actually very easy; the only thing you need to realise is that a positive number is forwards and a negative number is backwards. + +!!! tip + The actual direction of travel of a motor, when mounted on a robot, will depend on its orientation and the way in which the wires are connected to the motor board. If the motor appears to be going in the wrong direction, just swap the motor's positive and negative wires over. + +Here's the code: + +```python +from sbot import Robot + +robot = Robot() + +while True: + r.motor_board.motors[0].power = 0.5 + r.motor_board.motors[1].power = 0.5 + r.sleep(3) + + r.motor_board.motors[0].power = 0 + r.motor_board.motors[1].power = 0 + r.sleep(1.4) + + r.motor_board.motors[0].power = -0.5 + r.motor_board.motors[1].power = -0.5 + r.sleep(1) + + r.motor_board.motors[0].power = 0 + r.motor_board.motors[1].power = 0 + + r.sleep(4) +``` + +You're familiar with the first few lines; in fact, the only lines you may not be familiar with are the `r.motor_board...` lines. For a comprehensive reference to the `motor` object, see [`motor` API](../programming/motor-board.md) page. + +But, to summarise: + +`r.motor_board.motors[0].power = 0.5` sets the target power of the motor connected to output 0 on the first [motor board](../kit/motor-board.md) to half speed forwards (i.e. a duty-cycle of 50% forwards). As you would expect, then, `-0.5` will put this motor into reverse at half power. +`r.motor_board.motors[0].power = 0` will brake the motor and stop it. + +So, if you put the above code on your robot, you should be able to see a motor spin forwards, stop, spin backwards, stop, and then repeat... + +!!! info + If you find that the motor doesn't turn when you run the above code, check that you've got all the cables connected to the right places, in particular note that the motor board has _two_ outputs. + +## Changing the speed + +Now we're going to modify the program to vary the speed of the motor. Our aim is to do the forwards and backwards bit (as above), but, before we loop round again, ramp the power up to 70%, then down to -70%, and then back to 0 (all in steps of 10%). Here's the code: + +```python +from sbot import Robot + +robot = Robot() + +while True: + r.motor_board.motors[0].power = 0.5 + r.motor_board.motors[1].power = 0.5 + r.sleep(3) + + r.motor_board.motors[0].power = 0 + r.motor_board.motors[1].power = 0 + r.sleep(1.4) + + r.motor_board.motors[0].power = -0.5 + r.motor_board.motors[1].power = -0.5 + r.sleep(1) + + r.motor_board.motors[0].power = 0 + r.motor_board.motors[1].power = 0 + r.sleep(4) + + # ^^ code from before ^^ + + # power up to 0.7 (from 0.1) + for pwr in range(10, 80, 10): + r.motor_board.motors[0].power = pwr / 100 + r.motor_board.motors[1].power = pwr / 100 + r.sleep(0.1) + + # power down from 0.7 (to 0.1) + for pwr in range(70, 0, -10): + r.motor_board.motors[0].power = pwr / 100 + r.motor_board.motors[1].power = pwr / 100 + r.sleep(0.1) + + # set power to 0 for a second + r.motor_board.motors[0].power = 0 + r.motor_board.motors[1].power = 0 + r.sleep(1) + + # power up to -0.7 (from -0.1) + for pwr in range(-10, -80, -10): + r.motor_board.motors[0].power = pwr / 100 + r.motor_board.motors[1].power = pwr / 100 + r.sleep(0.1) + + # power down to -0.1 (from -0.7) + for pwr in range(-70, 0, 10): + r.motor_board.motors[0].power = pwr / 100 + r.motor_board.motors[1].power = pwr / 100 + r.sleep(0.1) + + # set power to 0 for a second + r.motor_board.motors[0].power = 0 + r.motor_board.motors[1].power = 0 + r.sleep(1) +``` + +## Next steps + +From here, you should be able to make your robot move about in a controlled manner. See if you can make your robot drive forwards to a given point, stop, turn around and then return to its starting point. diff --git a/docs/tutorials/getting-code-on-the-robot.md b/docs/tutorials/getting-code-on-the-robot.md new file mode 100644 index 00000000..d4340c2f --- /dev/null +++ b/docs/tutorials/getting-code-on-the-robot.md @@ -0,0 +1,25 @@ +# Getting code on the robot + +Getting your code on to the robot is quite simple. You will need to put your code on a USB drive which will need to be formatted with either FAT32, exFAT or ext 2-4. Upon plugging in the drive or starting up, the robot will run the `robot.py` file found in the root of the drive. + +To re-run your program, simply remove the USB stick from the robot and plug it back in again and it will restart automatically. + +## Windows + +1. Open your code in File Explorer +2. Select all of your code files (++ctrl+a++ to select all files) +3. Right-click the files and click "Copy" +4. Open your USB drive in File Explorer +5. Right-click in the directory and click "Paste" + +## macOS + +1. Open your code in Finder +2. Select all of your code files (++cmd+a++ to select all files) +3. Right-click (or Control-click) the files and click "Copy" +4. Open your USB drive in Finder +5. Right-click in the directory and click "Paste N items" + +## Robot logs + +When your program runs on the robot, the output of `print(...)` statements and any errors which occur are written to a log file on the USB stick as `log.txt`. diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md new file mode 100644 index 00000000..a3f9a174 --- /dev/null +++ b/docs/tutorials/index.md @@ -0,0 +1,5 @@ +--- +title: Tutorials +--- + +This part of the docs contains some practical guides for getting starting with both the physical kit and Python API. diff --git a/docs/tutorials/python-lab.md b/docs/tutorials/python-lab.md new file mode 100644 index 00000000..cf97dcc6 --- /dev/null +++ b/docs/tutorials/python-lab.md @@ -0,0 +1,8 @@ +# Python Lab + +The Python Lab is used in the general Python programming workshop. It's designed to help develop your Python skills through a series of tasks to add features to an existing application. + +!!! info + This lab assumes a basic knowledge of Python. If you're not familiar with Python, check out the [Whirlwind Tour](./python-whirlwind-tour.md). + +[View Python Lab :material-file-document:](https://sourcebots.github.io/python-lab/){ .md-button .md-button--primary target="_blank" } diff --git a/content/tutorials/python-whirlwind-tour.md b/docs/tutorials/python-whirlwind-tour.md similarity index 96% rename from content/tutorials/python-whirlwind-tour.md rename to docs/tutorials/python-whirlwind-tour.md index 47680b8d..9f8d789c 100644 --- a/content/tutorials/python-whirlwind-tour.md +++ b/docs/tutorials/python-whirlwind-tour.md @@ -1,10 +1,8 @@ ---- -title: "Python: A Whirlwind Tour" ---- +# Python: A Whirlwind Tour -# The Basics +## Installation -## Installing Python on Windows +### Installing Python on Windows Below are step-by-step instructions for installing Python 3.9.6 (which is required for the competition): @@ -14,15 +12,15 @@ Below are step-by-step instructions for installing Python 3.9.6 (which is requir 3. Click “save file” and wait for the installer to download. 4. Find your downloads folder and open the Python installer. You should get this window: -  +  5. Tick the **“Add Python 3.9 to PATH”** checkbox and click “Install Now” (important) 6. Windows will warn you on whether you want to make changes to this device. Click “yes”. 7. If the Python install was successful then you will get this window: -  +  -## Installing Python on Mac +### Installing Python on Mac Below are step-by-step instruction for installing Python 3.9.6 (which is required for the competition): @@ -30,7 +28,7 @@ Below are step-by-step instruction for installing Python 3.9.6 (which is require 2. Scroll down “Files” and download the relevant Mac installer for your device. 3. Find your downloads folder and open the Python installer. You should get this window: -  +  4. Follow the rest of the instructions as given by the installer. @@ -349,11 +347,11 @@ Below is a list of mathematical operators that you can use: | Operator Name | in Python | Operator in mathematical form | | ------------- | --------- | ----------------------------- | -| Add | `a + b` |  | -| Subtract | `a - b` |  | -| Divide | `a / b` |  | -| Multiply | `a * b` |  | -| Powers | `a ** b` |  | +| Add | `a + b` |  | +| Subtract | `a - b` |  | +| Divide | `a / b` |  | +| Multiply | `a * b` |  | +| Powers | `a ** b` |  | #### Additional Resources - Basic Operators diff --git a/layouts/partials/custom-header.html b/layouts/partials/custom-header.html deleted file mode 100644 index c37a1bb8..00000000 --- a/layouts/partials/custom-header.html +++ /dev/null @@ -1 +0,0 @@ - diff --git a/layouts/partials/favicon.html b/layouts/partials/favicon.html deleted file mode 100644 index 7261e9dd..00000000 --- a/layouts/partials/favicon.html +++ /dev/null @@ -1 +0,0 @@ - diff --git a/layouts/partials/logo.html b/layouts/partials/logo.html deleted file mode 100644 index 59b50605..00000000 --- a/layouts/partials/logo.html +++ /dev/null @@ -1,3 +0,0 @@ - -
![]({{ relURL "/img/logo-white.svg" }}){kind=logo}
-
diff --git a/layouts/partials/menu-footer.html b/layouts/partials/menu-footer.html
deleted file mode 100644
index 8696e6c5..00000000
--- a/layouts/partials/menu-footer.html
+++ /dev/null
@@ -1 +0,0 @@
-Built with with Learn and Hugo.
diff --git a/layouts/shortcodes/added_in.html b/layouts/shortcodes/added_in.html deleted file mode 100644 index 272d9764..00000000 --- a/layouts/shortcodes/added_in.html +++ /dev/null @@ -1,21 +0,0 @@ -{{ $feature := .Get "feature" }} -{{ $update := .Get "update" }} - -{{ with $.Site.GetPage "page" "updates" $update }} -
-
-{{ else }}
-
- - Support for {{ $feature }} was added in the - {{ .Title }} - update. You need to be running at least that version of the kit software - in order to use this feature. -
-
-
-{{ end }}
diff --git a/layouts/shortcodes/center.html b/layouts/shortcodes/center.html
deleted file mode 100644
index d4a64a97..00000000
--- a/layouts/shortcodes/center.html
+++ /dev/null
@@ -1,3 +0,0 @@
-- ERROR: - {{ errorf "Invalid update specified: '%s' does not exist." $update }} -
-
- {{ .Inner }}
-
diff --git a/layouts/shortcodes/python_minor_version.html b/layouts/shortcodes/python_minor_version.html
deleted file mode 100644
index 2620cd9a..00000000
--- a/layouts/shortcodes/python_minor_version.html
+++ /dev/null
@@ -1 +0,0 @@
-{{ delimit (first 2 (split .Site.Params.pythonVersion ".")) "." -}}
diff --git a/layouts/shortcodes/python_patch_version.html b/layouts/shortcodes/python_patch_version.html
deleted file mode 100644
index 0359a524..00000000
--- a/layouts/shortcodes/python_patch_version.html
+++ /dev/null
@@ -1 +0,0 @@
-{{ .Site.Params.pythonVersion -}}
diff --git a/layouts/updates/list.html b/layouts/updates/list.html
deleted file mode 100644
index 9c9e1236..00000000
--- a/layouts/updates/list.html
+++ /dev/null
@@ -1,28 +0,0 @@
-{{ partial "header.html" . }}
-
-{{ .Content }}
-
-| - | Version number | -Release Date | -Image Download | -
|---|---|---|---|
| {{ .Title }} | -{{ default "N/A" .Params.version }} | -{{ .Date.Format "2006-01-02" }} | -
- {{ if .Params.image }}
- Download pi-image.img.xz
- {{ else }}
- No SD card image available
- {{ end }}
- |
-
| Download SD Card Image | - {{ end }} - - {{ if .Params.update }} -Download Update File | - {{ end }} -