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.
- {epicsdev-3.3.3 → epicsdev-3.3.4}/PKG-INFO +29 -11
- {epicsdev-3.3.3 → epicsdev-3.3.4}/README.md +28 -10
- {epicsdev-3.3.3 → epicsdev-3.3.4}/config/epicsdev_pp.py +9 -8
- {epicsdev-3.3.3 → epicsdev-3.3.4}/config/multiadc_pp.py +6 -5
- epicsdev-3.3.4/docs/epicsdev_continuous_integration.md +286 -0
- {epicsdev-3.3.3 → epicsdev-3.3.4}/docs/generate_server.md +18 -1
- epicsdev-3.3.4/docs/imagegenUsage.md +120 -0
- {epicsdev-3.3.3 → epicsdev-3.3.4}/docs/template.py +2 -2
- {epicsdev-3.3.3 → epicsdev-3.3.4}/epicsdev/epicsdev.py +20 -15
- epicsdev-3.3.4/epicsdev/imagegen.py +254 -0
- {epicsdev-3.3.3 → epicsdev-3.3.4}/epicsdev/multiadc.py +41 -25
- {epicsdev-3.3.3 → epicsdev-3.3.4}/pyproject.toml +1 -1
- epicsdev-3.3.4/uv.lock +417 -0
- epicsdev-3.3.3/epicsdev/imagegen.py +0 -202
- {epicsdev-3.3.3 → epicsdev-3.3.4}/LICENSE +0 -0
- {epicsdev-3.3.3 → epicsdev-3.3.4}/docs/generate_opi.md +0 -0
- {epicsdev-3.3.3 → epicsdev-3.3.4}/docs/generate_opi.py +0 -0
- {epicsdev-3.3.3 → epicsdev-3.3.4}/epicsdev/README.md +0 -0
- {epicsdev-3.3.3 → epicsdev-3.3.4}/epicsdev/__init__.py +0 -0
- {epicsdev-3.3.3 → epicsdev-3.3.4}/epicsdev/putlog.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: epicsdev
|
|
3
|
-
Version: 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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
##
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
##
|
|
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
|
|
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__ = '
|
|
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'
|
|
25
|
-
PaneWF = ' '.join([f'
|
|
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:
|
|
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=
|
|
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}
|
|
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+'
|
|
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
|
-
['
|
|
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__ = '
|
|
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:
|
|
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=
|
|
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+'
|
|
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
|
-
['
|
|
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
|
-
###
|
|
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
|
|