Update simulator documentation

.spelling

@@ -27,6 +27,7 @@ Scarzy
 srobo
 ST7202USBGB
 studentrobotics
+unfound
 usbkey
 usercode
 Webots

_data/sidebar_tree.yaml

@@ -123,6 +123,8 @@ tree:
       title: Using the Simulator
     - url: /simulator/simulated_robot
       title: The Simulated Robot
+    - url: /simulator/troubleshooting
+      title: Troubleshooting
   - url: /troubleshooting/
     title: Troubleshooting
     tree:

programming/arduino/custom_firmware.md

@@ -12,11 +12,6 @@ On this page we talk specifically about Arduinos.
 However this page is applicable to opening any device that shows up as a serial port.
 </div>
 
-<div class="info">
-  This documentation refers to a feature which is only available on the physical robot kits.
-</div>
-
-
 ## Ignoring a device
 
 By default when the `robot` object is created it will try to communicate with all Arduinos and will expect them to respond in the way the SR firmware does.

programming/arduino/extended_sr_firmware.md

@@ -5,10 +5,6 @@ title: Arduino extended firmware
 
 # Arduino with extended SR firmware
 
-<div class="info">
-  This documentation refers to a feature which is only available on the physical robot kits.
-</div>
-
 You may wish to extend the SR firmware with additional functionality.
 This will allow you to continue using the commands already provided by the SR firmware (e.g. `digital_read()`),
 which means any existing robot code you have won't need modifying very much.

programming/arduino/sr_firmware.md

@@ -128,3 +128,23 @@ However, for simple electronics, a microswitch for example, you would normally b
 However, the built-in pull-up resistor alleviates this need.
 It essentially wires in a resistor connected to 5.0V, meaning that when this option is enabled, an input pin will "default" to being high.
 This means you can simply connect a switch between the input pin and a ground pin without any need of resistors - when the switch is open, the pin will read high; when closed, it will read low.
+
+## Ultrasound Sensors
+
+You can also measure distance using an ultrasound sensor from the arduino. Ultrasound sensors return the distance of the closest object in mm.
+
+To use this on your robot you will need use HC-SR04 ultrasound modules.
+
+```python
+# Trigger pin: 4
+# Echo pin: 5
+
+# Measure distance in mm
+distance_mm = robot.arduino.ultrasound_measure(4, 5)
+```
+
+<div class="warning">
+The ultrasound sensor can measure distances up to around 4 metres.
+If the ultrasound signal has to travel further, the echo may not be detected. 
+This will cause the sensor to timeout and return 0.
+</div>

programming/cheat_sheet.md

@@ -124,10 +124,6 @@ robot.motor_board.motors[1].power = -1
 
 ### Special motor values
 
-<div class="info">
-  This documentation refers to a feature which is only available on the physical robot kits.
-</div>
-
 Setting a motor to `BRAKE` is equivalent to power level `0`.
 
 ~~~~~ python
@@ -157,10 +153,6 @@ You can also set the position to `0`, which is the approximate centre.
 
 ### Taking a photo
 
-<div class="info">
-  This documentation refers to a feature which is only available on the physical robot kits.
-</div>
-
 It can sometimes be useful to save a photo of what markers the robot can see:
 
 ~~~~~ python
@@ -169,10 +161,6 @@ robot.camera.save("my-photo.jpg")  # Save my-photo.jpg to the USB drive
 
 ### Capturing an openCV array
 
-<div class="info">
-  This documentation refers to a feature which is only available on the physical robot kits.
-</div>
-
 Take a photo using the webcam, and return the image data as an OpenCV array:
 
 ~~~~~ python

programming/leds.md

@@ -8,10 +8,6 @@ title: Brain Board LED API
 Brain Board LED API
 ===================
 
-<div class="info">
-  This documentation refers to a feature which is only available on the physical robot kits.
-</div>
-
 The KCH board provides diagnostic information about the state of your robot through a collection of preconfigured and user-controllable LEDs.
 It is part of the [Brain Board](/docs/kit/brain_board) assembly and will be found attached to the top of the Raspberry Pi.
 

programming/motors.md

@@ -124,10 +124,6 @@ print(robot.motor_boards["srABC1"].motors[0].power)
 Special Values
 --------------
 
-<div class="info">
-  This documentation refers to a feature which is only available on the physical robot kits.
-</div>
-
 In addition to the numeric values, there are two special constants that can be used:
 - `BRAKE`
 - `COAST`
@@ -156,7 +152,7 @@ Motor currents
 --------------
 
 <div class="info">
-  This documentation refers to a feature which is only available on the physical robot kits.
+  In the simulator, the current values always return 0.
 </div>
 
 The Motor Board can also measure the current being drawn by each of the ports on the board.

programming/servos.md

@@ -58,10 +58,6 @@ print(robot.servo_board.servos[1].position)
 Disabling servo outputs
 -----------------------
 
-<div class="info">
-  This documentation refers to a feature which is only available on the physical robot kits.
-</div>
-
 Setting a position to `None` will disable an output.
 This is the state all the servo outputs are in when the board turns on, where no servo pulses are being sent to the outputs.
 
@@ -74,10 +70,6 @@ robot.servo_board.servos[5].position = None
 Extended servo range
 --------------------
 
-<div class="info">
-  This documentation refers to a feature which is only available on the physical robot kits.
-</div>
-
 For an RC servo the angle of rotation is determined by the width of an electrical pulse on the control wire.
 A typical servo expects to see a pulse every 20ms, with a pulse width between 1ms and 2ms.
 Our API will take the position provided (between -1 and 1) and map it to the correct pulse width.

programming/vision/index.md

@@ -49,9 +49,6 @@ Try pausing movement while taking an image.
 
 save
 :   Take a photo using the webcam, draw a box around the detected markers and save it to the provided location.
-    <div class="info">
-      This function is only available on the physical robot kits.
-    </div>
 
 ~~~~~ python
 from sr.robot3 import *
@@ -63,9 +60,6 @@ robot.camera.save(robot.usbkey / "initial-view.jpg")
 
 capture
 :   Take a photo using the webcam, and return the image data as an OpenCV array.
-    <div class="info">
-      This function is only available on the physical robot kits.
-    </div>
 
 ~~~~~ python
 import cv2
@@ -114,15 +108,9 @@ size
 
 pixel_centre
 :   A [`PixelCoordinates`](#pixel-coordinates) object describing the position of the centre of the marker in the image.
-    <div class="info">
-      This attribute is only available on the physical robot kits.
-    </div>
 
 pixel_corners
 :   A list of 4 [`PixelCoordinates`](#pixel-coordinates) objects, each representing the position of a corner of the marker in the image.
-    <div class="info">
-      This attribute is only available on the physical robot kits.
-    </div>
 
 position
 :   A `Position` object describing the position of the marker.
@@ -163,10 +151,6 @@ orientation
 
 ### Pixel Coordinates
 
-<div class="info">
-  This documentation refers to a feature which is only available on the physical robot kits.
-</div>
-
 A named tuple of `x` and `y` coordinates for the point, in pixels relative to the top left of the image.
 
 ~~~~~ python

simulator/index.md

@@ -7,28 +7,24 @@ title: Simulator
 
 ![Image of the SR2024 arena rendered within the simulated environment]({{ site.baseurl }}/images/content/simulator/sr2024-arena.png)
 
-The simulator is used for the virtual competition and is a useful development tool, it allows you to become familiar with our API and to get started coding straight away even if you have yet to construct your robot.
-It could also be used to test out game strategies before applying them in real life.
+The simulator is a useful development tool that allows you to become familiar with our API and test out robotics concepts even if you haven't finished building your robot yet.
+It could also be used to test out game strategies before applying them in real life, the simulator will be used for a virtual competition part way through the year.
 
-## Programming
+The simulator is built around the [Webots](https://cyberbotics.com/#download) platform, which runs the simulation.
+You control the virtual robot using the [Robot API]({{ site.baseurl }}/programming/robot_api/), just like on the physical robots.
 
-Programming for the simulator is very similar to [programming for your physical robot]({{ site.baseurl }}/programming/).
+## Setup
 
-The simulator provides a subset of the `sr.robot3` [Robot API]({{ site.baseurl }}/programming/robot_api/) which is used on the physical robots.
-As a result code which is written for the simulator should largely work on your robot and vice-versa.
+To use the simulator, you will need to install the simulator software and download our simulation environment.
+This is detailed in the [Setting up the Simulator]({{ site.baseurl }}/simulator/setting_up_simulator) section.
 
-## Getting started
-
-In order to use the simulator you will need to install the simulator software and download the Student Robotics simulation.
-This is detailed in the section on [Setting up the Simulator]({{ site.baseurl }}/simulator/setting_up_simulator).
-
-Once you're set up, the page on [Using the Simulator]({{ site.baseurl }}/simulator/using_the_simulator) provides details on how to use the simulator software as well as get started on developing the code for your simulated robot.
+Once you're set up, the [Using the Simulator]({{ site.baseurl }}/simulator/using_the_simulator) section provides details on how to use the simulator software and get started on developing the code for your simulated robot.
 
 Just as for programming your robot, we recommend that you use a code editor.
 A good code editor can provide you with features such as auto completion and syntax highlighting which will help you more easily write code.
 For suggestions of suitable editors, and how to set them up see the [Code Editors]({{ site.baseurl }}/tutorials/editors/) section.
 
-## The Simulated Robot
+## The Robot
 
-The simulation contains a pre-built robot, constructed around a set of simulated kit components.
-The capabilities and limitations of this robot are detailed in the section on [The Simulated Robot]({{ site.baseurl }}/simulator/simulated_robot).
+The simulator contains a pre-built robot, constructed around a set of simulated kit components.
+The connected boards and sensors are covered in the [Simulated Robot]({{ site.baseurl }}/simulator/simulated_robot) section.

simulator/setting_up_simulator.md

@@ -6,118 +6,76 @@ title: Setting up the Simulator
 Setting up the Simulator
 ========================
 
-There are three key components you will need in order to be able to use the simulator:
+## Required Software
 
-- [Webots](#webots), the platform which runs the simulation
-- [Python](#python), the interpreter for the your robot code
-- The [world simulation](#world-simulation), which includes the SR API for use in the simulator
+In order to use the simulator a few set-up steps need to be done.
+First you need to install Python 3.8+ and Webots R2023b.
 
+To install Python, you can download the latest version from the [Python website](https://www.python.org/downloads/). If you have already installed Python from a package manager, such as homebrew on MacOS, apt on Ubuntu, or the Windows store on Windows, you can skip this step.
+![python download site]({{ site.baseurl }}/images/content/simulator/python-download.png)
 
-## Webots
+We recommend using **Python 3.11** as it is the version which is used on your physical robot.
 
-Webots is a free open-source robot simulator. It is the program which runs the simulation.
+To install Webots, you can download the latest version from the [Webots website](https://cyberbotics.com/#download). Use the default settings when installing Webots.
+![webots download site]({{ site.baseurl }}/images/content/simulator/webots-download.png)
 
-You need to download [Webots from here](https://cyberbotics.com/#download) and install it.
+## Simulator Bundle
 
-The current supported version is **R2023b**.
+Once you have installed these, you need to download our [simulator bundle](https://github.com/srobo/sbot_simulator/releases/download/2024.0.1/sbot-simulator-2024.0.1.zip).
+This is a zip file containing the arena and the necessary files to allow the sr-robot3 library to be used in the simulator.
 
-### Troubleshooting: performance
+Once this has downloaded, extract the contents to an empty folder.
+This folder will contain the arena as well as the code you will develop to control the robot.
 
-The default settings work for most users however if you are using a less powerful computer or one without a dedicated graphics card (as is the case on many laptops), you may wish to adjust the graphics settings to enable the simulation to run faster.
+<div class="info" markdown="1">
+The contents of the folder should look like this:
 
-If you find that the simulation runs very slowly we suggest disabling both Ambient Occlusion and Shadows.
-These should not affect the behaviour of the simulation, only the rendered visuals.
-
-To do this on Windows, open webots and go to the menu **Tools** &rarr; **Preferences** &rarr; **OpenGL**, then set **Ambient Occlusion** to "none" and check the box next to "Disable shadows".
-
-To do this on Mac, open webots and go to the menu **Webots** &rarr; **Preferences** &rarr; **OpenGL**, then set **Ambient Occlusion** to "none" and check the box next to "Disable shadows".
-
-## Python
-
-You will also need Python installed.
-If it is not already installed this can be downloaded and installed from the [Python website](https://www.python.org/downloads/).
-
-We recommend using **Python 3.11** as it is the newest supported version and is the version which is used on your physical robot.
-The most recent version of Python (3.12), which is the default download, is not yet supported by Webots.
-
-| Platform | Supported Python Version |
-|----------|--------------------------|
-| Windows  | 3.8-3.11 (64-bit)        |
-| macOS    | 3.8-3.11                 |
-| Linux    | 3.8-3.11                 |
-
-
-### Python libraries
-
-There are a small number of [external libraries]({{ site.baseurl }}/kit/brain_board/python_libraries) which are available on the physical kit that may be useful in the simulator.
-If you want to use these in your code you will need to install these yourself.
-
-Once you have downloaded the simulation, the libraries can be installed with the following command in a terminal.
-
-~~~~~bash
-pip install -r competition-simulator-<version>/libraries.txt
-~~~~~
-
-
-### Troubleshooting: setting your version of Python
-
-Sometimes Webots will not automatically detect your installed Python in which case it will need to be set manually.
-When this happens Webots will print errors to its console and your robot will not move.
-
-You will need the full path to the version of Python that you want to use.
-This will vary based on the system you have.
-One way to find the path is by launching Python and running the following code:
-
-~~~~~ python
-import sys
-print(sys.executable)
-~~~~~
-
-Once you have the path you need to enter this into the Webots settings.
-
-To do this on Windows, open webots and go to the menu **Tools** &rarr; **Preferences** &rarr; **General** &rarr; **Python command** and enter the path in that box.
-Your Python path is likely similar to `C:\Users\<USERNAME>\AppData\Local\Programs\Python\Python311\python.exe` when using Python 3.11, where `<USERNAME>` is your login.
+![File contents of a release]({{ site.baseurl }}/images/content/simulator/release-contents.png)
+</div>
 
-On Mac you can set the path to the Python version to use via **Webots** &rarr; **Preferences** <kbd>⌘</kbd><kbd>,</kbd>.
-Your Python path is likely similar to `/Library/Frameworks/Python.framework/Versions/3.11/bin/python3` when using Python 3.11.
-If you installed Python using Homebrew, it will be in `/opt/homebrew/bin/python3.11` (or `/usr/local/bin/python3.11` on an Intel-based Mac)
+- The `simulator` folder contains our code to support running your code in the simulator.
+- The `zone_0` folder is where you will write your code, and it must contain a file called `robot.py`.
+- The `setup.py` and `run_simulator.py` files are used to set up the environment and run the simulator respectively.
+- The `readme.html` file contains a single page guide to using the simulator, similar to this one.
 
-If you're still having problems, ask for help in [Discord][discord].
+If the world supports multiple zones, you will see a `zone_1` folder, and so on.
 
+<div class="info" markdown="1">
+If you had previously downloaded the simulator, you can copy your code from the previous installation by copying just the `zone_0` folder from the old installation to the new one.
+</div>
 
-## The world simulation {#world-simulation}
+## Setting up the Environment
 
-The world simulation we provide defines the environment that contains the simulated arena and robot as well as the SR API for use in the simulator.
+Now that you have downloaded and extracted the simulator, you need to set up the environment to run the simulator.
+Since the simulator uses the sr-robot3 library, there are a series of python packages that need to be installed and Webots needs to be configured to use the correct version of Python.
+We have provided a script that will set up this environment for you.
 
-1. Create a directory, perhaps called `simulation` where you will store your robot code.
-2. [Download the simulation](https://github.com/srobo/competition-simulator/releases/download/sr2024.2/competition-simulator-sr2024.2.zip), the latest version is sr2024.2, released on 2024-02-04.
-3. Unzip the simulation as a folder inside the folder you created in the first step:
-    ```
-    simulation
-    ├── competition-simulator-<version>
-    │   ├── ...
-    │   └─ libraries.txt
-    │   └─ worlds
-    │       └── Arena.wbt
-    └── robot.py
-    ```
-    If there is not an existing `robot.py` an example one will be created when the simulator first runs.
+First, navigate to the folder you extracted the simulator into. This folder should contain a file called `setup.py`.
+Run this script and it will set up the environment for you.
+A terminal window will open and you will see the output of the script, if there are any errors displayed you should ask for help in [Discord][discord].
 
-4. Open the Webots IDE, then use that to open the `worlds/Arena.wbt` file.
+<div class="info" markdown="1">
+In order to run the Python script, instead of opening the file you may need to right-click and select **Open with** &rarr; **Python**.
 
-You may receive a warning about your computer's GPU not being good enough, which can be ignored.
+![Open with Python]({{ site.baseurl }}/images/content/simulator/open-with-python.png)
+</div>
 
 <div class="info">
-On recent versions of macOS you may need to give Webots permission to access the directory where you have extracted the simulation files.
+On recent versions of macOS you may need to give Python permission to access the directory where you have extracted the simulation files.
 </div>
 
+This will create a contained python installation with the required libraries in a `venv` folder, this is called a virtual environment.
+This also configures the Webots settings to use the correct version of Python.
 
 ## Updates
 
 Occasionally, we may release an update to the simulation.
-To update, you will need to delete the `competition-simulator-<version>` folder and replace it with the new version that can be downloaded using the above link.
+To update, download the new version of the simulator using the link above and extract it to an empty folder.
+Then, run the `setup.py` script again to update the environment.
+
+If you want to use code from a previous version of the simulator, you can copy the `zone_0` folder from the old installation to the new one.
 
 If you need a specific version of the simulator, or want to see what changes have been made with each version, please see the [list of releases][release-list].
 
 [discord]: {{ site.baseurl }}/tutorials/discord
-[release-list]: https://github.com/srobo/competition-simulator/releases
+[release-list]: https://github.com/srobo/sbot_simulator/releases