synchronize develop with master

Software/Python/Examples/easy_Motors.py

@@ -21,24 +21,22 @@
 # import the time library for the sleep function
 import time
 # import the GoPiGo3 drivers
-import easygopigo3 as easy
+from easygopigo3 import EasyGoPiGo3
 
 # Create an instance of the GoPiGo3 class.
 # GPG will be the GoPiGo3 object.
-gpg = easy.EasyGoPiGo3()
+gpg = EasyGoPiGo3()
 
 print("Move the motors forward freely for 1 second.")
 gpg.forward()
 time.sleep(1)
+gpg.stop()
 
 print("Stop the motors for 1 second.")
-gpg.stop()
 time.sleep(1)
 
 print("Drive the motors 50 cm and then stop.")
 gpg.drive_cm(50, True)
-
-print("Wait 1 second.")
 time.sleep(1)
 
 print("Turn right 1 second.")

Software/Python/easygopigo3.py

@@ -348,6 +348,7 @@ def spin_right(self):
              You can achieve the same effect by calling ``steer(100, -100)`` (method :py:meth:`~easygopigo3.EasyGoPiGo3.steer`).
 
         """
+
         self.set_motor_dps(self.MOTOR_LEFT, self.NO_LIMIT_SPEED)
         self.set_motor_dps(self.MOTOR_RIGHT, self.NO_LIMIT_SPEED * -1)
 
@@ -408,7 +409,6 @@ def steer(self, left_percent, right_percent):
         self.set_motor_dps(self.MOTOR_RIGHT, self.NO_LIMIT_SPEED * right_percent / 100)
 
 
-
     def orbit(self, degrees, radius_cm=0, blocking=True):
         """
         Control the GoPiGo so it will orbit around an object.  
@@ -420,7 +420,6 @@ def orbit(self, degrees, radius_cm=0, blocking=True):
         .. important:: 
            Note that while in non-blocking mode the speed cannot be changed before the end of the orbit as it would negate all orbit calculations. 
            After a non-blocking call, :py:meth:`~easygopigo3.EasyGoPiGo3.set_speed` has to be called before any other movement.
-
         """
         speed = self.get_speed()
         radius = radius_cm * 10

docs/source/api-basic/structure.rst

@@ -103,6 +103,8 @@ Functions Short-List
 Here's a short summary of the methods of all classes that are documented. We start off with a couple of lists for the methods/functions/methods of the :py:mod:`easygopigo3` module and then
 we finish with another few for the :py:mod:`easysensors` module, so that we can create a visual distinction one from another and thus make it more easy to search around.
 
+.. _gopigo3-movement-api-methods:
+
 """""""""""""""""""""""""""""""""""""
 GoPiGo3 Movement
 """""""""""""""""""""""""""""""""""""

docs/source/tutorials-basic/button.rst

@@ -166,8 +166,5 @@ Then, on the Rasperry Pi, from within a terminal, type the following commands.
 
 .. image:: http://i.imgur.com/6SQr3vY.gif
 
-
-
-
 .. _gopigo3: https://www.dexterindustries.com/shop/gopigo-advanced-starter-kit/
 .. _grove button: https://www.dexterindustries.com/shop/grove-button/

docs/source/tutorials-basic/distance_sensor.rst

@@ -1,7 +1,7 @@
 .. _tutorials-basic-distance-sensor:
 
 **********************************
-Measuring with the Distance Sensor
+Measuring Distance
 **********************************
 
 ========

docs/source/tutorials-basic/driving.rst

@@ -0,0 +1,201 @@
+.. _tutorials-basic-driving-chapter:
+
+**************************
+Driving Around
+**************************
+
+Driving the GoPiGo3 around is only a matter of choosing the right methods from the :py:class:`~easygopigo3.EasyGoPiGo3` class.
+In all of our examples, the :py:mod:`~easygopigo3` is required and needs to be imported and a :py:class:`~easygopigo3.EasyGoPiGo3` object
+can be instantiated this way:
+
+.. code-block:: python
+
+   from easygopigo3 import EasyGoPiGo3 # importing the EasyGoPiGo3 class
+   gpg = EasyGoPiGo3() # instantiating a EasyGoPiGo3 object
+
+Instantiating :py:class:`~easygopigo3.EasyGoPiGo3` object can fail if the GoPiGo3 is not present or there's a firmware mismatch.
+Check the :py:class:`~easygopigo3.EasyGoPiGo3.__init__` constructor of this class to see what exceptions can be raised.
+
+=======================
+Forward, R/L, Backward
+=======================
+
+The most basic commands don't offer control over how much distance the GoPiGo3 travels. They only get called once and then
+it's the responsability of the user to stop the GoPiGo3 from moving, regularly by using the :py:meth:`~easygopigo3.EasyGoPiGo3.stop` command.
+
+We first need to import the :py:class:`easygopigo3` and the :py:mod:`python:time` modules and instantiate a EasyGoPiGo3 object.
+
+.. code-block:: python
+
+    # import the time library for the sleep function
+    import time
+    from easygopigo3 import EasyGoPiGo3
+
+    # create an instance of the GoPiGo3 class.
+    # gpg will be the GoPiGo3 object.
+    gpg = EasyGoPiGo3()
+
+Next, move the robot forward for exactly one second and right after that continue to the next block of code.
+
+.. code-block:: python
+
+    print("Move the motors forward freely for 1 second.")
+    gpg.forward()
+    time.sleep(1)
+    gpg.stop()
+
+Stop the motors for a second.
+
+.. code-block:: python
+
+    print("Stop the motors for 1 second.")
+    time.sleep(1)
+
+And then move forward again, but this time for 50 centimeters and once the moving function ends, wait a second until the next block of code
+gets executed. Notice that :py:meth:`~easygopigo3.EasyGoPiGo3.drive_cm` is a blocking function in this case.
+
+.. code-block:: python
+
+    print("Drive the motors 50 cm and then stop.")
+    gpg.drive_cm(50, True)
+    time.sleep(1)
+
+
+Then right for a second.
+
+.. code-block:: python
+
+    print("Turn right 1 second.")
+    gpg.right()
+    time.sleep(1)
+
+And likewise to the left.
+
+.. code-block:: python
+
+    print("Turn left 1 second.")
+    gpg.left()
+    time.sleep(1)
+
+Finally, stop the robot.
+
+.. code-block:: python
+
+    print("Stop!")
+    gpg.stop()
+    print("Done!")
+
+If you want to run this by yourself, `here's the script on github <https://github.com/DexterInd/GoPiGo3/blob/master/Software/Python/Examples/easy_Motors.py>`_.
+
+.. image:: https://i.imgur.com/xWzt6c4.gif
+
+=======================
+Describing a Square
+=======================
+
+To make the GoPiGo3 describe a square by moving itself, you need to run the following script.
+To do this, :py:meth:`~easygopigo3.EasyGoPiGo3.drive_cm` and :py:meth:`~easygopigo3.EasyGoPiGo3.turn_degrees`
+methods are required. A square with the side length of 30cm is drawn. The square is drawn clockwise.
+
+.. code-block:: python
+
+   from easygopigo3 import EasyGoPiGo3
+
+   gpg = EasyGoPiGo3()
+   length = 30
+
+   for i in range(4):
+     gpg.drive_cm(length) # drive forward for length cm
+     gpg.turn_degrees(90) # rotate 90 degrees to the right
+
+.. image:: https://i.imgur.com/6Q7uHq9.gif
+
+=====================
+Making Circular Moves
+=====================
+
+Driving straight in one direction is one thing, but rotating around a center axis at a specific radius is
+something entirely different. In this example, the GoPiGo3 draws half a circle and then returns
+on the same track by spinning itself on the spot.
+
+The radius of the circle is set at 50 centimeters and the robot will move for half of the circle (aka 180 degrees).
+
+.. code-block:: python
+
+   from easygopigo3 import EasyGoPiGo3
+
+   gpg = EasyGoPiGo3()
+
+   gpg.orbit(180, 50) # draw half a circle
+   gpg.turn_degrees(180) # rotate the GoPiGo3 around
+   gpg.orbit(-180, 50) # return on the initial path
+   gpg.turn_degrees(180) # and put it in the initial position
+
+.. image:: https://i.imgur.com/cfdbsID.gif
+
+====================
+Drawing an *8* Shape
+====================
+
+Let's say we want to draw an 8 shape with the GoPiGo3 and at the end have the GoPiGo3 reach the same position
+it initially left from.
+
+To do this, we have to use :py:meth:`~easygopigo3.EasyGoPiGo3.orbit` and :py:meth:`~easygopigo3.EasyGoPiGo3.drive_cm` methods.
+
+.. code-block:: python
+
+   from easygopigo3 import EasyGoPiGo3
+
+   gpg = EasyGoPiGo3()
+   radius = 30
+
+   gpg.orbit(-270, radius) # to rotate to the left
+   gpg.drive_cm(radius * 2) # move forward
+   gpg.orbit(270, radius) # to rotate to the right
+   gpg.drive_cm(radius * 2) # move forward
+
+.. image:: https://i.imgur.com/SQrRBd8.gif
+
+=================================
+Going Forward at Increasing Speed
+=================================
+
+In this example, we make the GoPiGo3 go forward at an ever increasing speed. We start of with a speed of ``50`` and end up going at ``300``.
+:py:meth:`~easygopigo3.EasyGoPiGo3.forward`, :py:meth:`~easygopigo3.EasyGoPiGo3.set_speed` and :py:meth:`~easygopigo3.EasyGoPiGo3.stop` methods are used.
+
+.. warning::
+
+   This example will not work with versions released before November 2018. Do an update before running it.
+
+.. code-block:: python
+
+   from easygopigo3 import EasyGoPiGo3
+   from time import time, sleep
+
+   gpg = EasyGoPiGo3()
+
+   # setting speed to lowest value and
+   # calculating the step increase in speed
+   current_speed = 50
+   end_speed = 400
+   step = (end_speed - current_speed) / 20
+   gpg.set_speed(current_speed)
+
+   # start moving the robot at an ever increasing speed
+   gpg.forward()
+   while current_speed <= end_speed:
+     sleep(0.1)
+     gpg.set_speed(current_speed)
+     current_speed += step
+
+   # and then stop it
+   gpg.stop()
+
+.. image:: https://i.imgur.com/v4KqoZr.gif
+
+==============
+Other Examples
+==============
+
+There are also other examples you can look at, namely `the projects <https://github.com/DexterInd/GoPiGo3/blob/master/Projects>`_ in the GoPiGo3 repository.
+Also, to see all methods for moving around the GoPiGo3, check the :ref:`GoPiGo3 movement API <gopigo3-movement-api-methods>`.

docs/source/tutorials-basic/index.rst

@@ -10,12 +10,13 @@ Please make sure you have followed all the instructions found in :ref:`Getting S
 In all these tutorials, you will need:
 
   1. A `GoPiGo3`_ robot.
-  2. Sensor/Actuator specific for the tutorial : i.e.: a `Grove Buzzer`_, a `Line Follower`_, etc.
+  2. A sensor/actuator if requested in the tutorial : i.e.: a `Grove Buzzer`_, a `Line Follower`_, etc.
 
 .. toctree::
    :maxdepth: 1
    :caption: Contents:
 
+   driving
    led
    button
    buzzer