README.md

@@ -1,2 +1,16 @@
 # modbus-utils
+
 Internal Modbus TCP polling scripts for Galion Systems client sites.
+
+Reads holding registers from client PLCs, returns tag:value pairs for
+upstream logging. See `config/sites.yaml.example` for config format.
+
+## Usage
+
+```python
+from galion_modbus.poll import poll_site
+from galion_modbus.sites import load_sites
+
+sites = load_sites()
+data = poll_site(sites["walnut_creek"])
+```

config/sites.yaml.example

@@ -1,3 +1,4 @@
+# Copy to sites.yaml and populate with real site data
 sites:
   walnut_creek:
     plcs:
@@ -9,6 +10,7 @@ sites:
           "0": flow_rate_gpm
           "1": tank_level_ft
           "2": pump1_status
+          "3": pump2_status
   gary_in:
     plcs:
       - host: 10.20.1.10

galion_modbus/poll.py

@@ -19,6 +19,7 @@ def read_holding_registers(host, port=502, unit=1, address=0, count=10):
 
 
 def poll_site(site_cfg):
+    """Poll all configured PLCs for a site and return {tag: value}."""
     results = {}
     for plc in site_cfg.get("plcs", []):
         regs = read_holding_registers(
@@ -33,6 +34,7 @@ def poll_site(site_cfg):
 
 
 def write_coil(host, port=502, unit=1, address=0, value=True):
+    """Write single coil — used for pump enable/disable commands."""
     c = ModbusTcpClient(host, port=port)
     c.connect()
     try:
@@ -40,4 +42,4 @@ def write_coil(host, port=502, unit=1, address=0, value=True):
         return not rr.isError()
     finally:
         c.close()
-# increase timeout for slow RTUs
+fix timeout on slow RTUs

galion_modbus/sites.py

@@ -0,0 +1,10 @@
+"""Site PLC configs — loaded from sites.yaml at runtime."""
+import yaml
+import os
+
+_SITES_PATH = os.path.join(os.path.dirname(__file__), "..", "config", "sites.yaml")
+
+
+def load_sites():
+    with open(_SITES_PATH) as fh:
+        return yaml.safe_load(fh)