pymscada 0.2.0rc8__py3-none-any.whl → 0.2.2__py3-none-any.whl

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/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/callout.py

@@ -25,41 +25,52 @@ Operation:
 """
 
 ALM = 0
+
 IDLE = 0
 NEW_ALM = 1
 CALLOUT = 2
 
+SENT = 0
+REMIND = 1
+
 
-def normalise_callees(callees: list | None):
-    """Normalise callees to include delay_ms and remove delay."""
+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 'delay' in callee:
-            callee['delay_ms'] = callee['delay'] * 1000
-            del callee['delay']
+        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'] = []
+            callee['group'] = ''
     callees.sort(key=lambda x: x['delay_ms'])
     return callees
 
 
-def alarm_in_callee_group(alarm_group: list, callee_group: list):
-    """Check if alarm_group is in callee_group."""
-    if not callee_group:
-        if not alarm_group:
-            return ''
-        return alarm_group[0]
-    if not alarm_group:
-        return None
-    for group in alarm_group:
-        if group in callee_group:
-            return group
-    return None
+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:
@@ -71,10 +82,13 @@ class Callout:
         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: list | None = None
+        groups: dict = {},
+        escalation: list | None = None
     ) -> None:
         """
         Connect to bus_ip:bus_port, monitor alarms and manage callouts.
@@ -99,97 +113,139 @@ class Callout:
                 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')
 
-        logging.warning(f'Callout {bus_ip} {bus_port} {rta_tag}')
+        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.groups = []
-        if groups is not None:
-            self.groups = groups
-        self.status = None
+        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.status.value = IDLE
         self.busclient = BusClient(bus_ip, bus_port, module='Callout')
-        self.busclient.add_callback_rta(alarms_tag, self.alarms_cb)
-        self.busclient.add_callback_rta(ack_tag, self.ack_cb)
         self.rta = Tag(rta_tag, dict)
-        self.rta.value = {}
+        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, request):
+    def alarms_cb(self, alm_tag):
         """Handle alarm messages from alarms.py."""
-        if request['kind'] != ALM:
+        alarm = alm_tag.value
+        if 'kind' not in alarm or alarm['kind'] != ALM:
             return
         alarm = {
-            'date_ms': request['date_ms'],
-            'alarm_string': request['alarm_string'],
-            'desc': request['desc'],
-            'group': request['group'],
+            '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: str):
+    def ack_cb(self, ack_tag):
         """Handle ACK requests for alarm acknowledgment."""
-        if ack == '__all':
+        if ack_tag.value == 1:
             self.alarms = []
-            return
-        callee = None
-        for c in self.callees:
-            if ack == c['sms']:
-                callee = c
-                break
-            if ack == c['name']:
-                callee = c
-                break
-        if callee is None:
-            logging.warning(f'ACK rejected: {ack}')
-            return
-        logging.info(f'ACK accepted: {ack}')
-        group = callee['group']
-        remaining_alarms = []
-        for alarm in self.alarms:
-            alarm_group = alarm_in_callee_group(alarm['group'], group)
-            if alarm_group is None:
-                remaining_alarms.append(alarm)
-        self.alarms = remaining_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 'delay' in request:
-                        callee['delay_ms'] = request['delay'] * 1000
+                    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. Can be called independently for testing."""
+        """Check alarms and send callouts."""
         time_ms = int(time.time() * 1000)
         for callee in self.callees:
-            message = ''
+            if not callee['role']:
+                continue
             count = 0
-            group = callee['group']
+            message = ''
             notify_ms = time_ms - callee['delay_ms']
+            remind_ms = notify_ms - 60000
             for alarm in self.alarms:
-                if alarm['date_ms'] < notify_ms:
-                    alarm_group = alarm_in_callee_group(alarm['group'], group)
-                    if alarm_group is not None and callee['name'] not in alarm['sent']:
-                        count += 1
-                        message += f"{alarm['alarm_string']}\n"
-                        alarm['sent'][callee['name']] = time_ms
+                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:
-                send_message = f"{alarm_group} {count} unack alarms\n{message}"
-                logging.warning(f'Callout to {callee["name"]}: {send_message}')
-                self.rta.value = {'action': 'SMS', 'sms': callee['sms'],
-                                  'message': send_message}
+                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
 

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/demo/callout.yaml

@@ -1,16 +1,26 @@
 bus_ip: 127.0.0.1
 bus_port: 1324
 rta_tag: __callout__
-alarms: __alarms__
-ack: SI_Alarm_Ack
-status: SO_Alarm_Status
+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:
-- name: Aniwhenua Station
-  group:
-- name: Aniwhenua System
-  group: System
+  Wind:
+    tagnames: [Mt, Fh]
+  System:
+    groups: [__system__, Comms]
+  Test:
+    tagnames: [alarm]

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/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/demo/pymscada-callout.service

@@ -0,0 +1,16 @@
+[Unit]
+    Description=pymscada - callout
+    BindsTo=pymscada-bus.service
+    After=pymscada-bus.service
+
+[Service]
+    WorkingDirectory=__DIR__
+    ExecStart=__PYMSCADA__ callout --config __DIR__/config/callout.yaml --tags __DIR__/config/tags.yaml
+    Restart=always
+    RestartSec=5
+    User=__USER__
+    Group=__USER__
+    KillSignal=SIGINT
+
+[Install]
+    WantedBy=multi-user.target

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/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/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/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/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/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/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}')