feature - update documentation for the latest (#41)

* feature - configuring the environment for RTD

* feature - bulk changes to docs

* feature - add comment on how to build documentation

* feature - add part of the documentation

* feature - completing the documentation for easy sensors + tutorials

* feature - work on the tutorials + other stuff

* feature - fix the mutexes tutorial

* feature - change organization of documentation

* feature - remove an unnecessary section

* feature - show the right command for installing di-sensors

* feature - small changes

* feature - fix documentation & and missing parts

* feature - fix naming of the package

* Revert commit

Python/Examples/EasyDistanceSensor.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python
+#
+# https://www.dexterindustries.com
+#
+# Copyright (c) 2017 Dexter Industries
+# Released under the MIT license (http://choosealicense.com/licenses/mit/).
+# For more information see https://github.com/DexterInd/DI_Sensors/blob/master/LICENSE.md
+#
+# Python example program for the Dexter Industries Distance Sensor
+
+from __future__ import print_function
+from __future__ import division
+
+# import the modules
+from di_sensors.easy_distance_sensor import EasyDistanceSensor
+from time import sleep
+
+# instantiate the distance object
+my_sensor = EasyDistanceSensor()
+
+# and read the sensor iteratively
+while True:
+  read_distance = my_sensor.read()
+  print("distance from object: {} mm".format(read_distance))
+
+  sleep(0.1)

Python/Examples/EasyDistanceSensorMutexes.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python
+#
+# https://www.dexterindustries.com
+#
+# Copyright (c) 2017 Dexter Industries
+# Released under the MIT license (http://choosealicense.com/licenses/mit/).
+# For more information see https://github.com/DexterInd/DI_Sensors/blob/master/LICENSE.md
+#
+# Python example program for the Dexter Industries Temperature Humidity Pressure Sensor
+
+from __future__ import print_function
+from __future__ import division
+
+# do the import stuff
+from di_sensors.easy_distance_sensor import EasyDistanceSensor
+from time import time, sleep
+from threading import Thread, Event, get_ident
+
+# instantiate the distance object
+my_sensor = EasyDistanceSensor(use_mutex = True)
+start_time = time()
+runtime = 2.0
+# create an event object for triggering the "shutdown" of each thread
+stop_event = Event()
+
+# target function for each thread
+def readingSensor():
+    while not stop_event.is_set():
+      thread_id = get_ident()
+      distance = my_sensor.read()
+      print("Thread ID = {} with distance value = {}".format(thread_id, distance))
+      sleep(0.001)
+
+# create an object for each thread
+thread1 = Thread(target = readingSensor)
+thread2 = Thread(target = readingSensor)
+
+# and then start them
+thread1.start()
+thread2.start()
+
+# let it run for [runtime] seconds
+while time() - start_time <= runtime:
+    sleep(0.1)
+
+# and then set the stop event variable
+stop_event.set()
+
+# and wait both threads to end
+thread1.join()
+thread2.join()

Python/Examples/LightColorSensor.py → Python/Examples/EasyLightColorSensor.py

@@ -1,28 +1,28 @@
-#!/usr/bin/env python
-#
-# https://www.dexterindustries.com
-#
-# Copyright (c) 2017 Dexter Industries
-# Released under the MIT license (http://choosealicense.com/licenses/mit/).
-# For more information see https://github.com/DexterInd/DI_Sensors/blob/master/LICENSE.md
-#
-# Python example program for the Dexter Industries Light Color Sensor
-
-from __future__ import print_function
-from __future__ import division
-
-import time
-from di_sensors.light_color_sensor import LightColorSensor
-
-print("Example program for reading a Dexter Industries Light Color Sensor on an I2C port.")
-
-lcs = LightColorSensor(led_state = True)
-
-while True:
-    # Read the R, G, B, C color values
-    red, green, blue, clear = lcs.get_raw_colors()
-
-    # Print the values
-    print("Red: {:5.3f} Green: {:5.3f} Blue: {:5.3f} Clear: {:5.3f}".format(red, green, blue, clear))
-
-    time.sleep(0.02)
+#!/usr/bin/env python
+#
+# https://www.dexterindustries.com
+#
+# Copyright (c) 2017 Dexter Industries
+# Released under the MIT license (http://choosealicense.com/licenses/mit/).
+# For more information see https://github.com/DexterInd/DI_Sensors/blob/master/LICENSE.md
+#
+# Python example program for the Dexter Industries Light Color Sensor
+
+from __future__ import print_function
+from __future__ import division
+
+from time import sleep
+from di_sensors.easy_light_color_sensor import EasyLightColorSensor
+
+print("Example program for reading a Dexter Industries Light Color Sensor on an I2C port.")
+
+my_lcs = EasyLightColorSensor(led_state = True)
+
+while True:
+    # Read the R, G, B, C color values
+    red, green, blue, clear = my_lcs.safe_raw_colors()
+
+    # Print the values
+    print("Red: {:5.3f} Green: {:5.3f} Blue: {:5.3f} Clear: {:5.3f}".format(red, green, blue, clear))
+
+    sleep(0.02)

Python/Examples/TempHumPress.py → Python/Examples/EasyTempHumPress.py

@@ -11,24 +11,24 @@
 from __future__ import print_function
 from __future__ import division
 
-import time
-from di_sensors.temp_hum_press import TempHumPress
+from time import sleep
+from di_sensors.easy_temp_hum_press import EasyTHPSensor
 
 print("Example program for reading a Dexter Industries Temperature Humidity Pressure Sensor on an I2C port.")
 
-thp = TempHumPress()
+my_thp = EasyTHPSensor()
 
 while True:
     # Read the temperature
-    temp = thp.get_temperature_celcius()
+    temp = my_thp.safe_celsius()
 
     # Read the relative humidity
-    hum = thp.get_humidity()
+    hum = my_thp.safe_humidity()
 
     # Read the pressure
-    press = thp.get_pressure()
+    press = my_thp.safe_pressure()
 
     # Print the values
     print("Temperature: {:5.3f} Humidity: {:5.3f} Pressure: {:5.3f}".format(temp, hum, press))
 
-    time.sleep(0.02)
+    sleep(0.02)

Python/di_sensors/distance_sensor.py

@@ -27,7 +27,7 @@ def __init__(self, bus = "RPI_1"):
         """
         self.VL53L0X = VL53L0X.VL53L0X(bus = bus)
 
-        # set to long range (about 2 meters)
+        # set to long range (about 2.3 meters)
         self.VL53L0X.set_signal_rate_limit(0.1)
         self.VL53L0X.set_vcsel_pulse_period(self.VL53L0X.VcselPeriodPreRange, 18)
         self.VL53L0X.set_vcsel_pulse_period(self.VL53L0X.VcselPeriodFinalRange, 14)
@@ -52,7 +52,7 @@ def read_range_continuous(self):
         """
         Read the detected range while the sensor is taking continuous measurements at the set rate.
 
-        :returns: The detected range of the sensor as measured in millimeters. The range can go up to 2 meters.
+        :returns: The detected range of the sensor as measured in millimeters. The range can go up to 2.3 meters.
         :rtype: int
         :raises ~exceptions.OSError: When the distance sensor is not reachable or when the :py:meth:`~di_sensors.distance_sensor.DistanceSensor.start_continuous` hasn't been called before. This exception gets raised also when the user is trying to poll data faster than how it was initially set with the :py:meth:`~di_sensors.distance_sensor.DistanceSensor.start_continuous` method.
 
@@ -72,7 +72,7 @@ def read_range_single(self, safe_infinity=True):
 
         :param boolean safe_infinity = True: As sometimes the distance sensor returns a small value when there's nothing in front of it, we need to poll again and again to confirm the presence of an obstacle. Setting ``safe_infinity`` to ``False`` will avoid that extra polling.
 
-        :returns: The detected range of the sensor as measured in millimeters. The range can go up to 2 meters.
+        :returns: The detected range of the sensor as measured in millimeters. The range can go up to 2.3 meters.
         :rtype: int
         :raises ~exceptions.OSError: When the distance sensor is not reachable.
 

Python/di_sensors/easy_distance_sensor.py

@@ -5,59 +5,27 @@
 # For more information see https://github.com/DexterInd/DI_Sensors/blob/master/LICENSE.md
 #
 
-
-#######################################################################
-#
-# DistanceSensor
-#
-# under try/except in case the Distance Sensor is not installed
-#######################################################################
-try:
-    from di_sensors import distance_sensor
-
-except:
-    print("DI Sensors library not found")
-    # try:
-    #     from mock_package import distance_sensor
-    # print ("Loading library without distance sensor")
-    # except:
-    #     pass
-
-import time
-
 from di_sensors.easy_mutex import ifMutexAcquire, ifMutexRelease
+import time
+from di_sensors import distance_sensor
 
 
 class EasyDistanceSensor(distance_sensor.DistanceSensor):
     """
     Class for the `Distance Sensor`_ device.
 
-    We can create this :py:class:`~easygopigo3.DistanceSensor` object similar to how we create it in the following template.
-
-    .. code-block:: python
-
-        # create an EasyGoPiGo3 object
-        gpg3_obj = EasyGoPiGo3()
-
-        # and now let's instantiate a DistanceSensor object through the gpg3_obj object
-        distance_sensor = gpg3_obj.init_distance_sensor()
-
-        # read values continuously and print them in the terminal
-        while True:
-            distance = distance_sensor.read()
-
-            print(distance)
+    This class compared to :py:class:`~di_sensors.distance_sensor.DistanceSensor` uses mutexes that allows a given
+    object to be accessed simultaneously from multiple threads/processes.
+    Apart from this difference, there may
+    also be functions that are more user-friendly than the latter.
 
     """
-    def __init__(self, port="I2C",gpg=None, use_mutex=False):
+    def __init__(self, use_mutex=False):
         """
         Creates a :py:class:`~easygopigo3.DistanceSensor` object which can be used for interfacing with a `distance sensor`_.
 
-        :param str port = "I2C": Port to which the distance sensor is connected.
-        :param easygopigo3.EasyGoPiGo3 gpg = None: Object that's required for instantianting a :py:class:`~easygopigo3.DistanceSensor` object.
-        :param bool use_mutex = False: When using multiple threads/processes that access the same resource/device, mutexes should be enabled.
-        :raises IOError: If :py:class:`di_sensors.distance_sensor.DistanceSensor` can't be found. Probably the :py:mod:`di_sensors` module isn't installed.
-        :raises TypeError: If the ``gpg`` parameter is not a :py:class:`~easygopigo3.EasyGoPiGo3` object.
+        :param bool use_mutex = False: When using multiple threads/processes that access the same resource/device, mutexes should be enabled. Check the :ref:`hardware specs <hardware-interface-section>` for more information about the ports.
+        :raises ~exceptions.OSError: When the distance sensor is not connected to the designated bus/port, where in this case it must be ``"I2C"``. Most probably, this means the distance sensor is not connected at all.
 
         To see where the ports are located on the `GoPiGo3`_ robot, please take a look at the following diagram: :ref:`hardware-ports-section`.
 
@@ -84,8 +52,8 @@ def read_mm(self):
 
         .. note::
 
-             1. Sensor's range is **5-8,000** millimeters.
-             2. When the values are out of the range, it returns **8190**.
+             1. Sensor's range is **5-2300** millimeters.
+             2. When the values are out of the range, it returns **3000**.
 
         """
 
@@ -134,8 +102,8 @@ def read(self):
 
         .. note::
 
-             1. Sensor's range is **0-800** centimeters.
-             2. When the values are out of the range, it returns **819**.
+             1. Sensor's range is **0-230** centimeters.
+             2. When the values are out of the range, it returns **300**.
 
         """
 
@@ -151,10 +119,9 @@ def read_inches(self):
 
         .. note::
 
-             1. Sensor's range is **0-314** inches.
-             2. Anything that's bigger than **314** inches is returned when the sensor can't detect any target/surface.
+             1. Sensor's range is **0-90** inches.
+             2. Anything that's bigger than **90** inches is returned when the sensor can't detect any target/surface.
 
         """
         cm = self.read()
         return round(cm / 2.54, 1)
-