Patch 9

.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,43 @@
+---
+name: Bug Report
+about: Submit a bug report
+labels: "bug"
+title: '[BUG]'
+---
+
+
+**Bug Report**
+
+(A clear and concise description of what the bug is.)
+
+**To Reproduce**
+
+```python
+# Ideally, a small sample program that demonstrates the problem.
+```
+
+**Expected Behavior**
+
+<!--
+How did you expect saspy to behave? It’s fine if you’re not sure your understanding is correct.
+Write down what you thought would happen.
+-->
+
+**Actual Behavior**
+
+<!-- What went wrong? Some output would be nice. -->
+
+**Your Environment**
+
+<!-- Include as many relevant details about the environment you experienced the bug in -->
+
+- SASPy version used:
+- Python version used:
+- O.S. running the code:
+- VLT Vendor and Model:
+
+**Connection Method (check one please)**
+- [ ] Prolific USB Cable
+- [ ] Raspberry miniUART
+- [ ] RS-232 to TTL (Like MAX3323)
+- [ ] Other: <!-- Write here -->

.github/ISSUE_TEMPLATE/feature.md

@@ -0,0 +1,15 @@
+---
+name: Feature Proposal
+about: This is a template for proposing a new feature to SASPy
+title: '[FEATURE]'
+---
+
+**Author**:
+
+### Summary of the feature being proposed
+(write here)
+
+### What value does this feature bring to SASPy ?
+(write here)
+### Are you willing to implement this feature yourself?
+(write here)

.github/workflows/versioning.yml

@@ -0,0 +1,24 @@
+name: Semantic Release
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    concurrency: release
+    permissions:
+      id-token: write
+      contents: write
+
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
+
+    - name: Python Semantic Release
+      uses: python-semantic-release/python-semantic-release@master
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -35,6 +35,9 @@ MANIFEST
 pip-log.txt
 pip-delete-this-directory.txt
 
+# Local testing
+example.py
+
 # Unit test / coverage reports
 htmlcov/
 .tox/
@@ -102,3 +105,8 @@ venv.bak/
 
 # mypy
 .mypy_cache/
+
+# IDEs
+.idea
+
+.benchmark

.readthedocs.yaml

@@ -0,0 +1,32 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+   - pdf
+
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - requirements: docs/requirements.txt

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019 thomas-pythonas
+Copyright (c) 2024 thomas-pythonas | zacharytomlinson | well-it-wasnt-me
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,13 +1,34 @@
-# saspy
-Slots accounting system protocol based on Python for arm architecture
+# SASPY
+[![Documentation Status](https://readthedocs.org/projects/saspy/badge/?version=latest)](https://saspy.readthedocs.io/en/latest/?badge=latest)
 
-The SAS library was made using python and can be used for linux-based single-board computers (Raspberry, Orange PI, Banana Pi).
-The Library is used for connecting to EGM by RS-232 protocol and for receiving and processing some data of SAS-protocol.
+<p align="center">
+<img src="https://github.com/zacharytomlinson/saspy/assets/15037424/e8a8efc8-e83f-44f9-9ca1-7543a280e6b3" width="300" height="auto">
+</p>
+Slots Accounting System (SAS) Protocol is a standard when comes to Slot Machine and VLTs. And because we were bored and with not enough things to do we decided to build this library
 
-SAS  (Slot  Accounting  System)  protocol  is  the  de  facto  casino communications  standards  designed  to  automate  slot  machine  meter  reporting  and event  logging,  player  tracking,  bonusing,  ticketing  and  cashless  gaming. 
+## Scope
+This project, once reached a stable release, will be published on [PyPi](https://pypi.org/) as a Python package.
 
-The EGM and SMIB communicate each other in SAS protocol standards, whereas  communication  between  the  SMIB  and  host  is  not  standardized,  which interoperability  and  standards  issue  is  resolved  by  new  standards,  G2S  (Game to System)  protocol.  SMIB also  provides touch  screen and  card readers  for AFT  and player tracking service. 
+# Documentation
+Since this library is still under heavy development (but at least is working !) comments are still not complete and there is a draft of documentation into `docs/` folder. 
 
-The  System  architecture  of  SAS  Protocol:  SAS  protocol  is used  for  communication between EGM and SMIB. SAS protocol consists of 3 layers of physical layer, link layer, and application layer. The  physical  layer  leverages  RS-232  at  9.2kbps  of  1  start  bit,  8  data  bits,  and 1wakeup bit  and 1 stop bit. The  wakeup bit is used for  signaling the frame start byte and  needs  special  care  in  implementation  (described  later).  Master-slave  polling mechanism  is  used  for  the  medium  access  control  similar  to  USB  and  traditional remote terminal system. Each EGM is assigned a link address of 1 to 127. ‘0’ is used for  broadcasting.  The  polling  rate ranges  from 200ms  to 5s  but can  be reduced  to 40ms when EGM support RTE (real time event) mode.   SMIB uses two different types of polls, GP (general poll) and LP (long poll). GP is one  byte  EGM  address  with  wakeup  bit  set,  and  polls  events  generated  in  the receiving EGM system. The  receiving  EGM  should  respond with 1 byte event code, which is  called  ‘exception’  in  the specification.  The  exceptions include  non-priority exceptions such as no event, game start, game end, system tilt, and priority exceptions such as  handpay condition, ticket out, ticket in,  and  fund-transfer request.  LP  is used for  SMIB  to send  command  to  EGMs and  classified  into  R(read)-type,  S(set)-type, M(multi-game)-type, and G (global)-type. LP starts with 1 byte command value with wakeup bit set, and the lengths of LP are fixed or variable depending on the command. All  LP  except  R-type  contains  CRC-16  (cyclic  redundancy  check)  for  bit  error detection. The  response frame uses the similar format but with wakeup bit off. SMIB use implied ACK mechanism for confirming the receipt. 
+All the latest documentation regarding this library can be found on [Read The Docs](https://saspy.readthedocs.io/)
 
-SAS Protocol Application Functions: ROM signature request, Metric, Progressive broadcast, Tournament operation, RTE (real time event), Bonus Controller, Jackpot hand-pay, TITO(Ticket in/out), Multi-denomination, AFT, Component Authentication
+In the meantime feel free to checkout the [WiKi of this project](https://github.com/zacharytomlinson/saspy/wiki) where you are gonna find response and solutions to common problems we faced during our journey
+
+# Contribute
+Not many rules. Fork the repo, write your code, create pull request. Remember to use black for formatting and give a shot to pylint.
+
+## Issue & Implementation
+Please, use the [Issues tab](https://github.com/zacharytomlinson/saspy/issues) to propose an eventual enhancement or to submit an issue.
+
+# Authors
+This project was initiated by [thomas-pythonas](https://github.com/thomas-pythonas) in 2018 and has no update since then.
+
+Current author and mantainer are:
+
+- [Zachary Tomlinson](https://github.com/zacharytomlinson)
+- [Antonio D'Angelo](https://github.com/well-it-wasnt-me)
+
+# Thanks to
+* [Grigor Kolev](https://github.com/dedalgr) for his precious help

config.yml

@@ -0,0 +1,21 @@
+connection:
+  serial_port: /dev/ttyUSB0
+  timeout: 2
+  baudrate: 19200
+  infinite: False
+
+events:
+  poll_timeout: 0.5
+  poll_address: 0x82 # Standard Poll Address - On most the machines | Try 0x80 if 82 dont work
+
+debug:
+  level: DEBUG #    CRITICAL | ERROR | WARNING | INFO | DEBUG | NOTSET
+
+security:
+  key: 44
+
+machine:
+  pos_id: "B374A402"
+  reg_key: "0000000000000000000000000000000000000000"
+  asset_number: "15cd5b07" # Asset Magic Number - Works on every machine !
+  denomination: 0.01

config_handler.py

@@ -0,0 +1,17 @@
+import yaml
+
+
+class ConfigHandler:
+    def __init__(self, file_path="config.yml"):
+        self.config_file_path = file_path
+        self.config = None
+
+    def read_config_file(self):
+        with open(self.config_file_path, "r") as yaml_file:
+            self.config = yaml.safe_load(yaml_file)
+
+    def get_config_value(self, section, key):
+        if self.config:
+            return self.config.get(section, {}).get(key)
+        else:
+            raise ValueError("Configuration not loaded. Call read_config_file first.")

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,58 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'SASPy'
+copyright = "2024, Zachary Tomlinson, Antonio D'Angelo"
+author = "Zachary Tomlinson, Antonio D'Angelo"
+
+# The full version, including alpha/beta/rc tags
+release = '2.0.0'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.coverage',
+    'sphinx.ext.napoleon'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

docs/index.rst

@@ -0,0 +1,27 @@
+Welcome to SASPy's documentation!
+===================================
+
+.. image:: saspy-logo.jpeg
+   :align: center
+   :width: 300
+
+|
+| **SASPy** is a Python library for handling your beloved VLTs via SAS Protocol.
+
+At moment is compatible with SAS v6.02+
+
+Check out the :ref:`wiki-home`. section for more information about connections and common problems.
+
+.. note::
+   This project is under active development.
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Table of Contents
+   :name: mastertoc
+   :glob:
+
+   Home <self>
+   Wiki <wiki/WikiHome>
+   The Library <sas-lib/main>

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,3 @@
+sphinx
+sphinx_rtd_theme
+readthedocs-sphinx-search

docs/sas-lib/error_handler.rst

@@ -0,0 +1,7 @@
+Error Handling
+=====================
+
+.. automodule:: error_handler
+   :members:
+   :undoc-members:
+   :show-inheritance: