pymscada 0.1.11b10__py3-none-any.whl → 0.2.0__py3-none-any.whl

pymscada/checkout.py

@@ -6,100 +6,98 @@ import sys
 from pymscada.config import get_demo_files, get_pdf_files
 
 
-PATH = {
-    '__PYTHON__': Path(f'{sys.exec_prefix}/bin/python').absolute(),
-    '__PYMSCADA__': Path(sys.argv[0]).absolute(),
-    '__DIR__': Path('.').absolute(),
-    '__HOME__': Path.home().absolute(),
-    '__USER__': getpass.getuser()
-}
-if sys.platform == "win32":
-    PATH = {
-        '__PYTHON__': Path(f'{sys.exec_prefix}/python.exe').absolute(),
-        '__PYMSCADA__': Path(sys.argv[0]).absolute(),
-        '__DIR__': Path('.').absolute(),
-        '__HOME__': Path.home(),
-        '__USER__': getpass.getuser()
-    }
+class Checkout:
+    """Create and manage configuration files."""
+    
+    def __init__(self, **kwargs):
+        """Initialize paths and settings."""
+        self.path = {
+            '__PYTHON__': Path(f'{sys.exec_prefix}/bin/python').absolute(),
+            '__PYMSCADA__': Path(sys.argv[0]).absolute(),
+            '__DIR__': Path('.').absolute(),
+            '__HOME__': Path.home().absolute(),
+            '__USER__': getpass.getuser()
+        }
+        if sys.platform == "win32":
+            self.path['__PYTHON__'] = Path(f'{sys.exec_prefix}/python.exe').absolute()
+        
+        self.overwrite = kwargs.get('overwrite', False)
+        self.diff = kwargs.get('diff', False)
 
-def make_history():
-    """Make the history folder if missing."""
-    history_dir = PATH['__DIR__'].joinpath('history')
-    if not history_dir.exists():
-        print("making 'history' folder")
-        history_dir.mkdir()
+    def make_history(self):
+        """Make the history folder if missing."""
+        history_dir = self.path['__DIR__'].joinpath('history')
+        if not history_dir.exists():
+            print("making 'history' folder")
+            history_dir.mkdir()
 
+    def make_pdf(self):
+        """Make the pdf folder if missing."""
+        pdf_dir = self.path['__DIR__'].joinpath('pdf')
+        if not pdf_dir.exists():
+            print('making pdf dir')
+            pdf_dir.mkdir()
+        for pdf_file in get_pdf_files():
+            target = pdf_dir.joinpath(pdf_file.name)
+            target.write_bytes(pdf_file.read_bytes())
 
-def make_pdf():
-    """Make the pdf folder if missing."""
-    pdf_dir = PATH['__DIR__'].joinpath('pdf')
-    if not pdf_dir.exists():
-        print('making pdf dir')
-        pdf_dir.mkdir()
-    for pdf_file in get_pdf_files():
-        target = pdf_dir.joinpath(pdf_file.name)
-        target.write_bytes(pdf_file.read_bytes())
+    def make_config(self):
+        """Make the config folder, if missing, and copy files in."""
+        config_dir = self.path['__DIR__'].joinpath('config')
+        if not config_dir.exists():
+            print('making config dir')
+            config_dir.mkdir()
+        for config_file in get_demo_files():
+            target = config_dir.joinpath(config_file.name)
+            rt = 'Creating '
+            if target.exists():
+                if self.overwrite:
+                    rt = 'Replacing '
+                    target.unlink()
+                else:
+                    continue
+            print(f'{rt} {target}')
+            rd_bytes = config_file.read_bytes()
+            if target.name.lower() != 'readme.md':
+                for k, v in self.path.items():
+                    rd_bytes = rd_bytes.replace(k.encode(), str(v).encode())
+            target.write_bytes(rd_bytes)
 
+    def read_with_subst(self, file: Path):
+        """Read the file and replace DIR markers."""
+        rd = file.read_bytes().decode()
+        for k, v in self.path.items():
+            rd = rd.replace(k, str(v))
+        lines = rd.splitlines()
+        return lines
 
-def make_config(overwrite: bool):
-    """Make the config folder, if missing, and copy files in."""
-    config_dir = PATH['__DIR__'].joinpath('config')
-    if not config_dir.exists():
-        print('making config dir')
-        config_dir.mkdir()
-    for config_file in get_demo_files():
-        target = config_dir.joinpath(config_file.name)
-        rt = 'Creating '
-        if target.exists():
-            if overwrite:
-                rt = 'Replacing '
-                target.unlink()
+    def compare_config(self):
+        """Compare old and new config."""
+        config_dir = self.path['__DIR__'].joinpath('config')
+        if not config_dir.exists():
+            print('No config dir, are you in the right directory')
+            return
+        for config_file in get_demo_files():
+            target = config_dir.joinpath(config_file.name)
+            if target.exists():
+                new_lines = self.read_with_subst(config_file)
+                old_lines = self.read_with_subst(target)
+                diff = list(difflib.unified_diff(old_lines, new_lines,
+                            fromfile=str(target), tofile=str(config_file)))
+                if len(diff):
+                    print('\n'.join(diff), '\n')
             else:
-                continue
-        print(f'{rt} {target}')
-        rd_bytes = config_file.read_bytes()
-        if target.name.lower() != 'readme.md':
-            for k, v in PATH.items():
-                rd_bytes = rd_bytes.replace(k.encode(), str(v).encode())
-        target.write_bytes(rd_bytes)
+                print(f'\n--- MISSING FILE\n\n+++ {config_file}')
 
-
-def read_with_subst(file: Path):
-    """Read the file and replace DIR markers."""
-    rd = file.read_bytes().decode()
-    for k, v in PATH.items():
-        rd = rd.replace(k, str(v))
-    lines = rd.splitlines()
-    return lines
-
-
-def compare_config():
-    """Compare old and new config."""
-    config_dir = PATH['__DIR__'].joinpath('config')
-    if not config_dir.exists():
-        print('No config dir, are you in the right directory')
-        return
-    for config_file in get_demo_files():
-        target = config_dir.joinpath(config_file.name)
-        if target.exists():
-            new_lines = read_with_subst(config_file)
-            old_lines = read_with_subst(target)
-            diff = list(difflib.unified_diff(old_lines, new_lines,
-                        fromfile=str(target), tofile=str(config_file)))
-            if len(diff):
-                print('\n'.join(diff), '\n')
+    async def start(self):
+        """Execute checkout process."""
+        for name in ['__PYTHON__', '__PYMSCADA__', '__DIR__', '__HOME__']:
+            if not self.path[name].exists():
+                raise SystemExit(f'{self.path[name]} is missing')
+        
+        if self.diff:
+            self.compare_config()
         else:
-            print(f'\n--- MISSING FILE\n\n+++ {config_file}')
-
-
-def checkout(overwrite=False, diff=False):
-    """Do it."""
-    for name in ['__PYTHON__', '__PYMSCADA__', '__DIR__', '__HOME__']:
-        if not PATH[name].exists():
-            raise SystemExit(f'{PATH[name]} is missing')
-    if diff:
-        compare_config()
-    else:
-        make_history()
-        make_pdf()
-        make_config(overwrite)
+            self.make_history()
+            self.make_pdf()
+            self.make_config()

pymscada/console.py

@@ -3,7 +3,8 @@ import asyncio
 import logging
 import sys
 from pymscada.bus_client import BusClient
-from pymscada.tag import Tag, tag_for_web
+from pymscada.tag import Tag
+from pymscada.www_server import standardise_tag_info
 try:
     import termios
     import tty
@@ -153,7 +154,7 @@ class Console:
     """Provide a text console to interact with a Bus."""
 
     def __init__(self, bus_ip: str = '127.0.0.1', bus_port: int = 1324,
-                 tag_info: dict = {}):
+                 tag_info: dict = {}) -> None:
         """
         Connect to bus_ip:bus_port and provide console interaction with a Bus.
 
@@ -177,7 +178,7 @@ class Console:
         self.busclient = BusClient(bus_ip, bus_port, module='Console')
         self.tags: dict[str, Tag] = {}
         for tagname, tag in tag_info.items():
-            tag_for_web(tagname, tag)
+            standardise_tag_info(tagname, tag)
             self.tags[tagname] = Tag(tagname, tag['type'])
 
     def write_tag(self, tag: Tag):

pymscada/demo/alarms.yaml

@@ -0,0 +1,5 @@
+bus_ip: 127.0.0.1
+bus_port: 1324
+rta_tag: __alarms__
+db: __HOME__/config/pymscada-alarms.sqlite
+table: alarms

pymscada/demo/callout.yaml

@@ -0,0 +1,17 @@
+bus_ip: 127.0.0.1
+bus_port: 1324
+rta_tag: __callout__
+alarms_tag: __alarms__
+ack_tag: SI_Alarm_Ack
+status_tag: SO_Alarm_Status
+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

pymscada/demo/openweather.yaml

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

pymscada/demo/pymscada-alarms.service

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

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-openweather.service

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

pymscada/demo/{pymscada-io-accuweather.service → pymscada-io-witsapi.service}

@@ -1,11 +1,11 @@
 [Unit]
-    Description=pymscada - AccuWeather client
+    Description=pymscada - WITS client
     BindsTo=pymscada-bus.service
     After=pymscada-bus.service
 
 [Service]
     WorkingDirectory=__DIR__
-    ExecStart=__PYMSCADA__ accuweatherclient --config __DIR__/config/accuweather.yaml
+    ExecStart=__PYMSCADA__ witsapiclient --config __DIR__/config/witsapi.yaml
     Restart=always
     RestartSec=5
     User=__USER__

pymscada/demo/tags.yaml

@@ -113,10 +113,14 @@ localhost_ping:
   desc: Ping time to localhost
   type: float
   units: ms
+  alarm: '> 500 for 300'
+  group: System
 google_ping:
   desc: Ping time to google
   type: float
   units: ms
+  alarm: '> 100 for 30'
+  group: System
 Murupara_Temp:
   desc: Murupara Temperature
   type: float

pymscada/demo/witsapi.yaml

@@ -0,0 +1,17 @@
+bus_ip: 127.0.0.1
+bus_port: 1324
+proxy:
+api:
+  url: 'https://api.electricityinfo.co.nz'
+  client_id: ${WITS_CLIENT_ID}
+  client_secret: ${WITS_CLIENT_SECRET}
+  gxp_list:
+    - MAT1101
+    - CYD2201
+    - BEN2201
+  back: 1
+  forward: 12
+tags:
+  - MAT1101_RTD
+  - CYD2201_RTD
+  - BEN2201_RTD

pymscada/files.py

@@ -10,13 +10,13 @@ class Files():
     """Connect to bus_ip:bus_port, store and provide a value history."""
 
     def __init__(self, bus_ip: str = '127.0.0.1', bus_port: int = 1324,
-                 path: str = '', files: list = None,
+                 path: str = '', files: list[dict] = [],
                  rta_tag: str = '__files__') -> None:
         """
         Connect to bus_ip:bus_port, serve and update files.
 
-        TODO
-        Write something.
+        Scans paths in files at the root defined by path. These should
+        be readable by wwwserver so that download links work.
 
         Event loop must be running.
         """

pymscada/history.py

@@ -1,9 +1,32 @@
-"""Store and provide history."""
+"""Store and provide history.
+
+History File Structure
+---------------------
+History files are binary files stored as <tagname>_<time_us>.dat where time_us
+is the microsecond timestamp of the first entry in that file.
+
+Each file contains a series of fixed-size records (16 bytes each):
+- For integer tags: 8 bytes timestamp (uint64) + 8 bytes value (int64)
+- For float tags: 8 bytes timestamp (uint64) + 8 bytes value (double)
+
+Files are organized in chunks:
+- Each chunk is 1024 records (16KB)
+- Each file contains up to 64 chunks (1MB)
+- New files are created when:
+  1. Current file reaches max size (64 chunks)
+  2. Manual flush() is called
+  3. Application shutdown
+
+Timestamps are stored as microseconds since epoch in network byte order (big-endian).
+Values are also stored in network byte order.
+"""
 import atexit
 import logging
 from pathlib import Path
 from struct import pack, pack_into, unpack_from, error
 import time
+import socket
+from typing import TypedDict, Optional
 from pymscada.bus_client import BusClient
 from pymscada.tag import Tag, TYPES
 
@@ -14,11 +37,12 @@ CHUNK_SIZE = ITEM_COUNT * ITEM_SIZE
 FILE_CHUNKS = 64
 
 
-def tag_for_history(tagname: str, tag: dict):
-    """Correct tag dictionary in place to be suitable for web client."""
+def standardise_tag_info(tagname: str, tag: dict):
+    """Correct tag dictionary in place to be suitable for modules."""
     tag['name'] = tagname
     tag['id'] = None
     if 'desc' not in tag:
+        logging.warning(f"Tag {tagname} has no description, using name")
         tag['desc'] = tag['name']
     if 'multi' in tag:
         tag['type'] = int
@@ -38,6 +62,16 @@ def tag_for_history(tagname: str, tag: dict):
         tag['deadband'] = None
 
 
+class Request(TypedDict, total=False):
+    """Type definition for request dictionary."""
+    tagname: str 
+    start_ms: Optional[int]  # Allow web client to use native ms
+    start_us: Optional[int]  # Native for pymscada server
+    end_ms: Optional[int]
+    end_us: Optional[int]
+    __rta_id__: Optional[int]  # Empty for a change that must be broadcast
+
+
 def get_tag_hist_files(path: Path, tagname: str) -> dict[int, Path]:
     """Parse path for history files matching tagname."""
     files_us = {}
@@ -188,9 +222,14 @@ class TagHistory():
 class History():
     """Connect to bus_ip:bus_port, store and provide a value history."""
 
-    def __init__(self, bus_ip: str = '127.0.0.1', bus_port: int = 1324,
-                 path: str = 'history', tag_info: dict = {},
-                 rta_tag: str = '__history__') -> None:
+    def __init__(
+        self,
+        bus_ip: str = '127.0.0.1',
+        bus_port: int = 1324,
+        path: str = 'history',
+        tag_info: dict[str, dict] = {},
+        rta_tag: str | None = '__history__'
+    ) -> None:
         """
         Connect to bus_ip:bus_port, store and provide a value history.
 
@@ -200,12 +239,29 @@ class History():
 
         Event loop must be running.
         """
+        if not isinstance(bus_ip, str):
+            raise ValueError("bus_ip must be a string")
+        try:
+            socket.gethostbyname(bus_ip)
+        except socket.gaierror:
+            raise ValueError(f"Invalid bus_ip: {bus_ip}")
+        if not isinstance(bus_port, int):
+            raise ValueError("bus_port must be an integer")
+        if not 1024 <= bus_port <= 65535:
+            raise ValueError(f"bus_port must be between 1024 and 65535")
+        if not isinstance(path, str):
+            raise ValueError("path must be a string")
+        if not isinstance(tag_info, dict):
+            raise ValueError("tag_info must be a dictionary")
+        if not isinstance(rta_tag, (str, type(None))):
+            raise ValueError("rta_tag must be a string or None")
+
         self.busclient = BusClient(bus_ip, bus_port, module='History')
         self.path = path
         self.tags: dict[str, Tag] = {}
         self.hist_tags: dict[str, TagHistory] = {}
         for tagname, tag in tag_info.items():
-            tag_for_history(tagname, tag)
+            standardise_tag_info(tagname, tag)
             if tag['type'] not in [float, int]:
                 continue
             self.hist_tags[tagname] = TagHistory(
@@ -217,7 +273,7 @@ class History():
         self.rta.value = b'\x00\x00\x00\x00\x00\x00'
         self.busclient.add_callback_rta(rta_tag, self.rta_cb)
 
-    def rta_cb(self, request):
+    def rta_cb(self, request: Request):
         """Respond to bus requests for data to publish on rta."""
         if 'start_ms' in request:
             request['start_us'] = request['start_ms'] * 1000