Merge pull request dmroeder#97 from kodaman2/docs

[WIP] Documentation - Merging this as the initial documentation, we can work on it as we go, but I think this is a good start.
BenGood · Apr 1, 2020 · 1911fc9 · 1911fc9
2 parents d7ec01b + 1bc5729
commit 1911fc9
Show file tree

Hide file tree

Showing 22 changed files with 319 additions and 1 deletion.
diff --git a/changelog b/changelog
@@ -1,3 +1,10 @@
+4/01/20
+  - Added Docs folder
+  - Added Templates for Issues and Pull requests
+  - Added Guides
+  - Added UnitTesting doc
+  - Upped version to 0.6.6
+
 03/29/20
   - Fixed routing to Micro800 controllers
   - Fixed GetDeviceProperties for Micro800

diff --git a/docs/Contributing.md b/docs/Contributing.md
@@ -0,0 +1 @@
+## Contributing
diff --git a/docs/Documentation.md b/docs/Documentation.md
@@ -0,0 +1 @@
+## API Documentation
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,9 @@
+## Documentation Contents
+
+- [Starter Guide](./guides/Starter-Guide.md)
+- [Continuous Reading](./guides/Continuous-Reading.md)
+- [Working with Files](./guides/Working-With-Files.md)
+- [Working with LogFiles](./guides/Working-With-LogFiles.md)
+- [API](Documentation.md) TODO
+- [Contributing](Contributing.md) TODO
+- [Unit testing](../tests/README.md)
diff --git a/docs/guides/Continuous-Reading.md b/docs/guides/Continuous-Reading.md
@@ -0,0 +1,5 @@
+## Continuous Reading
+
+This example just uses a while loop, to keep reading a tag.
+
+Run [test-03.py](../python_code/test-03.py) to see how this works.
diff --git a/docs/guides/Starter-Guide.md b/docs/guides/Starter-Guide.md
@@ -0,0 +1,110 @@
+# Starter Guide
+
+This guide makes some knowledge assumptions, experience with AB plc programs and some familiarity with python.
+
+> Danger: As we all know PLCs control dangerous equipment so ensure you are not writing tags in live systems unless you know what you are doing, and do so at your own risk.
+
+## Initial Setup
+
+If you don't have python installed, download and install [Python Download](https://www.python.org/downloads/). Ensure path checkbox is checked, or set path for your system accordingly for `/Python37/Scripts`.
+
+The best thing to do with python installed is to use pip which is a python package manager, otherwise you have to copy and paste libraries to where your script is located.
+
+Install pylogix:
+
+```
+ pip install git+https://github.com/dmroeder/pylogix
+```
+
+> In the near future pylogix will be available from pypi
+
+## RSLogix5000 Project
+
+If you have an existing project then skip this section. You want to test this library with a very minimal code like [test-01.py](../python_code/test-01.py), this will ensure you have connection to the PLC before writing complex code. I am using softlogix 5800, but this applies to any Contrologix, and Compactlogix. If you already have existing code, then go to controller tags, and pick a boolean tag, and replace it on test-01.py line 25.
+
+> Note: Ethernet Protocol does not work with emulator.
+
+Create a new project, select your controller type, and once the project is done, add the whatever ethernet module you have in your rack, and configure the IP settings.
+
+Save, and download program to the plc. If you can go online with the PLC, then we have good connection. If you don't check the below:
+
+![Run_Mode](../pics/Run_Mode.PNG)
+
+- ping plc
+  - If you can't ping it, check network cables
+  - Ensure your PC is on the same subnet, i.e. plc: 192.168.1.97, PC: 192.168.1.95
+- Ensure project slots are the same as physical layout.
+
+### Adding tags to the plc project
+
+In the controller organizer pane, select controller tags:
+
+![Controller_Tags](../pics/Select_Controller_Tags.PNG)
+
+Select Edit Tags:
+
+![Edit_Tags](../pics/Edit_Tags.PNG)
+
+Add a boolean tag:
+
+![bool_tag](../pics/Add_Bool_01.PNG)
+
+### Test the boolean tag
+
+Run [test-01.py](../python_code/test-01.py), you can open the file in python idle, or in the command line:
+
+```
+python test-01.py
+```
+
+On Windows:
+
+```
+py -3.7 test-01.py
+```
+
+Output:
+
+```
+bool_01 True Success
+```
+
+If the tag name is wrong, and doesn't exists, you'll get a value of None, and an error
+
+```
+bool_01 None Path segment error
+```
+
+If you're able to read that boolean you are good to go with pylogix. If not see possible issues.
+
+### Test a boolean tag in a program
+
+Let's use the default program MainProgram, and double click in Program Tags. In the same fashion as before, click on Edit Tags, and add `bool_01`. Run [test-02.py](/python_code/test-02.py). Remember controller tags are global scope you can use in any program, and program are local scope. Even when we used the same name bool_01 those are two different tags.
+
+## Possible Issues
+
+There are quite a few issues that can arise.
+
+- If you can't go online with rslogix:
+
+  - ping controller
+  - check ethernet cable
+  - check ethernet ip in the IO configuration
+  - check ip of your pc
+
+- If you are having import errors:
+  - ensure pylogix is installed
+
+## Report Issues
+
+https://github.com/dmroeder/pylogix/issues
+
+Before posting a usage issue, ensure you have ran through test-01.py. If you can't get test-01.py to run or to read the boolean tag, post the following in the issue:
+
+- Post whatever traceback errors you are getting
+- Which slot is the plc in?
+- A screenshot of the configuration of the ethernet module
+- Run ipconfig or ifconfig on linux, post screenshot
+- Plc model, OS system, python version, plc firmware
+
+The more information you post, the easier, and faster you'll get a response. We are giving free help, on a free repository so be mindful of your responses we can't read your mind.
diff --git a/docs/guides/Working-With-Files.md b/docs/guides/Working-With-Files.md
@@ -0,0 +1,50 @@
+## Working with Files
+
+It is pretty useful to have configuration files with given tags for read/write.
+
+### To read all lines from a file:
+
+tags.txt
+
+```
+tag_01
+tag_02
+tag_03
+...
+```
+
+```python
+
+file_extension = txt
+
+with open(path + "\\" + file + "." + file_extension) as f:
+        all_lines = f.readlines()
+```
+
+### To write tags to a file:
+
+saved_tags.txt
+
+First append tags to a list:
+
+```python
+# read online value
+
+for index in range(len(all_lines)):
+        ret = Read(all_lines[index])
+
+        # could have a sanity check here if ret.Value is None
+
+        put_string = ret.TagName + "|" + str(ret.Value)
+
+        # append to list
+        tags_list.append(put_string)
+
+```
+
+Then save to a file:
+
+```python
+with open(path + "\\" + file + "_Save." + file_extension, "w") as dp_save_file:
+        dp_save_file.writelines(tags_list)
+```
diff --git a/docs/guides/Working-With-LogFiles.md b/docs/guides/Working-With-LogFiles.md
@@ -0,0 +1,33 @@
+# Working with Log Files
+
+Logging is useful to figure out what is going wrong. Using our files example, we'd probably want to log the error instead of printing it.
+
+Time of error is very important, I am using the datetime library for that.
+
+```python
+import datetime
+
+now = datetime.datetime.now()
+log = open("log.txt", "a+")
+check_error_log = False
+
+# read online value
+ret = Read(plc_tag)
+put_string = ret.TagName + "|" + str(ret.Value)
+
+# Neccesary sanity check, because there are no exceptions with pylogix
+if ret.Status == "Success":
+    # append to list
+    tags_list.append(put_string)
+
+if ret.Status != "Success":
+    log.write("%s Save Error: %s tag %s\n" % (now.strftime("%c"), ret.TagName, ret.Status))
+    log.flush() # this ensures it logs to the file in the case of a crash
+    check_error_log = True # flag to alert user there are errors logged
+```
+
+Remember to close the file at the very end of your application.
+
+```
+log.close()
+```
diff --git a/docs/issue_template.md b/docs/issue_template.md
@@ -0,0 +1,36 @@
+### Preflight checks
+
+- [ ] Have you tried the examples?
+- [ ] Have you tried pylogix-tester?
+- [ ] Have you read previous issues?
+
+## Type of issue
+
+- [ ] Bug
+- [ ] Feature Request
+- [ ] Question
+- [ ] Other
+
+> Delete items that do not apply below.
+
+## Description of issue
+
+## Expected behavior
+
+## Actual behavior
+
+## Code
+
+Please provide a minimal, reproducible example
+
+## Screenshots
+
+## Stacktrace
+
+## Versions
+
+Include versions to
+
+- pylogix:
+- python:
+- OS:
diff --git a/docs/pics/Add_Bool_01.PNG b/docs/pics/Add_Bool_01.PNG
diff --git a/docs/pics/Edit_Tags.PNG b/docs/pics/Edit_Tags.PNG
diff --git a/docs/pics/Run_Mode.PNG b/docs/pics/Run_Mode.PNG
diff --git a/docs/pics/Select_Controller_Tags.PNG b/docs/pics/Select_Controller_Tags.PNG
diff --git a/docs/pics/create_bool_arr_01.PNG b/docs/pics/create_bool_arr_01.PNG
diff --git a/docs/pics/create_bool_arr_02.PNG b/docs/pics/create_bool_arr_02.PNG
diff --git a/docs/pics/progressbar_01.PNG b/docs/pics/progressbar_01.PNG
diff --git a/docs/pics/progressbar_02.PNG b/docs/pics/progressbar_02.PNG
diff --git a/docs/pull_request_template.md b/docs/pull_request_template.md
@@ -0,0 +1,28 @@
+## Short description of change
+
+## Types of changes
+
+<!--- What types of changes does your code introduce? Put an `x` in all the boxes that apply: -->
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] I have read the **docs/CONTRIBUTING.md** document.
+- [ ] My code follows the code style of this project.
+- [ ] My change requires a change to the documentation.
+- [ ] I have updated the documentation accordingly.
+- [ ] I have read **tests/README.md**.
+- [ ] I have added tests to cover my changes.
+- [ ] All new and existing tests passed.
+
+## What is the change?
+
+## What does it fix/add?
+
+## Test Configuration
+
+- PLC Model
+- PLC Firmware
+- pylogix version
+- python version
+- OS type and version
diff --git a/docs/python_code/test-01.py b/docs/python_code/test-01.py
@@ -0,0 +1,12 @@
+from pylogix import PLC
+
+# Setup the PLC object with initial parameters
+# Change to your plc ip address, and slot, default is 0, shown for clarity
+comm = PLC('192.168.1.207', 0)
+
+# Read returns Response class (.TagName, .Value, .Status)
+ret = comm.Read('bool_01')
+print(ret.TagName, ret.Value, ret.Status)
+
+# Close Open Connection to the PLC
+comm.Close()
diff --git a/docs/python_code/test-02.py b/docs/python_code/test-02.py
@@ -0,0 +1,12 @@
+from pylogix import PLC
+
+# Setup the PLC object with initial parameters
+# Change to your plc ip address, and slot, default is 0, shown for clarity
+comm = PLC('192.168.1.207', 0)
+
+# Read returns Response class (.TagName, .Value, .Status)
+ret = comm.Read('Program:MainProgram.bool_01')
+print(ret.TagName, ret.Value, ret.Status)
+
+# Close Open Connection to the PLC
+comm.Close()
diff --git a/docs/python_code/test-03.py b/docs/python_code/test-03.py
@@ -0,0 +1,14 @@
+from pylogix import PLC
+import time
+
+# Setup the PLC object with initial parameters
+# Change to your plc ip address, and slot, default is 0, shown for clarity
+comm = PLC('192.168.1.207', 0)
+
+# try to read a tag, else print error
+while True:
+    ret = comm.Read('bool_01')
+    time.sleep(1)  # Change seconds here
+    print(ret.Value)  # Do Ctrl + C to interrupt process
+
+comm.Close()
diff --git a/pylogix/__init__.py b/pylogix/__init__.py
@@ -1,4 +1,4 @@
 from .lgxDevice import LGXDevice
 from .eip import PLC
-__version_info__ = (0, 6, 5)
+__version_info__ = (0, 6, 6)
 __version__ = '.'.join(str(x) for x in __version_info__)