Docs update

docs/bot_editing.rst

@@ -13,8 +13,6 @@ If you want to change the design of an existing bot, you can select that bot and
   :width: 600
   :alt: The bot select screen highlighting the new and edit buttons.
 
-If you have the windows one click install, you can also find your bot in ``workspace/robots`` and right click, select ``Open`` to edit the bot.
-
 If you are creating a new bot, you'll be prompted to pick a baseplate for the bot.
 The baseplate is the object that all other components of your robot will rest on. This can be a circle, a regular polygon, or a rectangle.
 
@@ -36,7 +34,7 @@ There are 4 types of elements:
 * Devices (Motors, Sensors, Buttons)
 
 Click the respective icon on the left sidebar to select that element. 
-If you instead click the cursor icon, you will be return to select mode, where you can select elements already on the bot, and change/remove them.
+If you instead click the cursor icon, you will be returned to select mode, where you can select elements already on the bot, and change/remove them.
 
 .. image:: images/bot_edit_holding_elements.png
   :width: 600
@@ -51,7 +49,7 @@ Modifying elements
 ^^^^^^^^^^^^^^^^^^
 
 To modify an element on the robot, we first need to enter the selecting mode, by clicking the cursor icon on the left sidebar.
-Then, click on the element to select it. After this, the bottom bar should populate with properties to edit:
+Then, click and drag to move an element, or click on the element to select it. After this, the bottom bar should populate with properties to edit:
 
 * Rotation
 * Fill and Stroke colour
@@ -63,9 +61,7 @@ And many others. You can edit these properties and see them change in real time
 Any numerical property can be edited simply by typing out the value you want, after clicking in the box. 
 You can also scroll while hovering over the value to increase/decrease it with ease.
 
-The fill and stroke properties can be change by clicking the colour swatch next to it. This should open a colour picker.
-
-The device port entry can be whatever you want it to be, but this property tends to be ``in1,in2,in3...`` for sensors, and ``outA,outB,outC...`` for motors.
+The fill and stroke properties can be changed by clicking the colour swatch next to it. This should open a colour picker.
 
 .. image:: images/bot_edit_properties.png
   :width: 600
@@ -81,17 +77,12 @@ Additionally, the backspace key should also remove the element.
 Adding code to a bot
 --------------------
 
-Designing a good bot also includes designing code to run! You can specify the code location for a specific bot by selecting it in the bot menu and pressing the settings cog.
+Designing a good bot also includes designing code to run!
 
-If you have the windows one click install, you can also find your bot in ``workspace/robots`` and right click, select ``Edit`` to go to the same window.
+You can design this code by selecting the Folder icon when the bot is selected. This should open up a window with a folder containing three items:
 
-.. image:: images/bot_menu_settings.png
-  :width: 600
-  :alt: The bot menu screen, showing the bot properties cog.
+* ``code.py`` - The python file your program will run.
+* ``config.bot`` - Your robot information stored in a file.
+* ``preview.png`` - A preview of your bot.
 
-Then press the button next to 'Bot script' to open the file selector. 
-All code you want to run on your bot should be located in the ``code`` folder of your workspace!
-
-.. image:: images/bot_edit_code.png
-  :width: 600
-  :alt: The bot property editing screen, showing the code location button.
+To design code for your robot, simply edit the contents of ``code.py``.

docs/custom_presets.rst

@@ -3,4 +3,6 @@ Custom Preset Types
 
 You can actually define your own preset types such as soccer and rescue, and run them through EV3Sim!
 
-I haven't documented this because I'm not sure anyone will read this far. If you do want some information on this however, let me know with an issue on github and I can give you some help as well as populate this page!
+I haven't documented this because I'm not sure anyone will read this far. If you do want some information on this however, let me know with an `issue on github`_ and I can give you some help as well as populate this page!
+
+.. _issue on github: https://github.com/MelbourneHighSchoolRobotics/ev3sim/issues

docs/ev3_extensions.rst

@@ -5,12 +5,12 @@ While your robots still run python-ev3dev2 code in the simulation, you also have
 
 Almost all of the below functionality is available in the package ``ev3sim.code_helpers``. In order for this code to work on your physical robot, there also needs to be a package on the physical bot filesystem called ``ev3sim.code_helpers``, containing `this file`_.
 
-For a demo of most of these features, see ``demo.bot`` in the simulator. The code it runs is available `here`_.
+For a demo of most of these features, see the ``demo`` bot in the simulator. The code it runs is available `here`_.
 
 Waiting for simulation ticks
 ----------------------------
 
-As most ev3 programs tend to have a single loop which handles all of the robot's logic, in the interest of efficiency on simulator we highly recommend you attempt to sync this program loop up with each tick of the simulator.
+As most ev3 programs tend to have a single loop which handles all of the robot's logic, in the interest of efficiency on simulator it is essentially required that you attempt to sync this program loop up with each tick of the simulator.
 This is because running multiple program loops per simulation tick is useless (as sensor values won't change) and it can degrade the reliability of sensor values in future, if this program is spending a lot of CPU time running these pointless loops.
 
 You can achieve such a sync with the ``wait_for_tick`` method from the code helpers:
@@ -21,9 +21,10 @@ You can achieve such a sync with the ``wait_for_tick`` method from the code help
 
     while True:
         # Program logic...
+        # Wait for the next simulation tick before I continue...
         wait_for_tick()
 
-Importing this means you need to transfer ``ev3sim/code_helpers.py`` onto the brick for this to run (Just create a folder named ``ev3sim`` and place `code_helpers.py`_ in there).
+Importing this means you need to transfer ``ev3sim/code_helpers.py`` onto the brick for this to run on a physical bot (Just create a folder named ``ev3sim`` and place `code_helpers.py`_ in there).
 
 Robot ID
 --------
@@ -38,7 +39,7 @@ Since you might be running multiple instances of the same code on different robo
 
 This will also work on the brick, it should print "Robot-0".
 
-Importing this means you need to transfer ``ev3sim/code_helpers.py`` onto the brick for this to run (Just create a folder named ``ev3sim`` and place `code_helpers.py`_ in there).
+Importing this means you need to transfer ``ev3sim/code_helpers.py`` onto the brick for this to run on a physical bot (Just create a folder named ``ev3sim`` and place `code_helpers.py`_ in there).
 
 Printing to console
 -------------------
@@ -81,7 +82,7 @@ Example:
     # This message will stay on the console for 3 seconds
     format_print("Hello world!")
     # This message will stay on the console for 5 seconds
-    format_print("Hello world!", life=3)
+    format_print("Hello world!", life=5)
     # This message will stay on the console for 1 second.
     format_print("Hello world!", life=1)
 
@@ -107,7 +108,7 @@ This message will stay open in the console, and its message contents will change
 Logs
 ----
 
-All prints made to the console will also be stored in log files. These log files are available in your workspace if the workspace is defined. Otherwise they will be stored in your EV3Sim install location.
+All prints made to the console will also be stored in log files (As well as error messages). These log files are available in your workspace if the workspace is defined. Otherwise they will be stored in your EV3Sim install location.
 
 Simulation testing
 ------------------
@@ -126,7 +127,7 @@ As an example, the simulator currently does not implement the ``Led`` functional
     if is_sim:
         print("Hello from the sim! Sadly I can't do lights at the moment :(")
 
-Importing this means you need to transfer ``ev3sim/code_helpers.py`` onto the brick for this to run (Just create a folder named ``ev3sim`` and place `code_helpers.py`_ in there).
+Importing this means you need to transfer ``ev3sim/code_helpers.py`` onto the brick for this to run on a physical bot (Just create a folder named ``ev3sim`` and place `code_helpers.py`_ in there).
 
 Handling simulation events
 --------------------------
@@ -149,12 +150,12 @@ To handle such events you can use the code helpers EventSystem:
     EventSystem.on_goal_scored = handle_scored
 
     while True:
-        EventSystem.handle_events()
         wait_for_tick()
+        EventSystem.handle_events()
 
 ``EventSystem.handle_events`` must be called often (ie in every loop iteration, simply add this line after every occurrence of ``wait_for_tick``) to allow such events to fire the related code. Any event in the system returns a data object, which will contain any useful information about the event.
 
-Importing this means you need to transfer ``ev3sim/code_helpers.py`` onto the brick for this to run (Just create a folder named ``ev3sim`` and place `code_helpers.py`_ in there).
+Importing this means you need to transfer ``ev3sim/code_helpers.py`` onto the brick for this to run on a physical bot (Just create a folder named ``ev3sim`` and place `code_helpers.py`_ in there).
 
 The full list of events is:
 
@@ -169,7 +170,7 @@ Fires whenever a goal is scored by either team.
 Fires whenever the game is reset manually.
 
 ``on_penalty_start``
-^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^
 Fires whenever you are placed in the penalty box.
 
 ``on_penalty_end``
@@ -188,7 +189,7 @@ Here is the list of supported commands:
 ``CommandSystem.TYPE_DRAW``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Draws an object to the screen using the same syntax as the simulator. The data passed in must be a dictionary with the following keys:
+Draws an object to the screen using the same syntax as the simulator source code. The data passed in must be a dictionary with the following keys:
 
 - ``obj``: The visual representation of the object.
 - ``key``: The key the visual object will be referenced by (This means you can update the object position by sending the same key).
@@ -198,7 +199,7 @@ Draws an object to the screen using the same syntax as the simulator. The data p
 ``CommandSystem.TYPE_CUSTOM``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-A custom event that can be caught by any custom presets you want to define.
+A custom event that can be caught by any custom simulations you want to define.
 
 Example:
 
@@ -247,14 +248,14 @@ As bluetooth communications are a popular option for complicated strategies with
 
 The communications are written in a client/server architecture, as with normal use of bluetooth comms.
 
-This should also work on the physical robots over bluetooth, provided that the MAC Address and port are correct (Follow the instructions for normal bluetooth connectivity). As with above importing this means you need to transfer ``ev3sim/code_helpers.py`` onto the brick for this to run (Just create a folder named ``ev3sim`` and place `code_helpers.py`_ in there).
+This should also work on the physical robots over bluetooth, provided that the MAC Address and port are correct (Follow the instructions for normal bluetooth connectivity). As with above importing this means you need to transfer ``ev3sim/code_helpers.py`` onto the brick for this to run on a physical bot (Just create a folder named ``ev3sim`` and place `code_helpers.py`_ in there).
 
 For an example of robots communicating device data to each other (in this case through a server, but client/server messaging could also simply work between two robots) try this example (place all 4 commands in separate terminals), you can run the simulation preset ``ev3sim/examples/sims/communications_demo.yaml``
 
 Sources: `communication_client.py`_, `communication_server.py`_
 
-.. _here: https://github.com/MelbourneHighSchoolRobotics/ev3sim/tree/main/ev3sim/examples/robots/demo.py
+.. _here: https://github.com/MelbourneHighSchoolRobotics/ev3sim/tree/main/ev3sim/examples/robots/demo/code.py
 .. _this file: https://github.com/MelbourneHighSchoolRobotics/ev3sim/tree/main/ev3sim/code_helpers.py
 .. _code_helpers.py: https://github.com/MelbourneHighSchoolRobotics/ev3sim/tree/main/ev3sim/code_helpers.py
-.. _communication_client.py: https://github.com/MelbourneHighSchoolRobotics/ev3sim/tree/main/ev3sim/robots/communication_client.py
-.. _communication_server.py: https://github.com/MelbourneHighSchoolRobotics/ev3sim/tree/main/ev3sim/robots/communication_server.py
+.. _communication_client.py: https://github.com/MelbourneHighSchoolRobotics/ev3sim/tree/main/ev3sim/examples/robots/communication_client/code.py
+.. _communication_server.py: https://github.com/MelbourneHighSchoolRobotics/ev3sim/tree/main/ev3sim/examples/robots/communication_server/code.py

docs/index.rst

@@ -27,11 +27,10 @@ A full video on what EV3Sim is and how you can install it can be found here:
    :caption: Contents:
 
    setup
-   batched_commands
+   simulation_settings
    bot_editing
    ev3_extensions
    custom_presets
+   randomisation
    contributing
    system
-
-.. TODO: Support randomisation through settings.

docs/randomisation.rst

@@ -1,50 +1,19 @@
 Randomisation
 =============
 
-TODO: Change this to gui docs
+While disabled by default, you can enable some randomisation for device data (to simulate real life issues) By changing the settings of ev3sim:
 
-When executing ``ev3sim`` you may notice that the following is printed:
+.. image:: images/randomisation_settings.png
+  :width: 600
+  :alt: The settings screen, highlighting randomisation settings.
 
-.. code-block:: bash
+You can also configure these values to your liking / realism by pressing the button on the right:
 
-    Simulating with seed 0000000000
+.. image:: images/randomisation_settings2.png
+  :width: 600
+  :alt: The settings screen, highlighting randomisation settings.
 
-But with a different number to the one above. This number is the 'seed' and essentially defines all randomness that will occur within the system.
-
-Despite being mostly the same on every run, some elements of the simulation require randomness, for realism, and to ensure that every run is slightly different:
-
-* The spawn positions of bots and balls is slightly randomised.
-* The way a colour sensor detects colours requires randomness.
-
-As such in order to redo a simulation exactly as was done before, we want to be able to use the same seed, to ensure all random numbers are also the same.
-
-You can do this with the ``--seed`` or ``-s`` flag in ``ev3sim``. As an example, to simulate with seed 123456789, you can do the following:
-
-.. code-block:: bash
-
-    ev3sim bot.yaml --seed 123456789
-
-Note that the ``Simulating with seed`` line will respect this change. The seed can be any integer from 0 to 2^32 - 1, inclusive.
-
-To make simulation of devices a bit more realistic, there is also support for the randomisation of device characteristics, in similar ways to what you might expect in real life. Examples include:
-
-* Motors having a theoretical maximum speed, but also a physical one which differs slightly
-* Sensors having slight biases towards certain directions
-
-And you can enable this randomisation by using the ``soccer_random.yaml`` preset rather than ``soccer.yaml``:
-
-.. code-block:: bash
-
-    ev3sim bot.yaml --seed 123456789 -p soccer_random.yaml
-
-To add randomisation to your particular preset, you only need to add the following:
-
-.. code-block:: yaml
-
-    settings:
-      ev3sim.simulation.loader.ScriptLoader.RANDOMISE_SENSORS: true  
-
-That being said, some of this randomisation is not done based on the seed, but rather the port and robot the device is connected to (This is to simulate you working with the same device with the same bias between runs). As a rule of thumb:
+In general, the following rules occur to device randomness:
 
 * Internal biases of devices will be static on the same port / robot filename.
-* Randomness which is introduced over time or every game tick is tied to the seed.
+* Randomness which is introduced over time or every game tick is tied to the seed, and so different every time.