py61850.server#

Server API

This module contains all class and function to implement an IEC61850 server.

Classes

`ControlHandlerResult`(*values)	Result codes for control handler (`ControlWaitForExecutionHandler` and `ControlHandler`)
`DataAttribute`(handle, parent)	DataAttribute according IEC 61850
`DataAttributeType`(*values)	Represent the type of a `DataAttribute`
`DataObject`(handle, parent)	DataObject according IEC 61850
`IedModel`(name)	IedModel object is the root node of an IEC 61850 data model
`LogicalDevice`(handle, ied_model)	LogicalDevice according IEC 61850
`LogicalNode`(handle, parent)	LogicalNode according IEC 61850
`ModelNode`(handle, parent)	Base model for `LogicalDevice`, `LogicalNode`, `DataObject`, `DataAttribute`
`ModelNodeType`(*values)	Represent the type of a `ModelNode`
`SettingGroupControlBlock`(handle)	SettingGroupControlBlock according IEC 61850
`CheckHandlerResult`(*values)	Result code for `ControlPerformCheckHandler`
`ClientConnection`(handle)	Client connection with a server
`ControlAction`(handle)	Provide additional information on a control action from a client
`IedServer`(ied_model[, config])	IED server instance
`IedServerConfig`()	IedServer configuration object
`SelectStateChangedReason`(*values)	Reason why a select state of a control object changed

class py61850.server.ControlHandlerResult(*values)#

Result codes for control handler (ControlWaitForExecutionHandler and ControlHandler)

FAILED = 0#: check or operation failed

OK = 1#: check or operation was successful

WAITING = 2#: check or operation is in progress

class py61850.server.DataAttribute(handle: LP_ModelNode, parent: ModelNode | IedModel)#

DataAttribute according IEC 61850

property attribute_type: DataAttributeType#: Type of the data attribute

property fc: FunctionalConstraint#: Functional constraint of the data attribute

init_value(value: MmsValue)#

Set the initial value before the server is started

Parameters:: value (MmsValue) – Value when server will start

property trigger_options: DataAttributeTriggerOptions#: Indicate trigger option that can generate an event

class py61850.server.DataAttributeType(*values)#

Represent the type of a DataAttribute

BOOLEAN = 0#: int

INT8 = 1#: int8_t

INT16 = 2#: int16_t

INT32 = 3#: int32_t

INT64 = 4#: int64_t

INT128 = 5#: no native mapping!

INT8U = 6#: uint8_t

INT16U = 7#: uint16_t

INT24U = 8#: uint32_t

INT32U = 9#: uint32_t

FLOAT32 = 10#: float

FLOAT64 = 11#: double

OPTFLDS = 31#: bit-string(10)

TRGOPS = 32#: bit-string(6)

class py61850.server.DataObject(handle: LP_ModelNode, parent: ModelNode | IedModel)#

DataObject according IEC 61850

child_with_fc(obj_ref: str | bytes, fc: FunctionalConstraint) → DataAttribute | None#

Lookup a child by its object reference and functional constraint

Parameters:

obj_ref (str | bytes) – _description_
fc (FunctionalConstraint) – _description_

Returns:

_description_

Return type:

DataAttribute | None

class py61850.server.IedModel(name: str | bytes)#

IedModel object is the root node of an IEC 61850 data model

static create_from_config_file(filename: str | bytes) → IedModel#

Helper function to create an IedModel from a confg file

Parameters:: filename (str | bytes) – Path of the config file
Returns:: IedModel
Return type:: IedModel
Raises:: RuntimeError – _description_

create_logical_device(inst: str | bytes, name: str | bytes | None = None) → LogicalDevice#

Create a logical device in the IedModel

Parameters:

inst (str | bytes) – inst of the logical device
name (str | bytes | None, optional) – Optional loigcal device name, by default None

Returns:

LogicalDevice created

Return type:

LogicalDevice

Raises:

RuntimeError – _description_

property handle: LP_IedModel#: Pointer to the underlying C structure

logical_device_by_instance(ld_inst: str | bytes) → LogicalDevice | None#

Lookup logical device (LD) by device instance name

Parameters:: ld_inst (str | bytes) – Logical device instance name
Returns:: Return the LogicalDevice or None if the instance is not found
Return type:: LogicalDevice | None

model_node_by_reference(obj_ref: str | bytes) → ModelNode | None#

Lookup a model node by its object reference.

This function uses the full logical device reference as part of the object reference. E.g. if IED name is “IED1” and the logical device instance “WD1” the resulting LD name would be “IED1WD1”. However if the optional ldName is set then this attribute is used.

Parameters:: obj_ref (str | bytes) – Reference of the object
Returns:: ModelNode instance or None if model node does not exist
Return type:: ModelNode | None

model_node_by_short_reference(obj_ref: str | bytes) → ModelNode | None#

Lookup a model node by its short reference.

This version uses the object reference that does not contain the IED name or functional name as part of the logical device name. Instead the LD part consists of the LD instance name (“inst” attribute).

Parameters:: obj_ref (str | bytes) – Reference of the object
Returns:: ModelNode instance or None if model node does not exist
Return type:: ModelNode | None

property name: bytes#: Name of the IedModel

class py61850.server.LogicalDevice(handle: LP_LogicalDevice, ied_model: IedModel)#

LogicalDevice according IEC 61850

create_logical_node(name: str | bytes) → LogicalNode#

Create a logcail node in the logical device

Parameters:: name (str | bytes) – Name of the logical node
Returns:: LogicalNode created
Return type:: LogicalNode
Raises:: RuntimeError – _description_

property ied_model: IedModel#: Reference to the IedModel where the node belongs

property ld_name: bytes | None#: Return the optional ldName attribute

class py61850.server.LogicalNode(handle: LP_ModelNode, parent: ModelNode | IedModel)#

LogicalNode according IEC 61850

create_dataset(name: str | bytes) → Dataset#

Create a dataset in the logical node

Parameters:: name (str | bytes) – Name of the dataset
Returns:: Dataset created
Return type:: Dataset
Raises:: RuntimeError – _description_

create_goose_control_block(name: str | bytes, app_id: str | bytes, dataset_name: str | bytes | None = None, conf_ref: int = 1, min_time: int = 200, max_time: int = 3000) → GooseControlBlock#

Create a goose control block (GoCB) in the logical node

Parameters:

name (str | bytes) – Name of the GoCB
app_id (str | bytes) – Application ID of the GoCB
dataset_name (str | bytes | None, optional) – Name of the dataset or None if no dataset is assigned to the GoCB, by default None
conf_ref (int, optional) – Configuration revision, by default 1
min_time (int, optional) – Minimum GOOSE retransmission time, by default 200
max_time (int, optional) – Maximum GOOSE retransmission time, by default 3000

Returns:

Goose control block created

Return type:

GooseControlBlock

Raises:

RuntimeError – _description_

Create a report control block (BRCB or URCB) in the logical node

Parameters:

name (str | bytes) – Name of the report control block
rpt_id (str | bytes) – _description_
is_buffered (bool) – True for a buffered RCB - False for unbuffered RCB
dataset_name (str | bytes | None, optional) – Name of the dataset or None if no dataset is assigned to the RCB, by default None
conf_ref (int, optional) – Configuration revision, by default 1
trg_ops (TrgOps, optional) – Initial value trigger options, by default TrgOps.DATA_CHANGED | TrgOps.INTEGRITY | TrgOps.GI
rpt_options (ReportOptions, optional) – Initial value for inclusion options. Specifies what elements are included in a report, by default ReportOptions.SEQ_NUM | ReportOptions.TIME_STAMP | ReportOptions.REASON_FOR_INCLUSION | ReportOptions.DATA_SET | ReportOptions.BUFFER_OVERFLOW | ReportOptions.ENTRY_ID | ReportOptions.CONF_REV
buf_tm (int, optional) – Initial value for buffering time of the RCB in milliseconds (time between the first event and the preparation of the report), by default 50
intg_pd (int, optional) – Initial value for integrity period in milliseconds, by default 90000

Returns:

Report control block created

Return type:

ReportControlBlock

Raises:

RuntimeError – _description_

create_setting_group_control_block(act_sg: int, num_of_sg: int) → SettingGroupControlBlock#

Create a setting group control block (SGCB) in the logical node

The function does not check if the setting group control block is created in the LLN0 or in another node. According IEC61850, it should be only in LLN0.

Parameters:

act_sg (int) – Active setting group on server startup
num_of_sg (int) – Number of setting groups

Returns:

Setting group control block created

Return type:

SettingGroupControlBlock

Raises:

RuntimeError – _description_

create_sv_control_block(name: str | bytes, sv_id: str | bytes, dataset_name: str | bytes | None = None, conf_ref: int = 1, smp_mod: ~py61850.common.common.SVSmpMod = SVSmpMod.SAMPLES_PER_PERIOD, smp_rate: int = 80, opt_flds: ~py61850.common.common.SampledValueOptions = <SampledValueOptions: 0>, is_unicast=False) → SVControlBlock#

Create a multicast or unicast Sampled Value (SV) control block (SvCB)

Parameters:

name (str | bytes) – Name of the SvCB
sv_id (str | bytes) – application ID of the SvCB
dataset_name (str | bytes | None, optional) – Name of the dataset or None if no dataset is assigned to the SvCB, by default None
conf_ref (int, optional) – Configuration revision, by default 1
smp_mod (SVSmpMod, optional) – Sampling mode, by default SVSmpMod.SAMPLES_PER_PERIOD
smp_rate (int, optional) – Sampled rate, by default 80
opt_flds (SampledValueOptions, optional) – Optional fields, by default SampledValueOptions(0)
is_unicast (bool, optional) – True for a unicast sampled value - False for maluticast sampled value, by default False

Returns:

Sampled value control block created

Return type:

SVControlBlock

Raises:

RuntimeError – _description_

class py61850.server.ModelNode(handle: LP_ModelNode, parent: ModelNode | IedModel)#

Base model for LogicalDevice, LogicalNode, DataObject, DataAttribute

child(obj_ref: str | bytes) → ModelNode | None#

Lookup a child by its object reference.

Parameters:: obj_ref (str | bytes) – Reference of the object
Returns:: ModelNode instance or None if model node does not exist
Return type:: ModelNode | None

property handle: LP_ModelNode#: Pointer to the underlying C structure

property ied_model: IedModel#: Reference to the IedModel where the node belongs

property model_type: ModelNodeType#: Type of the node

property name: bytes#: Name of the node

class py61850.server.ModelNodeType(*values)#

Represent the type of a ModelNode

LOGICAL_DEVICE = 0#: Logical device

LOGICAL_NODE = 1#: Logical node

DATA_OBJECT = 2#: Data object

DATA_ATTRIBUTE = 3#: Data attribute

class py61850.server.SettingGroupControlBlock(handle: LP_SettingGroupControlBlock)#

SettingGroupControlBlock according IEC 61850

property act_sg: int#: Active setting group

property edit_sg: int#: Edited setting group

property handle: LP_SettingGroupControlBlock#: Pointer to the underlying C structure

property num_of_sgs: int#: Number of setting group

class py61850.server.CheckHandlerResult(*values)#

Result code for ControlPerformCheckHandler

ACCEPTED = -1#: check passed

WAITING_FOR_SELECT = 0#: select operation in progress - handler will be called again later

HARDWARE_FAULT = 1#: check failed due to hardware fault

TEMPORARILY_UNAVAILABLE = 2#: control is already selected or operated

OBJECT_ACCESS_DENIED = 3#: check failed due to access control reason - access denied for this client or state

OBJECT_UNDEFINED = 4#: object not visible in this security context ???

VALUE_INVALID = 11#: ctlVal out of range

class py61850.server.ClientConnection(handle: int)#

Client connection with a server

property addressof: int#: Address of the underlying C structure

class py61850.server.ControlAction(handle: c_void_p)#

Provide additional information on a control action from a client

getT() → Timestamp#

Gets the time (attribute “T”) of the last received control action (Oper or Select)

Returns:: _description_
Return type:: Timestamp

get_client_connection() → ClientConnection#

Gets the client object associated with the client that caused the control action.

Returns:: _description_
Return type:: ClientConnection

get_control_object() → DataObject#

Gets the control object that is subject to this action.

Returns:: _description_
Return type:: DataObject

get_control_time() → datetime | None#

Gets the time of the control (attribute “operTm”).

Returns:: None when it is not a timeActivatedControl
Return type:: datetime.datetime | None

get_ctl_num() → int#

Get the ctlNum attribute send by the client.

Returns:: _description_
Return type:: int

get_interlock_check() → bool#

Gets the interlockCheck bit provided by the client.

Returns:: _description_
Return type:: bool

get_originator_category() → OrCat#

Gets the originator category provided by the client.

Returns:: _description_
Return type:: OrCat

get_originator_identifier() → bytes#

Gets the originator identifier provided by the client.

Returns:: _description_
Return type:: bytes

get_synchro_check() → bool#

Gets the synchroCheck bit provided by the client.

Returns:: _description_
Return type:: bool

is_select() → bool#

Check if the control callback is called by a select or operate command.

Returns:: _description_
Return type:: bool

set_add_cause(add_cause: ControlAddCause)#

Sets the add cause for the next command termination or application error message.

Parameters:: add_cause (ControlAddCause) – _description_

set_error(error: ControlLastApplError)#

Sets the error code for the next command termination or application error message.

Parameters:: error (ControlLastApplError) – _description_

class py61850.server.IedServer(ied_model: IedModel, config: IedServerConfig | None = None)#

IED server instance

get_bit_string(data_attribute: DataAttribute) → int#

Get data attribute value of a bit string data attribute.

If data attribute is not a bit string, the behavior of the return value is unpredictible.

Parameters:: data_attribute (DataAttribute) – Data attribute
Returns:: Value of the attribute
Return type:: int

get_boolean(data_attribute: DataAttribute) → bool#

Get data attribute value of a boolean data attribute.

If data attribute is not a boolean, the behavior of the return value is unpredictible.

Parameters:: data_attribute (DataAttribute) – Data attribute
Returns:: Value of the attribute
Return type:: bool

get_float(data_attribute: DataAttribute) → float#

Get data attribute value of a float data attribute.

If data attribute is not a float, the behavior of the return value is unpredictible.

Parameters:: data_attribute (DataAttribute) – Data attribute
Returns:: Value of the attribute
Return type:: float

get_int32(data_attribute: DataAttribute) → int#

Get data attribute value of an int32 data attribute.

If data attribute is not an int32, the behavior of the return value is unpredictible.

Parameters:: data_attribute (DataAttribute) – Data attribute
Returns:: Value of the attribute
Return type:: int

get_int64(data_attribute: DataAttribute) → int#

Get data attribute value of an int64 data attribute.

If data attribute is not an int64, the behavior of the return value is unpredictible.

Parameters:: data_attribute (DataAttribute) – Data attribute
Returns:: Value of the attribute
Return type:: int

get_string(data_attribute: DataAttribute) → bytes#

Get data attribute value of a string data attribute.

If data attribute is not a string, the behavior of the return value is unpredictible.

Parameters:: data_attribute (DataAttribute) – Data attribute
Returns:: Value of the attribute
Return type:: bytes

get_uint32(data_attribute: DataAttribute) → int#

Get data attribute value of an uint32 data attribute.

If data attribute is not an uint32, the behavior of the return value is unpredictible.

Parameters:: data_attribute (DataAttribute) – Data attribute
Returns:: Value of the attribute
Return type:: int

get_utc_time(data_attribute: DataAttribute) → datetime#

Get data attribute value of an UTC time data attribute.

If data attribute is not an UTC time, the behavior of the return value is unpredictible.

Parameters:: data_attribute (DataAttribute) – Data attribute
Returns:: Value of the attribute
Return type:: datetime.datetime

get_value(data_attribute: DataAttribute) → MmsValue | None#

Get data attribute value.

Parameters:: data_attribute (DataAttribute) – Data attribute
Returns:: MmsValue object of the MMS Named Variable or None if the value does not exist.
Return type:: MmsValue | None

get_value_with_fc(data_object: DataObject, fc: FunctionalConstraint) → MmsValue | None#

Get the MmsValue object related to a functional constrained data object (FCD)

Get the MmsValue from the server cache that is associated with the Functional Constrained Data (FCD) object that is specified by the DataObject and the given Function Constraint (FC). Accessing the value will directly influence the values presented by the server. This kind of direct access will also bypass the report notification mechanism (i.e. changes will not cause a report!). Therefore this function should be used with care. It could be useful to access arrays of DataObjects.

Parameters:

data_object (DataObject) – Data object to specify the FCD
fc (FunctionalConstraint) – Functional constraint to specify the FCD

Returns:

MmsValue object of the MMS Named Variable or None if the value does not exist.

Return type:

MmsValue | None

property is_running: bool#: Check if IedServer instance is listening for client connections.

lock_data_model()#

Lock the data model for data update.

This function should be called before the data model is updated. After updating the data model the function IedServer_unlockDataModel should be called. Client requests will be postponed until the lock is removed.

py61850.server#

This Page