From 75f1887e6fd737ffc89be426f6caf9b448c00111 Mon Sep 17 00:00:00 2001
From: Joe Stanley <33275230+engineerjoe440@users.noreply.github.com>
Date: Tue, 26 Dec 2023 13:26:06 -0800
Subject: [PATCH] made tcp client somewhat available, added most basic
 documentation examples

---
 .../simple_autoconfiguration.md               | 59 +++++++++++++++++++
 docsource/examples.md                         | 24 ++++++++
 docsource/index.md                            |  1 +
 selprotopy/__init__.py                        |  2 +-
 selprotopy/client/ethernet.py                 |  6 +-
 5 files changed, 90 insertions(+), 2 deletions(-)
 create mode 100644 docsource/client_examples/simple_autoconfiguration.md
 create mode 100644 docsource/examples.md

diff --git a/docsource/client_examples/simple_autoconfiguration.md b/docsource/client_examples/simple_autoconfiguration.md
new file mode 100644
index 0000000..40b82a2
--- /dev/null
+++ b/docsource/client_examples/simple_autoconfiguration.md
@@ -0,0 +1,59 @@
+# Performing Automatic Configuration with an SEL Relay
+
+SEL Protocol operates in a self-describing manner wherein the relay or intelligent electronic
+device provides a standard interface for binary messages to describe the layout of specific
+data regions. This makes it possible for the relay to describe the methods in which a user may
+query the device for data, send control operations, or otherwise interact with the relay.
+
+SELProtoPy provides mechanisms for the client objects to negotiate the automatic configuration
+process with a device to establish the devices capabilities.
+
+## Autoconfiguration with a Serially-Connected Device
+
+The following example assumes a Linux environment using a USB-to-serial adapter (thus the
+`/dev/ttyUSB1`) in use.
+
+```python
+# Import the serial client object from SELProtoPy
+from selprotopy.client import SerialSELClient
+
+# Define the connection parameters
+PORT = '/dev/ttyUSB1'
+BAUD = 9600
+
+# Establish the connection - this will NOT start the autoconfiguration
+client = SerialSELClient(port=PORT, baudrate=BAUD)
+
+# Start the Automatic Configuration process
+client.autoconfigure()
+
+# If no exceptions are raised, the configuration process has succeeded
+
+# Poll the relay using fast-meter
+client.poll_fast_meter()
+```
+
+## Autoconfiguration with a Ethernet-Connected Device
+
+The following example uses a raw TCP socket connection (does not use `telnetlib`) to
+establish a connection with the relay.
+
+```python
+# Import the TCP client object from SELProtoPy
+from selprotopy.client import TCPSELClient
+
+# Define the connection parameters
+IP = '192.168.1.100'
+TCP_PORT = 23
+
+# Establish the connection - this will NOT start the autoconfiguration
+client = TCPSELClient(ip_address=IP, port=TCP_PORT)
+
+# Start the Automatic Configuration process
+client.autoconfigure()
+
+# If no exceptions are raised, the configuration process has succeeded
+
+# Poll the relay using fast-meter
+client.poll_fast_meter()
+```
\ No newline at end of file
diff --git a/docsource/examples.md b/docsource/examples.md
new file mode 100644
index 0000000..81ab289
--- /dev/null
+++ b/docsource/examples.md
@@ -0,0 +1,24 @@
+# Examples of SELProtoPy in Action
+
+SELProtoPy may be used for a variety of standard interactions with SEL relays. The following
+references are a variety of example use-cases or implementations of the SELProtoPy package.
+Do not mistake them as recommendations, they are provided here as a support for education
+surrounding this tool.
+
+```{toctree}
+---
+maxdepth: 1
+---
+
+examples/*
+```
+
+```{note}
+It's important to acknowledge that although SEL Protocol is largely standardized, this library
+has only been used on, or tested against a limited set of SEL intelligent electronic devices.
+As such you may encounter errors where such devices do not behave in an expected fashion.
+
+In such cases, it is requested that an issue is opened on
+[GitHub](https://github.com/engineerjoe440/selprotopy/issues) to make maintainers aware of the
+problem.
+```
diff --git a/docsource/index.md b/docsource/index.md
index f29ad59..969a40f 100644
--- a/docsource/index.md
+++ b/docsource/index.md
@@ -31,6 +31,7 @@ maxdepth: 1
 ---
    
 selprotopy
+examples
 ```
 
 ```{warning}
diff --git a/selprotopy/__init__.py b/selprotopy/__init__.py
index 09951cd..670119f 100644
--- a/selprotopy/__init__.py
+++ b/selprotopy/__init__.py
@@ -23,7 +23,7 @@
 from selprotopy.support import telnet
 
 # Describe Package for External Interpretation
-__version__ = "0.1.3"
+__version__ = "0.1.4"
 
 # `telnetlib` Discards Null Characters, but SEL Protocol Requires them
 telnetlib.Telnet.process_rawq = telnet.process_rawq
diff --git a/selprotopy/client/ethernet.py b/selprotopy/client/ethernet.py
index c28d2d6..309456d 100644
--- a/selprotopy/client/ethernet.py
+++ b/selprotopy/client/ethernet.py
@@ -16,6 +16,8 @@
 """
 ################################################################################
 
+from typing import Optional
+
 from selprotopy.client.base import SELClient
 
 __all__ = ["TCPSELClient"]
@@ -81,10 +83,12 @@ class TCPSELClient(SELClient):
 
     def __init__(
         self,
+        ip_address: str,
+        port: Optional[int] = 23,
         **kwargs
     ):
         """Connect over Serial to the SEL Protocol Device."""
         # Establish a TCP Connection
-        connection=None # TODO
+        connection = socket.create_connection((ip_address, port))
         # Attach Super Object
         super().__init__(connApi=connection, **kwargs)