Document robot.sleep and robot.time

programming/robot_api/index.md

@@ -108,6 +108,43 @@ is_simulated
 :   A boolean value indicating whether or not the code is running in the simulator.
     This value is `True` when in the simulator and `False` when on the robot.
 
+sleep(seconds)
+:   A method, similar to the built-in [`time.sleep`](https://docs.python.org/3/library/time.html#time.sleep), which pauses the program's execution for a given number of seconds.
+
+    ~~~~~ python
+    from sr.robot3 import Robot
+
+    robot = Robot()
+
+    print("The robot just started.")
+
+    robot.sleep(2.5)
+
+    print("The robot has been running for 2.5 seconds.")
+    ~~~~~
+
+    This method is particularly useful in the simulator, where the simulation may be running faster than real-time. Whilst `time.sleep` will still work as expected on the physical robot, it's still recommended to use `robot.sleep` to ensure your code is portable.
+
+    See [Simulation of Time]({{ site.baseurl }}/simulator/using_the_simulator#simulation-of-time) for more information.
+
+time()
+:   Returns the current time in seconds, measured since an [epoch](https://en.wikipedia.org/wiki/Epoch) (reference time). This method is similar to the built-in [`time.time`](https://docs.python.org/3/library/time.html#time.time) method.
+
+    Whilst the exact time on the robot will not be correct (it won't match a clock), it will still progress as expected, making it useful to measure the duration between 2 points in time. The exact value of the time itself is meaningless.
+
+    ~~~~~ python
+    from sr.robot3 import Robot
+
+    robot = Robot()
+
+    start = robot.time()
+    do_expensive_operation()
+    end = robot.time()
+
+    duration = end - start
+
+    print(f"The expensive operation took {duration:.2f} seconds.")
+    ~~~~~
 
 ## Custom Robot Object Initialisation
 

simulator/using_the_simulator.md

@@ -114,12 +114,14 @@ As time in the simulator is part of the simulation itself, your code must regula
 To allow the simulation to be run at various speeds, `time.sleep` must not be used.
 Instead, `robot.sleep` should be used.
 This allows the simulator to simulate the time your robot would be sleeping for.
+For similar reasons, to obtain the current time, `robot.time` must be used over `time.time`.
 
 While the simulator does simulate the time taken for each call to our API, it does not simulate the time taken for general computation.
 This means that if you have a loop that does not contain a `robot.sleep`, the simulator will freeze as it waits for the loop to complete.
 If you find the timer is not advancing, or is very slow, you likely have a loop without a sleep.
 Generally, it is best practice to have a `robot.sleep` in every loop, even if it is a very short time.
 
+
 ### Reopening the Camera Overlay
 
 To reopen the camera overlay if it has been closed, you can follow these steps: