Merge pull request #172 from sourcebots/simulator-section

tpoomlmly · web-flow · commit cc06521c2a6f · 2021-08-16T14:05:44.000+01:00
Create dedicated simulator section
diff --git a/content/api/_index.md b/content/api/_index.md
@@ -1,6 +1,6 @@
 ---
 title: API
-weight: 3
+weight: 2
 ---
 
 Programming your robot is done in [Python](https://www.python.org/),
diff --git a/content/api/arduino.md b/content/api/arduino.md
@@ -1,6 +1,5 @@
 ---
 title: Arduino API
-weight: 5
 ---
 
 The [Arduino](https://store.arduino.cc/arduino-uno-rev3) provides a
diff --git a/content/api/game-state.md b/content/api/game-state.md
@@ -1,6 +1,5 @@
 ---
 title: Game State
-weight: 9
 ---
 
 ## Mode
diff --git a/content/api/motor-board.md b/content/api/motor-board.md
@@ -1,6 +1,5 @@
 ---
 title: Motor Board API
-weight: 1
 ---
 
 The kit can control multiple motors simultaneously. One Motor Board can
diff --git a/content/faqs/_index.md b/content/faqs/_index.md
@@ -1,6 +1,6 @@
 ---
 title: FAQs
-weight: 7
+weight: 6
 ---
 
 Teams often ask us questions, so we've put the most common ones below, so others can learn from them.
diff --git a/content/kit/_index.md b/content/kit/_index.md
@@ -1,10 +1,10 @@
 ---
 title: Kit
-weight: 9
+weight: 5
 ---
 
 {{% notice warning %}}
-These kit docs are only relevant for the physical robot, as opposed to the [simulator](../tutorials/simulator).
+These kit docs are only relevant for the physical robot, as opposed to the [simulator](/simulator/).
 {{% /notice %}}
 
 ## Boards
diff --git a/content/rules/_index.md b/content/rules/_index.md
@@ -1,6 +1,6 @@
 ---
 title: Rules
-weight: 5
+weight: 4
 ---
 
 You can find the rules for Smallpeice 2021 competition here!:
diff --git a/content/simulator/_index.md b/content/simulator/_index.md
@@ -0,0 +1,37 @@
+---
+title: Simulator
+weight: 3
+---
+
+{{% notice note %}}
+Should you wish to run the simulator locally, this is fine, however it will drastically limit your ability to collaborate with the rest of your team.
+{{% /notice %}}
+
+## Running simulations
+
+To ease the load on your computers, the Webots simulator will be run by us, which you can interact with through our runner interface. The runner allows you to run simulations, and view the logs and recordings afterwards.
+
+To run a simulation, click the "Run Simulation" button. The button will prevent you from running additional simulations whilst a simulation is running. Once the simulation has finished, the button will return to "Run Simulation", and an entry will be shown below it with a link to the logs and animation for your simulation run. Note that this always uses the files in the `zone-0` / `zone-1` directory.
+
+## Directory structure
+
+In VSCode, you will see a directory structure which looks similar to this:
+
+``` plain
+.
+├── competition-simulator
+│   ├── controllers
+│   │   ├── example_controller
+│   │   └── sr_controller
+│   ├── ...
+│   └── worlds
+├── output
+│   └── 2021-08-07T19_20_46.108422
+│       ├── 2021-08-07T18_31_56.html
+│       ├── 2021-08-07T18_31_56.json
+│       ├── 2021-08-07T18_31_56.x3d
+│       └── logs.txt
+└── zone-0
+    ├── crane.py
+    └── forklift.py
+```
diff --git a/content/simulator/local.md b/content/simulator/local.md
@@ -1,9 +1,8 @@
 ---
-title: Simulator
-weight: 5
+title: Local installation
 ---
 
-To test out your robot code, you can use our Simulator. This gives you a realistic environment to run your code, against a dummy robot, without the need for a physical arena. This simulator is currently only available on Windows.
+Should you wish to run the simulator locally, this is fine, however it will drastically limit your ability to collaborate with the rest of your team.
 
 ## Installation
 
@@ -17,7 +16,9 @@ You will also need Python 3.9 installed.
 
 There are a small number of [external libraries](/api#included-libraries) which will be available to your robot code during the competition. For local development you will need to install these yourself.
 
-{{% notice warning %}} If you are installing python on Windows, you will need to add python to PATH otherwise Webots will not be able to find the python installation {{% /notice %}}
+{{% notice warning %}}
+If you are installing python on Windows, you will need to add python to `PATH` otherwise Webots will not be able to find the python installation
+{{% /notice %}}
 
 ### Installing the simulation
 
@@ -30,7 +31,6 @@ You may receive a warning about your computer’s GPU not being good enough, whi
 
 If Webots is picking up the incorrect version of Python, you’ll need to change it. This can be done using Tools > Preferences > General > Python command. You’ll need to ensure a matching version of Python is installed.
 
-
 ## Overview
 
 Within the Webots IDE, there are a few different panels:
@@ -40,25 +40,6 @@ Within the Webots IDE, there are a few different panels:
 - At the bottom is the console, where output from your robot code will be displayed
 - At the top are your general controls which include the time controls. Press the centre play button to run the simulation at normal speed.
 
-## Other robots
-
-There is another robot in the arena, in its starting zone. By default, this robot will not move.
-
-To control the other robot, you will need to provide its code:
-
-Create the robot code in `zone-1/robot.py`. Your code at `robot.py` will be used for zone 0, though you are encouraged to move your code to `zone-0/robot.py` when running multiple robots. Robots which do not have any robot code in their `zone-x` directory will not do anything.
-
-``` plain
-.
-├── competition-simulator
-│   ├── controllers
-│   │   ├── example_controller
-│   │   └── sr_controller
-│   ├── ...
-│   └── worlds
-└── robot.py
-```
-
 ## Time
 
 In the simulated environment, time advances only at the pace that the simulator is run. The relation between this time and the real passage of time depends on a couple of factors: the speed the simulation is configured to run at and the ability of the computer running the simulation to process it fast enough.
diff --git a/content/simulator/programming/_index.md b/content/simulator/programming/_index.md
@@ -0,0 +1,56 @@
+---
+title: Programming
+weight: 1
+---
+
+On first run, the robot will execute an example program for convenience. On first run, this will be copied into `zone-0` in the same directory that `competition-simulator-<version>` is stored in:
+
+```plain
+.
+├── competition-simulator-<version>
+│   ├── ...
+│   └── worlds
+│       └── Arena.wbt
+├── zone-0
+│   ├── crane.py
+│   └── forklift.py
+└── zone-1
+```
+
+Your code for the forklift robot should go in `forklift.py` and the crane in `crane.py`.
+
+{{% notice warning %}}
+Only your controller code will be present in the competition environment.
+{{% /notice %}}
+
+### Time
+
+In the simulated environment, time advances only at the pace that the simulator
+is run. As a result, using `time.time` to know how long your robot has been
+running for or `time.sleep` to wait for some duration will be unreliable.
+
+As a result the API present in the simulator supports a slightly different
+approach to handling time. See the documentation about [simulated time](./time)
+for more details.
+
+## Other robots
+
+There is another robot in the arena; its starting zone is zone 1. By default, this robot will not move.
+
+To control the zone 1 robot, you will need to provide its code:
+
+Create the robot code in `zone-1/forklift.py` and `zone-1/crane.py`. Your original code in `zone-0/` will still be used to control zone 0 robots. Robots which do not have any robot code in their `zone-x` directory will not do anything.
+
+``` plain
+.
+├── competition-simulator
+│   ├── controllers
+│   │   ├── example_controller
+│   │   └── sr_controller
+│   ├── ...
+│   └── worlds
+├── zone-0
+│   └── crane.py
+└── zone-1
+    └── crane.py
+```
diff --git a/content/simulator/programming/time.md b/content/simulator/programming/time.md
@@ -0,0 +1,40 @@
+---
+title: Time
+---
+
+In the simulated environment, time advances only at the pace that the simulator is run and in cooperation with the controller code (such as the code controlling your robot). As a result, using `time.time` to know how long your robot has been running for or `time.sleep` to wait for some duration will have unpredictable results, especially when run on a computer other than the one you are developing on (such as during the competition).
+
+Instead your code should explicitly signal to the simulator when it is ready for time to advance and should query for the current time from the simulator. This can be done by using the methods detailed below.
+
+{{% notice tip %}}
+If you find that the simulator freezes then this indicates that your code is busy doing something without giving the simulator a chance to run. This usually indicates that you have a loop somewhere which is expecting time to advance on its own and which should be modified to call `R.sleep` occasionally (even a very small value will allow the simulator to progress).
+{{% /notice %}}
+
+## Sleeping
+
+If you want to wait for something to happen within the simulation, and you can be reasonably confident that it will take a given amount of time, you can use sleep method on your robot to pause your code for a given duration.
+
+Internally this uses the simulation’s own clock and so is suitable for use in place of `time.sleep`. Note that, just as with `time.sleep`, while your code is sleeping your robot will continue any actions it was doing.
+
+```python
+# Blink the output
+R.arduino.pins[8].digital_state = True
+R.sleep(1.5)  # Sleep for a second and a half of simulation time
+R.arduino.pins[8].digital_state = False
+```
+
+## Getting the current time
+
+If you need to measure the time since some previous moment within the simulator, your robot has a time method which can be used in place of `time.time` to get a number (in seconds) that increases in line with simulation time.
+
+Time zero as returned by this method is the point at which the simulation began, however you should not rely on that being a useful reference point as it may not be the moment at which the match began.
+
+```python
+then = R.time()
+
+# .. do some other things ..
+
+now = R.time()
+
+duration = now - then
+```
diff --git a/content/tutorials/_index.md b/content/tutorials/_index.md
@@ -7,4 +7,3 @@ This part of the docs contains some practical guides for getting starting with b
 
 * [Basic Movement](basic-movement) - explains how to use the kit to operate a motor
 * [Python: A Whirlwind Tour](python-whirlwind-tour) - a guide to using Python, aimed towards those who haven't used it before
-* [A basic guide to using the simulator](simulator) - a guide to using the Webots simulator
diff --git a/content/tutorials/basic-movement.md b/content/tutorials/basic-movement.md
@@ -1,6 +1,5 @@
 ---
 title: Basic Movement
-weight: 1
 ---
 
 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.
diff --git a/content/tutorials/python-whirlwind-tour.md b/content/tutorials/python-whirlwind-tour.md
@@ -1,6 +1,5 @@
 ---
 title: "Python: A Whirlwind Tour"
-weight: 10
 ---
 
 # The Basics
@@ -10,8 +9,8 @@ weight: 10
 Below are step-by-step instructions for installing Python 3.9.6 (which is required for the competition):
 
 1. Go to [https://www.python.org/downloads/release/python-396/ (Python 3.9.6)](https://www.python.org/downloads/release/python-396/)
-2. Scroll down “Files” and click on “**Windows installer 64 bit**” (if you are on a 64 bit machine) or “**Windows installer 32 bit**” (if you are on a 32 bit machine).  
-   If you do not know what version to get, then type in your windows search bar “**About your PC**”. Under ‘system type’ it should tell you what bit of operating system you have.  
+2. Scroll down “Files” and click on “**Windows installer 64 bit**” (if you are on a 64 bit machine) or “**Windows installer 32 bit**” (if you are on a 32 bit machine).
+   If you do not know what version to get, then type in your windows search bar “**About your PC**”. Under ‘system type’ it should tell you what bit of operating system you have.
 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:
 
@@ -252,15 +251,15 @@ If statements let you execute code depending on whether the condition evaluates
 ```python
 name = "mary"
 if len(name) > 3:
-    print("Your name isn't all that short") 
+    print("Your name isn't all that short")
 ```
 
 You can add an `else` statement following your `if` statement to execute code if the condition is false, e.g:
 
 ```python
 name = "mary"
 if len(name) > 3:
-    print("Your name isn't all that short") 
+    print("Your name isn't all that short")
 else:
     print("Wow that's a short name")
 ```

-Original file line number
+Diff line change
@@ @@ -1,6 +1,5 @@ @@
 ---
 title: Game State
 -weight: 9
 ---
 ## Mode