machine_access_control 0.1.0__py3-none-any.whl

dm_mac/__init__.py

@@ -0,0 +1,14 @@
+"""Decatur Makers Machine Access Control."""
+
+from flask import Flask
+
+
+def create_app() -> Flask:
+    """Factory to create the app."""
+    app: Flask = Flask("dm_mac")
+
+    from dm_mac.views.api import api
+
+    app.register_blueprint(api)
+
+    return app

dm_mac/machine_state.py

@@ -0,0 +1,73 @@
+"""Classes and functions related to machine state."""
+from typing import Optional
+from logging import getLogger, Logger
+from time import time
+
+
+logger: Logger = getLogger(__name__)
+
+DEFAULT_DISPLAY_TEXT: str = 'Please Insert\nRFID Card'
+
+
+class MachineState:
+    """Object representing frozen state in time of a machine."""
+
+    def __init__(self, machine_name: str):
+        """Initialize a new MachineState instance."""
+        logger.debug('Instantiating new MachineState for %s', machine_name)
+        #: The name of the machine
+        self.name: str = machine_name
+        #: Float timestamp of the machine's last checkin time
+        self.last_checkin: Optional[float] = None
+        #: Float timestamp of the last time that machine state changed,
+        #: not counting `current_amps` or timestamps.
+        self.last_update: Optional[float] = None
+        #: Value of the RFID card/fob in use, or None if not present.
+        self.rfid_value: Optional[str] = None
+        #: Float timestamp when `rfid_value` last changed to a non-None value.
+        self.rfid_present_since: Optional[float] = None
+        #: Whether the output relay is on or not.
+        self.relay_is_on: bool = False
+        #: Whether the output relay should be on or not.
+        self.relay_desired_state: bool = False
+        #: Whether the machine's Oops button has been pressed.
+        self.is_oopsed: bool = False
+        #: Whether the machine is locked out from use.
+        self.is_locked_out: bool = False
+        #: Whether the machine is force-enabled without RFID present.
+        self.is_force_enabled: bool = False
+        #: Last reported output ammeter reading (if equipped).
+        self.current_amps: float = 0
+        #: Text currently displayed on the machine LCD screen
+        self.display_text: str = DEFAULT_DISPLAY_TEXT
+        self._load_from_cache()
+
+    def _save_cache(self):
+        """Save machine state cache to disk."""
+        raise NotImplementedError()
+
+    def update_has_changes(
+        self, rfid_value: str, relay_state: bool, oops: bool, amps: float
+    ) -> bool:
+        """Return whether or not the update causes changes to significant state values."""
+        if (
+            rfid_value != self.rfid_value or
+            relay_state != self.relay_is_on or
+            oops != self.is_oopsed
+        ):
+            return True
+        return False
+
+    def noop_update(self, amps: float):
+        """Just update amps and last_checkin and save cache."""
+        self.current_amps = amps
+        self.last_checkin = time()
+        self._save_cache()
+
+    @property
+    def machine_response(self) -> dict:
+        """Return the response dict to send to the machine."""
+        return {
+            'relay': self.relay_desired_state,
+            'display': self.display_text
+        }

dm_mac/views/__init__.py

@@ -0,0 +1 @@
+"""Init for views (empty)."""

dm_mac/views/api.py

@@ -0,0 +1,12 @@
+"""API Views."""
+
+from flask import Blueprint
+
+
+api: Blueprint = Blueprint("api", __name__, url_prefix="/api")
+
+
+@api.route("/")
+def index():
+    """Main API index route - placeholder."""
+    return "Hello, World!"

dm_mac/views/machine.py

@@ -0,0 +1,30 @@
+"""Views related to machine endpoints."""
+from typing import Any, Dict
+from flask import Blueprint, request, app
+
+
+machine: Blueprint = Blueprint("machine", __name__, url_prefix="/machine")
+
+
+@machine.route("/update", methods=['POST'])
+def update():
+    """
+    API method to update machine state.
+
+    Accepts POSTed JSON containing the following key/value pairs:
+
+    - "name" (string) - name of the machine sending the update
+    - "rfid_value" (string) - value of the RFID fob/card that is currently
+        present in the machine, or empty string if none present
+    - "relay_state" (boolean) - the current on/off (true/false) state of the
+        relay
+    - "oops" (boolean) - whether the oops button is pressed, or has been pressed
+        since the last check-in
+    - "amps" (float) - amperage value from the current clamp ammeter, if present,
+        or 0.0 otherwise.
+    """
+    data: Dict[str, Any] = request.json
+    machine_name: str = data.pop('name')
+    # get the MachineState object for this machine, or else return an error
+    #    that error should be formatted for display on the device (helper method for this)
+    # check if this data would update the state; if not, just call noop_update() and return the same display value

machine_access_control-0.1.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jason Antman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

machine_access_control-0.1.0.dist-info/METADATA

@@ -0,0 +1,54 @@
+Metadata-Version: 2.1
+Name: machine_access_control
+Version: 0.1.0
+Summary: Decatur Makers Machine Access Control package
+Home-page: https://github.com/jantman/machine_access_control
+License: MIT
+Author: Jason Antman
+Author-email: jason@jasonantman.com
+Requires-Python: >=3.12,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: flask (>=3.0.3,<4.0.0)
+Project-URL: Changelog, https://github.com/jantman/machine_access_control/releases
+Project-URL: Documentation, https://github.com/jantman/machine_access_control
+Project-URL: Repository, https://github.com/jantman/machine_access_control
+Description-Content-Type: text/markdown
+
+# Decatur Makers Machine Access Control (dm-mac)
+
+[![Project Status: Concept – Minimal or no implementation has been done yet, or the repository is only intended to be a limited example, demo, or proof-of-concept.](https://www.repostatus.org/badges/latest/concept.svg)](https://www.repostatus.org/#concept)
+[![Tests](https://github.com/jantman/machine_access_control/workflows/Tests/badge.svg)](https://github.com/jantman/machine_access_control/actions?workflow=Tests)
+
+This is a software and hardware project for using RFID cards/fobs to control use of various power tools and equipment in the [Decatur Makers](https://decaturmakers.org/) makerspace. It is made up of custom ESP32-based hardware (machine control units) controlling power to each enabled machine and running ESPHome, and a central access control/management/logging server application written in Python/Flask. Like our [“glue” server](https://github.com/decaturmakers/glue) that powers the RFID-based door access control to the makerspace, dm-mac uses the [Neon CRM](https://www.neoncrm.com/) (or a local flat-file when in development mode) as its backend datastore.
+
+## Software Components
+
+At a high level, the system is made up of the central control server and the ESPHome configuration for the ESP32’s.
+
+### Control Server
+
+This is a Python/Flask application that provides authentication and authorization for users via RFID credentials, control of the ESP32-based machine control units;, and logging and monitoring as well as basic management capabilities.
+
+**Why not use the Glue server?** First, because the glue server is currently running in a cloud hosting provider. That makes sense for its purpose, but less so for direct control of physical machines in our space. We want the machine access control system to always function, regardless of the state of our Internet connection, with low latency. We also aren’t concerned about reliability through a power outage, as that will also prevent the controlled machines from working. Secondly, having the business logic contained in a central server with relatively “dumb” machine control units on the machines allows for simpler management of the system.
+
+### Machine Control Unit Software
+
+The machine control units run ESPHome, because it is well-supported with an active community, requires minimal programming (just a YAML configuration), and allows updating and managing many devices wirelessly from a central point. The machine control units (and their ESPHome configuration) are relatively simple - they just react to events (RFID card insertion or removal, button press, or a timer ticking), send their current state to the control server via a HTTP POST, and receive a response with the intended state of their outputs (control relay, LCD screen, LEDs). All of the logic of the system is contained in the central control server.
+
+In the event of an extended control server outage, special event, or other exigent circumstance, the machine control unit software is configured with a list of permanently-authorized RFID cards that will enable the machine without requiring authorization from the control server.
+
+## Installation
+
+It's recommended to install and run via Docker. Details TBD.
+
+## Contributing and Development
+
+Contributions are very welcome. To learn more, see the [Contributor Guide](https://github.com/jantman/machine_access_control/blob/main/CONTRIBUTING.md).
+
+## License
+
+Distributed under the terms of the [MIT license](https://github.com/jantman/machine_access_control/blob/main/LICENSE), _Machine_Access_Control_ (`dm_mac`) is free and open source software.
+

machine_access_control-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+dm_mac/__init__.py,sha256=_uuRQaFFpWBEakxBpf-SjspfrT7arO1YWQOWGSOO1cU,256
+dm_mac/machine_state.py,sha256=yzIGjqebHa_M-fg4rOff9MggccO91LgsIZUFOZ1jRJI,2810
+dm_mac/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dm_mac/views/__init__.py,sha256=U79DC2wZ9YQSJJfdwuS5Ben45AIvO-oPHpinq39KNwQ,30
+dm_mac/views/api.py,sha256=InNokuWIV_C7GxsNNN2MkFL_yTpzkR8ouvaQytYpCUA,215
+dm_mac/views/machine.py,sha256=mMUcc1l4kEhKbTC73A7hM3pik9TGThw46wYvigDBSmA,1251
+machine_access_control-0.1.0.dist-info/LICENSE,sha256=TeKo6ThhJh4LJ9xJziWpGNKpBA2Ojnweppy0rzaRbDw,1069
+machine_access_control-0.1.0.dist-info/METADATA,sha256=lN0V-osN4I588WZTPGEu9Q6EH3Ne7Kxnvha2LgbhmQw,4416
+machine_access_control-0.1.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+machine_access_control-0.1.0.dist-info/RECORD,,

machine_access_control-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.9.0
+Root-Is-Purelib: true
+Tag: py3-none-any