Remote Tech Support On-The-Go: Your Hermes-Powered USB Troubleshooting Kit

Hey Bumbling Electrons!

Ever wished you could magically reach into a friend's struggling computer, fix their woes, and walk away without leaving a trace of installed software? Forget clunky remote desktop setups that require firewall acrobatics or trusting unknown executables. Today, we're diving into a project that lets you do just that: a portable, Hermes-powered USB troubleshooting kit that gives you secure, "no-install" SSH access to a friend's Windows PC.

This is about pure, unadulterated remote PC diagnostics, leveraging the power of a tiny USB drive and Cloudflare's robust tunnel technology.

The Problem: Remote Help is Hard

Helping friends with computer issues is often a pain. You need to:

• Talk them through installing software.
• Deal with their antivirus flagging your tools.
• Navigate their confusing network setup.
• Worry about leaving software behind on their machine.

Our solution sidesteps all these headaches with a simple, secure, and easily removable kit.

The Concept: Hermes on a Stick, with a Secure Tunnel

Our idea revolves around a standard USB drive containing a few essential tools. When plugged into a friend's Windows computer, it enables a secure SSH connection back to you, the operator (or directly to your Hermes Agent!). The magic comes from Cloudflare Tunnel, which creates an outbound-only connection from their PC, bypassing firewalls and NAT, and routing SSH traffic to a persistent hostname.

Here's how it works:

1. The USB drive contains the necessary scripts and configuration templates, and the setup process will download the latest cloudflared client.
2. A one-time setup enables OpenSSH Server on their Windows machine and installs your public SSH key for passwordless access.
3. When they need help, they simply double-click a batch file on the USB.
4. A secure tunnel pops up to a specific hostname (e.g., YOUR_CHOSEN_HOSTNAME.YOUR_CHOSEN_DOMAIN).
5. You, the operator (or Hermes), SSH into that hostname and get a PowerShell prompt on their machine.

Simple, secure, and no lingering software after they remove the USB.

Getting the Kit Files (and Installing Your Hermes Helper Skill!)

This is where the magic of Hermes truly shines! Instead of manually downloading, configuring, and assembling the kit, you can leverage your own Hermes Agent to automate most of the heavy lifting.

We'll provide a GitHub repository containing the core scripts and templates. Your task is simply to clone it and then install a special helper skill from within the repo. This skill will then walk you through generating the necessary Cloudflare Tunnel components and customizing the kit for your specific setup.

Repository Structure (Example)

Let's assume the repository is located at https://github.com/mainmeister/hermes-friend-diag-kit.git. It would contain:

• remote-diag-kit.md: This is the Hermes skill definition itself. It contains the logic for the automated setup.
• templates/config.yml.template: A template for the cloudflared configuration.
• templates/setup-openssh.ps1.template: A template for the PowerShell setup script.
• templates/connect.bat.template: A template for the batch script that starts the tunnel. The executable connect.bat is generated by the skill.
• stop.bat: The batch script for stopping the tunnel.
• README.md: General overview of the kit.

Your Hermes, The Orchestrator

Here's how your Hermes Agent will help you set up the kit:

1. Clone the Repository: First, you (or your Hermes, with a terminal command) will clone the repository to your local machine. bash git clone https://github.com/mainmeister/hermes-friend-diag-kit.git ~/hermes-friend-diag-kit
2. Install the Hermes Skill: Now, install the helper skill from the cloned repository. This makes the skill available to your Hermes Agent. bash hermes skill install ~/hermes-friend-diag-kit/remote-diag-kit.md Note: The remote-diag-kit skill itself handles its dependencies: cloudflared CLI will be installed if not present, and it leverages git (for cloning) and the Python requests library (for downloading cloudflared.exe).
3. Run the Skill for Setup: You'll then instruct your Hermes Agent to run the setup-kit action of the newly installed skill to create the USB kit. bash hermes skill run remote-diag-kit setup-kit This command will kick off the automated setup process. Your Hermes Agent, guided by the remote-diag-kit skill, will then:
   • Cloudflare Login & Tunnel Creation: Guide you through the cloudflared tunnel login process (which typically involves opening a browser window for authentication to your Cloudflare account). Once authenticated, it will:
     • Prompt you for a desired tunnel name (e.g., friend-diag).
   • Hermes will guide you through the cloudflared tunnel login process (which typically involves opening a browser window for authentication to your Cloudflare account). Once authenticated, you will be prompted for a desired tunnel name (e.g., friend-diag). Hermes will then execute cloudflared tunnel create <TUNNEL_NAME> and confirm the creation, generating the unique friend-diag-credentials.json file in your ~/.cloudflared/ directory (which the skill will then copy to the kit).
   • Domain & DNS Configuration: Ask for your chosen domain (e.g., yourdomain.com) and the desired hostname (e.g., helpdesk). It will then use cloudflared tunnel route dns <TUNNEL_NAME> <HOSTNAME>.<YOUR_DOMAIN> to create the necessary CNAME record in your Cloudflare DNS, linking your chosen hostname to your tunnel.
   • config.yml Customization: Take the templates/config.yml.template from the repo, insert your newly generated Tunnel ID, and configure it to route SSH traffic from your chosen hostname (e.g., YOUR_CHOSEN_HOSTNAME.YOUR_CHOSEN_DOMAIN) to localhost:22 on the friend's machine.
   • Download cloudflared.exe: Download the latest cloudflared.exe for Windows directly from Cloudflare's GitHub releases into your kit directory.
   • SSH Key Injection: Read your ~/.ssh/id_rsa.pub (your public SSH key) and embed it directly into the templates/setup-openssh.ps1.template to create the final setup-openssh.ps1 script for your friend. This ensures passwordless, key-based authentication.
   • Assemble the Kit: Finally, Hermes will assemble all these generated, downloaded, and customized files into the final kit directory structure (e.g., ~/my-usb-kit/friend-diag/), ready for you to copy to a physical USB drive.

This automated process ensures that anyone with Hermes Agent can quickly and correctly set up their own personalized remote troubleshooting kit, with minimal manual intervention!

What's on Our USB Drive? (The Assembled Kit Files)

Once your Hermes Agent has finished its work, the ~/my_friend_usb/usb-kit/friend-diag/ directory will contain these crucial pieces:

• cloudflared.exe: The Cloudflare tunnel client (portable Windows executable), downloaded by Hermes.
• config.yml: The configuration file for cloudflared, customized by Hermes with your Tunnel ID and hostname.
• friend-diag-credentials.json: CRITICAL SECRET! This file, generated by Hermes, contains the credentials for your Cloudflare Tunnel. Anyone with this file can run the tunnel, so keep it safe and don't share the USB indiscriminately.
• setup-openssh.ps1: The PowerShell script, customized by Hermes with your public SSH key, designed to run once as Administrator.
• connect.bat: A simple batch script for starting the tunnel.
• stop.bat: A batch script for stopping the tunnel.
• README.txt: (Our comprehensive guide!) Provides all the instructions and troubleshooting. This file is generated by the skill for the end-user from the README.md in the repository.

One-Time Setup on Your Friend's PC (The "Install Nothing" Part!)

This step only needs to be done once per friend's computer. It enables the built-in Windows OpenSSH Server and configures it for your access.

1. Plug in the USB drive.
2. Right-click setup-openssh.ps1 on the USB drive.
3. Choose "Run with PowerShell as Administrator."
4. Click "Yes" on the User Account Control (UAC) prompt.
5. Wait for "Done!" to appear (usually about 30 seconds).
6. Note the Windows username printed at the end (or type whoami in PowerShell anytime). You'll need this username to SSH in.
7. Send that username to yourself (the operator). No password is needed; the kit uses key-based authentication.

Every Time You Want Help

Once the one-time setup is done, getting help is quick and painless:

1. Friend double-clicks connect.bat on the USB drive.
2. A black command window opens. They wait until they see a line that says "Registered tunnel connection" (usually 5-15 seconds). This means the tunnel is active.
3. Friend tells you: "Tunnel is up, you can SSH in now."
4. You (or Hermes) SSH in using their Windows username and the configured hostname: ssh <windows-username>@YOUR_CHOSEN_HOSTNAME.YOUR_CHOSEN_DOMAIN.
5. Important: The friend leaves the black window open while you're working.
6. When done, they simply close the window (or run stop.bat).

Unlike older versions of this kit, the hostname YOUR_CHOSEN_HOSTNAME.YOUR_CHOSEN_DOMAIN stays the same and doesn't expire, making it reliable.

Hermes in Action: Remote Diagnosis

With an SSH connection established, your Hermes Agent can now fully utilize its terminal and file tools to diagnose problems:

• Read system information: Check logs, running processes, network configuration.
• Run diagnostic commands: Execute PowerShell commands, check disk space, inspect services.
• View/modify files: Examine configuration files, temporary directories (with appropriate caution and permission).
• Install/remove software: Only with explicit verbal permission from your friend.

Hermes provides a powerful, text-based interface to their computer, allowing for precise and efficient troubleshooting.

Troubleshooting & Pitfalls (Where the Electrons Really Bumble!)

Here are the common bumps we hit during setup and operation, and how to smooth them out:

• "sshd service not found" or "service did not start":
  • Workaround: This usually means the OpenSSH Server wasn't enabled or started correctly. Simply re-run setup-openssh.ps1 as Administrator.
• Friend says "connection refused" or "no route to host":
  • Workaround: The tunnel isn't active or properly registered. Ensure connect.bat is still running on their PC and displaying "Registered tunnel connection" lines.
• Friend says "permission denied (publickey)":
  • Workaround: Your public SSH key isn't correctly installed or recognized. Re-run setup-openssh.ps1 as Administrator. This script installs your public key into both the user's personal authorized_keys file and the system-wide one (C:\ProgramData\ssh\administrators_authorized_keys) that Windows OpenSSH Server checks for admin accounts. If this step failed, the key won't be there. Also, double-check that you're using the correct Windows username (the one printed at the end of setup-openssh.ps1).
• "Windows Defender SmartScreen prevented an unrecognized app":
  • Workaround: cloudflared.exe is signed by Cloudflare, but SmartScreen might still warn on first run. Instruct your friend to click "More info" then "Run anyway."
• "Execution of scripts is disabled on this system" (for setup-openssh.ps1):
  • Workaround: Windows' PowerShell execution policy often blocks .ps1 scripts by default, even for administrators. That's why the repository now includes an install.bat wrapper. Instead of fighting with execution policies or making your friend type arcane commands, just tell them to right-click install.bat and select "Run as Administrator". The batch script handles the policy bypass automatically.
• "failed to fetch configuration" or "tunnel not found":
  • Workaround: This points to issues with the friend-diag-credentials.json file. Verify that it is present in the same folder as cloudflared.exe on the USB drive and hasn't been corrupted.
• "Network is unreachable" when you try to SSH in:
  • Workaround: If you created the Cloudflare Tunnel manually, ensure that your chosen hostname (e.g., helpdesk.yourdomain.com) isn't already set up as a standard A/CNAME record serving web traffic. It must be a tunnel route pointing to the tunnel's UUID. Check your Cloudflare dashboard, delete any conflicting DNS records for that hostname, and run cloudflared tunnel route dns <TUNNEL_NAME> <HOSTNAME>.
• cloudflared tunnel login fails with a certificate conflict:
  • Workaround: If you already use cloudflared for something else on your machine, you might have an existing cert.pem. The login command will warn you before overwriting it. You can safely back it up or delete it to proceed with the new login.

What Your Friend Can See (and What They Can't)

Transparency is key when helping friends. Here's a quick overview of what access you (or Hermes) have:

They Can: * You'll have a PowerShell prompt as their Windows user. * Read system information, run diagnostic commands. * View files in their user profile. * Change settings, install/remove software (but only with their explicit permission).

They Cannot: * See their desktop or watch their screen (unless they manually send a screenshot). * Access other user accounts on their PC. * Reach their PC after they close connect.bat. * Reach this PC from anywhere other than through the specific tunnel hostname (YOUR_CHOSEN_HOSTNAME.YOUR_CHOSEN_DOMAIN).

Security Notes

• The friend-diag-credentials.json file is a secret. Treat the USB stick as a sensitive tool. Don't share it, and don't leave it plugged in when not in use.
• The tunnel only forwards port 22 (SSH). No other services on their PC are exposed to the internet.
• Revocation: If you stop using the kit, you can delete the tunnel from your Cloudflare account to permanently revoke the credentials.

Future Enhancements: Hermes, The Ultimate Diagnostic Sidekick

The core kit provides robust access, but with Hermes at the helm, the possibilities for advanced diagnostics are vast. Here are some ideas for how your Hermes Agent could further supercharge this troubleshooting kit:

• Automated Initial Health Check & Reporting: Instead of manually running commands, your Hermes could be instructed to perform a comprehensive initial scan. It would check disk space, memory, CPU, running processes, recent Windows Event Log errors (System, Application, Security), network connectivity, installed updates, and startup programs. Hermes would then synthesize this data into a concise, prioritized report for you.
• Guided Troubleshooting Workflows: For common problems (e.g., "slow PC," "printer isn't working"), Hermes could guide you through a predefined troubleshooting sequence. It would execute commands, interpret results, and suggest next steps, effectively acting as an intelligent diagnostic expert.
• Smart Log Analysis: Windows Event Logs can be overwhelming. Hermes could query, filter, and interpret these logs intelligently. Ask Hermes to "Summarize critical errors from the last 24 hours in the System log" or "Find all warnings related to network adapters," and it will provide actionable insights.
• Secure File Transfer and Management: Leverage Hermes to securely transfer log files from the remote machine to your local system, or push small diagnostic scripts and fixes to the friend's PC using scp or sftp over the established SSH tunnel.
• Contextual Command and Error Explanations: Encounter a cryptic error message or an unfamiliar PowerShell command? Ask Hermes for an immediate explanation, syntax, and examples. It can leverage its knowledge or perform quick web searches to provide instant context.
• Automated System Restorations / Rollbacks (with consent): If a configuration change made during troubleshooting causes new issues, Hermes could assist in reverting. It could guide the operator through creating system restore points or reverting problematic Windows updates using PowerShell commands, always with explicit user consent.

To Uninstall Everything

If your friend no longer wants the setup on their PC:

1. Go to Settings -> Apps -> Optional Features.
2. Find "OpenSSH Server" and click "Uninstall."
3. Simply delete the kit directory (or the entire USB kit folder) from the USB drive.

That's it! No lingering software. The tunnel credentials remain valid (and you can revoke them from Cloudflare), but nothing is left on their PC.

A Canadian perspective on the Consumer Reports Talking Carts 17: CR Investigation Reveals High Levels of Additives and Contaminants in Snacks

This is a Canadian perspective on the same subject matter as the Consumer Reports article Talking Carts 17: CR Investigation Reveals High Levels of Additives and Contaminants in Snacks. I used AntiGravity withe the Gemini 3.5 Flash in medium mode to examine this URL and I prompted it with "is there any information from a canadian perspective equivalent to https://www.consumerreports.org/money/shopping-retail/talking-carts-17-cr-finds-additives-contaminants-in-snacks-a1530698323/"

Yes, there are several Canadian equivalents that publish similar investigations, testing, and reports regarding food additives, chemicals, and contaminants in grocery products.

The **Consumer Reports** study (in collaboration with the Yuka app) tested 40 snack foods for 8 additives and 2 contaminants (specifically highlighting substances like **Red Dye 40, Titanium Dioxide, and Glycidol** which exceed European or Californian safety thresholds but are permitted under US FDA rules).

Here is the equivalent information and sources from a Canadian perspective:

### 1. CBC Marketplace: "What's in Our Food?" (Investigation)

The closest Canadian equivalent to Consumer Reports' product testing is **CBC Marketplace**, Canada's flagship consumer advocacy program. 

* **Titanium Dioxide Investigation:** In February 2024, *Marketplace* aired an in-depth investigation revealing that popular candies sold in Canada (like Skittles, M&Ms, and Nerds) contain **titanium dioxide** (a whitening and color-enhancing agent). 

* **The Discrepancy:** The investigation highlighted that because the European Union banned titanium dioxide in 2021 (due to concerns by the European Food Safety Authority that it could cause DNA damage), manufacturers formulate the exact same snacks *without* it for the European market, while continuing to sell the version *with* titanium dioxide to Canadian consumers.

* **Heavy Metals in Rice Cereals:** *Marketplace* has also run laboratory testing on baby snacks and rice cereals sold in Canada, identifying concerning levels of **arsenic** in products marketed for infants.

### 2. Protégez-Vous (The Canadian "Consumer Reports")

Based in Quebec, **[Protégez-Vous](https://www.protegez-vous.ca)** is a non-profit, independent consumer organization that operates exactly like *Consumer Reports*. 

* They conduct independent laboratory testing on grocery store products, cosmetics, and appliances.

* They frequently publish comparative studies on food quality, pesticides in produce, and dossiers explaining how to identify and avoid controversial food additives on Canadian ingredient lists.

### 3. Health Canada & CFIA Surveys

For official testing data, Health Canada and the **Canadian Food Inspection Agency (CFIA)** publish reports from their **Total Diet Studies** and targeted chemical contaminant surveys.

* Health Canada conducts a "state of the science" review for additives. For example, unlike the EU, Health Canada released a report in 2022 concluding that the current levels of titanium dioxide in food do not pose an immediate health concern, which is why it remains legal in Canada.

* They regularly publish surveys monitoring heavy metals (lead, arsenic, cadmium, mercury) and banned dyes in foods sold on Canadian shelves.

### Summary of Work Done

- Researched the details of the Consumer Reports *Talking Carts* investigation (concerning Red Dye 40, Glycidol, and Titanium Dioxide).

- Identified matching Canadian investigative reports (specifically *CBC Marketplace's* 2024 food additives investigation and *Protégez-Vous* testing).

- Summarized the regulatory differences between Canada (Health Canada), the US (FDA), and Europe (EFSA).

Creating Drive Lights: Now for Linux and Windows!

Last post, I wrote about creating “Drive Lights” on Linux using GPIO pins on a Raspberry Pi. It was a fun project that used the kernel’s fanotify API to monitor disk activity and flash physical LEDs. But what if you’re on Windows? Or what if you’re using a modern desktop without native GPIO pins? Today, I’m excited to share a major update to the Drive_Lights project. It’s now cross-platform, supports USB GPIO hardware, and uses modern Python tooling! What’s New? 1. Windows Support (ReadDirectoryChangesW) The biggest addition is a full Windows port (mainw.py). While Linux uses fanotify at the kernel level, Windows provides the ReadDirectoryChangesW API. I’ve implemented a recursive monitoring loop that captures file creations, deletions, renames, and modifications across an entire drive or directory. 2. USB GPIO Hardware (MCP2221A) You no longer need a Raspberry Pi to see your drive lights! By using a simple USB-to-GPIO adapter like the MCP2221A or FT232H, you can add physical LEDs to any Windows or Linux desktop. The project now supports Adafruit Blinka, which allows gpiozero and other libraries to talk to USB GPIO hardware as if it were a native Pi. 3. Modern Dependency Management with uv I’ve migrated the project to uv. This means you can get up and running with a single command: bash uv sync No more manual pip install or broken virtual environments! Technical Deep Dive: Fanotify vs. ReadDirectoryChangesW One of the most interesting parts of this update was comparing how different operating systems handle file events: Linux (fanotify): This is a powerful, low-level kernel feature. It allows us to monitor an entire mount point (like /) and see every single read or write event system-wide. It requires root privileges but is incredibly efficient. Windows (ReadDirectoryChangesW): This API is directory-based. We tell Windows, “Watch this folder and all its children.” While it’s slightly more “high-level” than fanotify, it’s perfect for monitoring a specific drive or project folder. Hardware Setup The hardware remains simple. You just need two LEDs (one for Read, one for Write) and two resistors (around 220-330 ohms). If you’re using a Raspberry Pi, connect them to GPIO 20 and 21. If you’re using the MCP2221A, you can map the pins in the .env file: READ_LED=20 WRITE_LED=21 I’ve included updated Fritzing diagrams (Sketch.fzz) and schematics in the repository to help with the wiring. Get the Code The full project, including both the Linux and Windows scripts, is available on the GitHub repository. Check out the README.md for detailed installation instructions and the OVERVIEW.md for a deeper look at the code structure. Happy monitoring!

Creating Drive Lights on GPIO - LINUX ONLY!

Github repository

Drive_Lights

Description

If you are using a Raspberry PI or have a USB add on for your PC with GPIO pins (MCP2221A USB to Gpio Adapter Board) you can have LEDs to flash on disk drive read and write. I will use python for this.

This uses GPIOZERO to talk to the LEDs. It uses Fanotify to monitor reads and writes on a mount point. You can use two separate LEDs, one for read and one for write, or a dual color LED which can show two colors in a single body. I recommend two separate LEDs. I've tried a dual color LED but the amount of time the read is on verses the write, the write color gets overwhelmed.

This will need to run as root because the fanotify API is a system level call. I used the fanotify to monitor the '/' mount point. If there are other devices mounted under the root they will not be included. You could have multiple fanotify's running, one for each mount point. You could either provide a separate set of LEDs for each mount point or you could multiplex them all to use the same two LEDs.

I envision a small device with two LEDs, a green and a red, and a USB connector. The software could be provided on the device as a USB FAT32 file system. Of course the user would have to have python installed which is usually the case for most Linux distributions. I would provide a shell script the user would run which would install GPIOZERO if required and then run the python script. The python script could display a list of mount points and allow selection of one or more to monitor, All reads and writes would be multiplexed on the single pair of LEDs. But that's for another time.

The GPIOZERO is on PyPI so you can PIP install. The fanotify is a C library (libc.so.6) included in Linux. You access it in python using the ctypes.CDLL interface.

Mounting a solderless breadboard to a Raspberry PI is made very easy with a GPIO Breakout Kit.This allows you to experiment with the GPIO pins easily on a solderless breadboard. My only complaint is the length of the included ribbon cable I find a little short. I bought a 18 inch one and it seems to work fine. If you are going to use higher speed signals, like SPI or I2C then you shouldn't exceed the recommended length.

Protocol / Task	Recommended Max Length	Why?
High-Speed SPI	15 cm (6 inches)	High clock speeds (MHz) are extremely sensitive to signal "rounding" caused by cable capacitance.
I2C Communication	20 cm (8 inches)	I2C uses pull-up resistors. Long cables add capacitance that prevents the signal from returning to "high" quickly enough.
PWM (Servos/LEDs)	30 cm (12 inches)	High-frequency switching can cause electromagnetic interference (EMI) that leaks into adjacent wires in the ribbon.
Simple Digital I/O	50 cm (20 inches)	Reading buttons or blinking LEDs is less timing-sensitive, though "debouncing" becomes more critical.

I arbitrarily choose to use pin 20 for the read LED and pin 21 for the write LED. This was chosen strictly for convenience as they appear on the bottom right corner of the breadboard adaptor.

NOTE:

I want to point out that this program monitors software activity on a mount point. The actual hardware mounted on this mount point may or may not show the same activity on their own hardware activity LEDs due to buffering and other factors. If you are monitoring an SSD you might be alarmed at times by the number of writes being shown on the write LED. This is only showing you the operating systems calls to the device drivers write method. It is up to the device driver when or if a physical write takes place on the physical drive.

Curcuit

Curcuit diagram

The code

In order to address the GPIO pins we need to import from the GPIOZERO library. We will use three items from the library.

#-------------------------------------------------------------------------------------

#   Title:      Drive_Lights

#   Author:     Wiilliam Main

#   Created:    2021-05-20

#   Synopsys:   When there are GPIO pins available, flash a LED for reads and writes

#   Inputs:     Mount point to monitor default '/'

#-------------------------------------------------------------------------------------

from gpiozero import LED, Device

from gpiozero.pins.lgpio import LGPIOFactory

import os

import ctypes

import struct

import argparse

import sys

from typing import NoReturn

# Initialize the pin factory

try:

    Device.pin_factory = LGPIOFactory()

except ImportError:

    # If LGPIOFactory is not available, let gpiozero choose the best one

    pass

# Initialize LEDs once

write_led = LED(21)

read_led = LED(20)

def blink(led_device: LED):

    """

    Flash the LED for a short duration.

    Reusing the LED object avoids frequent thread creation/destruction issues.

    """

    try:

        # on_time=0.01: High for 0.01 second

        # off_time=0: No low time needed after the pulse

        # n=1: Do this only once

        # background=True: Script continues running immediately

        led_device.blink(on_time=0.01, off_time=0, n=1, background=True)

    except Exception:

        pass

# Fanotify constants from <sys/fanotify.h>

FAN_CLASS_NOTIF = 0x00000000

FAN_MARK_ADD = 0x00000001

FAN_MARK_MOUNT = 0x00000010

FAN_ACCESS = 0x00000001

FAN_MODIFY = 0x00000002

FAN_EVENT_METADATA_LEN = 24  # Size of fanotify_event_metadata

libc = ctypes.CDLL("libc.so.6")

class FanotifyMonitor:

    """Monitors a mount point for read/write events using fanotify."""

    def __init__(self, mount_path: str) -> None:

        self.mount_path: str = mount_path

        self.fd: int = -1

    def _initialize_fanotify(self) -> None:

        """Initialize the fanotify group and mark the mount point."""

        self.fd = libc.fanotify_init(FAN_CLASS_NOTIF, os.O_RDONLY)

        if self.fd < 0:

            raise OSError("Failed to initialize fanotify. Are you root?")

        mask: int = FAN_ACCESS | FAN_MODIFY

        result: int = libc.fanotify_mark(

            self.fd, FAN_MARK_ADD | FAN_MARK_MOUNT, mask, -1,

            self.mount_path.encode('utf-8')

        )

        if result < 0:

            raise OSError(f"Failed to mark mount point: {self.mount_path}")

    def run(self) -> NoReturn:

        """Read and process events in a loop."""

        self._initialize_fanotify()

        #print(f"Monitoring {self.mount_path}... Press Ctrl+C to stop.")

        try:

            while True:

                # Read event metadata from the file descriptor

                data = os.read(self.fd, 4096)

                offset = 0

                while offset + FAN_EVENT_METADATA_LEN <= len(data):

                    # Unpack header: event_len (I), vers (B), reserved (B),

                    # metadata_len (H), mask (Q), fd (i), pid (i)

                    header = struct.unpack_from("IBBHQii", data, offset)

                    event_len, _, _, _, mask, event_fd, pid = header

                    if event_fd >= 0:

                        if mask & FAN_ACCESS or mask & FAN_MODIFY:

                            if mask & FAN_MODIFY:

                                blink(write_led)           #flash write led

                            else:

                                blink(read_led)           #flash read led

                        os.close(event_fd)

                    offset += event_len

        except KeyboardInterrupt:

            sys.exit(0)

        finally:

            if self.fd >= 0:

                os.close(self.fd)

    @staticmethod

    def _get_path_from_fd(fd: int) -> str:

        """Retrieve the file path from its file descriptor via /proc."""

        try:

            return os.readlink(f"/proc/self/fd/{fd}")

        except FileNotFoundError:

            return "Unknown"

if __name__ == "__main__":

    parser = argparse.ArgumentParser(description="Monitor a mount point for read/write events using fanotify.")

    parser.add_argument(

        "mount_point",

        nargs="?",

        default="/",

        help="The mount point to monitor (default: /)"

    )

    args = parser.parse_args()

    # Initialize the FanotifyMonitor with the specified mount point

    monitor = FanotifyMonitor(args.mount_point)

    # Start the monitor

    monitor.run()

The main.py script is the core of the Drive_Lights project. Its purpose is to monitor a filesystem (like your SD card or an external drive) for read and write operations and flash physical LEDs connected to the Raspberry Pi's GPIO pins to provide a visual indicator of disk activity.

Here is a breakdown of how the code works:

---

1. Hardware Control (GPIO)

The script uses the gpiozero library to control the LEDs.

• Pin Factory: It specifically attempts to use LGPIOFactory (lines 18-23), which is the recommended backend for newer Raspberry Pi hardware (like the Pi 5) to ensure reliable pin control.
• LED Initialization: It defines two LED objects (lines 26-27):
  • Read LED: Connected to GPIO 20.
  • Write LED: Connected to GPIO 21.
• The blink function: This function (lines 29-41) triggers a very short pulse (0.01 seconds). It uses background=True so that the main monitoring loop isn't paused while the LED is flashing.

2. Kernel-Level Monitoring (Fanotify)

Instead of constantly polling files (which would be slow and resource-intensive), the script uses fanotify, a powerful Linux kernel feature.

• ctypes & libc: Since Python doesn't have a built-in high-level wrapper for fanotify, the script uses ctypes to talk directly to the C standard library (libc) (line 51).
• Initialization: The _initialize_fanotify method (lines 60-72) sets up a "fanotify group" and marks a specific mount point (like /) to be watched for two types of events:
  • FAN_ACCESS: Triggered when a file is read.
  • FAN_MODIFY: Triggered when a file is written to or modified.

3. The Event Loop (run method)

The heart of the script is the while True loop inside the FanotifyMonitor.run method (lines 80-98):

1. Reading Events: It reads raw binary data from the fanotify file descriptor. This data contains a series of metadata structures describing what happened.
2. Unpacking Metadata: It uses the struct module (line 87) to "unpack" the binary data into readable Python variables (like the event length, the event mask, and the file descriptor of the file being accessed).
3. Logic Switch:
   • If the mask contains FAN_MODIFY, it calls blink(write_led).
   • If the mask contains FAN_ACCESS, it calls blink(read_led).
4. Cleanup: It immediately closes the file descriptor (event_fd) created by the kernel for that specific event (line 96) to prevent the system from running out of available file handles.

4. Command Line Interface

The script uses argparse (lines 114-121) to allow flexibility:

• You can run it simply as sudo python main.py to monitor the root filesystem.
• Or specify a mount point, such as sudo python main.py /media/external_drive.

Summary of Execution Flow

1. Startup: Initialize GPIO pins and parse the target mount point.
2. Setup: Tell the Linux kernel: "Notify me whenever anything on this drive is read or changed."
3. Monitor: Wait for the kernel to send data.
4. Action: When data arrives, identify if it's a read or write and pulse the corresponding LED.
5. Repeat: Continue until the user stops the script with Ctrl+C.

Note: Because fanotify interacts directly with the kernel, the script must be run with root privileges (e.g., using sudo).