pymscada 0.2.1__tar.gz → 0.2.2__tar.gz

{pymscada-0.2.1/src/pymscada.egg-info → pymscada-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pymscada
-Version: 0.2.1
+Version: 0.2.2
 Summary: Shared tag value SCADA with python backup and Angular UI
 Author-email: Jamie Walton <jamie@walton.net.nz>
 License: GPL-3.0-or-later

{pymscada-0.2.1 → pymscada-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pymscada"
-version = "0.2.1"
+version = "0.2.2"
 description = "Shared tag value SCADA with python backup and Angular UI"
 authors = [
     {name = "Jamie Walton", email = "jamie@walton.net.nz"},

{pymscada-0.2.1 → pymscada-0.2.2}/src/pymscada/__init__.py

@@ -6,10 +6,12 @@ from pymscada.iodrivers.accuweather import AccuWeatherClient
 from pymscada.iodrivers.logix_client import LogixClient
 from pymscada.iodrivers.modbus_client import ModbusClient
 from pymscada.iodrivers.modbus_server import ModbusServer
+from pymscada.iodrivers.piapi import PIWebAPIClient
+from pymscada.iodrivers.sms import SMS
+from pymscada.iodrivers.witsapi import WitsAPIClient
 from pymscada.misc import find_nodes, ramp
 from pymscada.periodic import Periodic
 from pymscada.tag import Tag
-from pymscada.validate import validate
 
 __all__ = [
     'BusClient',
@@ -19,8 +21,10 @@ __all__ = [
     'LogixClient',
     'ModbusClient',
     'ModbusServer',
+    'PIWebAPIClient',
+    'SMS',
+    'WitsAPIClient',
     'find_nodes', 'ramp',
     'Periodic',
     'Tag',
-    'validate',
 ]

{pymscada-0.2.1 → pymscada-0.2.2}/src/pymscada/alarms.py

@@ -17,6 +17,7 @@ KIND = {
     ACT: 'ACT',
     INF: 'INF'
 }
+
 NORMAL = 0
 ALARM = 1
 
@@ -105,7 +106,8 @@ class Alarm():
     Generates the ALM and RTN messages for Alarms to publish via rta_tag.
     """
 
-    def __init__(self, tagname: str, tag: dict, alarm: str, group: str, rta_cb, alarms) -> None:
+    def __init__(self, tagname: str, tag: dict, alarm: str, group: str,
+                 rta_cb, alarms) -> None:
         """Initialize alarm with tag and condition(s)."""
         self.alarm_id = f'{tagname} {alarm}'
         self.tag = Tag(tagname, tag['type'])
@@ -229,7 +231,7 @@ class Alarms:
                 self.alarms.append(new_alarm)
         self.busclient = BusClient(bus_ip, bus_port, module='Alarms')
         self.rta = Tag(rta_tag, dict)
-        self.rta.value = {}
+        self.rta.value = {'__rta_id__': 0}
         self.busclient.add_callback_rta(rta_tag, self.rta_cb)
         self._init_db(db, table)
         self.periodic = Periodic(self.periodic_cb, 1.0)
@@ -283,6 +285,7 @@ class Alarms:
                         request)
                     res = self.cursor.fetchone()
                     self.rta.value = {
+                        '__rta_id__': 0,
                         'id': res[0],
                         'date_ms': res[1],
                         'alarm_string': res[2],
@@ -303,6 +306,7 @@ class Alarms:
                     res = self.cursor.fetchone()
                     if res:
                         self.rta.value = {
+                            '__rta_id__': 0,
                             'id': res[0],
                             'date_ms': res[1],
                             'alarm_string': res[2],

pymscada-0.2.2/src/pymscada/callout.py

@@ -0,0 +1,259 @@
+"""Callout handling."""
+import logging
+import socket
+import time
+from pymscada.bus_client import BusClient
+from pymscada.periodic import Periodic
+from pymscada.tag import Tag
+
+
+"""
+Callout monitors alarms and sends SMS notifications to configured callees.
+
+Configuration:
+- callees: list of recipients with SMS numbers, delays, and group filters
+- alarms_tag: RTA tag receiving alarms from alarms.py
+- ack_tag: tag for receiving acknowledgments
+- rta_tag: tag for configuration updates and SMS requests
+
+Operation:
+1. Collect alarms from alarms_tag (kind=ALM)
+2. For each callee, check if alarms match their group filter and delay
+3. Send SMS via rta_tag when conditions are met
+4. Track sent notifications in alarm['sent'] hash
+5. Remove alarms when callee acknowledges (matches their group)
+"""
+
+ALM = 0
+
+IDLE = 0
+NEW_ALM = 1
+CALLOUT = 2
+
+SENT = 0
+REMIND = 1
+
+
+def normalise_callees(callees: list | None, escalation: dict):
+    """Normalise callees to include delay_ms and remove role."""
+    if callees is None:
+        return []
+    for callee in callees:
+        if 'sms' not in callee:
+            raise ValueError(f'Callee {callee["name"]} has no sms number')
+        if 'role' in callee:
+            if callee['role'] not in escalation:
+                raise ValueError(f'Invalid role: {callee["role"]}. Must be'
+                                 f' one of: {list(escalation.keys())}')
+            callee['delay_ms'] = escalation[callee['role']]
+        else:
+            callee['delay_ms'] = 0
+            callee['role'] = ''
+        if 'group' not in callee:
+            callee['group'] = ''
+    callees.sort(key=lambda x: x['delay_ms'])
+    return callees
+
+
+def alarm_in_group(alarm, callee_group, groups):
+    """Check if alarm_group matches callee_group."""
+    if callee_group == '':
+        return True
+    if callee_group not in groups:
+        return False
+    group = groups[callee_group]
+    if 'tagnames' in group:
+        for tagname in group['tagnames']:
+            if alarm['alarm_string'].startswith(tagname):
+                return True
+    if 'groups' in group:
+        for group in group['groups']:
+            if group in alarm['group']:
+                return True
+    return False
+
+
+class Callout:
+    """Connect to bus_ip:bus_port, monitor alarms and manage callouts."""
+
+    def __init__(
+        self,
+        bus_ip: str | None = '127.0.0.1',
+        bus_port: int | None = 1324,
+        rta_tag: str = '__callout__',
+        alarms_tag: str | None = None,
+        sms_send_tag: str | None = None,
+        sms_recv_tag: str | None = None,
+        ack_tag: str | None = None,
+        status_tag: str | None = None,
+        callees: list | None = None,
+        groups: dict = {},
+        escalation: list | None = None
+    ) -> None:
+        """
+        Connect to bus_ip:bus_port, monitor alarms and manage callouts.
+
+        Monitor alarms via alarms_tag and manage callout messages to callees
+        based on configured delays and area filters.
+
+        Event loop must be running.
+
+        For testing only: bus_ip can be None to skip connection.
+        """
+        if bus_ip is None:
+            logging.warning('Callout has bus_ip=None, only use for testing')
+        else:
+            try:
+                socket.gethostbyname(bus_ip)
+            except socket.gaierror as e:
+                raise ValueError(f'Cannot resolve IP/hostname: {e}')
+            if not isinstance(bus_port, int):
+                raise TypeError('bus_port must be an integer')
+            if not 1024 <= bus_port <= 65535:
+                raise ValueError('bus_port must be between 1024 and 65535')
+        if not isinstance(rta_tag, str) or not rta_tag:
+            raise ValueError('rta_tag must be a non-empty string')
+        if alarms_tag is None:
+            raise ValueError('alarms_tag must be defined')
+        if sms_send_tag is None:
+            raise ValueError('sms_send_tag must be defined')
+        if sms_recv_tag is None:
+            raise ValueError('sms_recv_tag must be defined')
+
+        self.escalation = [list(d.keys())[0] for d in escalation]
+        self.delay_ms = {list(d.keys())[0]: list(d.values())[0]
+                         for d in escalation}
+        logging.warning(f'Callout {bus_ip} {bus_port} {rta_tag} '
+                        f'{sms_send_tag} {sms_recv_tag}')
+        self.alarms = []
+        self.callees = normalise_callees(callees, self.delay_ms)
+        self.groups = groups
+        self.alarms_tag = Tag(alarms_tag, dict)
+        self.alarms_tag.add_callback(self.alarms_cb)
+        self.sms_recv_tag = Tag(sms_recv_tag, dict)
+        self.sms_recv_tag.add_callback(self.sms_recv_cb)
+        self.sms_send_tag = Tag(sms_send_tag, dict)
+        if ack_tag is not None:
+            self.ack_tag = Tag(ack_tag, int)
+            self.ack_tag.add_callback(self.ack_cb)
+        if status_tag is not None:
+            self.status = Tag(status_tag, int)
+        self.busclient = BusClient(bus_ip, bus_port, module='Callout')
+        self.rta = Tag(rta_tag, dict)
+        self.rta.value = {'__rta_id__': 0,
+                          'callees': self.callees,
+                          'groups': self.groups,
+                          'escalation': self.escalation}
+        self.busclient.add_callback_rta(rta_tag, self.rta_cb)
+        self.periodic = Periodic(self.periodic_cb, 1.0)
+
+    def alarms_cb(self, alm_tag):
+        """Handle alarm messages from alarms.py."""
+        alarm = alm_tag.value
+        if 'kind' not in alarm or alarm['kind'] != ALM:
+            return
+        alarm = {
+            'date_ms': alarm['date_ms'],
+            'alarm_string': alarm['alarm_string'],
+            'desc': alarm['desc'],
+            'group': alarm['group'],
+            'sent': {}
+        }
+        self.alarms.append(alarm)
+        logging.info(f'Added alarm to list: {alarm}')
+        if self.status is not None and self.status.value == IDLE:
+            self.status.value = NEW_ALM
+
+    def ack_cb(self, ack_tag):
+        """Handle ACK requests for alarm acknowledgment."""
+        if ack_tag.value == 1:
+            self.alarms = []
+            if self.status is not None:
+                self.status.value = IDLE
+            logging.info('ACK: all alarms cleared')
+
+    def sms_recv_cb(self, sms_recv_tag: dict):
+        """Handle SMS messages from the modem."""
+        logging.info(f'sms_recv_cb {sms_recv_tag.value}')
+        _number = sms_recv_tag.value['number']
+        message = sms_recv_tag.value['message'][:2].upper()
+        if message in ['OK', 'AC', 'TH']:
+            self.alarms = []
+            if self.status is not None:
+                self.status.value = IDLE
+            logging.info('ACK: all alarms cleared')
+
+    def rta_cb(self, request):
+        """Handle RTA requests for callout configuration."""
+        logging.info(f'rta_cb {request}')
+        if 'action' not in request:
+            logging.warning(f'rta_cb malformed {request}')
+            return
+        if request['action'] == 'GET CONFIG':
+            self.rta.value = {'__rta_id__': request['__rta_id__'],
+                              'callees': self.callees,
+                              'groups': self.groups,
+                              'escalation': self.escalation}
+        elif request['action'] == 'MODIFY':
+            send_update = False
+            for callee in self.callees:
+                if callee['name'] == request['name']:
+                    if 'role' in request:
+                        callee['role'] = request['role']
+                        callee['delay_ms'] = self.delay_ms.get(
+                            request['role'], 30000)
+                    if 'group' in request:
+                        callee['group'] = request['group']
+                    logging.info(f'Modified callee with {request}')
+                    send_update = True
+            if send_update:
+                self.rta.value = {'__rta_id__': 0,
+                                  'callees': self.callees,
+                                  'groups': self.groups,
+                                  'escalation': self.escalation}
+
+    def check_callouts(self):
+        """Check alarms and send callouts."""
+        time_ms = int(time.time() * 1000)
+        for callee in self.callees:
+            if not callee['role']:
+                continue
+            count = 0
+            message = ''
+            notify_ms = time_ms - callee['delay_ms']
+            remind_ms = notify_ms - 60000
+            for alarm in self.alarms:
+                if not alarm_in_group(alarm, callee['group'], self.groups):
+                    continue
+                if notify_ms < alarm['date_ms']:
+                    continue
+                if callee['name'] not in alarm['sent']:
+                    message += f"{alarm['desc']}\n"
+                    alarm['sent'][callee['name']] = SENT
+                    count += 1
+                    continue
+                if remind_ms < alarm['date_ms']:
+                    continue
+                if alarm['sent'][callee['name']] != REMIND:
+                    message += f"REMIND {alarm['desc']}\n"
+                    alarm['sent'][callee['name']] = REMIND
+                    count += 1
+            if count > 0:
+                if len(message) > 200:
+                    message = message[:200] + '\n...'
+                send_message = f"{count} Alarms\n{message}"
+                self.sms_send_tag.value = {
+                    'number': callee['sms'],
+                    'message': send_message
+                }
+                if self.status is not None:
+                    self.status.value = CALLOUT
+
+    async def periodic_cb(self):
+        """Periodic callback to check alarms and send callouts."""
+        self.check_callouts()
+
+    async def start(self):
+        """Async startup."""
+        await self.busclient.start()
+        await self.periodic.start()

{pymscada-0.2.1 → pymscada-0.2.2}/src/pymscada/config.py

@@ -2,6 +2,8 @@
 import importlib.resources
 from importlib.abc import Traversable
 import logging
+import os
+import re
 from pathlib import Path
 from yaml import safe_load_all, YAMLError
 from pymscada import demo, pdf
@@ -38,6 +40,21 @@ def get_pdf_files() -> list[Traversable]:
     return files
 
 
+def _expand_env_vars(value):
+    """Recursively expand environment variables in config values."""
+    if isinstance(value, str):
+        pattern = re.compile(r'\$\{([^}]+)\}')
+        def replace_env(match):
+            env_var = match.group(1)
+            return os.environ.get(env_var, match.group(0))
+        return pattern.sub(replace_env, value)
+    elif isinstance(value, dict):
+        return {k: _expand_env_vars(v) for k, v in value.items()}
+    elif isinstance(value, list):
+        return [_expand_env_vars(item) for item in value]
+    return value
+
+
 class Config(dict):
     """Read config from yaml file."""
 
@@ -55,7 +72,9 @@ class Config(dict):
         with open(fp, 'r') as fh:
             try:
                 for data in safe_load_all(fh):
+                    if '__vars__' in data:
+                        del data['__vars__']
                     for x in data:
-                        self[x] = data[x]
+                        self[x] = _expand_env_vars(data[x])
             except YAMLError as e:
                 raise SystemExit(f'failed to load {filename} {e}')

pymscada-0.2.2/src/pymscada/demo/callout.yaml

@@ -0,0 +1,26 @@
+bus_ip: 127.0.0.1
+bus_port: 1324
+rta_tag: __callout__
+alarms_tag: __alarms__
+sms_send_tag: __sms_send__
+sms_recv_tag: __sms_recv__
+ack_tag: SI_Alarm_Ack
+status_tag: SO_Alarm_Status
+escalation:
+- OnCall: 60000
+- Backup 1: 180000
+- Backup 2: 300000
+- Escalate: 600000
+callees:
+- name: A name
+  sms: A number
+  group: System
+- name: B name
+  sms: B number
+groups:
+  Wind:
+    tagnames: [Mt, Fh]
+  System:
+    groups: [__system__, Comms]
+  Test:
+    tagnames: [alarm]

{pymscada-0.2.1 → pymscada-0.2.2}/src/pymscada/demo/openweather.yaml

@@ -2,7 +2,7 @@ bus_ip: 127.0.0.1
 bus_port: 1324
 proxy:
 api:
-  api_key: ${OPENWEATHERMAP_API_KEY}
+  api_key: ${MSCADA_OPENWEATHERMAP_API_KEY}
   units: metric
   locations:
     Murupara:

pymscada-0.2.2/src/pymscada/demo/piapi.yaml

@@ -0,0 +1,15 @@
+bus_ip: 127.0.0.1
+bus_port: 1324
+proxy:
+api:
+  url: 'https://192.168.15.1/'
+  webid: F1Em9DA80Xftdkec1gdWFtX7NAm1eiSAyV8BG1mAAMKQIjRQUEdQSVxQSU9ORUVSXFdFQkFQSVxNT0JJTEVTQ0FEQQ
+  averaging: 300
+tags:
+  I_An_G1_MW:
+    pitag: AnG1.AIMw
+  I_An_G2_MW:
+    pitag: AnG2.AIMw
+  I_Ko_Gn_MW:
+    pitag: KoGn.AIkW
+    scale: 1000

pymscada-0.2.2/src/pymscada/demo/pymscada-io-piapi.service

@@ -0,0 +1,15 @@
+[Unit]
+    Description=pymscada - OSI PI client
+    BindsTo=pymscada-bus.service
+    After=pymscada-bus.service
+
+[Service]
+    WorkingDirectory=__DIR__
+    ExecStart=__PYMSCADA__ witsapiclient --config __DIR__/config/piapi.yaml
+    Restart=always
+    RestartSec=5
+    User=__USER__
+    Group=__USER__
+
+[Install]
+    WantedBy=multi-user.target

pymscada-0.2.2/src/pymscada/demo/pymscada-io-sms.service

@@ -0,0 +1,18 @@
+[Unit]
+    Description=pymscada - SMS client
+    BindsTo=pymscada-bus.service
+    After=pymscada-bus.service
+
+[Service]
+    Environment="MSCADA_SMS_IP=an_ip_address"
+    Environment="MSCADA_SMS_USERNAME=a_user"
+    Environment="MSCADA_SMS_PASSWORD=a_password"
+    WorkingDirectory=__DIR__
+    ExecStart=__PYMSCADA__ sms --config __DIR__/config/sms.yaml
+    Restart=always
+    RestartSec=5
+    User=root
+    Group=root
+
+[Install]
+    WantedBy=multi-user.target

pymscada-0.2.2/src/pymscada/demo/sms.yaml

@@ -0,0 +1,11 @@
+bus_ip: 127.0.0.1
+bus_port: 1324
+sms_send_tag: __sms_send__
+sms_recv_tag: __sms_recv__
+modem: rut241
+modem_ip: ${MSCADA_SMS_IP}
+username: ${MSCADA_SMS_USERNAME}
+password: ${MSCADA_SMS_PASSWORD}
+listen_port: 8080
+info:
+  __default__: info

{pymscada-0.2.1 → pymscada-0.2.2}/src/pymscada/demo/tags.yaml

@@ -13,6 +13,9 @@ __opnotes__:
 __alarms__:
   desc: Alarms
   type: dict
+info:
+  desc: Info
+  type: str
 IntSet:
   desc: Integer Setpoint
   type: int

{pymscada-0.2.1 → pymscada-0.2.2}/src/pymscada/demo/witsapi.yaml

@@ -3,8 +3,8 @@ bus_port: 1324
 proxy:
 api:
   url: 'https://api.electricityinfo.co.nz'
-  client_id: ${WITS_CLIENT_ID}
-  client_secret: ${WITS_CLIENT_SECRET}
+  client_id: ${MSCADA_WITS_CLIENT_ID}
+  client_secret: ${MSCADA_WITS_CLIENT_SECRET}
   gxp_list:
     - MAT1101
     - CYD2201

{pymscada-0.2.1 → pymscada-0.2.2}/src/pymscada/demo/wwwserver.yaml

@@ -1,9 +1,20 @@
+__vars__:
+- &primary_color darkmagenta
+- &secondary_color green
 bus_ip: 127.0.0.1
 bus_port: 1324
 ip: 0.0.0.0
 port: 8324
 get_path:
 serve_path: __HOME__
+config:
+  primary_color: *primary_color
+  secondary_color: *secondary_color
+  mscada_link: http://127.0.0.1/
+  people:
+  - name: John Smith
+    email: john.smith@example.com
+    phone: '+64not_a_number'
 pages:
 - name: Notes
   parent:
@@ -78,6 +89,10 @@ pages:
       scale: mS
       color: red
       dp: 1
+    bands:
+    - series: [localhost_ping, google_ping]
+      fill: [green, 0.3]
+      dir: 1
 - name: Weather
   parent:
   items:

{pymscada-0.2.1 → pymscada-0.2.2}/src/pymscada/history.py

@@ -270,7 +270,7 @@ class History():
             self.tags[tagname] = Tag(tagname, tag['type'])
             self.tags[tagname].add_callback(self.hist_tags[tagname].callback)
         self.rta = Tag(rta_tag, bytes)
-        self.rta.value = b'\x00\x00\x00\x00\x00\x00'
+        self.rta.value = b'\x00\x00\x00\x00\x00\x00'  # rta_id is 0
         self.busclient.add_callback_rta(rta_tag, self.rta_cb)
 
     def rta_cb(self, request: Request):
@@ -278,9 +278,7 @@ class History():
         if 'start_ms' in request:
             request['start_us'] = request['start_ms'] * 1000
             request['end_us'] = request['end_ms'] * 1000
-        rta_id = 0
-        if '__rta_id__' in request:
-            rta_id = request['__rta_id__']
+        rta_id = request['__rta_id__']
         tagname = request['tagname']
         start_time = time.asctime(time.localtime(
             request['start_us'] / 1000000))
@@ -299,7 +297,7 @@ class History():
                 packtype = 2
             self.rta.value = pack('>HHH', rta_id, tagid, packtype) + data
             logging.info(f'sent {len(data)} bytes for {request["tagname"]}')
-            self.rta.value = b'\x00\x00\x00\x00\x00\x00'
+            self.rta.value = b'\x00\x00\x00\x00\x00\x00'  # rta_id is 0
         except Exception as e:
             logging.error(f'history rta_cb {e}')