This repository has been archived by the owner on Sep 3, 2022. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathsynApps.html
1905 lines (1560 loc) · 83.2 KB
/
synApps.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<title>synApps</title>
</head>
<body bgcolor="#FFFFFF">
<h1>synApps 6.1</h1>
<h1>Table of Contents</h1>
<ul>
<li><a href="#Introduction">Introduction</a></li>
<li><a href="#Contents">Contents</a></li>
<li><a href="#How to deploy synApps">How to deploy synApps</a></li>
<li><a href="#How to build synApps">How to build synApps</a></li>
<li><a href="#How to make synApps work">How to make synApps work</a></li>
<li><a href="#How to extend synApps">How to extend synApps</a></li>
<li><a href="#The synApps utils directory">The synApps utils directory</a></li>
<li><a href="#Appendix">Appendix</a></li>
</ul>
<a name="Introduction"></a>
<hr><h2>Introduction</h2><hr>
<P>synApps is a collection of <a href=http://www.aps.anl.gov/epics>EPICS</a> software
intended to support most of the common requirements of an x-ray laboratory or
synchrotron-radiation beamline. Because it is EPICS software, synApps is
extensible by developers and end users, to support new devices and experimental
techniques. This extensibility frees synApps to focus mostly on general-purpose
capabilities and infrastructure, from which application-specific software can be
built or assembled.
<blockquote>
<P>Thus, for example, synApps provides support for motors, scalers, and scans,
but it does not tie those items together into an immediately executable scan (of
specific motors, to acquire specific scaler channels, for a specific dwell time,
etc.). The user does this at run time (or a knowledgeable user can provide a
fully specified scan, and give the novice user a button to start it).
<P>Similarly, synApps provides support for ADC's and PID loops, but somebody has
to tell the PID software what feedback value to read, what conditioning function
to run it through, what PID parameters to use, and what actuator to drive. By
default, all of these choices can be made at top level, by the end user. Or, a
knowledgeable user can provide a fully specified PID loop, and make it available
to a novice user through a simplified or otherwise customized interface. The
techniques and tools used to accomplish this are essentially the same as those
a user would have applied at run time, so the packaged solution can be
prototyped and tested at run time.
</blockquote>
<P>synApps is organized into modules, whose structure is based on the example
directory tree produced by the EPICS application, <code>makeBaseApp.pl</code>,
typically with two additional directories: a documentation directory, and a
display-file directory. synApps modules typically contain source code, EPICS
databases and database-definition files, autosave-request files, client scripts,
display files, libraries and executables, and documentation.
<P>Most synApps modules are intended primarily to export support to other modules.
Some synApps modules produce bootable software, in addition to support
software, but in most cases, this bootable software is primarily for testing,
and for demonstrating how the support software can be used. The support
exported by a module is of the following types, with example names and locations
from the <b>calc</b> module:
<blockquote>
<dl>
<dt>database-definition file, in calc/dbd
<dd><code>calcSupport.dbd</code><br>...
<P><dt>link library, in calc/lib/<arch>
<dd><code>libcalc</code>
<P><dt>header files, in calc/include
<dd><code>transformRecord.h</code><br>...
<P><dt>database files, and associated autosave-request files,
in calc/calcApp/Db
<dd><code>userTransforms10.db</code>
<dd><code>userTransforms10_settings.req</code><br>...
<P><dt>display files, in calc/calcApp/op/adl, calc/calcApp/op/ui, and calc/calcApp/op/opi
<dd><code>userTransforms10.adl</code><br>
<code>userTransforms10.ui</code><br>
<code>userTransforms10.opi</code><br>...
</dl>
</blockquote>
One synApps module, the <b>xxx</b> module, is different: it doesn't export
anything. It imports support from other modules, and produces bootable software
to support an EPICS <i>IOC</i>. The <b>xxx</b> module is documentation in
runnable form, and also a template from which a synApps application can be
constructed. <b>xxx</b> is not comprehensive: it doesn't apply all of synApps;
it's usually a little behind the rest of synApps; it focusses more on VME crates
than on other kinds of IOCs; and it's a compromise between what is most widely
used and what is most likely to build and run out of the box.
<blockquote><i>
If you haven't run into the term 'IOC' yet, two things:
<ol>
<li>IOC stands for Input/Output Controller. Initially, this was a VME crate
with a processor running EPICS under the VxWorks operating system, but beginning
with EPICS 3.14, an EPICS IOC can also be a set of tasks on a workstation
running Linux, Windows, Cygwin, Solaris, RTEMS, Mac OS, and, no doubt, other
operating systems.
<li>The
<a href="https://epics.anl.gov/base/R3-15/6-docs/AppDevGuide/AppDevGuide.html">
</i>EPICS Application Developer's Guide<i></a> is an essential reference for
anyone planning to develop or deploy EPICS software. While you won't need to
read the guide to build or run synApps, you will need it to understand what
you've done, to diagnose problems, and to extend synApps in any significant way.
</ol>
</i></blockquote>
<a name="Contents"></a>
<hr><h2>Contents</h2><hr>
<P>Here's a list of the <b>modules</b> and <i>directories</i> in synApps:
<P><table border>
<tr><td><b>Module</b>/<i>directory</i><th><b>description</b>
<tr><td><b>alive</b><td>Support for collecting, maintaining, and displaying
status information about a collection of EPICS IOCs.
<tr><td><b>areaDetector<br>ADcore<br>ADSupport<br>ADSimDetector</br></b><td>Support for cameras and other 2D detectors.
areaDetector consists of some core modules, and many detector-specific
modules; synApps contains only the top-level directory, <i>areaDetector</i>,
and the modules <i>ADCore</i>, <i>ADSupport</i>, and <i>ADSimDetector</i>. See
<a href="https://github.com/areaDetector">areaDetector</a> for more information
<tr><td><b>autosave</b><td>Support for saving software parameters at run time,
and restoring them during the next reboot. Autosave also provides a way to
manage collections of PV values at runtime (<i>configMenu</i>), and a way to
initialize array PV's at boot time.
<tr><td><b>busy</b><td>The busy record, which allows developers more ways to
indicate when an operation is complete.
<tr><td><b>calc</b><td>Run-time expression evaluation, derived from the calcout
record in EPICS base, and extended to operate on strings, arrays, and to
implement coupled expressions.
<tr><td><b>caputRecorder</b><td>Support for recording a series of caputs as a
python function, and replaying the series.
<tr><td><b>camac</b><td>Support for CAMAC hardware.
<tr><td><i>configure</i><td>Build files
<tr><td><b>dac128V</b><td>Support for an IndustryPack DAC module.
<tr><td><b>delaygen</b><td>Support for delay generators, including the SRS
DG645, Colby Instruments PDL100A, and Gigabaudics PADL3.
<tr><td><i>documentation</i><td>Um... documentation
<tr><td><b>dxp</b><td>Support for X-Ray Instrumentation Associates's DXP digital
signal processor
<tr><td><b>dxpSITORO</b><td>Support for XIA SITORO based FalconX spectrometers
<tr><td><b>ip</b><td>Support for various serial, and other message-based,
devices.
<tr></b><td><b>ip330</b><td>Support for an IndustryPack ADC module
<tr><td><b>ipUnidig</b><td>Support for an IndustryPack digital I/O module
<tr><td><b>love</b><td>Support for Love controllers
<tr><td><b>lua</b><td>Support for Lua scripting language features
<tr><td><b>mca</b><td>Support for multichannel analyzers and multichannel
scalers.
<tr><td><b>measComp</b><td>Support for USB I/O modules from <a href="http://www.mccdaq.com">Measurement
Computing</a>
<tr><td><b>modbus</b><td>Support for ModBus-protocol devices over TCP, serial
RTU, and serial ASCII links
<tr><td><b>motor</b><td>Support for motors
<tr><td><b>optics</b><td>Support for optical tables, monochromators, slits, etc.
<tr><td><b>quadEM</b><td>Support for an APS-developed 4-channel electrometer
<tr><td><b>softGlue</b><td>Support for user-programmed "wiring" of custom FPGA
content loaded into an Acromag IP-EP201 module.
<tr><td><b>softGlueZynq</b><td>Support for user-programmed "wiring" of custom FPGA
content loaded into a Xilinx Zynq board.
<tr><td><b>sscan</b><td>Support for scans (programmed control and data
acquisition).
<tr><td><b>std</b><td>Miscellaneous EPICS support, including the epid (extended
PID), scaler, sseq (string sequence), and timestamp records; and pvHistory
support.
<tr><td><b>stream</b><td>Dirk Zimoch's streamDevice, in a module-flavored
wrapper.
<tr><td><i>utils</i><td>Miscellaneous tools, including support for converting an
application from one version of synApps to another; support for the MDA file
format, written by the <b>sscan</b> module; and support for
EPICS-application prototyping.
<tr><td><b>vac</b><td>Support for vacuum controllers
<tr><td><b>vme</b><td>Support for VME hardware
<tr><td><b>xspress3</b><td>Support for Quantum Detectors Xpress3 Hardware
<tr><td><b>xxx</b><td>Sample user-application directory
<tr><td><b>Yokogawa_DAS</b><td>Support for the Yokogawa MW100 Digital Acquisition Unit.
</table>
<P>See support/configure/RELEASE for a complete set of compatible module
versions. This release of synApps is compatible with EPICS 3.15 (and above) releases,
vxWorks 6.9, and the following EPICS modules, which are produced
and maintained by other members of the EPICS collaboration. These modules
are not part of synApps, but their maintainers have permitted us to distribute
copies along with synApps:
<P><table border>
<tr><th>Module<th>description
<tr><td><b>allenBradley</b><td>for communicating with Allen Bradley PLC's (ANL)
<tr><td><b>ipac</b><td>required for IndustryPack support (ANL)
<tr><td><b>asyn</b><td>required by many modules (ANL)
<tr><td><b>seq</b><td>for SNL programs in synApps (BESSY)<br>
source: http://www-csr.bessy.de/control/SoftDist/sequencer
<tr><td><b>stream</b><td>configurable device support for message-based devices (PSI)<br>
source: https://github.com/paulscherrerinstitute/StreamDevice
<tr><td><b>devIocStats</b><td>IOC statistics, replaces vxStats (SLAC)<br>
source: http://www.slac.stanford.edu/grp/cd/soft/epics/site/devIocStats/
</table>
<blockquote>
<P>Previous versions of synApps included and relied on the <b>genSub</b>,
<b>ccd</b>, and <b>pilatus</b> modules. Beginning with EPICS 3.14.10, a
replacement for the genSub record, called the aSub record, is included in base,
and synApps has been modified to use it instead of the genSub record. The
<b>ccd</b> and <b>pilatus</b> modules have been replaced by the
<b>areaDetector</b> module.
</blockquote>
<P>For convenience, this distribution includes the modules listed above,
in place and ready to build, with minor modifications to build files. A few of
the modules have suffered more substantial modifications to fix problems, add
display files, etc.
<P>synApps includes software developed by the Beamline Controls & Data Acquisition, Software
Services, and Accelerator Controls groups of the Advanced Photon Source (APS); by developers in
APS Collaborative Access Teams – notably, Mark Rivers (CARS-CAT); and by developers in
the EPICS collaboration outside of the APS – notably, those at the Diamond Light Source,
the Berliner Elektronenspeicherring-Gesellschaft für Synchrotronstrahlung (BESSY), the Stanford
Linear Accelerator Center (SLAC), the Swiss Light Source (SLS)/Paul Scherrer Institut (PSI),
the National Synchrotron Light Source (NSLS), the Deutsches Elektronen Synchrotron (DESY), the
Spallation Neutron Source (SNS), the Australian Light Source, and the Canadian Light Source.
<P>Aside from EPICS databases, SNL (State Notation Language) programs, and the
like, synApps contains the following code:
<ul>
<li><h3>Record support in or distributed with synApps</h3>
<table border>
<tr><th>Record<th>Description
<tr><td><b>ab*</b><td>AllenBradley-module custom records
<tr><td><b>alive</b><td>Send IOC status to a central server.
<tr><td><b>acalcout</b><td>calcout record extended to handle array expressions
<tr><td><b>asyn</b><td>provide access to nearly all of the features of the
asyn facility
<tr><td><b>busy</b><td>utility record: calls recGblFwdLink only when its
VAL field is zero, allowing CA clients, and asyn drivers to
participate in EPICS putNotify (ca_put_callback()) operations
<tr><td><b>camac</b><td>camac-module custom record
<tr><td><b>digitel</b><td>vac-module custom record
<tr><td><b>epid</b><td>Extended version of the PID record, previously in EPICS base.
Intended for implementing feedback loops
<tr><td><b>luarecord</b><td>Record with scriptable behavior
<tr><td><b>mca</b><td>support for multichannel analyzers, and some other
array-valued detectors
<tr><td><b>motor</b><td>stepper and servo motors, "soft" motor
<tr><td><b>scalcout</b><td>calcout record extended to handle string expressions,
links, and values
<tr><td><b>scaler</b><td>scaler bank
<tr><td><b>sscan</b><td>Replaces the scan record (Ned Arnold/APS) previously in EPICS
base. This version uses a modified version of recDynLlib that supports
dbNotify command completion. It uses ca_put_callback to do puts, instead of
ca_put.
<tr><td><b>scanparm</b><td>scan parameters for use with the scan record
<tr><td><b>sseq</b><td>string-sequence record. This is a modified version of
the seq record in base. This version can link to/from
either string or numeric PVs, and it can use
dbCaPutLinkCallback to wait for completion of the
execution started by one link before going on to the
next.
<tr><td><b>swait</b><td>replaces the wait record previously in EPICS base.
This version uses a modified version of recDynLlib
that supports dbNotify command completion. It uses
ca_put_callback to do puts, instead of ca_put.
<tr><td><b>table</b><td>6-degree-of-freedom optical table
<tr><td><b>transform</b><td>like an array of calc records, with output links
<tr><td><b>vme</b><td>generic vme record (Mark Rivers/APS/CARS-CAT)
<tr><td><b>timestamp</b><td>(written by Stephanie Allison/SLAC) Needed by the vxStats
module, but apparently not available in a published module.
<tr><td><b>vs</b><td>vac-module custom record
</table>
<P><li><h3>Device support in or distributed with synApps</h3>
<P>List appended to this document.
<P><li><h3>Other C code</h3>
<dl>
<dt>aCalcPostfix, aCalcPerform
sCalcPostfix, sCalcPerform
<dd>Support for run-time expression evaluation
<dt>recDynLink
<dd>Backward compatible extension of the dynamic-link software
previously in EPICS base. (New code should probably use
dbCaPutlinkCallback(), instead of recDynLink.)
<dt>autosave (save_restore, dbrestore, configMenu, asVerify, autosaveBuild)
<dd>Automatic parameter save and boot-time restore. Run-time management
of collections of PV values.
<dt>saveData
<dd>Saves scan data to files on an NFS-mounted disk (vxWorks), or to
a local disk (other operating systems).
<dt>luascript
<dd>Support for running scripts to control the value of standard records
</dl>
<P><li><h3>Documentation</h3>
<P>In addition to this top-level documentation, synApps modules have their own
documentation directories, and the <b>xxx</b> module contains examples of how much of the
software is imported, built, loaded, and run. Some modules have their own example iocBoot
directories.
<P><li><h3>Miscellaneous</h3>
<P>The synApps support/utils directory contains a variety of scripts,
programs, etc., that some have found useful. See <a href="#The synApps utils directory">The synApps utils directory</a> for details.
</ul>
<a name="How to deploy synApps"></a>
<hr><h2>How to deploy synApps</h2><hr>
<P>Although synApps is distributed as a single 'support' directory, it's
normally deployed as a two-part system: a 'support' directory, and one or more
'user' directories. The support directory can be installed on a read-only file
system, along with EPICS base and other modules, and used from there by user
directories, each of which typically begins as a copy (or a collection of
copies) of the <b>xxx</b> module, and is customized/extended to suit a
particular application and set of hardware.
<P>I'm not being very precise about what is meant by a user directory, because
there are a number of reasonable variations. At the simplest, a single copy of
the <b>xxx</b> module, which supports a single IOC, is a user directory. If
several IOC's cooperate to serve a single application (such as a synchrotron
beamline), one might make several independent copies of <b>xxx</b>, or one might
extend a single <b>xxx</b> copy to contain multiple xxxApp directories, and
multiple iocBoot/iocxxx directories. At APS, the BCDA group maintains around
100 top-level user directories (for each version of synApps) each of which
contains a number of copies of <b>xxx</b>, and most of which, in turn, contain
multiple xxxApp and iocBoot/iocxxx directories.
<P>Here's what a complete installation might look like (much detail omitted)
with all the files you will have to edit before you can build or boot an IOC:
<P><h4> The support directory</h4>
<pre>
synApps_X_X/support/
Makefile
alive/
allenBradley/
areaDetector/
asyn/
busy/
calc/
camac/
caputRecorder/
configure/
CONFIG
CONFIG_SITE <— EDIT to build
RELEASE <— EDIT to build
EPICS_BASE.<arch> <— EDIT to build for <arch>
Makefile
RELEASE
SUPPORT.<arch> <— EDIT to build for <arch>
...
dac128V/
delaygen/
devIocStats/
documentation/
dxp/
ip/
ip330/
ipUnidig/
ipac/
drvIpac/drvIpac.dbd <— EDIT to build
love/
mca/
measComp/
modbus/
motor/
motorApp/
Makefile <— EDIT to build
optics/
quadEM/
seq/
softGlue/
sscan/
std/
stream/
utils/
vac/
vme/
xxx/
</pre>
<P><h4> The user-directory tree</h4>
<pre>
synApps_X_X/ioc/
1bm/
Makefile
bin/
configure/
CONFIG_SITE <— EDIT to build
RELEASE <— EDIT to build
dbd/
iocBoot/
Makefile
nfsCommands <— EDIT to run
accessSecurity.acf <— EDIT to run
ioc1bma/
Makefile <— EDIT to build
*.cmd
*.req
*.substitutions
autosave/
cdCommands or envPaths
ioc1bmb/
ioc1bmc/
ioc1bmd/
<much like ioc1bma>
release.pl
setup_epics_common <— EDIT to run user interface
start_MEDM_1bma <— EDIT to run user interface
start_MEDM_1bmb <— EDIT to run user interface
start_MEDM_1bmc <— EDIT to run user interface
start_MEDM_1bmd <— EDIT to run user interface
start_putrecorder <— EDIT to use caputRecorder
1bmaApp/
1bmbApp/
1bmcApp/
1bmdApp/
1id/
2bm/
2id/
...
<much like 1bm>
</pre>
<P>As shown above, the following files can or must be edited to modify the way
the synApps support directory is built. After modifying files in the support,
or support/configure directories, you should run <code>make release</code>,
and <code>make rebuild</code>, in the support directory.
<blockquote>
<dl>
<dt><code>support/configure/RELEASE</code>
<dd>Edit the definitions of <code>EPICS_BASE</code> and <code>SUPPORT</code>
with the correct paths to these directories on your system.<br>
Comment out any modules you don't want to build.
<P><dt><code>support/configure/EPICS_BASE.<arch></code>
<dd>If you plan to build on more than one host architecture from a
single synApps directory, and the hosts use different paths to refer to
the same file (for example, Windows and Linux using a shared file
system) then you can override the definition of <code>EPICS_BASE</code>
in the <code>RELEASE</code> file by specifying host-specific paths to
base in separate <code>EPICS_BASE.<arch></code> files. If you
don't have such plans, then you can delete these files, but if they
exist, they must be correct.
<P><dt><code>support/configure/SUPPORT.<arch></code>
<dd>Similar to <code>EPICS_BASE.<arch></code>, but for the synApps
<code>support</code> directory
<P><dt><code>support/configure/CONFIG_SITE</code>
<dd>Edit to set the following variables, which control what will be built:
The supported values for these variables are <code>YES</code> and
<code>NO</code>.
<dl>
<dt><code>LINUX_USB_INSTALLED</code>
<dd>This controls the build of the <b>dxp</b> module. If usb is not
installed for developers, then parts of dxp/dxpApp/handelSrc will not be
built, and the example application executable, dxpApp, will not be
built, so dxp/iocBoot cannot be used.
<dt><code>LINUX_NET_INSTALLED</code>
<dd>This controls the build of the <b>mca</b> module, specifically,
support for the Canberra AIM hardware.
<dt><code>IOCS_APPL_TOP</code>
<dd>Path to application top as seen by IOC. Set this when your IOC and host use
different paths to access the application directory. This will be needed to boot from a
Microsoft FTP server or with some NFS mounts. You must rebuild in the iocBoot directory
for this to take effect.
</dl>
<P><dt><code>support/ipac/<version>/drvIpac/drvIpac.dbd</code>
<dd>uncomment <code>registrar()</code> commands for IndustryPack carriers
you plan to use.
<P><dt><code>support/motor/<version>/motorApp/Makefile</code>
<dd>comment or uncomment to select the motor support you want to build.
</dl>
</blockquote>
<P>The following files must be edited before building a user directory:
<blockquote>
<dl>
<dt><code>ioc/<appname>/configure/RELEASE</code><br>
<dd>edit the definition of <code>SUPPORT</code> with the correct path to
the support directory
<dt><code>ioc/<appname>/iocBoot/<iocname>/Makefile</code><br>
<dd>edit to specify the architecture that is to be built
</dl>
</blockquote>
<P>The following files must be edited before running the user interface:
<blockquote>
<dl>
<dt><code>ioc/setup_epics_common</code><br>
<dd>set the value of Channel Access variables, such as
EPICS_CA_MAX_ARRAY_BYTES.
<dt><code>ioc/start_***_xxx</code><br>
<dd>edit to specify the path to the application and display-file directories,
and the name of the top-level display file.
<dt><code>ioc/start_putrecorder</code><br>
<dd>edit to specify the path to the application and its python directory,
and to specify the ioc prefixe(s) to monitor.
</dl>
</blockquote>
<P>The association between a user directory, and the support directory on which
it depends, is made entirely by the file, configure/RELEASE, in the
user directory. Typically, this file simply includes the
configure/RELEASE file from the support directory, but it may
differ: it may specify EPICS modules not included in synApps, for example. Or,
if the support directory contains more than one built version of a module (the
original and a bug fix, for example) the user directory can choose which
version it will use.
<blockquote><i> Note, however, that the modules in synApps are interdependent.
Many of the modules depend on the <b>asyn</b> module, for example, and there are
many other dependencies, both direct and implied. (If module <b>a</b> depends on
module <b>b</b>, and module <b>b</b> depends on module <b>c</b>, then <b>a</b>
also depends on <b>c</b>, and it must specify the same version of <b>c</b> that
<b>b</b> specifies.) The complete set of modules selected by a user directory
must be self consistent, and the EPICS build will ensure this, unless you tell
it not to, by defining
<pre>CHECK_RELEASE=NO</pre>
or
<pre>CHECK_RELEASE=WARN</pre>
in <code>ioc/configure/CONFIG_SITE</code>.
</i></blockquote>
<P>For completeness, the format of a RELEASE-file path definition is
"<code><name>=<path></code>", where <name> is an arbitrary
string, and <path> is an absolute directory name (starts with '/' on a
unix host, or with a drive name such as 'C:' on Windows). Although <name>
is arbitrary, you should be consistent. Generally, the EPICS build doesn't care
what paths are named, because it's just going to collect them all into a list,
and use the list to search for libraries, .dbd files, etc. But, in the module
consistency check mentioned above, the name does matter, because EPICS can't
check that all modules in a build are using the same version of, say, the asyn
module, unless they all use the same <name> for it. Also, in the xxx
module, <name> is used extensively to find display files (that is, to set
the EPICS_DISPLAY_PATH environment variable), and to specify databases, autosave
request files, etc., when an ioc is booting.
<P>The synApps build imposes an additional constraing on module names. Because
synApps uses EPICS build rules to descend from <code>support</code> into the
modules, module names may not include the character '.'. (The EPICS build rules
expect '.' to be followed by a host or target architecture.)
<a name="How to build synApps"></a>
<hr><h2> How to build synApps</h2><hr>
<ol>
<h3><li>System configuration</h3>
<P>Before building synApps, you should ensure that your system has the
tools, libraries, header files, etc. required to build the modules you want
to build. Here's a list of dependencies we've
documented so far.
<blockquote><i>
Please help: new users are particularly well placed to help us complete this
list. Long-time developers typically have lots of things correctly configured
that they don't even remember configuring.
</i></blockquote>
<ul>
<li>The EPICS extension, <a href="http://www.aps.anl.gov/epics/extensions/msi/index.php">msi</a>,
version 1-5 or higher. If attempting to build with EPICS base 3.14, this tool is needed to
build some softGlue databases, EPICS base 3.15 and above include this as part of base.
<P><li>Linux:
<dl>
<dt>libusb.a, and associated header files<dd>needed for the <b>dxp</b> module
</dl>
<P><li>Cygwin:
<P>Cygwin is configured from a menu of choices organized by function. You will
need the following components from the following menu headings:
<ul>
<li>base
<ul>
<li>All default components
</ul>
<li>devel
<ul>
<li>gcc-core
<li>gcc-g++
<li>libncurses-devel
<li>make
<li>readline
</ul>
<li>interpreters
<ul>
<li>perl
</ul>
<li>libs
<ul>
<li>ncurses
<li>sunrpc (needed for the <b>asyn</b> and <b>sscan</b> modules). In
cygwin 1.7, rpc was replaced by libtirpc: instead of linking with
librpc, you link with libtirpc. EPICS base 3.14.12.1 defines
CYGWIN_RPC_LIB (configure/os/CONFIG.Common.cygwin-x86) to handle this.
</ul>
<li>misc
<ul>
<li>DLPORTIO (needed for the <b>dxp</b> module)
<li>the sequencer (version 2.1) uses re2c, which is not a standard part of
cygwin. You must install re2c version 0.13.3 or higher. This is
available from http://re2c.org/.
</ul>
</ul>
<P><li>Windows:
<dl>
<dt>DLPORTIO<dd>needed for the <b>dxp</b> module
</dl>
</ul>
<P><h3><li>Building and configuring the support directory</h3>
<P>If you have a built copy of EPICS base 3.14.12.4 or later, then building the
synApps support directory should be very simple:
<ol>
<li>Edit support/configure/RELEASE, and support/configure/CONFIG_SITE, as noted
above.
<li>Edit support/configure/EPICS_BASE.<arch>,
support/configure/SUPPORT.<arch>, as noted above, for the architectures you
want to build.
<li>Edit ipac/<version>/drvIpac/drvIpac.dbd, and
motor/<version>/motorApp/Makefile, as noted above.
<li>Set the environment variable <code>EPICS_HOST_ARCH</code> to the
architecture (and compiler, if there is a choice) on which you are building.
synApps is tested with the architectures <code>linux-x86_64</code>,
<code>win32-x86</code>, and <code>win64-x86</code>.
<li>In support, run '<code>make release</code>'. (See note below.)
<li>In support, run '<code>make</code>'. (You should be able to use
'<code>make -j</code>' to build synApps more quickly.)
</ol>
<P>You should use the same GNU Make executable that was used to build EPICS
base. You may need <code>$(EPICS_BASE)/bin/<arch></code> in your path,
and you may need <code>$(EPICS_BASE)/lib/<arch></code> in
<code>LD_LIBRARY_PATH</code>.
<P>When executed in the support directory, '<code>make release</code>' will go
to all of the modules <code>support/Makefile</code> is configured to build, and
edit the <code>configure/RELEASE</code> files in those modules so that they all build from
the same versions of EPICS base and other known modules.
<P>Typically, the build will not succeed the first time, because you will not
have all of the required system support. If you find that you cannot build some
synApps module, you can disable its build by commentng it out of
<code>support/configure/RELEASE</code>.
<P><h3><li>Building and configuring a user directory</h3>
<P>Once synApps' support directory has built without errors, the <b>xxx</b>
module will have been configured (<code>xxx/configure/RELEASE</code> will have
correct, absolute paths to base and support) and built, so you can use it as an
example – or, better, a template – for constructing user directories
to support your IOCs. To make a template of xxx, clean and uninstall it, and
tar a copy of the directory. To use the template, untar it, cd to its top-level
directory and run <code>support/utils/changePrefix</code> to change the PV-name
prefix from xxx to whatever you want. (Note you must have
<code>support/utils</code> in your command path, or you could copy
<code>support/utils/changePrefix</code> and <code>support/utils/doSed</code> to
a directory that is in your command path. Note that <code>changePrefix</code> is
synApps-version specific.)
<P>Here's what I do:
<pre>
# Do once when synApps is built:
cd $(SYNAPPS)/support/xxx
setenv EPICS_HOST_ARCH <host architecture>
make clean uninstall
(repeat as needed for any other architectures)
tar cvf ../xxx.tar *
# Do whenever a new user directory ('1bm', in this example) is needed:
cd $(SYNAPPS)/ioc
mkdir 1bm
cd 1bm
tar xf $(SYNAPPS)/support/xxx.tar
changePrefix xxx 1bma
mv iocBoot/iocvxWorks iocBoot/ioc1bma
edit iocBoot/ioc1bma/Makefile to specify the IOC processor type
make
</pre>
<P>To put a second application, 1bmb, into 1bm, I run the following commands:
<pre>
cd $(SYNAPPS)/ioc
mkdir temp
cd temp
tar xf $(SYNAPPS)/support/xxx.tar
changePrefix xxx 1bmb
mv iocBoot/iocvxWorks iocBoot/ioc1bmb
edit iocBoot/ioc1bmb/Makefile to specify the ioc processor type
cd $(SYNAPPS)/ioc
mv temp/1bmbApp/start_epics_1bmb 1bm
mv temp/1bmbApp 1bm
mv temp/iocBoot/ioc1bmb 1bm/iocBoot
rm -rf temp
cd 1bm
make
</pre>
<P>Edit the files above to agree with your hardware, to load the databases you
want, etc., set up the IOC processor's parameters to load from the software
just configured, and boot the crate. If you don't know how to do this, read
on.
</ol>
<a name="How to make synApps work"></a>
<hr><h2>How to make synApps work</h2><hr>
<ol>
<h3><li>Setting up the IOC (vxWorks)</h3>
<P>Ensure that <code>$(EPICS_BASE)/bin/<arch>/caRepeater</code> gets run
when your
workstation boots. If you have no way of doing this, you can run it manually
or put the command in your .login file.
<P>Setup your host system to work with the EPICS processor. See the <i>VxWorks
Programmer's Guide</i> if you have a copy. Here's what we do (on a Sun
workstation):
<ul>
<li>Add a user named <code><vx_username></code> with the password
<code><vx_password></code>. The user has nothing in its home
directory, and very few priviledges.
<li>Connect an ethernet cable to the processor.
<li>Setup the workstation to use a serial port at 9600 baud.
Connect a serial cable from the workstation to the VME
processor's "Console" port.
<li>Start up an "xterm" on the workstation and type
<pre>cu -lttya</pre>
<P>(On some workstations we must type "<code>cu -lcua/a</code>".)
This gets the xterm communicating with the crate processor.
<li>Turn the crate on. The crate processor says "Press any key to
stop auto-boot..." and a number counting down from 7. Pressing
a key gets the prompt "[VxWorks Boot]:"
<li>Type "p" to see the current boot parameters, type "c" to
change them. Here are sample boot parameters
<pre>
boot device : dc
processor number : 0
host name : <server>
file name : /usr/local/vxWorks/T222/mv2700-asd1
inet on ethernet (e) : xxx.xxx.xxx.xxx:fffffe00
inet on backplane (b):
host inet (h) : xxx.xxx.xxx.xxx
gateway inet (g) :
user (u) : <vx_username>
ftp password (pw) (blank = use rsh): <vx_password>
flags (f) : 0x0
target name (tn) : iocxxx
startup script (s) : /home/server/USER/epics/xxx/iocBoot/iocxxx/st.cmd
other (o) :
</pre>
</ul>
<P>See <code>support/xxx/iocBoot/ioc*/bootParms</code> for other processor
types. If your VME processor has mount access to an 'APSshare' NFS file
server, you can specify the 'file name', above, as
"/APSshare/vw/T222/mv2700-asd1".
<P><h3><li>Display files</h3>
<P>synApps includes hundreds of display files intended for use with the EPICS
display manager, MEDM, and translations of those files that work with CSS-BOY
and caQtDM. Other EPICS display managers exist, and I once did a mass automated
translation of MEDM display files to the EDM display manager's file format,
using software developed by others. This translation was only partially
satisfactory, but we don't have the resources to do the job better or more
generically. In this documentation, I'll limit attention to MEDM display files.
<P><h3><li>Fitting synApps to an application</h3>
<P>This happens in the user directory. Generally, you must tell "EPICS" what
hardware is in your crate, and what addresses, interrupt vectors, etc. you have
set your hardware to use. (See support/xxx/documentation/vme_address.html for a
list of suggested values.) You also must specify which motors any slit,
table, monochromator, etc., control software is to use. If you use serial or
GPIB, you must match port names to hardware devices, set serial-port parameters,
and specify GPIB addresses. For any IndustryPack modules, you must specify the
IP carrier and slot into which you've loaded those modules.
<P><h4>Overview</h4>
<P>In a complete job of fitting synApps to an IOC's hardware, all of the
following files will be touched:
<blockquote>
<dl>
<dt><code>xxx/iocBoot/ioc*/st.cmd.*</code>
<dd>This is the ioc's startup script, and it loads the other .cmd files
<P><dt><code>xxx/iocBoot/ioc*/examples/*.iocsh</code><br>
<code>xxx/iocBoot/ioc*/substitutions/*.substitutions</code>
<dd>Example command files that can be invoked by st.cmd
<P><dt><code>xxx/iocBoot/ioc*/auto_positions.req</code><br>
<code>xxx/iocBoot/ioc*/auto_settings.req</code>
<dd>specifies PV's to be saved periodically during operation, and restored
automatically when the ioc is rebooted. (But note that you can have these
files constructed for you during the boot process. See <a
href="https://htmlpreview.github.io/?https://github.com/epics-modules/autosave/blob/R5-10/documentation/autoSaveRestore.html#autosaveBuild">autosaveBuild</a>
in the autosave documentation.)
<P><dt><code>xxx/iocBoot/ioc*/saveData.req</code>
<dd>identifies PV's used by the saveData software, sscan records to be
monitored for data, and PV's whose values are to be included in all
scan-data files.
<P><dt><code>xxx/iocBoot/ioc*/bootParms</code>
<dd>a copy of the boot parameters (in case the IOC processor
crashes in a way that erases nonvolatile memory)
</dl>
</blockquote>
<P><h4>In more detail</h4>
<P><ul>
<li><code>xxx/iocBoot/ioc*/st.cmd.*</code>
<P>This is the file run by the IOC at boot time. It loads an executable built in
the IOC directory (e.g., <code>xxx</code>, or <code>xxx.munch</code>), sets parameters to configure that
software, makes calls to that software to configure it for a particular set of
hardware, and loads databases from synApps modules. Mostly, it sources ioc shell
files that do these same things.
<P>This file, and the files it sources, are probably worth studying. They are
reasonably well commented, and contain <code>dbLoadRecords()</code> commands for most of
the EPICS databases in synApps.
<P><li>Motors
<P>To load more motors, add lines to the file
<code>xxx/iocBoot/ioc*/motor.substitutions</code>. For motors controlled by a
VME board, edit <code>vme.cmd</code> to specify the hardware address, etc. For
motors controlled through a serial connection, edit <code>serial.cmd</code>.
<P>If you want the new motors to work with the 'AllStop' button
(<code>xxx:allstop.VAL</code>
– see the top-level MEDM display <code>xxx.adl</code>), load the database
<code>$(MOTOR)/db/motorUtil.db</code>, and run the command
<code>motorUtilInit("xxx:")</code>.
<P>If you want the IOC automatically to save positions and settings of the new
motors, and restore them when the crate reboots, add lines to the files
<code>xxx/iocBoot/ioc*/auto_settings.req</code> and
<code>xxx/iocBoot/ioc*/auto_positions.req</code>.
<P><li>Slits
<P>To use a pair of motors to control a slit, search for <code>2slit.db</code>
in <code>xxx/iocBoot/ioc*/examples/optics.iocsh</code>, and edit the
<code>dbLoadRecords()</code> command you'll find there. The example in
<code>optics.iocsh</code> loads two copies of <code>2slit.db</code> intended for use
as the horizontal and vertical members of a four-jaw slit. The MEDM displays
<code>2slit*.adl</code> and <code>4slit*.adl</code> are involved in these
applications.
<P>The slit database can make either of two sets of assumptions about the two
motors attached to the individual slit leaves, depending on the value of the
macro "RELTOCENTER" that may be supplied when loading the 2slit.db database.
<P>If "RELTOCENTER=0" is supplied, or if RELTOCENTER is omitted altogether:
<ul>
<li>Both motors have the same engineering units.
<li>Both motors are in the same coordinate system. When the center position is
increased, both motors' .VAL fields increase.
<li>The APS standard beamline coordinate system is used. Positive Z is the beam
direction; positive Y is upward; positive X is outward from the storage ring.
</ul>
<P>If "RELTOCENTER=1" is supplied:
<ul>
<li>Both motors have the same engineering units.
<li>Their .VAL fields increase as the slit opens.
<li>The APS standard beamline coordinate system is used. Positive Z is the beam
direction; positive Y is upward; positive X is outward from the storage ring.
</ul>
<P>The <code>2slit.db</code> database allows users to move either the slit
virtual motors or the actual motors, and it keeps all the readback values
current regardless of how the actual motors got moved or recalibrated. But it
does not automatically reset the slit <b>drive</b> values when the actual motors are
used. This must be done manually, using the "SYNC" button on the
<code>2slit.adl</code> display. Pressing this button causes the database to
read the actual motor drive values and set the slit-drive values accordingly.
<P>To recalibrate slit positions, press the "Set" button, type in the current slit
position as you want it to be called, and press the "Use" button. This
procedure uses the "Set" buttons of both motors the slit software talks to, and
the user/dial offsets of those motors actually implement the recalibration.