sttp.transport package

Subpackages

Submodules

sttp.transport.bufferblock module

class sttp.transport.bufferblock.BufferBlock(signalid: UUID = Ellipsis, buffer: bytearray = Ellipsis)[source]

Bases: object

BufferBlock defines an atomic unit of data, i.e., a binary buffer, for transport in STTP.

DEFAULT_BUFFER: bytearray | None = None
DEFAULT_SIGNALID = UUID('00000000-0000-0000-0000-000000000000')
property buffer: bytearray | None

Gets measurement buffer as an atomic unit of data, i.e., a binary buffer. This buffer typically represents a partial image of a larger whole.

signalid

Defines measurement’s globally unique identifier.

sttp.transport.compactmeasurement module

class sttp.transport.compactmeasurement.CompactMeasurement(signalindexcache: SignalIndexCache, includetime: bool, usemillisecondresolution: bool, basetimeoffsets: List[int64], signalid: UUID = Ellipsis, value: float64 = Ellipsis, timestamp: uint64 = Ellipsis, flags: StateFlags = Ellipsis)[source]

Bases: Measurement

Represents a measured value, in simple compact format, for transmission or reception in STTP.

decode(buffer: bytes) → Tuple[int, Exception | None][source]

Parses a CompactMeasurement from the specified byte buffer.

get_binarylength() → uint32[source]

Gets the binary byte length of a CompactMeasurement

get_compact_stateflags() → int8[source]

Gets byte level compact state flags with encoded time index and base time offset bits.

get_timestamp_c2() → uint16[source]

Gets offset compressed millisecond-resolution 2-byte timestamp.

get_timestamp_c4() → uint32[source]

Gets offset compressed tick-resolution 4-byte timestamp.

property runtimeid: int32

Gets the 4-byte run-time signal index for this measurement.

set_compact_stateflags(value: int8)[source]

Sets byte level compact state flags with encoded time index and base time offset bits.

class sttp.transport.compactmeasurement.CompactStateFlags(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntFlag

Enumeration constants represent each flag in the 8-bit compact measurement state flags.

BASETIMEOFFSET = 64
CALCULATEDVALUE = 16
DATAQUALITY = 2
DATARANGE = 1
DISCARDEDVALUE = 32
SYSTEMISSUE = 8
TIMEINDEX = 128
TIMEQUALITY = 4

sttp.transport.constants module

class sttp.transport.constants.CompressionModes(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntFlag

Enumeration of the possible compression modes supported by STTP.

Obsolete: Only used for backwards compatibility with pre-standard STTP implementations. OperationalModes now supports custom compression types

GZIP = 32

Bit flag used determine if GZip compression will be used to metadata exchange.

NOFLAGS = 0

Defines state where no compression will be used.

TSSC = 64

Bit flag used determine if the time-series special compression algorithm will be used for data exchange.

class sttp.transport.constants.ConnectStatus(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Enumeration of the possible connection status results used by the SubscriberConnector.

CANCELED = -1

Connection cancelled status.

FAILED = 0

Connection failed status.

SUCCESS = 1

Connection succeeded status.

class sttp.transport.constants.DataPacketFlags(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntFlag

Enumeration of the possible flags for a data packet.

CACHEINDEX = 16

Determines which signal index cache to use when decoding a data packet. Used by STTP version 2 or greater.

Bit set = use odd cache index (i.e., 1), bit clear = use even cache index (i.e., 0).

CIPHERINDEX = 4

Determines which cipher index to use when encrypting data packet.

Bit set = use odd cipher index (i.e., 1), bit clear = use even cipher index (i.e., 0).

COMPACT = 2

Determines if serialized measurement is compact.

Obsolete: Bit will be removed in future version. Currently this bit is always set.

COMPRESSED = 8

Determines if data packet payload is compressed.

Bit set = payload compressed, bit clear = payload normal.

NOFLAGS = 0

Defines state where there are no flags set.

class sttp.transport.constants.Defaults[source]

Bases: object

AUTORECONNECT = True

Default for auto-reconnect flag.

AUTOREQUESTMETADATA = True

Default for auto-request metadata flag.

AUTOSUBSCRIBE = True

Default for auto-subscribe flag.

COMPRESS_METADATA = True

Default for compress metadata flag.

COMPRESS_PAYLOADDATA = True

Default for compress payload data flag.

COMPRESS_SIGNALINDEXCACHE = True

Default for compress signal index cache flag.

CONSTRAINTPARAMETERS = ''

Default for constraint parameters.

DATACHANNEL_INTERFACE = ''

Default for interface for data channel.

DATACHANNEL_LOCALPORT = np.uint16(0)

Default for local port for data channel.

ENABLE_TIME_REASONABILITY_CHECK = False

Default for enable time reasonability check flag.

EXTRA_CONNECTIONSTRING_PARAMETERS = ''

Default for extra connection string parameters.

FILTEREXPRESSION = ''

Default for filter expression.

INCLUDETIME = True

Default for include time flag.

LAGTIME = np.float64(10.0)

Default for lag time in seconds.

LEADTIME = np.float64(5.0)

Default for lead time in seconds.

MAXRETRIES = -1

Default for maximum number of retries for a connection attempt.

MAXRETRYINTERVAL = 30.0

Default for maximum retry interval in seconds.

METADATAFILTERS = ''

Default for metadata filters.

PROCESSINGINTERVAL = np.int32(-1)

Default for processing interval in seconds.

PUBLISHINTERVAL = np.float64(1.0)

Default for publish interval in seconds.

REQUEST_NANVALUEFILTER = False

Default for request nan-value filter flag.

RETRYINTERVAL = 1.0

Default for retry interval in seconds.

SOCKET_TIMEOUT = 2.0

Default for socket timeout in seconds.

STARTTIME = ''

Default for start time.

STOPTIME = ''

Default for stop time.

THROTTLED = False

Default for throttled flag.

UDPDATACHANNEL = False

Default for UDP data channel flag.

USE_LOCALCLOCK_AS_REALTIME = False

Default for use local clock as real time flag.

USE_MILLISECONDRESOLUTION = False

Default for use millisecond resolution flag.

VERSION = np.int8(2)

Default for STTP version.

class sttp.transport.constants.OperationalEncoding(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Enumeration of the possible string encoding options of an STTP session.

UTF16BE = 256

Targets big-endian 16-bit Unicode character encoding for strings.

Obsolete: STTP currently only supports UTF-8 string encoding.

UTF16LE = 0

Targets little-endian 16-bit Unicode character encoding for strings.

Obsolete: STTP currently only supports UTF-8 string encoding.

UTF8 = 512

Targets 8-bit variable-width Unicode character encoding for strings.

class sttp.transport.constants.OperationalModes(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntFlag

Enumeration of the possible modes that affect how DataPublisher and DataSubscriber communicate during an STTP session.

COMPRESSMETADATA = 2147483648

Bit flag used to determine whether metadata is compressed when exchanging between publisher and subscriber.

Bit set = compress, bit clear = no compression.

COMPRESSPAYLOADDATA = 536870912

Bit flag used to determine whether payload data is compressed when exchanging between publisher and subscriber.

Bit set = compress, bit clear = no compression.

COMPRESSSIGNALINDEXCACHE = 1073741824

Bit flag used to determine whether the signal index cache is compressed when exchanging between publisher and subscriber.

Bit set = compress, bit clear = no compression.

ENCODINGMASK = 768

Bit mask used to get character encoding used when exchanging messages between publisher and subscriber.

STTP currently only supports UTF-8 string encoding.

IMPLEMENTATIONSPECIFICEXTENSIONMASK = 16711680

Bit mask used to apply an implementation-specific extension to STTP.

If the value is zero, no implementation specific extensions are applied. If the value is non-zero, an implementation specific extension is applied, and all parties need to coordinate and agree to the extension. If extended flags are unsupported, returned failure message text should be prefixed with UNSUPPORTED EXTENSION: as the context reference.

NOFLAGS = 0

State where there are no flags set.

RECEIVEEXTERNALMETADATA = 33554432

Bit flag used to determine whether external measurements are exchanged during metadata synchronization.

Bit set = external measurements are exchanged, bit clear = no external measurements are exchanged.

RECEIVEINTERNALMETADATA = 67108864

Bit flag used to determine whether internal measurements are exchanged during metadata synchronization.

Bit set = internal measurements are exchanged, bit clear = no internal measurements are exchanged.

VERSIONMASK = 255

Bit mask used to get version number of protocol.

Version number is currently set to 2.

class sttp.transport.constants.SecurityMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Enumeration of the possible security modes used by the DataPublisher to secure data sent over the command channel in STTP.

OFF = 0

Defines security mode where data will be sent over the wire unencrypted.

TLS = 1

Defines security mode where data will be sent over wire using Transport Layer Security (TLS).

class sttp.transport.constants.ServerCommand(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Enumeration of the possible server commands received by a DataPublisher and sent by a DataSubscriber during an STTP session.

CONFIRMBUFFERBLOCK = 8

Command code for receipt of a buffer block measurement.

This message is sent in response to ServerResponse.BufferBlock.

CONFIRMNOTIFICATION = 7

Command code for receipt of a notification.

This message is sent in response to ServerResponse.Notify.

CONFIRMUPDATEBASETIMES = 9

Command code for receipt of a base time update.

This message is sent in response to ServerResponse.UpdateBaseTimes.

CONFIRMUPDATECIPHERKEYS = 11

Command code for confirming the receipt of a cipher key update.

This verifies delivery of the cipher keys indicating that it is safe to transition to the new keys.

CONFIRMUPDATESIGNALINDEXCACHE = 10

Command code for confirming the receipt of a signal index cache.

This allows publisher to safely transition to next signal index cache.

CONNECT = 0

Command code handling connect operations.

Only used as part of connection refused response – value not sent on the wire.

DEFINEOPERATIONALMODES = 6

Command code for establishing operational modes.

As soon as connection is established, requests that server set operational modes that affect how the subscriber and publisher will communicate.

GETPRIMARYMETADATASCHEMA = 12

Command code for requesting the primary metadata schema.

GETSIGNALSELECTIONSCHEMA = 13

Command code for requesting the signal selection schema.

METADATAREFRESH = 1

Command code for requesting an updated set of metadata.

ROTATECIPHERKEYS = 4

Command code for manually requesting that server send a new set of cipher keys for data packet encryption (UDP only).

SUBSCRIBE = 2

Command code for requesting a subscription of streaming data from server based on connection string that follows.

UNSUBSCRIBE = 3

Command code for requesting that server stop sending streaming data to the client and cancel the current subscription.

UPDATEPROCESSINGINTERVAL = 5

Command code for manually requesting that server to update the processing interval with the following specified value.

USERCOMMAND00 = 208

Command code handling user-defined commands.

USERCOMMAND01 = 209

Command code handling user-defined commands.

USERCOMMAND02 = 210

Command code handling user-defined commands.

USERCOMMAND03 = 211

Command code handling user-defined commands.

USERCOMMAND04 = 212

Command code handling user-defined commands.

USERCOMMAND05 = 213

Command code handling user-defined commands.

USERCOMMAND06 = 214

Command code handling user-defined commands.

USERCOMMAND07 = 215

Command code handling user-defined commands.

USERCOMMAND08 = 216

Command code handling user-defined commands.

USERCOMMAND09 = 217

Command code handling user-defined commands.

USERCOMMAND10 = 218

Command code handling user-defined commands.

USERCOMMAND11 = 219

Command code handling user-defined commands.

USERCOMMAND12 = 220

Command code handling user-defined commands.

USERCOMMAND13 = 221

Command code handling user-defined commands.

USERCOMMAND14 = 222

Command code handling user-defined commands.

USERCOMMAND15 = 223

Command code handling user-defined commands.

class sttp.transport.constants.ServerResponse(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Enumeration of the possible server responses received sent by a DataPublisher and received by a DataSubscriber during an STTP session.

BUFFERBLOCK = 136

Response code indicating a buffer block.

Unsolicited response informs client that a raw buffer block follows.

CONFIGURATIONCHANGED = 138

Response code indicating a that the publisher configuration metadata has changed.

Unsolicited response provides a notification that the publisher’s source configuration has changed and that client may want to request a meta-data refresh.

DATAPACKET = 130

Response code indicating a data packet.

Unsolicited response informs client that a data packet follows.

DATASTARTTIME = 134

Response code indicating the start time of data being published.

Unsolicited response provides the start time of data being processed from the first measurement.

FAILED = 129

Response code indicating a failed response.

Informs client that its solicited server command failed, original command and failure message follow.

NOOP = 255

Response code indicating an empty-operation keep-alive ping.

The command channel can remain quiet for some time, this command allows a period test of client connectivity.

NOTIFY = 137

Response code indicating a notification.

Unsolicited response provides a notification message to the client.

PROCESSINGCOMPLETE = 135

Response code indicating that processing has completed.

Unsolicited response provides notification that input processing has completed, typically via temporal constraint.

SUCCEEDED = 128

Response code indicating a succeeded response.

Informs client that its solicited server command succeeded, original command and success message follow.

UPDATEBASETIMES = 132

Response code indicating a runtime base-timestamp offsets have been updated.

Unsolicited response requests that client update its runtime base-timestamp offsets with those that follow.

UPDATECIPHERKEYS = 133

Response code indicating a runtime cipher keys have been updated.

Response, solicited or unsolicited, requests that client update its runtime data cipher keys with those that follow.

UPDATESIGNALINDEXCACHE = 131

Response code indicating a signal index cache update.

Unsolicited response requests that client update its runtime signal index cache with the one that follows.

USERRESPONSE00 = 224

Response code handling user-defined responses.

USERRESPONSE01 = 225

Response code handling user-defined responses.

USERRESPONSE02 = 226

Response code handling user-defined responses.

USERRESPONSE03 = 227

Response code handling user-defined responses.

USERRESPONSE04 = 228

Response code handling user-defined responses.

USERRESPONSE05 = 229

Response code handling user-defined responses.

USERRESPONSE06 = 230

Response code handling user-defined responses.

USERRESPONSE07 = 231

Response code handling user-defined responses.

USERRESPONSE08 = 232

Response code handling user-defined responses.

USERRESPONSE09 = 233

Response code handling user-defined responses.

USERRESPONSE10 = 234

Response code handling user-defined responses.

USERRESPONSE11 = 235

Response code handling user-defined responses.

USERRESPONSE12 = 236

Response code handling user-defined responses.

USERRESPONSE13 = 237

Response code handling user-defined responses.

USERRESPONSE14 = 238

Response code handling user-defined responses.

USERRESPONSE15 = 239

Response code handling user-defined responses.

class sttp.transport.constants.StateFlags(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntFlag

Enumeration of the possible quality states of a Measurement value.

ALARMHIGH = 16

Measurement flag for an alarm for high value.

ALARMLOW = 32

Measurement flag for an alarm for low value.

BADDATA = 1

Measurement flag for a bad data state.

BADTIME = 65536

Measurement flag for a bad time state.

CALCULATEDVALUE = 4096

Measurement flag for a calculated value state.

CALCULATIONERROR = 8192

Measurement flag for a calculation error with the value.

CALCULATIONWARNING = 16384

Measurement flag for a calculation warning with the value.

COMPARISONALARM = 512

Measurement flag for a comparison alarm, i.e., outside threshold of comparison with a real-time value.

DISCARDEDVALUE = 4194304

Measurement flag for a discarded value state.

DOWNSAMPLED = 2097152

Measurement flag for a down-sampled state.

FLATLINEALARM = 256

Measurement flag for an alarm for flat-lined value, i.e., latched value test alarm.

FUTURETIMEALARM = 524288

Measurement flag for a future time alarm.

LATETIMEALARM = 262144

Measurement flag for a late time alarm.

MEASUREMENTERROR = 2147483648

Measurement flag for a measurement error state.

NORMAL = 0

Measurement flag for a normal state.

OVERRANGEERROR = 4

Measurement flag for an over range error, i.e., unreasonable high value.

RECEIVEDASBAD = 2048

Measurement flag for a bad value received.

RESERVEDQUALITYFLAG = 32768

Measurement flag for a reserved quality.

RESERVEDTIMEFLAG = 8388608

Measurement flag for a reserved time state.

ROCALARM = 1024

Measurement flag for a rate-of-change alarm.

SUSPECTDATA = 2

Measurement flag for a suspect data state.

SUSPECTTIME = 131072

Measurement flag for a suspect time state.

SYSTEMERROR = 536870912

Measurement flag for a system error state.

SYSTEMWARNING = 1073741824

Measurement flag for a system warning state.

UNDERRANGEERROR = 8

Measurement flag for an under range error, i.e., unreasonable low value.

UPSAMPLED = 1048576

Measurement flag for an up-sampled state.

USERDEFINEDFLAG1 = 16777216

Measurement flag for user defined state 1.

USERDEFINEDFLAG2 = 33554432

Measurement flag for user defined state 2.

USERDEFINEDFLAG3 = 67108864

Measurement flag for user defined state 3.

USERDEFINEDFLAG4 = 134217728

Measurement flag for user defined state 4.

USERDEFINEDFLAG5 = 268435456

Measurement flag for user defined state 5.

WARNINGHIGH = 64

Measurement flag for a warning for high value.

WARNINGLOW = 128

Measurement flag for a warning for low value.

sttp.transport.datasubscriber module

class sttp.transport.datasubscriber.DataSubscriber(compress_payloaddata: bool = Ellipsis, compress_metadata: bool = Ellipsis, compress_signalindexcache: bool = Ellipsis, version: int8 = Ellipsis, sttp_sourceinfo: str = Ellipsis, sttp_versioninfo: str = Ellipsis, sttp_updatedoninfo: str = Ellipsis, socket_timeout: float = Ellipsis)[source]

Bases: object

Represents a subscription for an STTP connection.

DEFAULT_COMPRESS_METADATA = True
DEFAULT_COMPRESS_PAYLOADDATA = True
DEFAULT_COMPRESS_SIGNALINDEXCACHE = True
DEFAULT_SOCKET_TIMEOUT = 2.0
DEFAULT_STTP_SOURCEINFO = 'STTP Python Library'
DEFAULT_STTP_UPDATEDONINFO = '2024-10-16'
DEFAULT_STTP_VERSIONINFO = '0.6.4'
DEFAULT_VERSION = np.int8(2)
property activesignalindexcache: SignalIndexCache

Gets the active signal index cache.

adjustedvalue(measurement: Measurement) → float64[source]

Gets the Value of a Measurement with any linear adjustments applied from the measurement’s Adder and Multiplier metadata, if found.

autoreconnect_callback: Callable[[], None] | None

Called when DataSubscriber automatically reconnects.

compress_metadata

Determines whether the metadata transfer is compressed, defaults to GZip.

compress_payloaddata

Determines whether payload data is compressed, defaults to TSSC.

compress_signalindexcache

Determines whether the signal index cache is compressed, defaults to GZip.

configurationchanged_callback: Callable[[], None] | None

Called when the DataPublisher sends a notification that configuration has changed.

connect(hostname: str, port: uint16) → Exception | None[source]

Requests the the DataSubscriber initiate a connection to the DataPublisher.

property connected: bool

Determines if a DataSubscriber is currently connected to a DataPublisher.

connectionterminated_callback: Callable[[], None] | None

Called when DataSubscriber terminates its connection.

property connector: SubscriberConnector

Gets the SubscriberConnector associated with this DataSubscriber.

data_starttime_callback: Callable[[uint64], None] | None

Called with timestamp of first received measurement in a subscription.

decodestr(data: bytes) → str[source]

Decodes an STTP string according to the defined operational modes.

disconnect()[source]

Initiates a DataSubscriber disconnect sequence.

dispose()[source]

Cleanly shuts down a DataSubscriber that is no longer being used, e.g., during a normal application exit.

property disposing: bool

Determines if DataSubscriber is being disposed.

encodestr(data: str) → bytes[source]

Encodes an STTP string according to the defined operational modes.

errormessage_callback: Callable[[str], None] | None

Called when an error message should be logged.

lookup_metadata(signalid: UUID, source: str = Ellipsis, id: uint64 = Ellipsis) → MeasurementRecord[source]

Gets the MeasurementRecord for the specified signal ID from the local registry. If the metadata does not exist, a new record is created and returned.

metadatacache

Defines the metadata cache associated with this DataSubscriber.

metadatareceived_callback: Callable[[bytes], None] | None

Called when DataSubscriber receives a metadata response.

newbufferblocks_callback: Callable[[List[BufferBlock]], None] | None

Called when DataSubscriber receives a set of new buffer block measurements from the DataPublisher.

newmeasurements_callback: Callable[[List[Measurement]], None] | None

Called when DataSubscriber receives a set of new measurements from the DataPublisher.

notificationreceived_callback: Callable[[str], None] | None

Called when the DataPublisher sends a notification that requires receipt.

processingcomplete_callback: Callable[[str], None] | None

Called when the DataPublisher sends a notification that temporal processing has completed, i.e., the end of a historical playback data stream has been reached.

send_servercommand(commandcode: ServerCommand, data: bytes = None)[source]

Sends a server command code to the DataPublisher with specified payload.

send_servercommand_withmessage(commandcode: ServerCommand, message: str)[source]

Sends a server command code to the DataPublisher along with the specified string message as payload.

socket_timeout

Defines the socket timeout in seconds for the DataSubscriber connection.

statusmessage_callback: Callable[[str], None] | None

Called when a informational message should be logged.

sttp_sourceinfo

Defines the STTP library API title as identification information of DataSubscriber to a DataPublisher.

sttp_updatedoninfo

Defines when the STTP library API was last updated as identification information of DataSubscriber to a DataPublisher.

sttp_versioninfo

Defines the STTP library API version as identification information of DataSubscriber to a DataPublisher.

subscribe() → Exception | None[source]

Notifies the DataPublisher that a DataSubscriber would like to start receiving streaming data.

property subscribed: bool

Determines if a DataSubscriber is currently subscribed to a data stream.

property subscriberid: UUID

Gets the subscriber ID as assigned by the DataPublisher upon receipt of the SignalIndexCache.

property subscription: SubscriptionInfo

Gets the SubscriptionInfo associated with this DataSubscriber.

subscriptionupdated_callback: Callable[[SignalIndexCache], None] | None

Called when DataSubscriber receives a new signal index cache.

property total_commandchannel_bytesreceived: uint64

Gets the total number of bytes received via the command channel since last connection.

property total_datachannel_bytesreceived: uint64

Gets the total number of bytes received via the data channel since last connection.

property total_measurementsreceived: uint64

Gets the total number of measurements received since last subscription.

unsubscribe()[source]

Notifies the DataPublisher that a DataSubscriber would like to stop receiving streaming data.

version

Defines the STTP protocol version used by this library.

sttp.transport.measurement module

class sttp.transport.measurement.Measurement(signalid: UUID = Ellipsis, value: float64 = Ellipsis, timestamp: uint64 = Ellipsis, flags: StateFlags = Ellipsis)[source]

Bases: object

Represents a basic unit of measured data for transmission or reception in the STTP API.

DEFAULT_FLAGS = 0
DEFAULT_SIGNALID = UUID('00000000-0000-0000-0000-000000000000')
DEFAULT_TIMESTAMP = np.uint64(0)
DEFAULT_VALUE = np.float64(nan)
property datetime: datetime

Gets Measurement ticks-based timestamp as a standard Python datetime value.

flags

Defines flags indicating the state of the measurement as reported by the device that took it.

signalid

Defines measurement’s globally unique identifier.

timestamp

Defines the STTP uint64 timestamp, in ticks, that measurement was taken.

property timestampvalue: int64

Gets the integer-based time from a Measurement ticks-based timestamp, i.e., the 62-bit time value excluding any leap-second flags.

value

Defines instantaneous value of the measurement.

sttp.transport.signalindexcache module

class sttp.transport.signalindexcache.SignalIndexCache[source]

Bases: object

Represents a mapping of 32-bit runtime IDs to 128-bit globally unique measurement IDs. The class additionally provides reverse lookup and an extra mapping to human-readable measurement keys.

contains(signalindex: int32) → bool[source]

Determines if the specified signalindex exists with the SignalIndexCache.

property count: uint32

Gets the number of Measurement records that can be found in the SignalIndexCache.

decode(ds: DataSubscriber, buffer: bytes) → Tuple[UUID, Exception | None][source]

Parses a SignalIndexCache from the specified byte buffer received from a DataPublisher.

id(signalindex: int32) → uint64[source]

Returns the Measurement integer ID for the specified signalindex in the SignalIndexCache.

record(signalindex: int32) → Tuple[UUID, str, uint64, bool][source]

Record returns the key Measurement values, signal ID Guid, source string, and integer ID and a final boolean value representing find success for the specified signalindex in the SignalIndexCache.

signalid(signalindex: int32) → UUID[source]

Returns the signal ID Guid for the specified signalindex in the SignalIndexCache.

property signalids: Set[UUID]

Gets a set for all the Guid values found in the SignalIndexCache.

signalindex(signalid: UUID) → int32[source]

Returns the signal index for the specified signal ID Guid in the SignalIndexCache.

source(signalindex: int32) → str[source]

Returns the Measurement source string for the specified signalindex in the SignalIndexCache.

sttp.transport.signalkind module

class sttp.transport.signalkind.SignalKind(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Enumeration of the possible kinds of signals a Measurement can represent.

ALARM = 9

Alarm defines an alarm value signal kind.

ANALOG = 6

Analog defines an analog value signal kind.

ANGLE = 0

Angle defines a phase angle signal kind (could be a voltage or a current).

CALCULATION = 7

Calculation defines a calculated value signal kind.

DFDT = 3

DfDt defines a frequency delta over time(dF/dt) signal kind.

DIGITAL = 5

Digital defines a digital value signal kind.

FREQUENCY = 2

Frequency defines a line frequency signal kind.

MAGNITUDE = 1

Magnitude defines a phase magnitude signal kind (could be a voltage or a current).

QUALITY = 10

Quality defines a quality flags signal kind.

STATISTIC = 8

Statistic defines a statistical value signal kind.

STATUS = 4

Status defines a status flags signal kind.

UNKNOWN = 11

Unknown defines an undetermined signal kind.

class sttp.transport.signalkind.SignalKindEnum[source]

Bases: object

Helper functions for the SignalKind enumeration.

static acronym(signalkind: SignalKind) → str[source]

Gets the SignalKind enumeration value as its two-character acronym string.

static parse_acronym(acronym: str) → SignalKind[source]

Gets the SignalKind enumeration value for the specified two-character acronym.

static signaltype(signalkind: SignalKind, phasortype: str = Ellipsis) → str[source]

Gets the specific four-character signal type acronym for a ‘SignalKind’ enumeration value and phasor type, i.e., “V” voltage or “I” current.

Parameters:

  • signalkind (The SignalKind enumeration value for the acronym.)

  • phasortype (“V” for voltage or “I” for current when signalkind is SignalKind.ANGLE or SignalKind.MAGNITUDE.)

sttp.transport.subscriberconnector module

class sttp.transport.subscriberconnector.SubscriberConnector(errormessage_callback: Callable[[str], None] = Ellipsis, reconnect_callback: Callable[[DataSubscriber], None] = Ellipsis, hostname: str = Ellipsis, port: np.uint16 = Ellipsis, maxretries: np.int32 = Ellipsis, retryinterval: float = Ellipsis, maxretryinterval: float = Ellipsis, autoreconnect: bool = Ellipsis)[source]

Bases: object

Represents a connector that will establish or automatically reestablish a connection from a DataSubscriber to a DataPublisher.

DEFAULT_AUTORECONNECT = True
DEFAULT_ERRORMESSAGE_CALLBACK()
DEFAULT_HOSTNAME = ''
DEFAULT_MAXRETRIES = np.int32(-1)
DEFAULT_MAXRETRYINTERVAL = 30.0
DEFAULT_PORT = np.uint16(0)
DEFAULT_RECONNECT_CALLBACK()
DEFAULT_RETRYINTERVAL = 1.0
autoreconnect

Defines flag that determines if connections should be automatically reattempted.

cancel()[source]

Stops all current and future connection sequences.

connect(ds: DataSubscriber) → ConnectStatus[source]

Initiates a connection sequence for a DataSubscriber

dispose()[source]

Cleanly shuts down a SubscriberConnector that is no longer being used, e.g., during a normal application exit.

errormessage_callback

Called when an error message should be logged.

hostname

DataPublisher DNS name or IP.

maxretries

MaxRetries defines the maximum number of times to retry a connection. Set value to -1 to retry infinitely.

maxretryinterval

Defines the maximum retry interval, in milliseconds.

port

TCP/IP listening port of the DataPublisher.

reconnect_callback

Called when SubscriberConnector attempts to reconnect.

reset_connection()[source]

Resets SubscriberConnector for a new connection.

retryinterval

defines the base retry interval, in milliseconds. Retries will exponentially back-off starting from this interval.

sttp.transport.subscriptioninfo module

class sttp.transport.subscriptioninfo.SubscriptionInfo(filterexpression: str = Ellipsis, throttled: bool = Ellipsis, publishinterval: float64 = Ellipsis, udpdatachannel: bool = Ellipsis, datachannel_localport: uint16 = Ellipsis, datachannel_interface: str = Ellipsis, includetime: bool = Ellipsis, enabletimereasonabilitycheck: bool = Ellipsis, lagtime: float64 = Ellipsis, leadtime: float64 = Ellipsis, uselocalclockasrealtime: bool = Ellipsis, usemillisecondresolution: bool = Ellipsis, requestnanvaluefilter: bool = Ellipsis, starttime: str = Ellipsis, stoptime: str = Ellipsis, constraintparameters: str = Ellipsis, processinginterval: int32 = Ellipsis, extra_connectionstring_parameters: str = Ellipsis)[source]

Bases: object

Defines subscription related settings for a DataSubscriber instance.

DEFAULT_CONSTRAINTPARAMETERS = ''
DEFAULT_DATACHANNEL_INTERFACE = ''
DEFAULT_DATACHANNEL_LOCALPORT = np.uint16(0)
DEFAULT_ENABLE_TIME_REASONABILITY_CHECK = False
DEFAULT_EXTRA_CONNECTIONSTRING_PARAMETERS = ''
DEFAULT_FILTEREXPRESSION = ''
DEFAULT_INCLUDETIME = True
DEFAULT_LAGTIME = np.float64(10.0)
DEFAULT_LEADTIME = np.float64(5.0)
DEFAULT_PROCESSINGINTERVAL = np.int32(-1)
DEFAULT_PUBLISHINTERVAL = np.float64(1.0)
DEFAULT_REQUEST_NANVALUEFILTER = False
DEFAULT_STARTTIME = ''
DEFAULT_STOPTIME = ''
DEFAULT_THROTTLED = False
DEFAULT_UDPDATACHANNEL = False
DEFAULT_USE_LOCALCLOCK_AS_REALTIME = False
DEFAULT_USE_MILLISECONDRESOLUTION = False
constraintparameters

Defines any custom constraint parameters for a requested temporal data playback. This can include parameters that may be needed to initiate, filter, or control historical data access.

datachannel_interface

Defines the desired network interface to use for UDP publication.

datachannel_localport

Defines the desired UDP port to use for publication.

enabletimereasonabilitycheck

Determines if publisher should perform time reasonability checks. When enabled lagtime and leadtime will be used to determine if a measurement timestamp is reasonable.

extra_connectionstring_parameters

Defines any extra or custom connection string parameters that may be needed for a subscription.

filterexpression

Defines the desired measurements for a subscription. Examples include:

  • Directly specified signal IDs (UUID values in string format):

    38A47B0-F10B-4143-9A0A-0DBC4FFEF1E8; {E4BBFE6A-35BD-4E5B-92C9-11FF913E7877}

  • Directly specified tag names:

    DOM_GPLAINS-BUS1:VH; TVA_SHELBY-BUS1:VH

  • Directly specified identifiers in “measurement key” format:

    PPA:15; STAT:20

  • A filter expression against a selection view:

    FILTER ActiveMeasurements WHERE Company=’GPA’ AND SignalType=’FREQ’

includetime

Determines if time should be included in non-compressed, compact measurements.

lagtime

Defines defines the allowed past time deviation tolerance in seconds (can be sub-second). Value is used to determine if a measurement timestamp is reasonable. Only applicable when enabletimereasonabilitycheck is True.

leadtime

Defines defines the allowed future time deviation tolerance in seconds (can be sub-second). Value is used to determine if a measurement timestamp is reasonable. Only applicable when enabletimereasonabilitycheck is True.

processinginterval

Defines the initial playback speed, in milliseconds, for a requested temporal data playback. With the exception of the values of -1 and 0, this value specifies the desired processing interval for data, i.e., basically a delay, or timer interval, over which to process data. A value of -1 means to use the default processing interval while a value of 0 means to process data as fast as possible.

publishinterval

Defines the down-sampling publish interval to use when throttled is True.

request_nanvaluefilter

Requests that the publisher filter, i.e., does not send, any NaN values.

starttime

Defines the start time for a requested temporal data playback, i.e., a historical subscription. Simply by specifying a StartTime and StopTime, a subscription is considered a historical subscription. Note that the publisher may not support historical subscriptions, in which case the subscribe will fail.

stoptime

Defines the stop time for a requested temporal data playback, i.e., a historical subscription. Simply by specifying a StartTime and StopTime, a subscription is considered a historical subscription. Note that the publisher may not support historical subscriptions, in which case the subscribe will fail.

throttled

Determines if data will be published using down-sampling.

udpdatachannel

Requests that a UDP channel be used for data publication.

use_millisecondresolution

Determines if time should be restricted to milliseconds in non-compressed, compact measurements.

uselocalclockasrealtime

Determines if publisher should use local clock as real time. If false, the timestamp of the latest measurement will be used as real-time. Only applicable when enabletimereasonabilitycheck is True.

Module contents