To work and test with beam synchronous data sources there is the bs command. The bs command provides easy to use receiving functionality to see and check whether data is streamed correctly. There is also a sub-command that gives statistics about the incoming stream. Both can be used point to point to the source or via the SwissFEL dispatching layer.
Beside that the bs command provides a way to configure the channels that should be streamed out from an IOC.
Warning / Attention: Please ensure that you don't connect to a production source directly nor that you connect twice to a single source unless you are knowing what you are doing! Due to the current data delivery scheme (PUSH/PULL) data might be lost otherwise! If you are in doubt please ask for assistance from the Controls HA group (daq<at>psi.ch).
The bs command provides some client side utilities to receive beam synchronous data from an IOC as well as configuring the IOC (which channels are recorded via bsread)
Therefore the command provides several subcommands with options.
Usage: bs [OPTIONS] COMMAND [arg...]
Commands:
config - Configure IOC
stats - Show receiving statistics
receive - Basic receiver
h5 - Dump stream into HDF5 file
create - Create a test softioc
simulate - Provide a test stream
avail - Show currently available beam synchronous channels
Run 'bs COMMAND --help' for more information on a command.Show currently available beam synchronous channels
usage: avail [-h] [-a] [pattern]
Get available beam synchronous channels
positional arguments:
pattern Regex channel pattern
optional arguments:
-h, --help show this help message and exit
-a, --all Display all meta information
bs receive can be used to receive and display bsread data from an IOC. If the client environment was set the -s option can be omitted.
usage: receive [-h] [-s SOURCE] [-c] [-m {pull,sub}] [-q QUEUE]
[channel [channel ...]]
bsread receive utility
positional arguments:
channel Channels to retrieve (from dispatching layer)
optional arguments:
-h, --help show this help message and exit
-s SOURCE, --source SOURCE
Source address - format "tcp://<address>:<port>"
-c, --clear Monitor mode / clear the screen on every message
-m {pull,sub}, --mode {pull,sub}
Communication mode - either pull or sub (default
depends on the use of -s option)
-q QUEUE, --queue QUEUE
Queue size of incoming queue (default = 100)Note: If -s is specified, the list of channels is ignored.
bs stats provides you with some basic statistics about the messages received. Also a basic check whether pulse_ids were missing in the stream is performed.
usage: stats [-h] [-s SOURCE] [-c] [-m {pull,sub}] [-n N] [-l LOG] [-v]
[-q QUEUE]
[channel [channel ...]]
bsread statistics utility
positional arguments:
channel Channels to retrieve (from dispatching layer)
optional arguments:
-h, --help show this help message and exit
-s SOURCE, --source SOURCE
source address, has to be in format
"tcp://<address>:<port>"
-c, --clear Monitor mode / clear the screen on every message
-m {pull,sub}, --mode {pull,sub}
Communication mode - either pull or sub (default
depends on the use of -s option)
-n N Limit message printing to every n messages, this will
reduce CPU load. Note that all messages are still
received, but are not displayed. If -n 0 is passed
message display is disabled
-l LOG, --log LOG Enable logging. All errors (pulse_id skip, etc..) will
be logged in file specified
-v, --value Display values
-q QUEUE, --queue QUEUE
Queue size of incoming queue (default = 100)Note: If -s is specified, the list of channels is ignored.
bs config reads and updates the configuration a bsread enabled IOC.
While using no options it reads the current configuration from the IOC. While using -u it generates and uploads a new configuration to the specified IOC. For the new configuration, the script reads from standard input. Therefore the input can also be piped into the program.
usage: config [-h] [-a] [-u] [-I INHIBIT] [-v] ioc
BSREAD configuration utility
positional arguments:
ioc URL of config channel of ioc to retrieve config from
optional arguments:
-h, --help show this help message and exit
-a, --all Stream all channels of the IOC
-u, --update Update IOC configuration
-I INHIBIT, --inhibit INHIBIT
Set inhibit bit
-v, --verbose Verbose output to show configuration json string
The script reads from standard input and terminates on EOF or empty lines
An input line looks like this:
<channel> modulo(optional, type=float ) offset(optional, type=int)
Note, that only the channel name is mandatory.
As mentioned before the configuration can also be piped from any other process. This is can be done like this:
echo -e "one\ntwo\nthree" | bs config -c <ioc> -ubs h5 will dump the incoming stream into an hdf5 file for later analysis. As with the other commands, if the environment was set via bs-source env the -s option can be omitted.
usage: h5 [-h] [-s SOURCE] [-m {pull,sub}] [-q QUEUE] [-n N_MESSAGES]
[--compact]
file [channel [channel ...]]
BSREAD hdf5 utility
positional arguments:
file Destination file
channel Channels to retrieve (from dispatching layer)
optional arguments:
-h, --help show this help message and exit
-s SOURCE, --source SOURCE
Source address - format "tcp://<address>:<port>"
-m {pull,sub}, --mode {pull,sub}
Communication mode - either pull or sub (default
depends on the use of -s option)
-q QUEUE, --queue QUEUE
Queue size of incoming queue (default = 100)
-n N_MESSAGES, --n_messages N_MESSAGES
Number of messages to receive.None means infinity.
--compact Use the compact version of the file formatbs h5 produces a very simple HDF5 structure. Each channel in the stream gets into a own group which holds the actual channel data, timestamp, timestamp_offset as well as the pulse_id of the channel. data, timestamp, etc. within a channel group are arrays of the size of pulse_id/messages received. The same index of the arrays corresponds to the same pulse_id which stored in the pulse_id dataset at the same index.
IOC-TEST-FAKEDATA:TEST_WVF-DOUBLE
timestamp [int64]
data [float64]
pulse_id [int64]
timestamp_offset [int64]
IOC-TEST-FAKEDATA:TEST_WVF-INT
timestamp [int64]
data [int32]
pulse_id [int64]
timestamp_offset [int64]
Note: If -s is specified, the list of channels is ignored.
To generate a test stream use:
bs simulate
Usage:
usage: simulate [-h] [-p PORT]
bsread simulation utility
optional arguments:
-h, --help show this help message and exit
-p PORT, --port PORT Port number of streamTo create the configuration of a test softioc use:
bs create MY-PREFIX 7777The first argument is the prefix for the test records as well as IOC name, the second needs to be a random port - especially when setting up a test IOC on the login cluster nodes. If the port is omitted, the default port 9999 is taken (the standard bsread port). However this port should only be used if you are sure your test ioc is the only IOC of the node running it.
usage: create [-h] [--db DB] prefix port
bsread create utility - creates a sample ioc configuration
positional arguments:
prefix ioc prefix
port ioc stream port
optional arguments:
-h, --help show this help message and exit
--db DB create additional test database with specified number of scalars
and waveforms using generator strings (e.g.
'scalar(10);waveform(10,1024)') input commands must be delimited
with ';'. Available input commands: scalar([no of scalars])
waveform([no of waveforms],[size of waveform])After creating the configuration files with the command use iocsh startup.cmd to start the IOC.
The creation and start of the test ioc can be done in one go with following command:
eval "$(bs create TOCK 7777)"