Add RTC instructions and files

OS_instructions/RTC/RTC_setup.md

@@ -0,0 +1,72 @@
+# RTC
+
+The RTC ensures the Pi has accurate datetime regardless of Internet connection and power loss. To stay up to date, the RTC also needs to be updated whenever the Pi has correct time via network time protocol (NTP) syncing.
+
+The instructions below configure the OS for the following behavior:
+- If Pi is disconnected from internet at startup: Update system time from RTC
+- If Pi successfully syncs to NTP via internet: Update RTC from system (NTP) time
+
+## Setup instructions
+
+The following files need to live in the Pi's `/etc/` directory:
+- `rc.local` sets behavior on boot
+- `dhcpcd.exit-hook` sets behavior on Internet connection
+
+Ensure both files have executable permission:
+```
+sudo chmod +x rc.local
+sudo chmod +x dhcpcd.exit-hook
+```
+
+## Tests (optional)
+
+Reboot after adding the above files to start the RTC before testing.
+
+### RTC in use
+
+Verify system vs RTC time using `timedatectl` in terminal. You will see a printout like this:
+```
+               Local time: Mon 2025-08-25 15:42:07 PDT
+           Universal time: Mon 2025-08-25 22:42:07 UTC
+                 RTC time: Mon 2025-08-25 22:42:08
+                Time zone: America/Los_Angeles (PDT, -0700)
+System clock synchronized: yes
+              NTP service: active
+          RTC in local TZ: no
+```
+
+If the RTC did not successfully start, RTC time will be listed as `n/a`.
+
+### System updated by RTC
+
+Test the use case where there's no Internet connection:
+
+First, turn off NTP sync, otherwise the time will automatically be corrected when `timedatectl` is run.
+```
+timedatectl ntp-sync false
+```
+
+Then, manually write an incorrect date/time to the RTC.
+```
+sudo hwclock --set --date "01/01/2001 00:00:00"
+```
+
+Run `timedatectl` to verify the RTC's datetime.
+
+
+Turn wifi off and reboot. The system time should now be the incorrect RTC time. Be patient as it can take up to 1 min for the system time to update after reconnection.
+
+_NOTE: If you ever want to overwrite system time using the RTC on the spot, run `sudo hwclock -s`._
+
+### RTC updated bt system (NTP) time
+
+Test the use case where the Pi reconnects to Internet:
+
+Turn on wifi when it was previously off or reboot Pi. Both the system time and RTC time should be correct and can be verified by running `timedatectl`
+
+_NOTE: If you ever want to overwrite the RTC using the NTP time on the spot, run `sudo hwclock -w`._
+
+
+## Supplementary info
+- [hwclock](https://linux.die.net/man/8/hwclock) tool
+- [timedatectl](https://www.freedesktop.org/software/systemd/man/latest/timedatectl.html) tool

OS_instructions/RTC/dhcpcd.exit-hook

@@ -0,0 +1,15 @@
+#!/bin/sh
+# Runs after dhcpcd processes a DHCP event.
+# Env vars available: $interface, $reason, $new_ip_address, $new_routers, etc.
+
+# Only act on Wi-Fi and only when we (re)obtained a lease
+if [ "$interface" = "wlan0" ]; then
+  case "$reason" in
+    BOUND|RENEW|REBIND|REBOOT)
+      timedatectl set-ntp true
+      sleep(1)
+      if timedatectl show -p NTPSynchronized | grep -q "yes"; then
+        sudo hwclock --systohc --noadjfile --localtime
+      fi
+  esac
+fi

OS_instructions/RTC/rc.local

@@ -0,0 +1,34 @@
+#!/bin/sh -e
+#
+# rc.local
+#
+# This script is executed at the end of each multiuser runlevel.
+# Make sure that the script will "exit 0" on success or any other
+# value on error.
+#
+# In order to enable or disable this script just change the execution
+# bits.
+#
+# By default this script does nothing.
+
+# Print the IP address
+_IP=$(hostname -I) || true
+if [ "$_IP" ]; then
+  printf "My IP address is %s\n" "$_IP"
+fi
+
+# Configure RTC
+sudo bash -c 'echo ds1307 0x68 > /sys/class/i2c-adapter/i2c-1/new_device'
+
+# Check if system time is NPT synced
+timedatectl set-ntp true
+sleep(1)
+if timedatectl show -p NTPSynchronized | grep -q "yes"; then
+  # Update RTC from system time
+  sudo hwclock --systohc --noadjfile --localtime
+else
+  # Update system time from RTC
+  sudo hwclock -s
+fi
+
+exit 0

setup.py

@@ -65,7 +65,7 @@ def readme():
             "remo-dev=ulc_mm_package.QtGUI.dev_run:main",
             "remo-fix-focus=ulc_mm_package.utilities.coarse_focus_utility:main",
             "remo-pneumatic-calibration=ulc_mm_package.utilities.pneumatic_utility:main",
-            "remo-zstack=ulc_mm_package.utilities.zstack_utility:main"
+            "remo-zstack=ulc_mm_package.utilities.zstack_utility:main",
         ]
     },
 )