Add various comments into the code

Author: chewett

RpiCluster/RpiBasicSecondaryThread.py

@@ -9,6 +9,16 @@
 
 
 class RpiBasicSecondaryThread(threading.Thread):
+    """Relatively basic class to represent a "simple" secondary node that connects to the primary and performs no actions.
+
+        Creating children from this base will allow more complex systems to be created. This inherits from thread so
+        you are able to start this running and perform other processing at the same time.
+
+        Attributes:
+            uuid: A UUID to represent the secondary thread. This is assigned by the primary
+            server_address: A tuple representing the IP address and port to use for the primary
+            connection_handler: A connection handler object which will be used for sending/recieving messages.
+    """
 
     def __init__(self, primary_ip, socket_port):
         threading.Thread.__init__(self)
@@ -17,6 +27,7 @@ def __init__(self, primary_ip, socket_port):
         self.connection_handler = None
 
     def run(self):
+        """Base method to begin running the thread, this will connect to the primary and then repeatedly call self.perform_action"""
         logger.info("Starting script...")
 
         while True:
@@ -47,6 +58,7 @@ def run(self):
                 message = self.connection_handler.get_message()
                 logger.info("We have information about the primary " + json.dumps(message['payload']))
 
+                # TODO: possibly add some way to signal to the thread that we want to stop
                 while True:
                     self.perform_action()
 
@@ -55,6 +67,7 @@ def run(self):
                 logger.info("Secondary will try and reconnect once primary is back online")
 
     def perform_action(self):
+        """This method is going to be the primary one you will override to make the node to custom exciting things"""
         logger.info("Now sending a keepalive to the primary")
         self.connection_handler.send_message("I am still alive, client: {num}".format(num=self.uuid))
         time.sleep(5)

RpiCluster/RpiClusterClient.py

@@ -8,6 +8,19 @@
 
 
 class RpiClusterClient(threading.Thread):
+    """This class is used to handle each secondary node that connects to the primary.
+
+        When running this will continually get messages from the secondary node and return a response
+        in some form.
+
+        Attributes:
+            uuid: A random UUID created for the node to give everyone a random ID
+            primary: a reference to the primary to get information from it
+            connection_handler: A handler that manages recieving and sending messages in the payload format
+            address: Address of the client
+            node_specifications: Details of the node if it provides it
+
+    """
 
     def __init__(self, primary, clientsocket, address):
         threading.Thread.__init__(self)
@@ -18,6 +31,7 @@ def __init__(self, primary, clientsocket, address):
         self.node_specifications = None
 
     def run(self):
+        """Method that runs handling the secondary and serving all of its messages"""
         try:
             message = True
             while message:

RpiCluster/RpiPrimary.py

@@ -4,13 +4,24 @@
 
 
 class RpiPrimary:
+    """Class to create a primary node which will handle connections coming in from a secondary
+
+        This will form the basis of a general primary node which will be in charge of listening for connections
+        and handling each one.
+
+        Attributes:
+            socket_bind_ip: IP address to bind the listening socket server to
+            socket_port: Port number to bind the listening socket server to
+            connected_clients: Dict of connected clients
+    """
 
     def __init__(self, socket_bind_ip, socket_port):
         self.socket_bind_ip = socket_bind_ip
         self.socket_port = socket_port
         self.connected_clients = {}
 
     def start(self):
+        """Start the handling of secondary nodes"""
         logger.info("Starting script...")
 
         listening_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
@@ -26,15 +37,16 @@ def start(self):
             rpi_client.start()
 
     def remove_client(self, rpi_client):
+        """Removes a given client from the list of connected clients, typically called after disconnection"""
         del self.connected_clients[rpi_client.uuid]
 
     def get_secondary_details(self):
+        """Allows retrieving some basic information of every secondary connected to the primary"""
         secondary_details = {}
         for uuid in self.connected_clients:
             secondary_details[uuid] = {
                 "uuid": uuid,
                 "address": str(self.connected_clients[uuid].address[0]) + ":" + str(self.connected_clients[uuid].address[1]),
-
             }
 
         return secondary_details

RpiCluster/RpiWebserverThread.py

@@ -5,6 +5,12 @@
 
 
 class RpiWebserverSecondaryThread(RpiBasicSecondaryThread):
+    """Subclass of the main RpiBasicSecondaryThread which handles connecting as a webserver
+
+        This is used to continually request data from the primary with the details of the cluster.
+        Static variables in this class are used to keep track of this data and make it easily accessible
+        by the webserver.
+    """
 
     current_primary_details = None
     current_secondary_details = None

RpiCluster/Tasks/MachineInfo.py

@@ -5,7 +5,12 @@
 
 
 def get_base_machine_info():
+    """When called various interesting stastics about the machine are returned
+
+        Currently this includes: hostname, cpu percentage, total ram, CPU name, number of cores the CPU has
+    """
     return {
+        #TODO: Consider making this an object
         'hostname': socket.gethostname(),
         'cpu_percent_used': psutil.cpu_percent(1),
         'ram': psutil.virtual_memory().total,

RpiCluster/Tasks/NodeTasks.py

@@ -3,36 +3,49 @@
 
 
 def reboot():
+    """When called the node will be rebooted"""
     subprocess.call(["sudo", "reboot"])
 
 
 def shutdown():
+    """When called the node will be shut down, make sure you can turn it back on if needed!"""
     subprocess.call(["sudo", "shutdown", "-h"])
 
 
 def update_node():
-    node_update_log_1 = subprocess.check_output(["sudo", "apt-get", "update"])
-    node_update_log_2 = subprocess.check_output(["sudo", "apt-get", "upgrade"])
+    """When called the node will run apt update followed by apt upgrade"""
+    node_update_log_1 = subprocess.check_output(["sudo", "apt", "update"])
+    node_update_log_2 = subprocess.check_output(["sudo", "apt", "upgrade", "-y"])
     return [node_update_log_1, node_update_log_2]
 
 
 def get_node_time():
+    """Returns the current node time which may be useful for times when the Pi clock might be out of sync"""
     return time.time()
 
 
 def get_node_codebase_revision():
+    """Gets the revision of the codebase currently on the filesystem
+
+        TODO: Improve this so we store the revision "on load" rather than hoping its the same
+    """
     # Note: This is not necessarily the revision of the code currently running
     current_rev = subprocess.check_output(["git", "rev-parse", "HEAD"])
     return current_rev.rstrip("\r\n")
 
 
 def get_node_codebase_revision_time():
+    """Gets the time of the revision of the codebase currently on the filesystem
+
+        TODO: Improve this so we store the revision "on load" rather than hoping its the same
+    """
     node_rev = get_node_codebase_revision()
     rev_time = subprocess.check_output(["git", "show", "-s", "--format=%ct", node_rev])
     return int(rev_time.rstrip("\r\n"))
 
 
 def update_node_codebase():
+    """Updates the codebase using git pull, note if any local changes are present this might fail horribly """
     update_log = subprocess.check_output(["git", "pull"])
     return update_log
 

basic_primary.py

@@ -13,6 +13,7 @@
 
 add_file_logger("primary.log")
 
+# The RpiPrimary class handles all of the interesting bits of work that the primary performs
 primary = RpiPrimary(socket_bind_ip, socket_port)
 primary.start()
 

basic_secondary.py

@@ -13,7 +13,7 @@
 
 add_file_logger("secondary.log")
 
+# This class creates and runs a basic secondary thread
 basic_secondary_thread = RpiBasicSecondaryThread(primary_ip, socket_port)
-
 basic_secondary_thread.start()