AUTOMATIC ALTERNATIVE
The installer/ directory contains installer V02. See the Automatic Linux installer
manual chapter and installer/INSTALL_FROM_THIS_PACKAGE.txt. Use either this
automatic route or the manual software setup below; hardware preparation and
commissioning remain required. Clean-card hardware validation is pending.

M.2 UPS PMH — Installation — Manual V14 / firmware V88

Use stable cable power. Assemble with all cable and battery power disconnected:
fit the official cooler, spacers, SSD, PCIe FPC cable, HAT and Pi button-control
connection. Align the 40-pin header and FPC contacts; close the cable latches.
Use one approved backup source, correct polarity and matching chemistry.
Never apply the Advanced 5–32 V input to a Raspberry Pi 5 V contact.

1. Extract the whole package into ~/M2_UPS_PMH_Manual_V91; keep the directory layout.
   cd ~/M2_UPS_PMH_Manual_V91

2. Install dependencies and enable I2C:
   sudo apt update
   sudo apt install -y python3-smbus i2c-tools util-linux python3-serial
   sudo raspi-config nonint do_i2c 0

3. Back up and edit the boot configuration:
   sudo cp /boot/firmware/config.txt /boot/firmware/config.txt.before-m2
   sudo nano /boot/firmware/config.txt
   In the applicable [all] section ensure these appear once:
   dtparam=i2c_arm=on
   dtoverlay=i2c-rtc,ds1307
   Preserve unrelated entries. Do not duplicate an existing UPS RTC overlay.
   If the OS uses /boot/config.txt, use that actual boot file instead.
   sudo reboot

4. Reconnect and identify the UPS RTC:
   ls -l /dev/rtc*
   for d in /sys/class/rtc/rtc*; do echo "$d"; cat "$d/name"; done
   Select rtc-ds1307 1-0068. Device numbering is not guaranteed.
   UU at address 0x68 means the kernel RTC driver owns the address.

5. Inspect existing installations before replacement:
   sudo systemctl cat M2_PMH_i2c.service
   pgrep -af M2_PMH_i2c.py
   Keep a copy of deliberate site-specific overrides. Stop an existing daemon
   immediately before replacing its files and restart it promptly under cable
   power. A new installation has no service to stop.

6. Install the daemon and supplied service:
   cd ~/M2_UPS_PMH_Manual_V91
   python3 -c "from smbus import SMBus; print('smbus OK')"
   sudo install -m 0755 installation/M2_PMH_i2c.py /usr/local/sbin/M2_PMH_i2c.py
   sudo install -m 0644 installation/M2_PMH_i2c.service.txt /etc/systemd/system/M2_PMH_i2c.service
   sudo systemctl daemon-reload
   sudo systemctl enable --now M2_PMH_i2c.service
   sudo systemctl restart M2_PMH_i2c.service

7. Verify:
   sudo systemctl status M2_PMH_i2c.service --no-pager
   sudo journalctl -u M2_PMH_i2c.service -b -n 15 --no-pager
   timedatectl status
   Expect a 250 ms heartbeat and increasing successful reads at 0x6B.
   RTC synchronization waits for confirmed NTP and then repeats hourly.

8. Select the operating mode using CONFIGURATION_AND_TESTS.txt.
   Normal: switch mode 0x00, runtime 0x01. Slide mode: 0xAA, runtime 0xFF.

9. Charge the battery under stable cable power. Remove the cable and check
   uninterrupted Pi/SSD operation. Normal runtime 0x01 starts FSSD after about
   70 seconds, then allows about 30 seconds for Linux shutdown.

10. Reconnect after shutdown. Repeat with cable return during FSSD, then test
    slide OFF/ON where fitted. Complete at least five consistent cycles.
    Inspect the journal for accumulating errors and preserve the serial trace.

M2_PMH_i2c.py --check is a ten-second read-only check, without shutdown
protection. Use it under cable power only, with the normal daemon stopped.
