Draft Documentation

Signed-off-by: mharb <mharb@noreply.localhost>

px-tcp1/ProtosXExercise/README.md

@@ -0,0 +1,81 @@
+## PX-TCP1 Demo Software (WIP)
+
+Abstract  
+--------  
+ProtosXdigitalDemo is a simple C# console application that connects over TCP/IP to a `Protos-X PX-TCP1` Modbus master device. It reads digital inputs and analog registers, displays raw values and flattened bits, then exercises all digital outputs in an off–on–off sequence. The program reports errors using predefined exit codes.
+
+Requirements  
+------------  
+• `.NET 8.0 SDK` or later  
+• `NModbus4` NuGet package  
+• Access to a Protos-X PX-TCP1
+
+How to Build  
+------------  
+1. Clone or download the repository to your machine.  
+2. Open a command prompt or terminal in the project folder.  
+3. Restore dependencies and compile:  
+   ```
+   dotnet restore
+   dotnet build
+   ```
+
+How to Test  
+-----------  
+1. Ensure the Protos-X PX-TCP1 is powered on and reachable at 10.10.1.1:502 (or change the IP/port constants in `Program.cs`).  
+2. In the project folder, run:  
+   ```
+   dotnet run -- [recipeName] [timesToRepeat]
+   ```
+   • `recipeName` (optional): a label to pass in.  
+   • `timesToRepeat` (optional): number of times to repeat the sequence (future extension).  
+3. Follow the on-screen prompts. The program will:  
+   - Read and display 16 discrete inputs.  
+   - Read and display 8 analog input registers.  
+   - Convert those registers into 128 bits and display each bit’s On/Off state.  
+   - Turn all 16 outputs OFF, wait for key press, then ON, wait again, then OFF.
+
+Features / Control Flow  
+-----------------------  
+1. Parse up to two command-line arguments (recipe name and repeat count).  
+2. Load standardized failure codes.  
+3. Connect via TCP to the Protos-X PX-TCP1 master.  
+4. Read discrete inputs through `InputReader` and display them.  
+5. Read input registers through `RegisterReader`, display raw values, flatten to bits, and display.  
+6. Exercise outputs in sequence via `OutputExerciser`:  
+   a. Set all outputs OFF → prompt user →  
+   b. Set all outputs ON → prompt user →  
+   c. Set all outputs OFF again  
+7. On any error (connection, read/write, argument count), print an error and exit with the designated code.
+
+Exit Codes  
+----------  
+• 0 – Success  
+• 1 – Write-error to hardware  
+• 2 – Too many command-line arguments  
+• 255 – Other fatal error
+
+## Warning
+
+THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+`TL;DR: Not my problem`
+
+## License
+
+The `GPL V2` license applies to this project. All copyrights belong to their respective copyright holders and all trademarks belong to their trademark holders.
+
+```
+This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation; either version 2
+of the License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.)