# Beam Synchronous Acquisition Service

The BSA Service consists of two components, the Collector and FileWriter.
This repository contains only the Collector which acts as a server to the FileWriter client.
The FileWriter is maintained separately in the bsasStore repository.

Running 'make' will install the Collector locally under ./bin/<arch>/bsas as a soft IOC.

Code entry points are in [bsasApp/src/hooks.cpp](bsasApp/src/hooks.cpp).
Multiple instances of the Collector softIOC will run, each configured with a separate set of files
- [iocBoot/lcls/sio-sys0-ba11](iocBoot/lcls/sio-sys0-ba11)
                - Directory contains configuration for normal conducting beamline, targeting hard x-ray production
- [iocBoot/lcls/sio-sys0-ba12](iocBoot/lcls/sio-sys0-ba12)
                - Directory contains configuration for normal conducting beamline, targeting soft x-ray production
- [iocBoot/lcls/sio-sys0-ba21](iocBoot/lcls/sio-sys0-ba21)
                - Directory contains configuration for superconducting beamline, targeting hard x-ray production
- [iocBoot/lcls/sio-sys0-ba22](iocBoot/lcls/sio-sys0-ba22)
                - Directory contains configuration for superconducting beamline, targeting soft x-ray production

Within each of those directories exist configuration files for production and development purposes.
Configuration for the production environment includes a shell script to generate the file from the EPICS v7 directory service.
For example:
        [iocBoot/lcls/sio-sys0-ba11/signals.cu-hxr](iocBoot/lcls/sio-sys0-ba11/signals.cu-hxr) is generated by
        [iocBoot/lcls/sio-sys0-ba11/create.signals.cu-hxr.bash](iocBoot/lcls/sio-sys0-ba11/create.signals.cu-hxr.bash)

Dependencies
--------

* [epics-base](https://github.com/epics-base/epics-base)
* [pvDataCPP](https://github.com/epics-base/pvDataCPP)
* [pvAccessCPP](https://github.com/epics-base/pvAccessCPP)
* [p4p](https://github.com/epics-base/p4p)

# API

Each collector has three PVs, available through the EPICS v7 pvAccess protocol, providing the primary software interface.
They all have a common prefix, as described below
- **SIG**: The table containing all acquired PV names
- **TBL**: The table containing all PV data for the current beam pulse
- **STS**: The table containing an ascii representation of the current running status

Two functions are available within the configuration file to set up the Collector.
- **bsasTableAdd** can be used to specify the prefix for the PVs managed by the Collector itself.
for Example, bsasTableAdd( "BSAS:SYS0:1:XXX:") tells the collector that all three PVs will have the given prefix and will look like this:
        * BSAS:SYS0:1:XXX:SIG
        * BSAS:SYS0:1:XXX:TBL
        * BSAS:SYS0:1:XXX:STS

- **bsasTableSet** is used to read PV names from a local file into a given table name, indicating all PVs from which data will be acquired.
For example, bsasTableSet( "BSAS_SYS0:1:XXX:SIG", "signals.cu-hxr.prod") will populate the given table with the names contained in the given file.

There are also nine internal variables used to set various operating parameters, which can be set within the configuration files.

|Name                     | Type        |Default Value  |Usable Range   |Purpose        |
|-------------------------|-------------|---------------|---------------|---------------|
|collectorDebug           | int         | 0             | 0 - 5         | Debugging of forwarding threads within Collector |
|collectorCaDebug         | int         | 0             | 0 - 3         | Debugging of Channel Access acquisition code |
|receiverPVADebug         | int         | 0             | 0 - 2         | Debugging of PVAccess distribution code |
|bsasBackFill             | int         | 0             | 0 - 1 (bool)  | Provide previous data if new data is not valid |
|bsasFlushPeriod          | double      | 2.0           | Not Checked   | Seconds to acquire data while previous queue is being distributed |
|collectorCaScalarMaxRate | double      | 140.0         | Not Checked   | Limit number of scalar elements acquired per bsasFlushPeriod |
|collectorCaArrayMaxRate  | double      | 1.5           | Not Checked   | Limit number of array elements acquired per bsasFlushPeriod |
|maxEventRate             | double      | 20.0          | Not Checked   | |
|maxEventAge              | double      | 2.5           | Not Checked   | |
