epicsdev 3.3.3__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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: epicsdev
3
- Version: 3.3.3
3
+ Version: 3.3.4
4
4
  Summary: Helper module for creating EPICS PVAccess servers using p4p
5
5
  Project-URL: Homepage, https://github.com/eicorg/epicsdev
6
6
  Project-URL: Bug Tracker, https://github.com/eicorg/epicsdev
@@ -16,9 +16,9 @@ Description-Content-Type: text/markdown
16
16
 
17
17
  # epicsdev
18
18
 
19
- `epicsdev` is a Python framework designed for rapidly developing EPICS PVAccess servers utilizing the [p4p](https://github.com/epics-base/p4p) library.
19
+ `epicsdev` is a Python framework designed for rapidly developing EPICS PVAccess servers using the [p4p](https://github.com/epics-base/p4p) library.
20
20
 
21
- Device Process Variables (PVs) are defined using a highly compact format:
21
+ Device process variables (PVs) are defined using a compact format:
22
22
  ```python
23
23
  [name, description, initial_value, attributes]
24
24
  ```
@@ -29,8 +29,9 @@ Device-specific logic resides within a small, well-structured Python file follow
29
29
 
30
30
  ## Key Features
31
31
 
32
+ * **High-Bandwidth Data Streaming:** Minimizes packet overhead and uses the optimized p4p bindings to move complex data structures directly.
32
33
  * **Built-in Services:** Out-of-the-box support for autosave/restore, IocStats, heartbeat monitoring, and PV-put logging.
33
- * **Rapid Prototyping:** Simple, declarative tuple structure for PV definitions.
34
+ * **Rapid Prototyping:** Simple, declarative format for PV definitions.
34
35
  * **LLM-Friendly:** Highly predictable boilerplate that allows AI code assistants to write drivers effortlessly.
35
36
  * **OPI Integration:** Automated operator interface generation for Phoebus.
36
37
 
@@ -39,26 +40,38 @@ Device-specific logic resides within a small, well-structured Python file follow
39
40
  ## Getting Started
40
41
 
41
42
  ### 1. Generate a PVAccess Server
42
- Follow the [Detailed Server Generation Guide](docs/generate_server.md) to bootstrap a functional PVAccess server supporting your instrument's core functions.
43
+ Follow the [Detailed Server Generation Guide](docs/generate_server.md) to bootstrap a functional PVAccess server supporting your instrument's core functions.
43
44
 
44
45
  ### 2. Generate an OPI Display
45
- 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.
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.
46
47
 
47
48
  ### 3. Quick Test (Simulation Mode)
48
- 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 of EPICS installations. The following command generates 100 noisy waveforms (1,000 points each) alongside 300 scalar parameters:
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:
49
50
 
50
51
  ```bash
51
52
  python -m epicsdev.multiadc -C 100 -n 1000
52
53
  ```
54
+ To change the data publication frequency, modify the `sleep` PV: `pvput multiadc:0:sleep .1`.
53
55
 
54
- Other examples to run: single waveform generator and multi-peak image generator
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:
55
65
  ```bash
56
66
  python -m epicsdev.epicsdev
57
67
  python -m epicsdev.imagegen
58
68
  ```
59
- ---
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.
60
73
 
61
- ## List of fully functional PVAccess servers, developed using epicsdev
74
+ ## Fully Functional PVAccess Servers Developed Using epicsdev
62
75
 
63
76
  Power Supplies
64
77
  * [CAEN FAST-PS](https://github.com/eicorg/epicsdev_ps_caen_fastps)
@@ -74,14 +87,19 @@ Signal Generators
74
87
  * [Siglent SDG series](https://github.com/eicorg/epicsdev_siggen_siglent_sdg)
75
88
  * [Keysight 33000 series](https://github.com/eicorg/epicsdev_siggen_keysight_33000)
76
89
 
77
- Data Acquisition instruments
90
+ Data Acquisition Instruments
78
91
  * [CAEN DT5202](https://github.com/eicorg/epicsdev_daq_caen_dt5202)
92
+ * [NI cDAQ](https://github.com/eicorg/epicsdev_cdaq). Under development
79
93
  * [LabJack U3](https://github.com/eicorg/epicsdev_daq_labjack_u3)
80
94
 
81
95
  Magnetometers
82
96
  * [Lake Shore Model 421](https://github.com/eicorg/epicsdev_magn_lakeshore)
83
97
  * [Caylar NMR20](https://github.com/eicorg/epicsdev_magn_caylar_nmr)
84
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
+
85
103
  Simulation Utilities
86
104
  * [Multi-channel Waveform Generator](https://github.com/eicorg/epicsdev/blob/main/epicsdev/multiadc.py)
87
105
  * [Multi-peak Image Generator](https://github.com/eicorg/epicsdev/blob/main/epicsdev/imagegen.py)
@@ -1,8 +1,8 @@
1
1
  # epicsdev
2
2
 
3
- `epicsdev` is a Python framework designed for rapidly developing EPICS PVAccess servers utilizing the [p4p](https://github.com/epics-base/p4p) library.
3
+ `epicsdev` is a Python framework designed for rapidly developing EPICS PVAccess servers using the [p4p](https://github.com/epics-base/p4p) library.
4
4
 
5
- Device Process Variables (PVs) are defined using a highly compact format:
5
+ Device process variables (PVs) are defined using a compact format:
6
6
  ```python
7
7
  [name, description, initial_value, attributes]
8
8
  ```
@@ -13,8 +13,9 @@ Device-specific logic resides within a small, well-structured Python file follow
13
13
 
14
14
  ## Key Features
15
15
 
16
+ * **High-Bandwidth Data Streaming:** Minimizes packet overhead and uses the optimized p4p bindings to move complex data structures directly.
16
17
  * **Built-in Services:** Out-of-the-box support for autosave/restore, IocStats, heartbeat monitoring, and PV-put logging.
17
- * **Rapid Prototyping:** Simple, declarative tuple structure for PV definitions.
18
+ * **Rapid Prototyping:** Simple, declarative format for PV definitions.
18
19
  * **LLM-Friendly:** Highly predictable boilerplate that allows AI code assistants to write drivers effortlessly.
19
20
  * **OPI Integration:** Automated operator interface generation for Phoebus.
20
21
 
@@ -23,26 +24,38 @@ Device-specific logic resides within a small, well-structured Python file follow
23
24
  ## Getting Started
24
25
 
25
26
  ### 1. Generate a PVAccess Server
26
- Follow the [Detailed Server Generation Guide](docs/generate_server.md) to bootstrap a functional PVAccess server supporting your instrument's core functions.
27
+ Follow the [Detailed Server Generation Guide](docs/generate_server.md) to bootstrap a functional PVAccess server supporting your instrument's core functions.
27
28
 
28
29
  ### 2. Generate an OPI Display
29
- 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.
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.
30
31
 
31
32
  ### 3. Quick Test (Simulation Mode)
32
- 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 of EPICS installations. The following command generates 100 noisy waveforms (1,000 points each) alongside 300 scalar parameters:
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:
33
34
 
34
35
  ```bash
35
36
  python -m epicsdev.multiadc -C 100 -n 1000
36
37
  ```
38
+ To change the data publication frequency, modify the `sleep` PV: `pvput multiadc:0:sleep .1`.
37
39
 
38
- Other examples to run: single waveform generator and multi-peak image generator
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:
39
49
  ```bash
40
50
  python -m epicsdev.epicsdev
41
51
  python -m epicsdev.imagegen
42
52
  ```
43
- ---
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.
44
57
 
45
- ## List of fully functional PVAccess servers, developed using epicsdev
58
+ ## Fully Functional PVAccess Servers Developed Using epicsdev
46
59
 
47
60
  Power Supplies
48
61
  * [CAEN FAST-PS](https://github.com/eicorg/epicsdev_ps_caen_fastps)
@@ -58,14 +71,19 @@ Signal Generators
58
71
  * [Siglent SDG series](https://github.com/eicorg/epicsdev_siggen_siglent_sdg)
59
72
  * [Keysight 33000 series](https://github.com/eicorg/epicsdev_siggen_keysight_33000)
60
73
 
61
- Data Acquisition instruments
74
+ Data Acquisition Instruments
62
75
  * [CAEN DT5202](https://github.com/eicorg/epicsdev_daq_caen_dt5202)
76
+ * [NI cDAQ](https://github.com/eicorg/epicsdev_cdaq). Under development
63
77
  * [LabJack U3](https://github.com/eicorg/epicsdev_daq_labjack_u3)
64
78
 
65
79
  Magnetometers
66
80
  * [Lake Shore Model 421](https://github.com/eicorg/epicsdev_magn_lakeshore)
67
81
  * [Caylar NMR20](https://github.com/eicorg/epicsdev_magn_caylar_nmr)
68
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
+
69
87
  Simulation Utilities
70
88
  * [Multi-channel Waveform Generator](https://github.com/eicorg/epicsdev/blob/main/epicsdev/multiadc.py)
71
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.
@@ -17,7 +17,24 @@ Copy the instrument programming manual to: ```misc/programming_manual.pdf```
17
17
 
18
18
  Copy the [server template](https://github.com/eicorg/epicsdev/blob/main/docs/template.py) to: ```my_server/__main__.py ```
19
19
 
20
- ### Use an AI agent
20
+ ### Check if basic functionality is working
21
+ ```bash
22
+ source .venv/bin/activate
23
+ python -m my_server
24
+ ```
25
+ Check from another terminal that the server publishes templated PVs:
26
+ ```bash
27
+ pvmonitor template:0:cycle template:0:cycleTime
28
+ ```
29
+ It should print:
30
+ ```bash
31
+ template:0:cycle 2026-10-15 11:04:08.735 61
32
+ template:0:cycleTime 2026-10-15 11:04:08.735 1.00443
33
+ template:0:cycle 2026-10-15 11:04:18.777 71
34
+ template:0:cycleTime 2026-10-15 11:04:18.778 1.00423
35
+ ...
36
+ ```
37
+ ### Use an AI agent to build the server according to the instrument's programming manual
21
38
 
22
39
  From the project directory, prompt an AI agent such as GitHub Copilot:
23
40