epicsdev 3.3.1__tar.gz → 3.3.4__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,105 @@
1
+ Metadata-Version: 2.5
2
+ Name: epicsdev
3
+ Version: 3.3.4
4
+ Summary: Helper module for creating EPICS PVAccess servers using p4p
5
+ Project-URL: Homepage, https://github.com/eicorg/epicsdev
6
+ Project-URL: Bug Tracker, https://github.com/eicorg/epicsdev
7
+ Author-email: Andrey Sukhanov <sukhanov@bnl.gov>
8
+ License-File: LICENSE
9
+ Classifier: License :: OSI Approved :: BSD License
10
+ Classifier: Operating System :: OS Independent
11
+ Classifier: Programming Language :: Python :: 3
12
+ Requires-Python: >=3.10
13
+ Requires-Dist: p4p>=4.2.2
14
+ Requires-Dist: psutil
15
+ Description-Content-Type: text/markdown
16
+
17
+ # epicsdev
18
+
19
+ `epicsdev` is a Python framework designed for rapidly developing EPICS PVAccess servers using the [p4p](https://github.com/epics-base/p4p) library.
20
+
21
+ Device process variables (PVs) are defined using a compact format:
22
+ ```python
23
+ [name, description, initial_value, attributes]
24
+ ```
25
+
26
+ Device-specific logic resides within a small, well-structured Python file following a predictable pattern. Given an instrument programming manual, an LLM assistant (such as GitHub Copilot) can easily leverage this pattern to spin up initial support for new hardware in under an hour.
27
+
28
+ ---
29
+
30
+ ## Key Features
31
+
32
+ * **High-Bandwidth Data Streaming:** Minimizes packet overhead and uses the optimized p4p bindings to move complex data structures directly.
33
+ * **Built-in Services:** Out-of-the-box support for autosave/restore, IocStats, heartbeat monitoring, and PV-put logging.
34
+ * **Rapid Prototyping:** Simple, declarative format for PV definitions.
35
+ * **LLM-Friendly:** Highly predictable boilerplate that allows AI code assistants to write drivers effortlessly.
36
+ * **OPI Integration:** Automated operator interface generation for Phoebus.
37
+
38
+ ---
39
+
40
+ ## Getting Started
41
+
42
+ ### 1. Generate a PVAccess Server
43
+ Follow the [Detailed Server Generation Guide](docs/generate_server.md) to bootstrap a functional PVAccess server supporting your instrument's core functions.
44
+
45
+ ### 2. Generate an OPI Display
46
+ You can automatically create an operator interface (OPI) layout using [phoebusgen](https://als-epics.github.io/phoebusgen/). See the [OPI Generation Instructions](docs/generate_opi.md) for details.
47
+
48
+ ### 3. Quick Test (Simulation Mode)
49
+ To see the framework in action without physical hardware, you can launch a simulated multi-channel waveform generator, which can be useful for stress-testing EPICS installations. The following command generates 100 noisy waveforms (1,000 points each) alongside 300 scalar parameters:
50
+
51
+ ```bash
52
+ python -m epicsdev.multiadc -C 100 -n 1000
53
+ ```
54
+ To change the data publication frequency, modify the `sleep` PV: `pvput multiadc:0:sleep .1`.
55
+
56
+ #### Quick GUI
57
+ To control and plot the server's PVs, you can use the `pypeto` and `pvplot` modules.
58
+
59
+ ```bash
60
+ pip install pypeto pvplot
61
+ python -m pypeto -f config/multiadc_pp
62
+ ```
63
+
64
+ Other examples include a single-waveform generator and a multi-peak image generator:
65
+ ```bash
66
+ python -m epicsdev.epicsdev
67
+ python -m epicsdev.imagegen
68
+ ```
69
+ See [imagegen usage](docs/imagegenUsage.md) for more details.
70
+
71
+ ### 4. Continuous Integration
72
+ To package `epicsdev`-based PVAccess servers as standalone Linux executables in your build pipeline, see the [Continuous Integration Guide](docs/epicsdev_continuous_integration.md) for PyInstaller build instructions and dependency requirements.
73
+
74
+ ## Fully Functional PVAccess Servers Developed Using epicsdev
75
+
76
+ Power Supplies
77
+ * [CAEN FAST-PS](https://github.com/eicorg/epicsdev_ps_caen_fastps)
78
+ * [CAEN EASY-DRIVER](https://github.com/eicorg/epicsdev_ps_caen_easydriver)
79
+
80
+ Oscilloscopes
81
+ * [Keysight (Agilent) DSO-X series](https://github.com/eicorg/epicsdev_osc_keysight_dsox)
82
+ * [Rigol DHO series](https://github.com/eicorg/epicsdev_osc_rigol)
83
+ * [Tektronix MSO and DPO series](https://github.com/eicorg/epicsdev_osc_tektronix_mso)
84
+ * [LeCroy WaveRunner series](https://github.com/eicorg/epicsdev_osc_lecroy_waverunner)
85
+
86
+ Signal Generators
87
+ * [Siglent SDG series](https://github.com/eicorg/epicsdev_siggen_siglent_sdg)
88
+ * [Keysight 33000 series](https://github.com/eicorg/epicsdev_siggen_keysight_33000)
89
+
90
+ Data Acquisition Instruments
91
+ * [CAEN DT5202](https://github.com/eicorg/epicsdev_daq_caen_dt5202)
92
+ * [NI cDAQ](https://github.com/eicorg/epicsdev_cdaq). Under development
93
+ * [LabJack U3](https://github.com/eicorg/epicsdev_daq_labjack_u3)
94
+
95
+ Magnetometers
96
+ * [Lake Shore Model 421](https://github.com/eicorg/epicsdev_magn_lakeshore)
97
+ * [Caylar NMR20](https://github.com/eicorg/epicsdev_magn_caylar_nmr)
98
+
99
+ Vacuum Gauge Controllers
100
+ * [Granville-Phillips 307 and 358](https://github.com/eicorg/epicsdev_vac)
101
+ * [B-RAX 3000 series](https://github.com/eicorg/epicsdev_vac) from InstruTech
102
+
103
+ Simulation Utilities
104
+ * [Multi-channel Waveform Generator](https://github.com/eicorg/epicsdev/blob/main/epicsdev/multiadc.py)
105
+ * [Multi-peak Image Generator](https://github.com/eicorg/epicsdev/blob/main/epicsdev/imagegen.py)
@@ -0,0 +1,89 @@
1
+ # epicsdev
2
+
3
+ `epicsdev` is a Python framework designed for rapidly developing EPICS PVAccess servers using the [p4p](https://github.com/epics-base/p4p) library.
4
+
5
+ Device process variables (PVs) are defined using a compact format:
6
+ ```python
7
+ [name, description, initial_value, attributes]
8
+ ```
9
+
10
+ Device-specific logic resides within a small, well-structured Python file following a predictable pattern. Given an instrument programming manual, an LLM assistant (such as GitHub Copilot) can easily leverage this pattern to spin up initial support for new hardware in under an hour.
11
+
12
+ ---
13
+
14
+ ## Key Features
15
+
16
+ * **High-Bandwidth Data Streaming:** Minimizes packet overhead and uses the optimized p4p bindings to move complex data structures directly.
17
+ * **Built-in Services:** Out-of-the-box support for autosave/restore, IocStats, heartbeat monitoring, and PV-put logging.
18
+ * **Rapid Prototyping:** Simple, declarative format for PV definitions.
19
+ * **LLM-Friendly:** Highly predictable boilerplate that allows AI code assistants to write drivers effortlessly.
20
+ * **OPI Integration:** Automated operator interface generation for Phoebus.
21
+
22
+ ---
23
+
24
+ ## Getting Started
25
+
26
+ ### 1. Generate a PVAccess Server
27
+ Follow the [Detailed Server Generation Guide](docs/generate_server.md) to bootstrap a functional PVAccess server supporting your instrument's core functions.
28
+
29
+ ### 2. Generate an OPI Display
30
+ You can automatically create an operator interface (OPI) layout using [phoebusgen](https://als-epics.github.io/phoebusgen/). See the [OPI Generation Instructions](docs/generate_opi.md) for details.
31
+
32
+ ### 3. Quick Test (Simulation Mode)
33
+ To see the framework in action without physical hardware, you can launch a simulated multi-channel waveform generator, which can be useful for stress-testing EPICS installations. The following command generates 100 noisy waveforms (1,000 points each) alongside 300 scalar parameters:
34
+
35
+ ```bash
36
+ python -m epicsdev.multiadc -C 100 -n 1000
37
+ ```
38
+ To change the data publication frequency, modify the `sleep` PV: `pvput multiadc:0:sleep .1`.
39
+
40
+ #### Quick GUI
41
+ To control and plot the server's PVs, you can use the `pypeto` and `pvplot` modules.
42
+
43
+ ```bash
44
+ pip install pypeto pvplot
45
+ python -m pypeto -f config/multiadc_pp
46
+ ```
47
+
48
+ Other examples include a single-waveform generator and a multi-peak image generator:
49
+ ```bash
50
+ python -m epicsdev.epicsdev
51
+ python -m epicsdev.imagegen
52
+ ```
53
+ See [imagegen usage](docs/imagegenUsage.md) for more details.
54
+
55
+ ### 4. Continuous Integration
56
+ To package `epicsdev`-based PVAccess servers as standalone Linux executables in your build pipeline, see the [Continuous Integration Guide](docs/epicsdev_continuous_integration.md) for PyInstaller build instructions and dependency requirements.
57
+
58
+ ## Fully Functional PVAccess Servers Developed Using epicsdev
59
+
60
+ Power Supplies
61
+ * [CAEN FAST-PS](https://github.com/eicorg/epicsdev_ps_caen_fastps)
62
+ * [CAEN EASY-DRIVER](https://github.com/eicorg/epicsdev_ps_caen_easydriver)
63
+
64
+ Oscilloscopes
65
+ * [Keysight (Agilent) DSO-X series](https://github.com/eicorg/epicsdev_osc_keysight_dsox)
66
+ * [Rigol DHO series](https://github.com/eicorg/epicsdev_osc_rigol)
67
+ * [Tektronix MSO and DPO series](https://github.com/eicorg/epicsdev_osc_tektronix_mso)
68
+ * [LeCroy WaveRunner series](https://github.com/eicorg/epicsdev_osc_lecroy_waverunner)
69
+
70
+ Signal Generators
71
+ * [Siglent SDG series](https://github.com/eicorg/epicsdev_siggen_siglent_sdg)
72
+ * [Keysight 33000 series](https://github.com/eicorg/epicsdev_siggen_keysight_33000)
73
+
74
+ Data Acquisition Instruments
75
+ * [CAEN DT5202](https://github.com/eicorg/epicsdev_daq_caen_dt5202)
76
+ * [NI cDAQ](https://github.com/eicorg/epicsdev_cdaq). Under development
77
+ * [LabJack U3](https://github.com/eicorg/epicsdev_daq_labjack_u3)
78
+
79
+ Magnetometers
80
+ * [Lake Shore Model 421](https://github.com/eicorg/epicsdev_magn_lakeshore)
81
+ * [Caylar NMR20](https://github.com/eicorg/epicsdev_magn_caylar_nmr)
82
+
83
+ Vacuum Gauge Controllers
84
+ * [Granville-Phillips 307 and 358](https://github.com/eicorg/epicsdev_vac)
85
+ * [B-RAX 3000 series](https://github.com/eicorg/epicsdev_vac) from InstruTech
86
+
87
+ Simulation Utilities
88
+ * [Multi-channel Waveform Generator](https://github.com/eicorg/epicsdev/blob/main/epicsdev/multiadc.py)
89
+ * [Multi-peak Image Generator](https://github.com/eicorg/epicsdev/blob/main/epicsdev/imagegen.py)
@@ -1,10 +1,11 @@
1
1
  """Pypet page for epicdev.epicsdev module"""
2
2
  # format: pypeto 1.2+
3
- __version__ = 'v0.0.1 2026-01-16'#
3
+ __version__ = 'v3.3.4 2026-11-12'# updated to match multiadc and epicsdev versions
4
4
  print(f'epicsScope {__version__}')
5
5
 
6
6
  #``````````````````Definitions````````````````````````````````````````````````
7
7
  # python expressions and functions, used in the spreadsheet
8
+ PREFIX = 'epicsDev:0:'
8
9
  _ = ''
9
10
  def span(x,y=1): return {'span':[x,y]}
10
11
  def color(*v): return {'color':v[0]} if len(v)==1 else {'color':list(v)}
@@ -21,16 +22,16 @@ lColor = color('lightGreen')
21
22
 
22
23
  # definition for plotting cell
23
24
  PyPath = 'python -m'
24
- PaneP2P = ' '.join([f'ch{i+1:01d}Mean ch{i+1:01d}Peak2Peak' for i in range(1)])
25
- PaneWF = ' '.join([f'ch{i+1:01d}Waveform' for i in range(1)])
25
+ PaneP2P = ' '.join([f'c{i+1:02d}Mean c{i+1:02d}Peak2Peak' for i in range(1)])
26
+ PaneWF = ' '.join([f'c{i+1:02d}Waveform' for i in range(1)])
26
27
  #PaneT = 'timing[1] timing[3]'
27
28
  Plot = {'Plot':{'launch':
28
- f'{PyPath} pvplot Y-5:5 -aV:epicsDev0: -#0"{PaneP2P}" -#1"{PaneWF}"',# -#2"{PaneT}"',
29
+ f'{PyPath} pvplot Y-5:5 -aV:{PREFIX} -#0"{PaneP2P}" -#1"{PaneWF}"',# -#2"{PaneT}"',
29
30
  **lColor, **ButtonFont}}
30
31
  print(f'Plot command: {Plot}')
31
32
  #``````````````````PyPage Object``````````````````````````````````````````````
32
33
  class PyPage():
33
- def __init__(self, instance='epicsDev0:',
34
+ def __init__(self, instance=PREFIX,
34
35
  title="Simulated oscilloscope", channels=1):
35
36
  """instance: unique name of the page.
36
37
  For EPICS it is usually device prefix
@@ -69,14 +70,14 @@ string or device:parameter and the value is dictionary of the features.
69
70
 
70
71
  #``````````Abbreviations, used in cell definitions
71
72
  def ChLine(suffix):
72
- return [f'{D}ch{ch+1:01d}{suffix}' for ch in range(channels)]
73
+ return [f'{D}c{ch+1:02d}{suffix}' for ch in range(channels)]
73
74
  #FOption = ' -file '+logreqMap.get(D,'')
74
75
  #``````````mandatory member```````````````````````````````````````````
75
76
  self.rows = [
76
- ['Device:', D, {D+'version':span(2,1)},_,_,_,_],
77
+ ['Device:', D, {D+'VERSION':span(2,1)},_,_,_,_],
77
78
  ['State:', D+'server','cycle:',D+'cycle',_,_,Plot], # 'Recall:', D+'setup',],
78
79
  ['Status:', {D+'status': span(8,1)}],
79
- ['Polling Interval:', D+'polling','nPoints:',D+'recordLength',
80
+ ['Sleep interval:', D+'sleep','nPoints:',D+'recordLength',
80
81
  'Noise:',D+'noiseLevel',_],
81
82
  [{'ATTRIBUTES':color('lightCyan')},
82
83
  'Channels:','CH1','CH2','CH3','CH4','CH5','CH6'],
@@ -1,12 +1,13 @@
1
1
  """Pypet page for epicdev.epicsdev module"""
2
2
  # pylint: disable=invalid-name
3
3
  # format: pypeto 1.2+
4
- __version__ = 'v0.0.2 2026-01-28'# corrected the Plot action
4
+ __version__ = 'v3.3.4 2026-11-12'# corrected naming convention for version
5
5
  print(f'multiadc {__version__}')
6
6
 
7
7
  #``````````````````Definitions````````````````````````````````````````````````
8
8
  # python expressions and functions, used in the spreadsheet
9
9
  _ = ''
10
+ PREFIX = 'multiadc:0:'
10
11
  def span(x,y=1): return {'span':[x,y]}
11
12
  def color(*v): return {'color':v[0]} if len(v)==1 else {'color':list(v)}
12
13
  def font(size): return {'font':['Arial',size]}
@@ -26,12 +27,12 @@ PaneP2P = ' '.join([f'c{i+1:02d}Mean c{i+1:02d}Peak2Peak' for i in range(1)])
26
27
  PaneWF = ' '.join([f'c{i+1:02d}Waveform' for i in range(1)])
27
28
  #PaneT = 'timing[1] timing[3]'
28
29
  Plot = {'Plot':{'launch':
29
- f'{PyPath} pvplot Y-5:5 -aV:multiadc0: -#0"{PaneP2P}" -#1"{PaneWF}"',# -#2"{PaneT}"',
30
+ f'{PyPath} pvplot Y-5:5 -aV:{PREFIX} -#0"{PaneP2P}" -#1"{PaneWF}"',# -#2"{PaneT}"',
30
31
  **lColor, **ButtonFont}}
31
32
  print(f'Plot command: {Plot}')
32
33
  #``````````````````PyPage Object``````````````````````````````````````````````
33
34
  class PyPage():
34
- def __init__(self, instance='multiadc0:',
35
+ def __init__(self, instance=PREFIX,
35
36
  title="Simulated oscilloscope", channels=6):
36
37
  """instance: unique name of the page.
37
38
  For EPICS it is usually device prefix
@@ -74,10 +75,10 @@ string or device:parameter and the value is dictionary of the features.
74
75
  #FOption = ' -file '+logreqMap.get(D,'')
75
76
  #``````````mandatory member```````````````````````````````````````````
76
77
  self.rows = [
77
- ['Device:', D, {D+'version':span(2,1)},_,_,_,_],
78
+ ['Device:', D, {D+'VERSION':span(2,1)},_,_,_,_],
78
79
  ['State:', D+'server','cycle:',D+'cycle',_,_,Plot], # 'Recall:', D+'setup',],
79
80
  ['Status:', {D+'status': span(8,1)}],
80
- ['Polling Interval:', D+'polling','nPoints:',D+'recordLength',
81
+ ['Sleep interval:', D+'sleep','nPoints:',D+'recordLength',
81
82
  'Noise:',D+'noiseLevel',_],
82
83
  [{'ATTRIBUTES':color('lightCyan')},
83
84
  'Channels:','CH1','CH2','CH3','CH4','CH5','CH6'],
@@ -0,0 +1,286 @@
1
+ # Building standalone executables for epicsdev PVAccess servers
2
+
3
+ An epicsdev-based Python PVAccess server can be packaged as a standalone
4
+ Linux executable with **PyInstaller**. The executable bundles the Python
5
+ interpreter, Python dependencies, and EPICS/PVXS shared libraries. The target
6
+ machine does not need Python, `uv`, or an activated virtual environment.
7
+
8
+ This procedure was verified with the vacuum-controller server
9
+ [epicsdev_vac](../epicsdev_vac/README.md). Adapt the package name and
10
+ device-specific dependencies when building another server.
11
+
12
+ ## 1. Prepare the project
13
+
14
+ Build from the project directory containing `pyproject.toml`. The server must
15
+ already run successfully from its Python environment, and its runtime
16
+ dependencies must be declared in that file.
17
+
18
+ For the vacuum-controller example, the runtime dependencies are:
19
+
20
+ ```toml
21
+ [project]
22
+ name = "epicsdev_vac"
23
+ version = "0.0.3"
24
+ requires-python = ">=3.11"
25
+ dependencies = [
26
+ "epicsdev>=3.3.3",
27
+ "pyvisa>=1.14",
28
+ "pyvisa-py>=0.7",
29
+ ]
30
+ ```
31
+
32
+ Add an optional dependency group for executable builds:
33
+
34
+ ```toml
35
+ [project.optional-dependencies]
36
+ binary = [
37
+ "pyinstaller>=6.16,<7",
38
+ "pyserial>=3.5",
39
+ ]
40
+ ```
41
+
42
+ PySerial is included here because this executable supports direct serial
43
+ connections through PyVISA-py. It is not required by every epicsdev server.
44
+ If serial support is required in the normal Python installation too, declare
45
+ PySerial as a runtime dependency instead.
46
+
47
+ Install `uv` and `make` on the build machine, then install the build environment:
48
+
49
+ ```sh
50
+ uv sync --extra binary
51
+ ```
52
+
53
+ Use a project-local environment rather than installing PyInstaller into an
54
+ unrelated system environment. `uv run --extra binary` below uses the same
55
+ project environment and includes the build dependencies.
56
+
57
+ ## 2. Select the entry point
58
+
59
+ Use the Python file that starts the server. For this example it is
60
+ `epicsdev_vac/__main__.py`, which calls `main()` under this guard:
61
+
62
+ ```python
63
+ if __name__ == '__main__':
64
+ main()
65
+ ```
66
+
67
+ PyInstaller executes this file as a script. If another server's entry module
68
+ uses package-relative imports, use a small launcher at the project root
69
+ instead, so the entry module is imported within its package:
70
+
71
+ ```python
72
+ from your_server_package.__main__ import main
73
+
74
+ if __name__ == '__main__':
75
+ main()
76
+ ```
77
+
78
+ Pass the launcher filename to PyInstaller in place of the package's
79
+ `__main__.py`. Adapt this launcher if the server exposes a differently named
80
+ startup function. Do not duplicate the server implementation in the launcher.
81
+
82
+ ## 3. Build the executable
83
+
84
+ The following command builds the vacuum-controller server:
85
+
86
+ ```sh
87
+ uv run --extra binary pyinstaller --noconfirm --clean --onefile \
88
+ --name epicsdev_vac \
89
+ --collect-all pyvisa_py \
90
+ --copy-metadata pyvisa-py \
91
+ --hidden-import serial \
92
+ --collect-binaries epicscorelibs \
93
+ --collect-submodules epicscorelibs.lib \
94
+ --collect-binaries pvxslibs \
95
+ --collect-submodules pvxslibs.lib \
96
+ epicsdev_vac/__main__.py
97
+ ```
98
+
99
+ For another epicsdev server, replace `epicsdev_vac` in `--name` and the entry
100
+ point path. Keep the EPICS/PVXS collection options. Include only the
101
+ device-specific collection options needed by that server.
102
+
103
+ ### Why these options are needed
104
+
105
+ | Option | Purpose |
106
+ | --- | --- |
107
+ | `--onefile` | Produce one executable rather than a directory of runtime files. |
108
+ | `--name epicsdev_vac` | Set the output filename. |
109
+ | `--noconfirm` | Allow replacement of generated output without an interactive prompt. |
110
+ | `--clean` | Clear PyInstaller caches and temporary build files before building. |
111
+ | `--collect-binaries epicscorelibs` | Bundle the EPICS native shared libraries. |
112
+ | `--collect-submodules epicscorelibs.lib` | Include dynamically imported EPICS library metadata modules. |
113
+ | `--collect-binaries pvxslibs` | Bundle the PVXS native shared libraries used by p4p. |
114
+ | `--collect-submodules pvxslibs.lib` | Include dynamically imported PVXS library metadata modules. |
115
+ | `--collect-all pyvisa_py` | Include the pure-Python VISA backend and its dynamically selected modules. |
116
+ | `--copy-metadata pyvisa-py` | Preserve the backend's distribution metadata for runtime version lookup. |
117
+ | `--hidden-import serial` | Include PySerial for direct serial resources. |
118
+
119
+ The EPICS metadata options are important: collecting shared libraries alone
120
+ is insufficient. An initial build without these submodules failed at startup
121
+ with:
122
+
123
+ ```text
124
+ ModuleNotFoundError: No module named 'epicscorelibs.lib.ca_dsoinfo'
125
+ ```
126
+
127
+ The metadata modules allow `setuptools_dso` to resolve the bundled native
128
+ libraries. Keep the analogous PVXS metadata modules as well.
129
+
130
+ Servers that do not use PyVISA can omit the three VISA/serial options and the
131
+ corresponding dependencies. Other dynamically loaded device backends may need
132
+ their own hidden imports, package data, or shared-library collection options.
133
+ Validate their actual runtime path; a successful build alone does not prove
134
+ that every backend has been bundled.
135
+
136
+ ### Repeatable Makefile target
137
+
138
+ The verified project contains this
139
+ [Makefile](../epicsdev_vac/Makefile):
140
+
141
+ ```makefile
142
+ .PHONY: executable
143
+
144
+ executable:
145
+ uv sync --extra binary
146
+ uv run --extra binary pyinstaller --noconfirm --clean --onefile \
147
+ --name epicsdev_vac \
148
+ --collect-all pyvisa_py \
149
+ --copy-metadata pyvisa-py \
150
+ --hidden-import serial \
151
+ --collect-binaries epicscorelibs \
152
+ --collect-submodules epicscorelibs.lib \
153
+ --collect-binaries pvxslibs \
154
+ --collect-submodules pvxslibs.lib \
155
+ epicsdev_vac/__main__.py
156
+ ```
157
+
158
+ Recipe lines must begin with a literal tab. Build from the project root:
159
+
160
+ ```sh
161
+ make executable
162
+ ```
163
+
164
+ PyInstaller writes:
165
+
166
+ - `dist/epicsdev_vac`: the deployable executable.
167
+ - `build/`: intermediate analysis and build output.
168
+ - `epicsdev_vac.spec`: the generated build specification.
169
+
170
+ Only the executable is needed on the target for this one-file build.
171
+ Keep generated output out of source control. The vacuum project already
172
+ ignores `dist/`, `build/`, and generated `*.spec` files. If a project instead
173
+ maintains a customized specification as its build definition, track that
174
+ specific file deliberately.
175
+
176
+ ## 4. Verify the bundled runtime
177
+
178
+ First check that imports and argument parsing work:
179
+
180
+ ```sh
181
+ ./dist/epicsdev_vac --help
182
+ ```
183
+
184
+ This is a startup smoke test, not a test of hardware communication or
185
+ PVAccess publication. Follow it with a simulator-based integration test that
186
+ starts the **executable**, rather than importing the source module.
187
+
188
+ The vacuum project provides an opt-in
189
+ [executable integration test](../epicsdev_vac/tests/test_executable.py):
190
+
191
+ ```sh
192
+ EPICSDEV_VAC_EXECUTABLE="$PWD/dist/epicsdev_vac" \
193
+ uv run --extra binary python -m unittest discover \
194
+ -s tests -p test_executable.py -v
195
+ ```
196
+
197
+ The test verifies all three supported models (`BRAX_3000`, `GP307`, and
198
+ `GP358`) against local TCP controller simulators. It checks connection health,
199
+ pressure and relay readback through a PVAccess client, and clean shutdown.
200
+ The executable runs from a temporary working directory with `PYTHONPATH`,
201
+ `PYTHONHOME`, and `LD_LIBRARY_PATH` removed, and without the virtual environment
202
+ on `PATH`. Python is needed to run the test harness, not the executable itself.
203
+
204
+ For another server, provide an equivalent test for its transport and
205
+ published PVs. Exercise each backend included in the executable. For serial
206
+ servers, a pseudo-terminal simulator can verify serial opening and protocol
207
+ framing without connecting to real equipment.
208
+
209
+ The vacuum build was also checked against a pseudo-terminal: its bundled
210
+ serial backend opened the ASRL resource and sent the expected native firmware
211
+ query, `# VER\r`.
212
+
213
+ Do not launch the server with its default resource merely to test packaging.
214
+ Without `--help`, it starts the PVAccess server and polls the configured
215
+ controller. Use explicit simulator resources during validation.
216
+
217
+ ## 5. Deploy and run
218
+
219
+ Copy `dist/epicsdev_vac` to the target Linux machine and preserve its executable
220
+ permission. It accepts the same arguments as the original module:
221
+
222
+ ```sh
223
+ ./epicsdev_vac --resource TCPIP0::192.168.27.10::2103::SOCKET --autosave
224
+ ```
225
+
226
+ Replace the address and port with the intended controller or gateway.
227
+ In this server, bare `--autosave` disables caching. To retain cached PV
228
+ values, pass a writable directory instead:
229
+
230
+ ```sh
231
+ ./epicsdev_vac --resource TCPIP0::192.168.27.10::2103::SOCKET \
232
+ --autosave /path/to/writable/cache
233
+ ```
234
+
235
+ Packaging does not change the server's arguments, PV definitions, control
236
+ semantics, or hardware-safety requirements. External configuration, caches,
237
+ operator displays, and device permissions still need to be managed separately.
238
+
239
+ ### Platform constraints
240
+
241
+ - Build on Linux for Linux deployment; this is not a cross-platform build.
242
+ - Match the target CPU architecture. The verified build is Linux x86-64.
243
+ - Build on a Linux distribution with glibc compatible with the target.
244
+ Building on the oldest supported distribution is generally preferable:
245
+ a newer build may require symbols unavailable on an older machine.
246
+ - System libraries such as glibc are not bundled. Test on the intended target
247
+ distribution before deployment.
248
+ - One-file executables extract their runtime to a temporary directory.
249
+ That directory must be writable and permit loading shared libraries.
250
+ If the default temporary filesystem is unsuitable, set `TMPDIR` to an
251
+ appropriate directory before launching.
252
+ - Network access, firewall rules, and serial-device permissions still apply.
253
+ - Retain required third-party license notices when distributing the bundle.
254
+
255
+ The verified vacuum executable was approximately 43 MB. Size depends on the
256
+ Python version, dependency versions, and collection options.
257
+
258
+ ## Continuous-integration use
259
+
260
+ Use the same build and simulator checks in CI. To keep dependencies stable,
261
+ generate and track `uv.lock` after updating the manifest. A CI runner can then
262
+ use the lock file without updating dependency resolution:
263
+
264
+ ```sh
265
+ uv sync --frozen --extra binary
266
+ uv run --frozen --extra binary pyinstaller --noconfirm --clean --onefile \
267
+ --name epicsdev_vac \
268
+ --collect-all pyvisa_py \
269
+ --copy-metadata pyvisa-py \
270
+ --hidden-import serial \
271
+ --collect-binaries epicscorelibs \
272
+ --collect-submodules epicscorelibs.lib \
273
+ --collect-binaries pvxslibs \
274
+ --collect-submodules pvxslibs.lib \
275
+ epicsdev_vac/__main__.py
276
+ ./dist/epicsdev_vac --help
277
+ EPICSDEV_VAC_EXECUTABLE="$PWD/dist/epicsdev_vac" \
278
+ uv run --frozen --extra binary python -m unittest discover \
279
+ -s tests -p test_executable.py -v
280
+ ```
281
+
282
+ Update the lock file intentionally when dependencies change; `--frozen`
283
+ assumes it already matches the intended manifest. Retain the executable as
284
+ the release artifact only after validation succeeds. Label artifacts with
285
+ the server version, operating system, and architecture, and record the build
286
+ environment so compatibility can be assessed later.
@@ -0,0 +1,15 @@
1
+ ## Generate the Operator Interface (OPI)
2
+
3
+ Copy this [OPI generator template](https://github.com/eicorg/epicsdev/blob/main/docs/generate_opi.py) to:
4
+
5
+ ```text
6
+ opi/generate_opi.py
7
+ ```
8
+
9
+ Then prompt an AI agent such as GitHub Copilot:
10
+
11
+ ```text
12
+ Modify opi/generate_opi.py to generate an OPI for the PVs defined in my_server/__main__.py.
13
+ ```
14
+
15
+ Include any display-specific requirements in the prompt, such as the desired layout, grouping of controls and readbacks, plots, alarms, or status indicators.
@@ -0,0 +1,76 @@
1
+ """Operator interface generator for template"""
2
+ __version__ = 'v0.0.1 2026-10-01'
3
+ # pylint: disable=invalid-name,broad-exception-caught
4
+
5
+ import argparse
6
+ from pathlib import Path
7
+
8
+ import phoebusgen.screen
9
+ import phoebusgen.widget
10
+
11
+ DEVICE = "template"
12
+ INSTANCE = "0"
13
+ TITLE = DEVICE+INSTANCE
14
+ PREFIX = f'pva://{DEVICE}:{INSTANCE}:'
15
+
16
+ def _parse_args() -> argparse.Namespace:
17
+ parser = argparse.ArgumentParser(
18
+ description=__doc__,
19
+ formatter_class=argparse.ArgumentDefaultsHelpFormatter,
20
+ epilog=__version__,
21
+ )
22
+ parser.add_argument("-t", "--title", default=TITLE, help="Screen title")
23
+ parser.add_argument("prefix", nargs="?", default=PREFIX,
24
+ help=(
25
+ "PV prefix used for all widget PV names. "
26
+ ),
27
+ )
28
+ return parser.parse_args()
29
+
30
+ def _add_items(widget, values: str) -> None:
31
+ for item in values.split(", "):
32
+ widget.item(item)
33
+
34
+ def main() -> None:
35
+ pargs = _parse_args()
36
+ prefix = pargs.prefix
37
+
38
+ screen = phoebusgen.screen.Screen(pargs.title, f"{TITLE}.bob")
39
+ screen.width(1080)
40
+ screen.height(660)
41
+
42
+ w = phoebusgen.widget
43
+ widgets = {
44
+ "title": w.Label("title", TITLE, 20, 10, 170, 30),
45
+ "Model_lbl": w.Label("Model_lbl", "Model:", 200, 14, 40, 20),
46
+ "Model": w.TextUpdate("Model", f"{prefix}Model", 245, 14, 80, 20),
47
+ "Version_lbl": w.Label("Version_lbl", "FW:", 340, 14, 25, 20),
48
+ "Version": w.TextUpdate("Version", f"{prefix}Version", 365, 14, 40, 20),
49
+ "dateTime": w.TextUpdate("dateTime", f"{prefix}dateTime", 420, 14, 70, 20),
50
+ }
51
+ y = 45
52
+ widgets.update({
53
+ "srvStatus_lbl": w.Label("srvStatus_lbl", "Server:", 20, y, 100, 20),
54
+ "srvStatus": w.TextUpdate("srvStatus", f"{prefix}status", 70, y, 790, 20),
55
+ })
56
+ y += 40
57
+ widgets.update({
58
+ "state_lbl": w.Label("state_lbl", "Run/Stop:", 20, y, 65, 20),
59
+ "server": w.ComboBox("server", f"{prefix}server", 90, y, 110, 20),
60
+ "sleep_lbl": w.Label("sleep_lbl", "Sleep:", 410, y, 40, 20),
61
+ "sleep": w.TextEntry("sleep", f"{prefix}sleep", 450, y, 50, 20),
62
+ "cycleTime_lbl": w.Label("cycleTime_lbl", "Period:", 510, y, 50, 20),
63
+ "cycleTime": w.TextUpdate("cycleTime", f"{prefix}cycleTime", 560, y, 60, 20),
64
+ "hb_lbl": w.Label("hb_lbl", "HB:", 640, y, 30, 20),
65
+ "HEARTBEAT": w.TextUpdate("HEARTBEAT", f"{prefix}HEARTBEAT", 670, y, 70, 20),
66
+ })
67
+
68
+ # TODO: add device widgets
69
+
70
+ screen.add_widget(list(widgets.values()))
71
+
72
+ out = Path(__file__).with_name(f"{TITLE}.bob")
73
+ screen.write_screen(str(out))
74
+
75
+ if __name__ == "__main__":
76
+ main()