engineerjoe440 / selprotopy

Schweitzer Engineering Laboratories (SEL) Protocol Bindings in Python

SELProtoPy

Schweitzer Engineering Laboratories (SEL) Protocol Bindings in Python

GitHub Pages (development documentation): https://engineerjoe440.github.io/selprotopy/

ReadTheDocs (production documentation): https://selprotopy.readthedocs.io/

This project is still in early stages, much is still to come.

Description

selprotopy is intended to be used as a protocol binding suite for the SEL Protocol suite which includes SEL Fast Meter, SEL Fast Message, and SEL Fast Operate; each of which are proprietary protocols designed by Schweitzer Engineering Laboratories for use primarily with protective electric relays, and other intelligent electronic devices.

⚠️ Caution

This project, although binding SEL Protocol, is not sponsored, tested, or vetted in any way by Schweitzer Engineering Laboratories (SEL). This project is authored and maintained as an open-source project. Testing is performed on a very small set of hardware running in the author's basement. In short, this project has no association with SEL.

Since this project is not rigorously tested across all SEL devices or in a wide variety of use-cases, any time this project is used, it should first be thoroughly tested. This project is not intended to serve protection-class systems in any capacity. It should primarily be used for research, exploration, and other learning objectives.

📚 Protocol Documentation

SEL Protocol was introduced in the early 1990s to support various communications and control of SEL protective relays. SEL provided a very supportive application guide which provides great detail about the protocol's implementation. This application guide is a great resource and thoroughly documents the core framework of SEL Protocol. This guide is the basis of the bindings provided here. The guide can be accessed with a free account on the SEL website:

Installation

From PyPI as a Python Package

Just go ahead and issue: pip install selprotopy

From Source on Github

To install selprotopy from GitHub:

1. Download the repository as a zipped package.
2. Unzip the repository.
3. Open a terminal (command-prompt) and navigate to the new folder that's been unzipped. (Hint: Use cd <the-path-to-the-folder-you-unzipped-in>/selprotopy)
4. Use pip or python to install with the following commands, respectively:
   • $> pip install .
   • $> python setup.py install
5. Verify that it's been installed by opening a Python instance and importing: >>> import selprotopy If no errors arise, the package has been installed.

Contributing

Want to get involved? We'd love to have your help!

Please help us by identifying any issues that you come across. If you find an error, bug, or just have questions, jump over to the issue page.

If you want to add features, or contribute yourself, feel free to open a pull-request.

Contact Info

ℹ️ As mentioned in the caution above, this project is not associated with Schweitzer Engineering Laboratories (SEL) in any way, and as such, all contacts for questions, support, or other items should be directed to the resources listed here.

For issues found in the source code itself, please feel free to open an issue, but for general inquiries and other contact, feel free to address Joe Stanley, the project maintainer.

• [email protected]

selprotopy's Issues

SEL 4xx Relays Don't Communicate Well over Telnet

It's been reported that SEL 4xx relays don't like talking over a Telnet connection, and that there's some issues with the communications, there. Work will need to be completed to set up a test system for this hardware.

Need to add tests for:

• Serial connection
• Raw Socket
• Telnet
• Meter2 Region Data

Add Support for Server Functionality with Decorator Style Syntax

It would be pretty cool to have a full decorator-styled syntax for a server to provide access to the various data points that could be defined for SEL Protocol Regions. Take this for example:

from selprotopy.server import SELProtoServer

# Create a simple server listening on all network interfaces on port 23
server = SELProtoServer(
    host="0.0.0.0",
    port=23,
    fid="SEL-751....",
)


@server.fast_meter_binary("52A")
def serve_52A() -> bool:
    """Respond with a Boolean to Represent the 52A Status."""
    return True

@server.fast_meter_analog("IA")
def serve_IA() -> complex:
    """Return the Complex Value for the Phase-A Current."""
    # Return the static value: 67 /_ 120
    return complex(-33.45 + 58.024j)

@server.command_response("MET E")
def met_e_command() -> str:
    """Respond to the `MET E` Command with an Appropriate set of Data."""
    with open("my_saved_met_e.txt", 'r', encoding='utf-8') as file:
        return file.read()


if __name__ == "__main__":
    server.run()

Add "Getting Started" Documentation

It's been suggested that getting started with the library is not the clearest. Some documentation should be provided to inform developers/users how they should start interacting with the library, and what considerations they might need to make.

Things like:

• Connection Media | Serial, Raw Socket, Telnet
• Data Collection | How to read data, what to do with it, how to interact with data structures
• Sending Controls | When and how to send controls

SEL 7xx Relays Don't Communicate Well over Telnet

It's been reported that SEL 7xx relays don't like talking over a Telnet connection, and that there's some issues with the communications, there. Work will need to be completed to set up a test system for this hardware.

Need to add tests for:

• Serial connection
• Raw Socket
• Telnet
• Meter2 Region Data

Add Support for `telnetlib3` as `telnetlib` is Deprecated from Python 3.11+

Python's built-in telnetlib is being deprecated in Python 3.11 (see PEP 594), and should be migrated towards telnetlib3.

telnetlib3 is an asyncio-capable library, and some modifications will need to be made, accordingly. Still, they've got a nice example of a client in their README:

import asyncio, telnetlib3

@asyncio.coroutine
def shell(reader, writer):
    while True:
        # read stream until '?' mark is found
        outp = yield from reader.read(1024)
        if not outp:
            # End of File
            break
        elif '?' in outp:
            # reply all questions with 'y'.
            writer.write('y')

        # display all server output
        print(outp, flush=True)

    # EOF
    print()

loop = asyncio.get_event_loop()
coro = telnetlib3.open_connection('localhost', 6023, shell=shell)
reader, writer = loop.run_until_complete(coro)
loop.run_until_complete(writer.protocol.waiter_closed)

Furthermore, it appears that the client.open_connection method will return a tuple of the reader/writer objects that can be used with other logic. Perhaps they could be sent as a tuple to the SELClient object?