Add Documentation for odometrty and robot class. Remove fast_fifo

compLib/MetricsLogging.py

@@ -3,7 +3,6 @@ import socket
 import uuid
 import os
 import multiprocessing
-import faster_fifo
 import datetime
 import requests
 import time
@@ -29,7 +28,7 @@ else:
 influx_client = InfluxDBClient(url=INFLUX_HOST, token=TOKEN)
 write_api = influx_client.write_api()
 
-point_queue = faster_fifo.Queue()
+point_queue = multiprocessing.Queue()
 workers = []
 
 class MetricsLogging():

compLib/Motor.py

@@ -21,6 +21,7 @@ class MotorMode(IntEnum):
     BACKWARD = 2,
     BREAK = 3
 
+
 class Motor(object):
     """Class used to control the motors
     """

compLib/Odom.py

@@ -13,22 +13,50 @@ orientation = 0
 
 
 class Odometry():
+    """DTO used for holding all odometry information. \n
+    Coordinate system: \n
+        X: + Forward; - Backwards \n
+        Y: + Right; - Left \n
+        Orientation: + Right; - Left
+    """
+
     def __init__(self, x, y, orientation):
         self.x = x
         self.y = y
         self.orientation = orientation
 
+    def get_x(self) -> float:
+        """Returns distance driven on x-axis in meters"""
+        return self.x
+
+    def get_y(self) -> float:
+        """Returns distance driven on y-axis in meters"""
+        return self.y
+
+    def get_orientation(self) -> float:
+        """Returns degrees turned in radians"""
+        return self.orientation
+
     def __str__(self):
         return f"X: {self.x} Y: {self.y} O: {self.orientation}"
 
+
 class Odom(object):
+    """Class used to track the movement of the robot in X, Y, Theta (Orientation)
+    """
 
     @staticmethod
-    def get_odom():
+    def get_odom() -> Odometry:
+        """
+        :return: Current orientation of the robot
+        """
         return Odometry(pos_x, pos_y, orientation)
 
     @staticmethod
-    def clear():
+    def clear() -> None:
+        """
+        Clears the current odometry information and start from X, Y, Orientation set to 0
+        """
         global last_run, last_enc_left, last_enc_right, pos_x, pos_y, orientation
 
         last_run = 0
@@ -39,7 +67,11 @@ class Odom(object):
         orientation = 0
 
     @staticmethod
-    def update():
+    def update() -> None:
+        """
+        Updates the current odometry information of the robot, Should be called in a loop with at least 100HZ.
+        Do not clear encoder positions between updates! Must be cleared, when clearing encoders!
+        """
         global last_run, last_enc_left, last_enc_right, pos_x, pos_y, orientation
 
         now = time.time()

compLib/Robot.py

@@ -2,11 +2,23 @@ import math
 
 
 class Robot(object):
-    
     WHEEL_CIRCUMFERENCE_MM = 71.0 * math.pi
+    """Circumference of a wheel in millimeters"""
+
     TICKS_PER_TURN = 27.7 * 100.0
+    """Ticks per 360 degree turn of a wheel"""
+
     ARBOR_LENGTH_MM = 139.0
+    """Distance between the two wheels in millimeters"""
+
     ARBOR_LENGTH_M = ARBOR_LENGTH_MM / 1000.0
+    """Distance between the two wheels in meters"""
+
     TICKS_PER_METER = 1000.0 / WHEEL_CIRCUMFERENCE_MM * TICKS_PER_TURN
+    """Ticks after driving one meter"""
+
     LEFT_PORT = 4
+    """Motor port for the left motor"""
+
     RIGHT_PORT = 1
+    """Motor port for the right motor"""

docs/source/conf.py

@@ -15,11 +15,12 @@ import sys
 
 sys.path.insert(0, os.path.abspath('../..'))
 sys.setrecursionlimit(1500)
+os.environ["EXTENSIVE_LOGGING"] = "False"
 
 # -- Project information -----------------------------------------------------
 
 project = 'CompLib'
-copyright = '2021, robo4you'
+copyright = '2022, Verein zur Förderung von Wissenschaft und Technik an Schulen (F-WuTS)'
 author = 'robo4you'
 
 # The full version, including alpha/beta/rc tags
@@ -35,7 +36,8 @@ extensions = [
     'sphinx_rtd_theme'
 ]
 
-autodoc_mock_imports = ["smbus", "compLib.PCA9685", "RPi", "pigpio", "flask", "apt", "spidev", "influxdb_client"]
+autodoc_mock_imports = ["smbus", "compLib.PCA9685", "RPi",
+                        "pigpio", "flask", "apt", "spidev", "influxdb_client"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/source/lib/Odom.rst

@@ -0,0 +1,50 @@
+.. _lib_odom:
+
+Odometry
+******
+
+Class Documentation
+====================
+
+.. autoclass:: compLib.Odom.Odometry
+   :members:
+
+.. autoclass:: compLib.Odom.Odom
+   :members:
+
+
+Examples
+=========
+
+Getting actual distance driven
+------------------------------
+
+.. code-block:: python
+
+   import time
+   import math
+   from compLib.Motor import Motor
+   from compLib.Encoder import Encoder
+   from compLib.Odom import Odom, Odometry
+
+    # distance in meters
+    # speed in % of max speed
+    def drive_example(distance, speed):
+        Odom.update()
+        odom = Odom.get_odom()
+        while abs(odom.get_x()) < distance:
+            Odom.update()
+            odom = Odom.get_odom()
+
+            Motor.power(4, speed)
+            Motor.power(1, -speed)
+
+        print(f" Forward: {odom.get_x()} m")
+        print(f" Right: {odom.get_y()} m")
+        print(f" Turned: {math.degrees(odom.get_orientation())} degrees")
+
+        Motor.active_break(1)
+        Motor.active_break(4)
+        time.sleep(0.1)
+        Encoder.clear_all()
+        Odom.clear()

docs/source/lib/Robot.rst

@@ -0,0 +1,11 @@
+.. _lib_robot:
+
+Robot
+******
+
+Class Documentation
+====================
+
+.. autoclass:: compLib.Robot.Robot
+   :members:
+   :private-members: