epicsdev 3.1.1__tar.gz → 3.1.3__tar.gz

{epicsdev-3.1.1 → epicsdev-3.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: epicsdev
-Version: 3.1.1
+Version: 3.1.3
 Summary: Helper module for creating EPICS PVAccess servers using p4p
 Project-URL: Homepage, https://github.com/ASukhanov/epicsdev
 Project-URL: Bug Tracker, https://github.com/ASukhanov/epicsdev
@@ -22,8 +22,13 @@ Helper module for building **EPICS PVAccess servers** using [p4p](https://github
 * Rapid PVAccess server development
 * High-rate data simulation and stress testing
 * GUI-based monitoring and control
+* Rapid instrument integration
 * AI-assisted automatic device support generation
 
+It integrates following EPICS IOC services:<br>
+* **Autosave**: automatically saves the values of EPICS process variables (PVs) to files on a server host, and restores those values when the server restarts.
+* **IocStats**: provides support for PVs that show the health and status of the server, plus a few control PVs.
+* **caPutLog**: logging of PVAccess **`put`** operations.
 ---
 
 ## Installation
@@ -31,9 +36,6 @@ Helper module for building **EPICS PVAccess servers** using [p4p](https://github
 ```bash
 python -m pip install epicsdev
 ```
-
----
-
 ## Quick Demo
 
 Start the demo PVAccess server:
@@ -41,10 +43,7 @@ Start the demo PVAccess server:
 ```bash
 python -m epicsdev.epicsdev
 ```
-
----
-
-## Control & Visualization
+### Control & Visualization
 
 Install optional GUI and plotting tools:
 
@@ -64,52 +63,53 @@ This provides:
 * Live waveform plots
 * Real-time parameter monitoring
 
----
+The screenshots can be seen here: [control page](docs/epicsdev_pypet.png), [plots](docs/epicsdev_pvplot.jpg).
 
-# Multi-Channel Waveform Generator
+### Phoebus Display
 
-`epicsdev.multiadc` generates high-throughput synthetic data for stress-testing EPICS systems.
+An example Phoebus display is provided: `config/epicsdev.bob`. [Screenshot](docs/phoebus_epicsdev.jpg).
 
-### Example
+## Multi-Channel Waveform Generator
+
+`epicsdev.multiadc` generates high-throughput synthetic data for stress-testing EPICS systems.
 
-Generate:
+For example, the following command :
+```bash
+python -m epicsdev.multiadc -s 0.1 -c 10000 -n 100
+```
+Will start a server, which generates:
 
 * **10,000** noisy waveforms per second
 * **100 points per waveform**
 * **40,000 scalar parameters per second**
 
-```bash
-python -m epicsdev.multiadc -s 0.1 -c 10000 -n 100
-```
 
 ### Monitoring GUI
 
 ```bash
 python -m pypeto -c config -f multiadc
 ```
+## Text Put Logger
 
-The GUI includes:
+`epicsdev.putlog` hosts a writable PV named `dump` and appends any written text to a file.
 
-* Control page
-* Real-time waveform plots<br>
-The screenshots can be seen here: [control page](docs/epicsdev_pypet.png), [plots](docs/epicsdev_pvplot.jpg).
----
+Start the logger server (required argument: output file path):
 
-## Phoebus Display
+```bash
+python -m epicsdev.putlog /tmp/putlog.txt
+```
 
-An example Phoebus display is provided:
+Default PV prefix is `putlog0:`, so write text to:
 
-```
-config/epicsdev.bob<br>
+```bash
+caput -p pva putlog0:dump "hello from client"
 ```
 ---
-[Screenshot](docs/phoebus_epicsdev.jpg)
-
-# AI-Assisted Device Support Development
+## AI-Assisted Device Support Development
 
 `epicsdev` is structured to enable automated server generation using AI tools such as GitHub Copilot.
 
-## Workflow Example
+### Workflow Example
 
 1. Create a new GitHub repository.
 
@@ -127,24 +127,14 @@ config/epicsdev.bob<br>
 
 ### Real-World Example
 
-Using this method, a server implementation for a **Tektronix MSO oscilloscope** was:
+Using this method, a server implementation for [Tektronix MSO oscilloscopes](https://github.com/ASukhanov/epicsdev_tektronix) was:
 
 * ~99% correct on first generation
 * Required only minor adjustments
 
 ---
 
-# Use Cases
-
-* EPICS PVAccess server prototyping
-* High-rate data simulation
-* Control system stress testing
-* Rapid instrument integration
-* AI-driven device support generation
-
----
-
-# Requirements
+## Requirements
 
 * Python 3.8+
 * p4p 4.2.2+

{epicsdev-3.1.1 → epicsdev-3.1.3}/README.md

@@ -7,8 +7,13 @@ Helper module for building **EPICS PVAccess servers** using [p4p](https://github
 * Rapid PVAccess server development
 * High-rate data simulation and stress testing
 * GUI-based monitoring and control
+* Rapid instrument integration
 * AI-assisted automatic device support generation
 
+It integrates following EPICS IOC services:<br>
+* **Autosave**: automatically saves the values of EPICS process variables (PVs) to files on a server host, and restores those values when the server restarts.
+* **IocStats**: provides support for PVs that show the health and status of the server, plus a few control PVs.
+* **caPutLog**: logging of PVAccess **`put`** operations.
 ---
 
 ## Installation
@@ -16,9 +21,6 @@ Helper module for building **EPICS PVAccess servers** using [p4p](https://github
 ```bash
 python -m pip install epicsdev
 ```
-
----
-
 ## Quick Demo
 
 Start the demo PVAccess server:
@@ -26,10 +28,7 @@ Start the demo PVAccess server:
 ```bash
 python -m epicsdev.epicsdev
 ```
-
----
-
-## Control & Visualization
+### Control & Visualization
 
 Install optional GUI and plotting tools:
 
@@ -49,52 +48,53 @@ This provides:
 * Live waveform plots
 * Real-time parameter monitoring
 
----
+The screenshots can be seen here: [control page](docs/epicsdev_pypet.png), [plots](docs/epicsdev_pvplot.jpg).
 
-# Multi-Channel Waveform Generator
+### Phoebus Display
 
-`epicsdev.multiadc` generates high-throughput synthetic data for stress-testing EPICS systems.
+An example Phoebus display is provided: `config/epicsdev.bob`. [Screenshot](docs/phoebus_epicsdev.jpg).
 
-### Example
+## Multi-Channel Waveform Generator
+
+`epicsdev.multiadc` generates high-throughput synthetic data for stress-testing EPICS systems.
 
-Generate:
+For example, the following command :
+```bash
+python -m epicsdev.multiadc -s 0.1 -c 10000 -n 100
+```
+Will start a server, which generates:
 
 * **10,000** noisy waveforms per second
 * **100 points per waveform**
 * **40,000 scalar parameters per second**
 
-```bash
-python -m epicsdev.multiadc -s 0.1 -c 10000 -n 100
-```
 
 ### Monitoring GUI
 
 ```bash
 python -m pypeto -c config -f multiadc
 ```
+## Text Put Logger
 
-The GUI includes:
+`epicsdev.putlog` hosts a writable PV named `dump` and appends any written text to a file.
 
-* Control page
-* Real-time waveform plots<br>
-The screenshots can be seen here: [control page](docs/epicsdev_pypet.png), [plots](docs/epicsdev_pvplot.jpg).
----
+Start the logger server (required argument: output file path):
 
-## Phoebus Display
+```bash
+python -m epicsdev.putlog /tmp/putlog.txt
+```
 
-An example Phoebus display is provided:
+Default PV prefix is `putlog0:`, so write text to:
 
-```
-config/epicsdev.bob<br>
+```bash
+caput -p pva putlog0:dump "hello from client"
 ```
 ---
-[Screenshot](docs/phoebus_epicsdev.jpg)
-
-# AI-Assisted Device Support Development
+## AI-Assisted Device Support Development
 
 `epicsdev` is structured to enable automated server generation using AI tools such as GitHub Copilot.
 
-## Workflow Example
+### Workflow Example
 
 1. Create a new GitHub repository.
 
@@ -112,24 +112,14 @@ config/epicsdev.bob<br>
 
 ### Real-World Example
 
-Using this method, a server implementation for a **Tektronix MSO oscilloscope** was:
+Using this method, a server implementation for [Tektronix MSO oscilloscopes](https://github.com/ASukhanov/epicsdev_tektronix) was:
 
 * ~99% correct on first generation
 * Required only minor adjustments
 
 ---
 
-# Use Cases
-
-* EPICS PVAccess server prototyping
-* High-rate data simulation
-* Control system stress testing
-* Rapid instrument integration
-* AI-driven device support generation
-
----
-
-# Requirements
+## Requirements
 
 * Python 3.8+
 * p4p 4.2.2+

epicsdev-3.1.3/docs/modules.md

@@ -0,0 +1,45 @@
+# Runnable Modules
+
+This page lists the main runnable programs in `epicsdev`.
+
+## `epicsdev.epicsdev`
+
+Generic/demo PVAccess server framework.
+
+Run:
+
+```bash
+python -m epicsdev.epicsdev
+```
+
+## `epicsdev.multiadc`
+
+Multi-channel waveform generator for load and stress testing.
+
+Run:
+
+```bash
+python -m epicsdev.multiadc
+```
+
+## `epicsdev.putlog`
+
+Hosts writable PV `dump`; every value written to it is appended to a file.
+
+Run:
+
+```bash
+python -m epicsdev.putlog /tmp/putlog.txt
+```
+
+Default writable PV name:
+
+```text
+putlog0:dump
+```
+
+Example write:
+
+```bash
+caput -p pva putlog0:dump "hello from client"
+```

epicsdev-3.1.3/epicsdev/__init__.py

@@ -0,0 +1,8 @@
+"""epicsdev package.
+
+Main runnable modules:
+- epicsdev.epicsdev : generic/demo PVAccess server framework
+- epicsdev.multiadc : multi-channel waveform generator example
+- epicsdev.putlog   : writable `dump` PV that appends incoming text to a file
+"""
+

{epicsdev-3.1.1 → epicsdev-3.1.3}/epicsdev/epicsdev.py

@@ -1,12 +1,13 @@
-"""Skeleton and helper functions for creating EPICS PVAccess server"""
+"""Helper functions for creating EPICS PVAccess server"""
 # pylint: disable=invalid-name
-__version__= 'v3.1.1 26-03-03'# Autosave is implemented.
+__version__= 'v3.1.3 26-03-04'# putlog functionality added, some refactoring, new features of epicsdev v3.1.0 used, some bugs fixed.
 # SPV removed, PvDefs definitions simplified, new features added.
 #TODO: add support for autosave, (feature 'A'), caputLog (feature 'H') and access rights
 
 import sys
 import time
 from time import perf_counter as timer
+from datetime import datetime
 import os
 #import shelve
 import json
@@ -23,6 +24,7 @@ PeriodicUpdateInterval = 10. # seconds
 AutosaveInterval = 10. # 
 AutosaveDefaultDirectory = '/operations/app_store/pvCache/' # Directory to save
 # autosave files. The actual file name will be <directory><prefix>.cache
+IFace = Context('pva')# client context for getting values from other servers
 
 dtype2p4p = {# mapping from numpy dtype to p4p type code
 's8':'b', 'u8':'B', 's16':'h', 'u16':'H', 'i32':'i', 'u32':'I', 'i64':'l',
@@ -51,6 +53,7 @@ class C_():
     cachefd = None
     lastPutTime = time.time()# last time when a put operation was performed.
     lastAutosaveTime = 0.# last time when the cache was saved to a file.
+    putlogPV = None # name of the PV where put operations are logged. If None, then put operations are not logged.
 
 #```````````````````Helper methods````````````````````````````````````````````
 def serverState():
@@ -223,16 +226,17 @@ def create_PVs(pvDefs, pvcache=None):
             spv.name = pname
             spv.setter = extra.get('setter')
 
-            # add put handler
+            # add a put handler
             @spv.put
             def handle(spv, op):
                 vv = op.value()
                 vr = vv.raw.value
                 ntNamedTuples = spv._wrap(spv.current())
+                oldvr = ntNamedTuples['value']
                 #print(f'Put request for {spv.name} = {repr(vv)}, current value: {repr(ntNamedTuples)}')
                 # check limits, if they are defined. That will be a good
                 # example of using control structure and valueAlarm.
-                printv(f'Put request for {spv.name} = {repr(vr)}, value: {ntNamedTuples["value"]}')
+                #print(f'Put request for {spv.name} = {repr(vr)}, value: {ntNamedTuples["value"]}, peer: {op.name()}, {op.peer()}, {op.account()}, {op.roles()}')
                 try:
                     limitLow = ntNamedTuples['control.limitLow']
                     limitHigh = ntNamedTuples['control.limitHigh']
@@ -253,6 +257,19 @@ def create_PVs(pvDefs, pvcache=None):
                 ct = time.time()
                 C_.lastPutTime = ct
                 spv.post(vr, timestamp=ct) # update subscribers
+
+                if C_.putlogPV is not None:
+                    dt = datetime.now().strftime('%Y-%m-%d %H:%M:%S.%f')[:-3].split()
+                    ip = op.peer().split(':')[3][:-1]# peer looks like: [::ffff:192.168.27.6]:46362
+                    jmsg = {"date":dt[0], "time":dt[1], 
+                        "host":ip, "user":op.account(),
+                        "pv":op.name(), "new":vr, "old":oldvr}
+                    s = json.dumps(jmsg)
+                    try:
+                        IFace.put(C_.putlogPV, "'"+s+"'", timeout=0.5)# quote the string to avoid interpreting it as JSON
+                    except TimeoutError:
+                        printw(f'WARNING: caPutLog feature will be disabled: PV {C_.putlogPV} not accessible.')
+                        C_.putlogPV = None
                 op.done()
 #,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
 #``````````````````Setters
@@ -343,14 +360,8 @@ def create_pvDefs(pvDefs=None, pvcache=None):
     create_PVs(C_.PVDefs, pvcache)
     return C_.PVs
 
-def get_externalPV(pvName:str, timeout=0.5):
-    """Get value of PV from another server. That can be used to check if the
-    server is already running, or to get values from other servers."""
-    ctxt = Context('pva')
-    return ctxt.get(pvName, timeout=timeout)
-
-def init_epicsdev(prefix:str, pvDefs:list, verbose=0,
-                serverStateChanged=None, listDir=None, autosaveDir=None, recall = True):
+def init_epicsdev(prefix:str, pvDefs:list, verbose=0, serverStateChanged=None,
+        listDir=None, autosaveDir=None, recall = True, putlogPV=None):
     """Initialize epicsdev with given prefix and PV definitions.
     prefix is a string that will be prepended to all PV names. It should end with ':'.
     pvDefs is a list of PV definitions, each definition is a list of 3 or 4 items:
@@ -386,7 +397,7 @@ def init_epicsdev(prefix:str, pvDefs:list, verbose=0,
     if serverStateChanged is not None:# set custom serverStateChanged function
         C_.serverStateChanged = serverStateChanged
     try: # check if server is already running
-        host = repr(get_externalPV(prefix+'HOSTNAME')).replace("'",'')
+        host = repr(IFace.get(prefix+'HOSTNAME', timeout=0.5)).replace("'",'')
         print(f'ERROR: Server for {prefix} already running at {host}. Exiting.')
         sys.exit(1)
     except TimeoutError:
@@ -430,6 +441,14 @@ def init_epicsdev(prefix:str, pvDefs:list, verbose=0,
     printi(f'Hosting {len(pvs)} PVs')
     C_.startTime = time.time()
 
+    try:
+        if putlogPV is not None:
+            _ = IFace.get(putlogPV, timeout=0.5)
+            C_.putlogPV = putlogPV
+    except TimeoutError:
+        printw(f'WARNING: caPutLog feature will not work: PV {putlogPV} not accessible.')
+        C_.putlogPV = None
+
     threading.Thread(target=_heartbeat_thread, daemon=True).start()
     return pvs
 
@@ -466,7 +485,8 @@ def sleep():
         C_.cycleTimeSum = 0.
         C_.cyclesAfterUpdate = 0
         sleeping = False
-    if tnow - C_.lastAutosaveTime > AutosaveInterval:
+
+    if C_.cachefd is not None and tnow - C_.lastAutosaveTime > AutosaveInterval:
         C_.lastAutosaveTime = tnow
         if C_.lastPutTime != 0.:
             C_.lastPutTime = 0.
@@ -560,15 +580,17 @@ if __name__ == "__main__":
     # The rest of options are not essential, they can be controlled at runtime using PVs.
     parser.add_argument('-n', '--npoints', type=int, default=nPoints, help=
 'Number of points in the waveform')
+    parser.add_argument('-p', '--putlogPV', default='putlog:dump', help=
+'Name of the PV where put operations are logged. If None, then put operations are not logged.')
     parser.add_argument('-v', '--verbose', action='count', default=0, help=
 'Show more log messages (-vv: show even more)') 
     pargs = parser.parse_args()
-    printv(pargs)
+    print(pargs)
 
     # Initialize epicsdev and PVs
     pargs.prefix = f'{pargs.device}{pargs.index}:'
     PVs = init_epicsdev(pargs.prefix, myPVDefs(), pargs.verbose, None,
-                        pargs.list, pargs.autosave, pargs.recall)
+                    pargs.list, pargs.autosave, pargs.recall, pargs.putlogPV)
     # Initialize the device using pargs if needed.
     init(pargs.npoints)
 

epicsdev-3.1.3/epicsdev/putlog.py

@@ -0,0 +1,70 @@
+"""PVAccess text logger server: writes text from PV `dump` to a file."""
+# pylint: disable=invalid-name
+__version__= 'v0.0.2 26-03-04'
+
+import argparse
+import threading
+
+from .epicsdev import Server, init_epicsdev, publish, printi, set_server, serverState, sleep
+
+
+class C_:
+    """Module-local storage."""
+    logfile = None
+    server = None
+    lock = threading.Lock()
+
+
+def set_dump(value, *_):
+    """Append text written to `dump` PV into the selected log file."""
+    text = str(value)
+    with C_.lock:
+        C_.logfile.write(text)
+        if not text.endswith("\n"):
+            C_.logfile.write("\n")
+        C_.logfile.flush()
+    publish('dump', text)
+
+
+def myPVDefs():
+    """PV definitions for putlog server."""
+    F = 'features'
+    T = 'type'
+    SET = 'setter'
+    return [
+        ['dump', 'Text to append to log file', '', {F: 'W', T: str, SET: set_dump}],
+    ]
+
+
+def main():
+    """Program entry point."""
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument('logfile', nargs='?', default='/tmp/putlog.log', help=
+        'Path to file where text written to the dump PV is appended.')
+    parser.add_argument('-p', '--prefix', default='putlog:', help='PV prefix')
+    parser.add_argument('-v', '--verbose', action='count', default=0, help=
+        'Show more log messages (-vv: more).')
+    pargs = parser.parse_args()
+
+    C_.logfile = open(pargs.logfile, 'a', encoding='utf-8')
+
+    pvs = init_epicsdev(pargs.prefix, myPVDefs(), pargs.verbose, listDir='')
+
+    set_server('Start')
+
+    C_.server = Server(providers=[pvs])
+    printi(f'Server started with prefix {pargs.prefix}, writing dump text to {pargs.logfile}')
+    try:
+        while True:
+            if serverState().startswith('Exit'):
+                break
+            sleep()
+    finally:
+        C_.logfile.close()
+        printi('Server has exited')
+
+if __name__ == '__main__':
+    main()

{epicsdev-3.1.1 → epicsdev-3.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "epicsdev"
-version = "3.1.1"
+version = "3.1.3"
 authors = [
   { name="Andrey Sukhanov", email="sukhanov@bnl.gov" },
 ]