Add virtual Arduino docs

.spelling

@@ -70,3 +70,7 @@ vcc
 VSCode
 W3Schools
 Webots
+www.python.org
+python-396
+_f_
+×

content/api/arduino.md

@@ -21,7 +21,55 @@ 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
+## Simulator
+
+In the simulator, the Arduino's pins are pre-populated and pre-configured.
+The first few digital pins are occupied by digital inputs, the next few by
+digital outputs, and the analogue pins are attached to ultrasound sensors.
+
+To find out how many inputs and outputs each type of robot has, check the
+[robot docs](../../robots).
+
+You won't be able to change pin mode like in
+a physical robot (see below), but pins 0 and 1 are still unavailable.
+
+### Digital Inputs
+
+Each robot has a number of digital inputs, starting from pin 2. If your
+robot has 5 inputs, those would occupy pins 2-6.
+
+These all have a digital state which you can read as a boolean.
+
+```python
+bumper_pressed = r.arduino.pins[5].digital_state
+```
+
+### Digital Outputs
+
+The digital outputs start the pin after the last input. If your robot has 5
+inputs and 3 outputs, the outputs would occupy pins 7-9.
+
+You can set their state similarly to reading the inputs, and you can also
+read the last value that was set.
+
+```python
+led_state = r.arduino.pins[8].digital_state
+r.arduino.pins[8].digital_state = not led_state  # Toggle output
+```
+
+### Analogue Inputs
+
+Any analogue input devices (e.g. distance sensors) are connected to the
+Arduino's analogue input pins starting from pin `A0`. You can read their
+values like this:
+
+```python
+distance = r.arduino.pins[AnaloguePin.A0].analogue_value
+```
+
+The value read is returned as a float.
+
+## Pin Mode (Unavailable in Simulator)
 
 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
@@ -112,23 +160,3 @@ The values are the voltages read on the pins, between 0 and 5.
 {{% notice warning %}}
 Pins `A4` and `A5` are reserved and cannot be used.
 {{% /notice %}}
-
-## Ultrasound Sensors
-
-You can also measure distance using an ultrasound sensor from the
-Arduino.
-
-``` python
-# Trigger pin: 4
-# Echo pin: 5
-u = r.arduino.ultrasound_sensors[4, 5]
-
-time_taken = u.pulse()
-
-distance_metres = u.distance()
-```
-
-{{% notice warning %}}
-If the ultrasound signal never returns, the sensor will timeout and
-return `None`.
-{{% /notice %}}

content/api/ultrasound.md

@@ -7,15 +7,36 @@ Ultrasound sensors can measure distance of objects from the sensor. Ultrasound s
 
 Ultrasound sensors measure distance in a 18 degree diameter cone in front of the sensor, and report the closest measured distance in that cone. Ultrasound sensors also have a maximum distance. (Ultrasound sensors typically also have a minimum distance too, but we do not simulate that in our simulator).
 
-In our robots, ultrasound sensors are connected to the 'Arduino' board, which is used to read sensors for many different purposes. Keep reading to learn how to take measurements.
- 
+In our robots, ultrasound sensors are connected to the ['Arduino'](../arduino) board, which is used to read sensors for many different purposes. Keep reading to learn how to take measurements.
+
 ## Reading the ultrasound sensor
-
-The ultrasounds sensors will be connected to a specific pin in the Arduino, and will constantly measure distances. Consult the description of the [robot](../../robots/) to see which pin you should use. The analogue value of the pin will be the measured distance, in metres.
+
+### Simulator
+
+The ultrasound sensors will be connected to a specific pin in the Arduino, and will constantly measure distances. Consult the description of the [robot](../../robots/) to see which pin you should use. The analogue value of the pin will be the measured distance, in metres.
 
 Ultrasound sensors have a maximum range of 2 metres, if objects are further than 2m away from the robot, it will report a distance of 2m.
 
 ``` python
 # Get the closest distance to the ultrasound sensor is reading.
 distance_metres = r.arduino.pins[pin].analogue_value
-```
+```
+
+### Physical
+
+Connect the ultrasound sensor to a pair of digital Arduino pins. You can read either the time taken for the sound pulse to reflect back or the pre-calculated distance from the API
+
+``` python
+trigger_pin = 4
+echo_pin = 5
+u = r.arduino.ultrasound_sensors[trigger_pin, echo_pin]
+
+time_taken = u.pulse()
+
+distance_metres = u.distance()
+```
+
+{{% notice warning %}}
+If the ultrasound signal never returns, the sensor will timeout and
+return `None`.
+{{% /notice %}}