Merge pull request #174 from sourcebots/andy-sp2021

Update docs for SP2021 game

Author: Adimote

.spelling

@@ -1,19 +1,23 @@
+×
 100x100mm
 11.1V
+15cm
+2.2A.
+2.5m
 20000Hz
 20Hz
 2200mAh
-2.2A.
 250x250mm
+2m
 2mm
 3.3V
 3.81mm
 3m
 4mm
 5mm
-70x84x20mm
-7.5mm
 7-zip
+7.5mm
+70x84x20mm
 83x99x24mm
 Adafruit
 AprilTag
@@ -25,7 +29,9 @@ Codecademy
 Datacamp
 dropdown
 elif
+energised
 enum
+forklift
 FreeCodeCamp
 H0-1
 iMAX
@@ -38,6 +44,7 @@ LiPo
 macOS
 Math
 matplotlib
+microswitch
 microswitches
 numpy
 piezo
@@ -46,19 +53,20 @@ Programiz
 PyCharm
 pyplot
 python3
+r.zone
 R2021b
 scikit-learn
 scipy
-SourceBots
 Smallpeice
+SourceBots
 square-ish
 StackOverflow
 submodule
+TargetInfo
 TeckNet
 Tutorialspoint
 Uno
 vcc
 VSCode
 W3Schools
 Webots
-×

content/api/compass.md

@@ -0,0 +1,13 @@
+---
+title: Compass
+weight: 10
+---
+
+The forklift robot has a compass unit. This allows [robots](../../robots/) to determine the direction it's facing in the arena.
+
+```python
+# Get the heading of the robot.
+heading = r.compass.get_heading() # Radians
+```
+
+When called, the `get_heading` method will return the heading of the robot in radians as a float. The heading is in the range 0 to tau (2π), where 0 is the robot facing directly North, and values increasing clockwise.

content/api/encoder.md

@@ -0,0 +1,32 @@
+---
+title: Motor Encoder API
+weight: 8
+---
+
+Most moving parts of the robot have encoders attached. There are two kinds of encoders, linear encoders and rotary encoders. You can tell which is which by the joint it is attached to; if the joint rotates it is a Rotary encoder, whilst if it slides, it is a linear encoder.
+
+## Linear Encoders
+
+Linear encoders are attached to joints that move in a straight line (i.e. raising/lowering the forklift).
+
+Linear encoders measure the distance the joint has moved from its start position, in *metres*.
+
+All encoders are stored in a list called `encoders`, you can access the encoder with `encoders[i]`, where `i` is the slot the encoder is plugged into. You can find this number in the [documentation for the robot](/robots/).
+
+```python
+# Get the distance from the start position
+distance_from_start = r.encoders[1].displacement # in Metres
+```
+
+## Rotary Encoders 
+
+Rotary encoders are attached to joints that rotate (i.e. wheel rotations).
+
+Rotary encoders measure the total rotation the joint has moved from its start position, in *radians*.
+
+All encoders are stored in a list called `encoders`, you can access the encoder with `encoders[i]`, where `i` is the slot the encoder is plugged into. You can find this number in the [documentation for the robot](/robots/).
+
+```python
+# Get the total rotation from the start position
+rotation_from_start = r.encoders[1].rotation # in Radians
+```

content/api/game-state.md

@@ -35,4 +35,4 @@ r.zone
 ```
 
 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`.
+which corner it's in. By default during development, this is `0`.

content/api/magnet.md

@@ -0,0 +1,36 @@
+---
+title: Magnet API
+weight: 8
+---
+
+The magnet is only available on the [Crane robot](../../robots/crane).
+ 
+The magnet of the crane will only stick to containers.
+ 
+## Getting the magnet's status
+ 
+A magnet can be either energised or de-energised, you can turn the magnet on or off by setting `r.magnet.energised` like so:
+```python
+# Turn on the magnet
+r.magnet.energised = True
+# Turn off the magnet
+r.magnet.energised = False
+```
+
+{{% notice warning %}}
+Check the spelling of `energised`, it's in British English, `energized` will not work!
+{{% /notice %}}
+
+You can get the current state of the magnet by getting the value of `energized` like so:
+
+```python
+magnet_on = r.magnet.energised
+```
+ 
+## Checking if a container is nearby
+
+The magnet can tell you if there is an object in range to be picked up. You can check if any object is in range by accessing the `nearby` method:
+```python
+# Is there a container nearby?
+is_nearby = r.magnet.nearby() # True or False
+```

content/api/power-board.md

@@ -0,0 +1,82 @@
+---
+title: Radio API
+weight: 6
+---
+
+Radio transmitters and receivers are attached to various items in the arena.
+Each transmitter encodes their identity, which means that receivers can identify these objects.
+
+Using the signal strength and bearing of the received radio signals, you're able to
+determine the distance and direction of a transmitter relative to the radio in 2D.
+
+Our library provides this through a `radio` attached to your `Robot`,
+which has a `sweep` function that detects transmitters that are in range:
+
+``` python
+# Get all transmitters that are in range.
+transmitters = r.radio.sweep()
+```
+
+When called, the `sweep()` function uses the radio receiver to scan for all transmitters in range.
+It returns a list of `Target` objects, each of which describes one of the transmitters that were found within range.
+A detailed description of the attributes of `Target` objects is provided at the bottom of this page.
+
+Here's an example that will repeatedly print out the information, bearing, and signal strength of each transmitter in range:
+
+``` python
+# Continuously prints details of nearby transmitters.
+while True:
+    transmitters = r.radio.sweep()
+    print("I found", len(transmitters), "transmitter(s):")
+
+    for tx in transmitters:
+        print("Transmitter ID:", tx.target_info.id)
+        print("  Type:", tx.target_info.type)
+        print("  Owner:", tx.target_info.owner)
+        print("  Bearing:", tx.bearing)
+        print("  Signal Strength:", tx.signal_strength)
+```
+
+## Detecting beacons
+
+There are 4 beacons in the arena, see [the rules](/rules/) for their locations. These beacons continually transmit their identity. Beacons can be detected up to 2.5m away.
+
+The beacons have the `target_info.type` value of `0` (`TargetType.BEACON`), which can be used to detect if it is a beacon. See '[Objects of the Radio System](#objects-of-the-radio-system)' below for all available information.
+
+## Detecting containers
+
+There are many containers in the arena, which are each owned by a specific team. Containers can be detected up to 2.5m away.
+
+The beacons have the `target_info.type` value of `1` (`TargetType.CONTAINER`), which can be used to detect if it is a container. See '[Objects of the Radio System](#objects-of-the-radio-system)' below for all available information.
+
+
+## Objects of the Radio System
+
+### Target
+
+A `Target` object contains information about a _detected_ transmitter.
+It has the following attributes:
+
+`target_info`
+: A [`TargetInfo`](#targetinfo) object containing information about the transmitter that was detected.
+
+`signal_strength`
+: The measured strength of the signal as a float.
+
+`bearing`
+: The angle to the `Target` in radians as a float.
+  A bearing of `0` is in front of the robot. Positive bearings are to the robot's right.
+
+### TargetInfo
+
+The `TargetInfo` object contains information about a transmitter.
+It has the following attributes:
+
+`id`
+: The ID of the transmitter, either 1-16 for containers, or 100-103 for beacons. See [the rules](/rules/) for the arena layout.
+
+`type`
+: The type of the transmitter, either `0` (`TargetType.BEACON`) for a beacon, or `1` (`TargetType.CONTAINER`) for a container.
+
+`owner`
+: The zone id of the robot that currently owns the stations territory. This can be `0` (`Owner.ZONE_0`), `1` (`Owner.ZONE_1`), or `-1` (`Owner.NULL`). which indicates it does not have an owner (i.e. it's a beacon). Remember, you can find out which zone your robot is in using [r.zone](/api/game-state)