add comments to startup, shutdown and cli-meter.

cli_meter.py

@@ -1,13 +1,25 @@
 #!/usr/bin/python3
 
 """
-CLI Meter
-====================================================================
-Takes a reading of the light using the meter attached via to the
-intended Raspberry PI. The reading is the sent to a server where the
-reading is stored. The intended use for this script is to be run via
-the command-line without the need for a G.U.I. This should be the
-version used when the "Return to Ritherdon" project is live.
+C.L.I. Meter
+======================================================================
+I wrote this script with the intention of using it as one part within
+a single cron-job. The cron-job begins with "startup.sh" and that,
+in-turn, will call this script when it is ready to do so.
+
+This scrip takes a reading of the current light-level in the room,
+using the Raspberry Pi (and the attached light-meter attached) it is
+running on. From there, it sends a J.S.O.N. object to the server
+(specified at "api_url"). The process is then repeated until it is
+killed manually or via "shutdown.sh" (as a cron-job most likely).
+
+You can use this script on Raspberry Pis without a G.U.I. because it
+is all C.L.I. based. If you prefer something more graphical, you can
+use "light_meter.py" -- which is part of this repository at time of
+writing.
+
+To end this script manually, use the usual "Ctrl-c" keyboard
+interrupt -- or something like Htop... doesn't matter.
 """
 
 import json
@@ -15,7 +27,7 @@ import RPi.GPIO as GPIO
 import time, math
 import requests
 from datetime import datetime
-# import pdb
+# import pdb # For testing.
 
 # Using BCM (Broadcom) names when referencing the GPIO pins.
 GPIO.setmode(GPIO.BCM)
@@ -24,13 +36,14 @@ GPIO.setwarnings(True)
 a_pin = 18 # Charges the capacitor.
 b_pin = 23 # Discharges the capacitor.
 
+# Make sure this is valid.
 api_url = "http://3.9.19.84/api/readings/add/1"
 
 def discharge():
     GPIO.setup(a_pin, GPIO.IN)
     GPIO.setup(b_pin, GPIO.OUT)
     GPIO.output(b_pin, False)
-    time.sleep(0.01) # 0.01 -- initial value
+    time.sleep(0.01) # 0.01 -- initial/default value.
 
 def charge_time():
     GPIO.setup(b_pin, GPIO.IN)
@@ -77,7 +90,7 @@ def update_reading():
 def main():
     try:
         while True:
-            #pdb.set_trace()
+            #pdb.set_trace() # For testing.
             update_reading()
     except KeyboardInterrupt:
         print("Keyboard Interrupt: quitting program.")
@@ -88,5 +101,5 @@ def main():
         GPIO.cleanup()
 
 if __name__ == "__main__":
-    # time.sleep(60)
+    # time.sleep(60) # For testing/debugging.
     main()

shutdown.sh

@@ -1,11 +1,23 @@
 #!/bin/bash
 
+# Shutdown Script
+# ====================================================================
+# I wrote this script with the intention of using it as part of a
+# cron-job. Before you set up the cron-job, you must make sure you
+# have either ran the "make-log-files.sh" script or created the
+# appropriate log file and folder at the location specified at
+# "logFile" below.
+# As an aside, I usually set-up as alias for "shutdown" called,
+# "powerdown". When I enter "powerdown" into the terminal, this script
+# should ran and then the "shutdown" command is ran at the end. The
+# "sleep" part is to give "curl" a bit of a buffer to finish its task.
+# I have found it sometimes fails otherwise.
+
 logDate=$(date '+%Y-%m-%dT%TZ')
 logFile="/home/rtrp/logs/shutdown-logs.txt"
-mainURL="http://3.9.19.84/api/status/update"
+mainURL="http://3.9.19.84/api/status/update" # Make sure this is valid.
 
 getApiUrl () {
-    # Copy and Paste for the win!
     case $HOSTNAME in
     	(factory1) apiURL="${mainURL}/1";;
     	(factory2) apiURL="${mainURL}/2";;

startup.sh

@@ -1,10 +1,30 @@
 #!/bin/bash  
 
+# Startup Script
+# ====================================================================
+# I wrote this script with the intention of using it to start a
+# cron-job -- when the Raspberry Pi is turned on. Before you set the
+# cron-job up, you must make sure you have either ran the
+# "make-log-files.sh" script or created the appropriate log file and
+# folder at the location specified at "logFile" below.
+# ====
+# Please note: This script calls another (Python) script at the end of
+# it. The code in the Python script (cli_meter.py) is an infinite-loop
+# so you will need to kill it manually or turn-off the  Raspberry Pi.
+# ====
+# I put the "sleep 60" call at the start to reduce any errors
+# occurring because a part of the system (I.E. curl) has not finished
+# loading. 60 seconds is a little excessive but I wrote this script
+# with the expectation of it running on an unmanned Raspberry Pi. So,
+# reliable/consistent behaviour is my preference over "fast start-up
+# times".
+
+
 sleep 60
 
 logDate=$(date '+%Y-%m-%dT%TZ')
 logFile="/home/rtrp/logs/startup-logs.txt"
-mainURL="http://3.9.19.84/api/status/update"
+mainURL="http://3.9.19.84/api/status/update" # Make sure this is valid.
 
 getApiUrl () {
     case $HOSTNAME in