gRPC + Protobuf API
Table of Contents
Services
Messages
Enums
Overview
File: ska/pst/lmc/ska_pst_lmc.proto
Python Package: ska_pst_lmc
C++ Package: ska::pst::lmc
The protobuf definitions for the PST Local Monitoring and Controle (LMC) used within the PST infrastructure. The interface between the PyTango devices and the the core PST applications is provided by gRPC which uses protobuf messages to define the exchange of data and request messages.
Messages are in general made map what is needed by the core applications and not the SKA Telmodel JSON schema. The LMC devices will need to map values from a JSON request to send to a remote implementaion.
C++ bindings are generated as part of the ska-pst-common build pipeline but the Python bindings are not generated to allow for the ska-pst-lmc project to use the correct version of protobuf/protoc to generate the bindings. Access to the C++ bindings are available in the ska-pst-common-builder Docker image in /usr/local/include/ska/pst/lmc
Services
The following rpc services are defined within the protobuf file.
PstLmcService
Service to expose the local monitoring and control functionality of a process.
| connect | |
|---|---|
| Signature: | rpc connect(ConnectionRequest) returns (ConnectionResponse) |
| Description: | Used by a client to try to connect to the remote service. |
| configure_beam | |
|---|---|
| Signature: | rpc configure_beam(ConfigureBeamRequest) returns (ConfigureBeamResponse) |
| Description: | Used by a client to configure the component with given beam configuration. Beam configuration is different to scan configuration as it relates to how the beam is configured for bandwidth, number of channels, and calculated subbands. Between scans the same beam configuration may be used and this allows the system to be reconfigured without the need of tearing down the shared memory ringbuffers. |
| deconfigure_beam | |
|---|---|
| Signature: | rpc deconfigure_beam(DeconfigureBeamRequest) returns (DeconfigureBeamResponse) |
| Description: | Used by a client to release a beam and put the component in an state that is not even connected to ring buffers. |
| get_beam_configuration | |
|---|---|
| Signature: | rpc get_beam_configuration(GetBeamConfigurationRequest) returns (GetBeamConfigurationResponse) |
| Description: | Used by a client to get the current beam configuration for the component. |
| configure_scan | |
|---|---|
| Signature: | rpc configure_scan(ConfigureScanRequest) returns (ConfigureScanResponse) |
| Description: | Used by a client to configure a server to be ready for a scan request putting the server in a READY state. |
| deconfigure_scan | |
|---|---|
| Signature: | rpc deconfigure_scan(DeconfigureScanRequest) returns (DeconfigureScanResponse) |
| Description: | Used by a client to deconfigure a server and put it back to an IDLE state. |
| get_scan_configuration | |
|---|---|
| Signature: | rpc get_scan_configuration(GetScanConfigurationRequest) returns (GetScanConfigurationResponse) |
| Description: | Utility method that can be used to get the current scan configuration for a component. |
| start_scan | |
|---|---|
| Signature: | rpc start_scan(StartScanRequest) returns (StartScanResponse) |
| Description: | Used by a client to start a scan of the component. |
| stop_scan | |
|---|---|
| Signature: | rpc stop_scan(StopScanRequest) returns (StopScanResponse) |
| Description: | Used by a client to end a scan of the component. The StopScanRequest has an end_time parameter that if set the service must stop the scan at that exact time. This method should block until that time has been reached as to allow the LMC to know that scanning has stopped. |
| get_state | |
|---|---|
| Signature: | rpc get_state(GetStateRequest) returns (GetStateResponse) |
| Description: | Used by a client to verify the state of the component. |
| monitor | |
|---|---|
| Signature: | rpc monitor(MonitorRequest) returns (stream MonitorResponse) |
| Description: | Used to monitor a service. The service is expected to stream results back and putting the monitor data specific to itself in a given sub-message, i.e. SMRB to return data in an SmrbMonitorData wrapped in a MonitorResponse. |
| abort | |
|---|---|
| Signature: | rpc abort(AbortRequest) returns (AbortResponse) |
| Description: | Used by a client to put the server into the ABORTED state. This can affect the configuring and scanning stages and the service must end those stages. If monitoring is happening due to be in a scanning state then the monitoring should also stop as that is only valid for scanning states. |
| reset | |
|---|---|
| Signature: | rpc reset(ResetRequest) returns (ResetResponse) |
| Description: | Used by a client to reset the device from ABORTED or FAULT state into an IDLE / deconfigured state. |
| restart | |
|---|---|
| Signature: | rpc restart(RestartRequest) returns (RestartResponse) |
| Description: | Used by a client to reset the device from ABORTED or FAULT state into an EMPTY state (i.e. not having any beam configuration). Implementations of this can do a logical restart, i.e. make sure the the system is deconfigured for scan and then deconfigure it for beam, resulting in all resources have been released. |
| go_to_fault | |
|---|---|
| Signature: | rpc go_to_fault(GoToFaultRequest) returns (GoToFaultResponse) |
| Description: | Used by a client to set the service into a FAULT state. This
can be due to another part of the logical BEAM being faulty
and a call to this method from a client it advising the service
to move to the FAULT state. By moving to the FAULT state the service can be reset or restarted. Implementations of this should stop scanning if there it is in a scanning state. |
| get_env | |
|---|---|
| Signature: | rpc get_env(GetEnvironmentRequest) returns (GetEnvironmentResponse) |
| Description: | Used by a client to get the environmental state for the sevice. The client may call this many times as a form of monitoring. Unlike the monitor fuction, which is for monitoring a scan, this method doesn’t stream results back as it is a standard request and response method. Implementations of this should document clearly what they provide in the map of values. The default implementation is to return an empty map of values. |
| set_log_level | |
|---|---|
| Signature: | rpc set_log_level(SetLogLevelRequest) returns (SetLogLevelResponse) |
| Description: | Used by a client to set LogLevel of the service. The client may call this many times to dynamically change the LogLevel. |
| get_log_level | |
|---|---|
| Signature: | rpc get_log_level(GetLogLevelRequest) returns (GetLogLevelResponse) |
| Description: | Used by a client to get LogLevel of the service. |
Messages
The following Protobuf messages are defined in the protobuf file.
AbortRequest
Have the server abort its current process. This can happen IDLE, CONFIGURING, READY, SCANNING, or RESETTING states.
This is an empty message without any fields.
AbortResponse
The Response message for the abort command.
This is an empty message without any fields.
BeamConfiguration
A message to represent the beam configuration for the different services used within PST. This message is used as a field within the configure_beam and get_beam_configuration service methods.
It is only valid to only one field set, such as smrb, receive, or the test field.
| Field | Type | Description |
|---|---|---|
| oneof configuration.smrb | SmrbBeamConfiguration | The beam configuration for SMRB. This message can only be used for sending to/from the SMRB services. |
| oneof configuration.receive | ReceiveBeamConfiguration | The beam configuration for RECV. This message can only be used for sending to/from the RECV services. |
| oneof configuration.dsp_disk | DspDiskBeamConfiguration | The beam configuration for DSP.DISK It is invalid to send DSP.DISK configuration to any other system. |
| oneof configuration.stat | StatBeamConfiguration | The beam configuration for STAT.CORE It is invalid to send STAT.CORE configuration to any other system. |
| oneof configuration.test | TestBeamConfiguration | The beam configuration used within testing. This field should only be used with unit testing in the ska-pst-common project. |
ConfigureBeamRequest
Configure beam is by the LMC to setup the PST system ready to then be used for configuring scans. The main purpose of this is setting up the ring buffers and the subbands that may not change between scans but can change between different types of observations at different frequency bands and different number of channels.
| Field | Type | Description |
|---|---|---|
| beam_configuration | BeamConfiguration | The beam configuration for the service. This uses a BeamConfiguration message that has specific fields for the difference services. |
| dry_run | bool | Whether to perform a validation of the configuration
without performing the actual configuration process
on the service. If not set or the default value of false then the request will be performed. |
ConfigureBeamResponse
An empty response message that is used to define successfully doing beam configuration.
This is an empty message without any fields.
ConfigureScanRequest
Request message to configure a server to be ready for a scan request.
| Field | Type | Description |
|---|---|---|
| scan_configuration | ScanConfiguration | The scan configuration for the service. This uses a ScanConfiguration message that has specific fields for the difference services. |
| dry_run | bool | Whether to perform a validation of the configuration
without performing the actual configuration process
on the service. If not set or the default value of false then the request will be performed. |
ConfigureScanResponse
An empty message used as a response for a configure request.
This is an empty message without any fields.
ConnectionRequest
A request message to be sent to the service to identify which client is connecting.
| Field | Type | Description |
|---|---|---|
| client_id | string | The ID of the client. For the TANGO devices this should be the full-qualified domain name of the device. |
ConnectionResponse
An empty response message for the connection request.
This is an empty message without any fields.
DeconfigureBeamRequest
An empty message used in requesting the service to deconfigure itself of the beam configuration, such as disconnecting from ring buffers.
This is an empty message without any fields.
DeconfigureBeamResponse
An empty response message that is used for successful response of deconfiguring beam.
This is an empty message without any fields.
DeconfigureScanRequest
An empty message used to request that a server deconfigures itself.
This is an empty message without any fields.
DeconfigureScanResponse
An empty message used as a response for a deconfigure request.
This is an empty message without any fields.
DspDiskBeamConfiguration
Message to represent configuration for the DSP.DISK of PST
| Field | Type | Description |
|---|---|---|
| data_key | string | The key for the data buffer to read from |
| weights_key | string | The key for the weights buffer to read from |
DspDiskMonitorData
Message for the DSP.DISK monitoring results of a subband.
| Field | Type | Description |
|---|---|---|
| disk_capacity | uint64 | Disk size (in bytes) |
| disk_available_bytes | uint64 | Available disk space left |
| bytes_written | uint64 | Amount of data written during current scan |
| write_rate | double | Current write rate, in bytes / second |
DspDiskScanConfiguration
Message used for the DSP.DISK scan configuration.
| Field | Type | Description |
|---|---|---|
| scanlen_max | double | maximum length of observation (in seconds) |
| bytes_per_second | double | The calculated bytes per second for the beam data |
| execution_block_id | string | Execution block id. Used to group multiple scans together with an overall context. |
EnvValue
Message representing value of an environment value. This is done as a `oneof` field which allows for a string, float, signed int/long, or a unsigned int/long.
| Field | Type | Description |
|---|---|---|
| oneof value.string_value | string | |
| oneof value.float_value | float | |
| oneof value.signed_int_value | sint64 | |
| oneof value.unsigned_int_value | uint64 |
GetBeamConfigurationRequest
An empty message used to request the current beam configuration.
This is an empty message without any fields.
GetBeamConfigurationResponse
The response message for getting the current beam configuration for the the component.
| Field | Type | Description |
|---|---|---|
| beam_configuration | BeamConfiguration | The beam configuration for the service. This uses a BeamConfiguration message that has specific fields for the difference services. |
GetEnvironmentRequest
An empty request message to get the environment of the service.
This is an empty message without any fields.
GetEnvironmentResponse
The response message for the get_env command.
| Field | Type | Description |
|---|---|---|
| values | map GetEnvironmentResponse.ValuesEntry | A map of values where the key is the environment variable
name and the value is of type `EnvValue`. It is valid to return an empty response. |
GetEnvironmentResponse.ValuesEntry
| Field | Type | Description |
|---|---|---|
| key | string | |
| value | EnvValue |
GetLogLevelRequest
An empty request message for the get_log_level command.
This is an empty message without any fields.
GetLogLevelResponse
The response message for the get_log_level command.
| Field | Type | Description |
|---|---|---|
| log_level | LogLevel | Enum containing the current LogLevel of the service |
GetScanConfigurationRequest
An empty message used to retreive the current scan configuration of a component.
This is an empty message without any fields.
GetScanConfigurationResponse
A response message used to return the scan configuration of the a component.
| Field | Type | Description |
|---|---|---|
| scan_configuration | ScanConfiguration |
GetStateRequest
Request from the server to find out what state it is in.
This is an empty message without any fields.
GetStateResponse
Response from the server for what state it is in.
| Field | Type | Description |
|---|---|---|
| state | ObsState | The current ObsState of the managed service. |
GoToFaultRequest
An empty request message for the go_to_fault command.
| Field | Type | Description |
|---|---|---|
| error_message | string | the message relating to the fault and why the go_to_fault message was called. |
GoToFaultResponse
An emptry response message for the go_to_fault command.
This is an empty message without any fields.
MonitorData
A message to represent the current monitoring data for the different services used within PST.
It is only valid to only one field set, such as smrb, receive, or the test field.
| Field | Type | Description |
|---|---|---|
| oneof monitor_data.smrb | SmrbMonitorData | The monitoring data for SMRB.CORE. |
| oneof monitor_data.receive | ReceiveMonitorData | The monitoring data for RECV.CORE. |
| oneof monitor_data.dsp_disk | DspDiskMonitorData | The monitoring data for DSP.CORE. |
| oneof monitor_data.stat | StatMonitorData | The monitoring data for STAT.CORE. |
| oneof monitor_data.test | TestMonitorData | Only used for testing |
MonitorRequest
Request from the server to stream monitoring telemetry.
| Field | Type | Description |
|---|---|---|
| polling_rate | uint64 | rate in milliseconds to stream data back. The
rate should be in the order of seconds but instead
of using a float using a long int to represent
that time. If the server does not respond in 2 * this rate then the client should raise an alert. |
MonitorResponse
Response message from the server that is an envelope for a specific type of monitoring data, such at SMRB to populate SmrbMonitorData messages and put them into the smrb field of the monitore_data sub-message field.
| Field | Type | Description |
|---|---|---|
| monitor_data | MonitorData | The current monitor data to be returned for the service. |
ReceiveBeamConfiguration
Message to represent configuration for the RECV.CORE of PST
| Field | Type | Description |
|---|---|---|
| udp_nsamp | uint32 | Number of time samples per packet |
| wt_nsamp | uint32 | Number of time samples per relative weight |
| udp_nchan | uint32 | Number of frequency channels per packet |
| frequency | double | Centre frequency of observation (in MHz) |
| bandwidth | double | Total critical bandwidth (in MHz) |
| nchan | uint32 | Total number of input channels |
| frontend | string | The timing beam identifier |
| fd_poln | string | native polarisation of feed |
| fd_hand | sint32 | handedness of feed, having valid values are +1 or -1. For value of +1 for XYZ forming RH set with Z in the direction of propagation. Looking up into the feed of a prime-focus receiver or at the sky). |
| fd_sang | float | feed angle (in degrees) |
| fd_mode | string | feed tracking mode |
| fa_req | float | feed position angle. If the feed_mode = ‘FA’ this is respect to the telescope’s reference frame (feed_angle = 0), and for feed_mode = ‘CPA’ this is with respect to the celestial north (parallic angle = 0) or with respect to the Galactic north for coordinate_mode = ‘GALACTIC’. |
| nant | uint32 | number of receptors in sub-array |
| antennas | string | comma separated list of anntenna names. |
| ant_weights | string | comma separated list of receptor weights (which are floats) |
| npol | uint32 | number of polarisation |
| nbits | uint32 | number of bits per sample |
| ndim | uint32 | number of dimensions - should always be 2 |
| tsamp | double | sampling time, inferred from the bandwidth, nchan and oversample (in microseconds) |
| ovrsamp | string | oversampling rate - this is a fraction expressed as numerator/denominator |
| nsubband | uint32 | number of subbands |
| subband_resources | ReceiveSubbandResources | subband configuration |
| udp_format | string | udp format for scan |
| bytes_per_second | double | calculated bytes_per_second |
| beam_id | string | the beam id for the scans |
ReceiveMonitorData
Message for the Receive monitoring results of a subband.
| Field | Type | Description |
|---|---|---|
| receive_rate | float | UDP data received in bytes per second. This is the instantaneous rate for the last second. |
| data_received | uint64 | UDP data received in the current scan (in bytes). |
| data_drop_rate | float | UDP data dropped in bytes per second. This is the instantaneous rate for the last second. |
| data_dropped | uint64 | UDP data dropped in the current scan (in bytes). |
| misordered_packets | uint64 | Number of out of order UDP packets received in the current scan. The UDP packets for all frequency channels of a given set of time samples that start at time t0 shall arrive before the first packet containing data sampled at time t0+2 delta_t, where delta_t is the time spanned by the set of time samples in a single packet. |
| misordered_packet_rate | float | Number of out of order UDP packets per second. This is the instantaneous rate for the last second. See the misordered_packets for more detail. |
| malformed_packets | uint64 | Malformed packets are valid UDP packets, but where contents of the UDP payload does not conform to the specification in the CBF/PST ICD. Examples of malformation include: bad magic-word field, invalid meta-data, incorrect packet size. |
| malformed_packet_rate | float | The rate of malformed packets per second for the current scan. See the malformed_packets field for more detail. |
| misdirected_packets | uint64 | Total number of (valid) UDP packets that were unexpectedly received. Misdirection could be due to wrong ScanID, Beam ID, Network Interface or UDP port. Receiving misdirected packets is a sign that there is something wrong with the upstream configuration for the scan. |
| misdirected_packet_rate | float | The rate of mis-directected packets per second. See documentation on the misdirected_packets field for explanation of what a misdirected packet is. |
| checksum_failure_packets | uint64 | Total number of packets with a UDP, IP header or CRC checksum failure. This value is reported from the network interface (NIC). |
| checksum_failure_packet_rate | float | The number of packet checksum failures per second. See the checksum_failure_packets field for more detail. |
| timestamp_sync_error_packets | uint64 | The number of packets received where the timestamp has become desynchronised with the packet sequence number * sampling interval |
| timestamp_sync_error_packet_rate | float | The number of packet timestamp sync errors per second. See the timestamp_sync_error_packets field for more detail. |
| seq_number_sync_error_packets | uint64 | The number of packets received where the packet sequence number has become desynchronised with the data rate and elapsed time. |
| seq_number_sync_error_packet_rate | float | The number of packet sequence number sync errors per second. See the seq_number_sync_error_packets for more detail. |
ReceiveScanConfiguration
Message representing scan configuration for RECV
NOTE - OBSMODE is listed in detailed design but the LMC is set into an OBSMODE and this would be sent to DSP directly.
| Field | Type | Description |
|---|---|---|
| activation_time | string | UTC data and time to perform the requested command (in UTC string format) |
| observation_id | string | Unique indentifer for observation |
| scan_id | uint64 | 64-bit scan ID (Deprecated - now part of the Start Scan request) |
| observer | string | The person in charge of the observation |
| projid | string | Project the observations are for |
| pnt_id | string | ID for sub-array pointing |
| subarray_id | string | ID for the sub-array |
| source | string | The name/id of the source |
| itrf | string | Comma separated string of IRTF coordinates of the telescope delay centre (in metres) |
| bmaj | float | Beam major axis |
| bmin | float | Beam minor axis |
| coord_md | string | frame of coordinates |
| equinox | string | coordinate epoch |
| stt_crd1 | string | X component of starting co-ords in COORD_MD frame. If equatorial coordinates this would be the RA in Hours, minutes, seconds |
| stt_crd2 | string | Y component of starting co-ords in COORD_MD frame. If equatorial coordinates this would be the Dec in degrees, minutes, seconds. |
| trk_mode | string | tracking mode |
| scanlen_max | int32 | maximum length of observation (in seconds) |
| test_vector | string | identifier of preconfigured test-vector |
| calibration | ScanCalibration | calibration information for the scan |
| execution_block_id | string | Execution block id. Used to group multiple scans together with an overall context. |
ReceiveSubbandResources
Message to represent subband configuration for RECV.CORE
The detailed design document has parameters for the networking interface, like IP listener address and UDP port numbers. These have not been added here due to the fact that we now use Docker/Kubernetes. If they are need in the future this is where they should be added.
| Field | Type | Description |
|---|---|---|
| data_key | string | subband data key |
| weights_key | string | subband weights key |
| bandwidth | double | RF bandwidth for sub-band (in MHz) |
| nchan | uint32 | number of input frequency channels for subband |
| start_channel | uint32 | lowest channel number for input of sub-band (in MHz) |
| end_channel | uint32 | highest channel number for input of sub-band (in MHz) |
| frequency | double | subband centre frequency (in MHz) |
| start_channel_out | uint32 | lowest frequency channel number for output of sub-band |
| end_channel_out | uint32 | highest channel number for input of sub-band (in MHz) |
| nchan_out | uint32 | number of output frequency channels of sub-band |
| bandwidth_out | double | total output bandwidth across the frequency channels of sub-band (in MHz) |
| frequency_out | double | centre RF frequency of output channels of subband (in MHz) |
| data_host | string | interface to listen on |
| data_port | uint32 | udp port to listen on |
ResetRequest
Request message to reset the state of a server. Based on the SKA Obs State model this should put the server in an IDLE (i.e. deconfigured/unconfigured) state but still have the beam configuration still set.
This is an empty message without any fields.
ResetResponse
The response message for the reset command.
This is an empty message without any fields.
RestartRequest
Request message to restart the state of a server. Based on the SKA Obs State model this should put the server back to an EMPTY (i.e. no beam configuration set) state. The implementation of this may do a logical restart rather than restarting the process.
This is an empty message without any fields.
RestartResponse
The response message for the reset command.
This is an empty message without any fields.
ScanCalibration
Message representing scan calibration values this is used to allow for the calibration values to be null (i.e. not set) as protobuf defaults not set fields to zero.
For now SKA will not be using calibration in PST but this may change in the future.
| Field | Type | Description |
|---|---|---|
| cal_mode | string | operation mode for the injected calibration |
| cal_freq | double | calibration modulation frequency (in MHz) |
| cal_dcyc | float | calibration signal duty cycle |
| cal_phs | float | calibration phase leading edge |
| cal_nphs | uint32 | number of states in calibration pulse |
ScanConfiguration
A message to represent the scan configuration for the different services used within PST. This message is used as a field within the configure and get_scan_configuration service methods.
It is only valid to only one field set, such as smrb, receive, or the test field.
| Field | Type | Description |
|---|---|---|
| oneof configuration.smrb | SmrbScanConfiguration | The scan configuration for SMRB. This message can only be used for sending to/from the SMRB services. |
| oneof configuration.receive | ReceiveScanConfiguration | The scan configuration for RECV. This message can only be used for sending to/from the RECV services. |
| oneof configuration.dsp_disk | DspDiskScanConfiguration | The scan configuration for DSP.DISK. This message can only be used for sending to/from the DSP services. |
| oneof configuration.stat | StatScanConfiguration | The scan configuration for STAT.CORE. This message can only be used for sending to/from the STAT services. |
| oneof configuration.test | TestScanConfiguration | The scan configuration used within testing. This field should only be used with unit testing in the ska-pst-common project. |
SetLogLevelRequest
The request message for the set_log_level command.
| Field | Type | Description |
|---|---|---|
| log_level | LogLevel | Enum containing the LogLevel to be implemented |
SetLogLevelResponse
An empty response message for the set_log_level command
This is an empty message without any fields.
SmrbBeamConfiguration
Represents the beam configuration for a share memory ring buffer (SMRB)
| Field | Type | Description |
|---|---|---|
| data_key | string | The key for the data buffer |
| weights_key | string | The key for the weights buffer |
| hb_nbufs | uint32 | The number of header buffers |
| hb_bufsz | uint64 | The size in bytes of the header buffers |
| db_nbufs | uint32 | The number of data buffers |
| db_bufsz | uint64 | The size in bytes of the data buffers |
| wb_nbufs | uint32 | The number of weights bufffers |
| wb_bufsz | uint64 | The size of the weights buffers |
SmrbMonitorData
Message for the monitor results of a subband. This includes the data and weights statistics. It is up to the client of this to aggregate the data and weights statistics.
| Field | Type | Description |
|---|---|---|
| data | SmrbStatitics | The data ring buffer statistics. |
| weights | SmrbStatitics | The weights ring buffer statistics. |
SmrbScanConfiguration
Message representing scan configuration for SMRB this is an empty message for SMRB as there is nothing specific for the scan that needs to be configured.
This is an empty message without any fields.
SmrbStatitics
Message for the statistics of a subband ring buffer
| Field | Type | Description |
|---|---|---|
| nbufs | uint32 | total number of buffers |
| bufsz | uint64 | size of each buffer in bytes |
| written | uint64 | total number of buffers written to the ring |
| read | uint64 | total number of buffers read from the ring |
| full | uint32 | number of filled buffers in the ring |
| clear | uint32 | number of cleared buffers in the ring |
| available | uint32 | number of free buffers in the ring |
StartScanRequest
Request that the component initiates a scan
Expect a timestamp for when the Scan should start. This is an open issue at the moment.
| Field | Type | Description |
|---|---|---|
| scan_id | int64 | The unique ID for the scan. |
StartScanResponse
Response for the scan request.
This is an empty message without any fields.
StatBeamConfiguration
Message to represent configuration for the STAT.CORE of PST
| Field | Type | Description |
|---|---|---|
| data_key | string | The key for the data buffer to read from |
| weights_key | string | The key for the weights buffer to read from |
StatMonitorData
Message for the STAT.CORE monitoring results of a subband. https://developer.skao.int/projects/ska-pst-stat/en/latest/architecture/index.html#hdf5-data-structure
| Field | Type | Description |
|---|---|---|
| mean_frequency_avg | repeated float | The mean of the data for each polarisation and dimension, averaged over all channels. |
| mean_frequency_avg_masked | repeated float | The mean of the data for each polarisation and dimension, averaged over all channels, except those flagged for RFI. |
| variance_frequency_avg | repeated float | The variance of the data for each polarisation and dimension, averaged over all channels. |
| variance_frequency_avg_masked | repeated float | The variance of the data for each polarisation and dimension, averaged over all channels, except those flagged for RFI. |
| mean_spectrum | repeated float | The mean of the data for each polarisation, dimension, and channel. |
| variance_spectrum | repeated float | The variance of the data for each polarisation, dimension, and channel. |
| mean_spectral_power | repeated float | Mean power of the data for each polarisation and channel. |
| max_spectral_power | repeated float | Maximum power of the data for each polarisation and channel. |
| histogram_1d_freq_avg | repeated uint32 | Histogram of the input data integer states for each polarisation and dimension, averaged over all channels. |
| histogram_1d_freq_avg_masked | repeated uint32 | Histogram of the input data integer states for each polarisation and dimension, averaged over all channels, except those flagged for RFI. |
| histogram_rebinned_2d_freq_avg | repeated uint32 | Rebinned 2D histogram of the input data integer states for each polarisation, averaged over all channels. |
| histogram_rebinned_2d_freq_avg_masked | repeated uint32 | Rebinned 2D histogram of the input data integer states for each polarisation, averaged over all channels, except those flagged for RFI. |
| histogram_rebinned_1d_freq_avg | repeated uint32 | Rebinned histogram of the input data integer states for each polarisation and dimension, averaged over all channels. |
| histogram_rebinned_1d_freq_avg_masked | repeated uint32 | Rebinned histogram of the input data integer states for each polarisation and dimension, averaged over all channels, except those flagged for RFI. |
| num_clipped_samples_spectrum | repeated uint32 | Number of clipped input samples (maximum level) for each polarisation, dimension, and channel. |
| num_clipped_samples | repeated uint32 | Number of clipped input samples (maximum level) for each polarisation and dimension, averaged over all channels. |
| num_clipped_samples_masked | repeated uint32 | Number of clipped input samples (maximum level) for each polarisation and dimension, averaged over all channels, except those flagged for RFI. |
| spectrogram | repeated float | Spectrogram of the data for each polarisation, rebinned in frequency to NCHAN_DS bins and in time to NDAT_DS bins. |
| timeseries | repeated float | Time series of the data for each polarisation, rebinned in time to NDAT_DS bins, averaged over all frequency channels. This includes max, min, and mean of the power in each bin. |
| timeseries_masked | repeated float | Time series of the data for each polarisation, rebinned in time to NDAT_DS bins, averaged over all frequency channels, except those flagged by RFI. This includes max, min, and mean of the power in each bin. |
StatScanConfiguration
Message used for the STAT.CORE scan configuration.
| Field | Type | Description |
|---|---|---|
| execution_block_id | string | Execution block id. Used to group multiple scans together with an overall context. |
| processing_delay_ms | uint32 | delay to wait between processing segements of statistics in milliseconds. |
| req_time_bins | uint32 | the requested number of temporal bins in integrated spectrograms and timeseries. |
| req_freq_bins | uint32 | the requested number of spectral bins in integrated spectrograms. |
| num_rebin | uint32 | the requested number of bins in integrated histograms. |
Status
A status message that will be returned by the services Only valid if there is an error
| Field | Type | Description |
|---|---|---|
| code | ErrorCode | The error code for which this status relates to. |
| message | string | Optional error message to be provided when the error occurs. |
StopScanRequest
Request that the component stops scanning
if end_time > 0 then the scan must stop at that exact time.
| Field | Type | Description |
|---|---|---|
| end_time | uint64 | the time at which all the scans should stop as to allow synchonisation between RECV subbands This is in milliseconds from UNIX epoch (January 1, 1970 00:00:00 UTC) |
StopScanResponse
Response for the end scan request.
This is an empty message without any fields.
TestBeamConfiguration
Message used in unit testing to stub out the need for ska-pst-common to know about the structure of the core PST beam configurations.
This should only be used internally of the ska-pst-common project.
| Field | Type | Description |
|---|---|---|
| resources | map TestBeamConfiguration.ResourcesEntry | A map to put any data into. |
TestBeamConfiguration.ResourcesEntry
| Field | Type | Description |
|---|---|---|
| key | string | |
| value | string |
TestMonitorData
Message used in unit testing to stub out the need for ska-pst-common for monitoring.
This should only be used internally of the ska-pst-common project.
| Field | Type | Description |
|---|---|---|
| data | map TestMonitorData.DataEntry | A map of any monitoring data. |
TestMonitorData.DataEntry
| Field | Type | Description |
|---|---|---|
| key | string | |
| value | string |
TestScanConfiguration
Message used in unit testing to stub out the need for ska-pst-common to know about the structure of the core PST scan configurations.
This should only be used internally of the ska-pst-common project.
| Field | Type | Description |
|---|---|---|
| configuration | map TestScanConfiguration.ConfigurationEntry | Map to put any test scan configuration data into. |
TestScanConfiguration.ConfigurationEntry
| Field | Type | Description |
|---|---|---|
| key | string | |
| value | string |
Enums
The following enums are defined within the protobuf file.
ErrorCode
Enum representing particular error code that might happen during processing.
| Name | Number | Description |
|---|---|---|
| OK | 0 | Not used but to avoid the default value |
| INVALID_REQUEST | 1 | Used if the request sent to the service is invalid, such as a Oneof value is not set when it should have been. |
| INTERNAL_ERROR | 2 | There was an internal server error raised. |
| CONFIGURED_FOR_BEAM_ALREADY | 3 | The component has already been configured for the beam. Should have been deconfigured for beam before the request was made. |
| NOT_CONFIGURED_FOR_BEAM | 4 | The component is not configured for beam. |
| ALREADY_SCANNING | 5 | The service is already performing a scann |
| NOT_SCANNING | 6 | The service is not scanning |
| CONFIGURED_FOR_SCAN_ALREADY | 7 | The component has already been configured for scan. Should have deconfigured for scan before the request had been made. |
| NOT_CONFIGURED_FOR_SCAN | 8 | There is no scan configuration for the server. |
LogLevel
Enum representing the LogLevel
| Name | Number | Description |
|---|---|---|
| INFO | 0 | The least verbose loglevel. |
| DEBUG | 1 | Information that is diagnostically helpful to people more than just developers. |
| WARNING | 2 | Anything that can potentially cause application oddities. |
| CRITICAL | 3 | Overall application or system failure that should be investigated immediately. |
| ERROR | 4 | Logs that highlight when the current flow of execution is stopped due to a failure. |
ObsState
This is a protobuf representation of the SKA Obs State model enum. This is used by the LMC client to check the state of the service. Not all states will be valid for the system but are provided to map one-to-one with the SKA specific model
| Name | Number | Description |
|---|---|---|
| EMPTY | 0 | The sub-array is ready to observe, but is in an undefined configuration and has no resources allocated. |
| RESOURCING | 1 | The system is allocating resources to, or deallocating resources from, the subarray. This may be a complete de/allocation, or it may be incremental. In both cases it is a transient state and will automatically transition to IDLE when complete. For some subsystems this may be a very brief state if resourcing is a quick activity. |
| IDLE | 2 | The subarray has resources allocated and is ready to be used for
observing. In normal science operations these will be the resources
required for the upcoming SBI execution. For PST this means that the component has beam configuration and connected to the appropriate ring buffers. |
| CONFIGURING | 3 | The subarray is being configured ready to scan. On entry to the state no assumptions can be made about the previous conditions. It is a transient state and will automatically transition to READY when it completes normally. |
| READY | 4 | The subarray is fully prepared to scan, but is not actually taking data or moving in the observed coordinate system (it may be tracking, but not moving relative to the coordinate system). |
| SCANNING | 5 | The subarray is taking data and, if needed, all components are synchronously moving in the observed coordinate system. Any changes to the sub-systems are happening automatically (this allows for a scan to cover the case where the phase centre is moved in a pre-defined pattern). |
| ABORTING | 6 | The subarray is trying to abort what it was doing due to having been interrupted by the controller. |
| ABORTED | 7 | The subarray has had its previous state interrupted by the controller, and is now in an aborted state. |
| RESETTING | 8 | The subarray device is resetting to the IDLE state. |
| FAULT | 9 | The subarray has detected an error in its observing state making it impossible to remain in the previous state. |
| RESTARTING | 10 | The subarray device is restarting, as the last known stable state is where no resources were allocated and the configuration undefined. |
ObservationMode
Enum representing the observation mode for the scan
| Name | Number | Description |
|---|---|---|
| PULSAR_TIMING | 0 | The default observation mode is Pulsar timing which is used to time a known pulsar. |
| DYNAMIC_SPECTRUM | 1 | Dynamic spectrum is used on a target, such as a candidate pulsar, to determine more details about it before doing a pulsar timing scanning. |
| FLOW_THROUGH | 2 | The observation mode that just records the data without processing the data. |
Protobuf Scalar Value Types
The following value types are standard Protobuf types and documented for reference