Merge pull request #64 from /issues/34

Fixes #34 - Slack Integration

.pre-commit-config.yaml

@@ -1,46 +1,29 @@
 repos:
-  - repo: local
+  - repo: https://github.com/psf/black
+    rev: 24.10.0
     hooks:
       - id: black
-        name: black
-        entry: black
-        language: system
-        types: [python]
-        require_serial: true
-      - id: darglint
-        name: darglint
-        entry: darglint
-        language: system
-        types: [python]
-        stages: [manual]
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
       - id: end-of-file-fixer
-        name: Fix End of Files
-        entry: end-of-file-fixer
-        language: system
-        types: [text]
-        stages: [commit, push, manual]
         exclude: ^hardware/
+  - repo: https://github.com/PyCQA/flake8
+    rev: 7.1.1
+    hooks:
       - id: flake8
-        name: flake8
-        entry: flake8
-        language: system
-        types: [python]
-        require_serial: true
-        args: ["--ignore=E203,S301,S403,W503,C901", --darglint-ignore-regex, .*]
-      - id: isort
-        name: isort
-        entry: isort
-        require_serial: true
-        language: system
-        types_or: [cython, pyi, python]
-        args: ["--filter-files"]
+        args: ["--ignore=E203,S301,S403,W503,C901"]
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v3.19.0
+    hooks:
       - id: pyupgrade
-        name: pyupgrade
-        description: Automatically upgrade syntax for newer versions.
-        entry: pyupgrade
-        language: system
-        types: [python]
         args: [--py37-plus]
+  - repo: https://github.com/PyCQA/isort
+    rev: 5.13.2
+    hooks:
+      - id: isort
+  - repo: local
+    hooks:
       - id: sphinx
         name: sphinx
         entry: "nox --non-interactive --session=docs"
@@ -71,6 +54,7 @@ repos:
         language: system
         files: "^(src/|tests/).*$"
         types: [python]
+        pass_filenames: false
         # run for every possible stage other than "manual", to prevent
         # a duplicate run in GitHub Actions, which also fails because
         # of a shallow git clone

docs/source/configuration.rst

@@ -3,7 +3,7 @@
 Configuration
 =============
 
-TBD.
+Configuration of the machine-access-control (MAC) server is accomplished by some JSON configuration files and optional environment variables, as detailed below.
 
 .. _configuration.users-json:
 
@@ -27,6 +27,42 @@ The schema of this file is as follows:
 
 .. jsonschema:: dm_mac.models.machine.CONFIG_SCHEMA
 
+.. _configuration.env-vars:
+
+Environment Variables
+---------------------
+
+.. list-table:: Environment Variables
+   :header-rows: 1
+
+   * - Variable
+     - Required?
+     - Description
+   * - ``USERS_CONFIG``
+     - no
+     - path to users configuration file; default ``./users.json``
+   * - ``MACHINES_CONFIG``
+     - no
+     - path to machines configuration file; default ``./machines.json``
+   * - ``MACHINE_STATE_DIR``
+     - no
+     - path to machine state directory; default ``./machine_state``
+   * - ``SLACK_BOT_TOKEN``
+     - no
+     - If using the Slack integration, the Bot User OAuth Token for your installation of the app.
+   * - ``SLACK_APP_TOKEN``
+     - no
+     - If using the Slack integration, the Socket OAuth Token for your installation of the app.
+   * - ``SLACK_SIGNING_SECRET``
+     - no
+     - If using the Slack integration, the Signing Secret for your installation of the app.
+   * - ``SLACK_CONTROL_CHANNEL_ID``
+     - no
+     - If using the Slack integration, the Channel ID of of the private channel for admins to control MAC.
+   * - ``SLACK_OOPS_CHANNEL_ID``
+     - no
+     - If using the Slack integration, the Channel ID of of the public channel where Oops and maintenance notices will be posted, and where machine status can be checked.
+
 .. _configuration.machine-state-dir:
 
 Machine State Directory

docs/source/contributing.rst

@@ -56,7 +56,7 @@ Running Locally
 
 .. code:: console
 
-   $ flask --app dm_mac run
+   $ mac-server --debug
 
 The app will now be available at http://127.0.0.1:5000
 

docs/source/dm_mac.rst

@@ -24,4 +24,5 @@ Submodules
 
    dm_mac.cli_utils
    dm_mac.neongetter
+   dm_mac.slack_handler
    dm_mac.utils

docs/source/dm_mac.slack_handler.rst

@@ -0,0 +1,8 @@
+dm\_mac.slack\_handler module
+=============================
+
+.. automodule:: dm_mac.slack_handler
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:

docs/source/hardware.rst

@@ -37,7 +37,7 @@ This is intended to work with `esphome-configs/2024.6.4/no-current-input.yaml </
 .. image:: ../../hardware/v1_mcu/Hardware_v1.png
    :alt: Wiring diagram of system
 
-* RFID Reader
+* RFID Reader - Note that if using the same model that I did, you must add a solder blob on ``S2`` for Wiegand output.
 
   * ``CST`` to ``GPIO25``
   * ``Gnd`` to ground
@@ -63,9 +63,9 @@ This is intended to work with `esphome-configs/2024.6.4/no-current-input.yaml </
 
 * Neopixel
 
-  * ``5v`` to ``5v``
-  * ``Gnd`` to ``Gnd``
-  * ``D1`` to Level Converter ``HV4`` to ``GPIO27``
+  * ``5v`` to ``5v`` (often red)
+  * ``Gnd`` to ``Gnd`` (often blue)
+  * ``D1`` to Level Converter ``HV4`` to ``GPIO27`` (often white)
 
 * LCD Display
 
@@ -74,22 +74,22 @@ This is intended to work with `esphome-configs/2024.6.4/no-current-input.yaml </
   * ``SDA`` to Level Converter ``HV2`` to ``GPIO22``
   * ``SCL`` to Level Converter ``HV3`` to ``GPIO23``
 
-* Optoisolated Relay
+* Optoisolated Relay - Output is N.O.
 
   * ``Gnd`` to ``Gnd``
   * ``In`` to ``GPIO33``
   * ``VCC`` to ``3v3``
 
 * GX16-8 (8 pin) connector for power, control, and additional inputs. The MCU should have the female socket which has visible pins in it, and the wire going to it should have the male plug which has a bakelite housing that accepts those pins. Note that GX16-8 connectors have an alignment notch, a ring of 7 contacts, and one central contact. Contacts are numbered 1-7 clockwise from the alignment notch with 8 in the center.
 
-  * ``1`` to +5VDC power in
-  * ``2`` to power supply ground
-  * ``3`` to relay input / common
-  * ``4`` to relay output Normally Open
-  * ``5`` to ESP32 ``GPIO12`` for tamper switch (not yet implemented in software)
-  * ``6`` to ESP32 ``GPIO14`` for future use
-  * ``7`` reserved for future ammeter / current clamp use (not implemented in V1)
-  * ``8`` reserved for future ammeter / current clamp use (not implemented in V1)
+  * ``1`` to +5VDC power in (red)
+  * ``2`` to power supply ground (black)
+  * ``3`` to relay input / common (green)
+  * ``4`` to relay output Normally Open (green or brown)
+  * ``5`` to ESP32 ``GPIO12`` for tamper switch (not yet implemented in software) (blue)
+  * ``6`` to ESP32 ``GPIO14`` for future use (white)
+  * ``7`` reserved for future ammeter / current clamp use (not implemented in V1) (yellow)
+  * ``8`` reserved for future ammeter / current clamp use (not implemented in V1) (yellow or orange)
 
 .. _hardware.v1.enclosure:
 

docs/source/index.rst

@@ -10,6 +10,7 @@
    Introduction <introduction>
    Installation <installation>
    Configuration <configuration>
+   Slack Integration <slack>
    Hardware <hardware>
    Administration <admin>
    Contributing and Development <contributing>

docs/source/slack.rst

@@ -0,0 +1,55 @@
+.. _slack:
+
+Slack Integration
+=================
+
+machine-access-control (MAC) offers a Slack integration for logging and control.
+
+.. _slack.setup:
+
+Setup
+-----
+
+To set up the Slack integration:
+
+1. `Create a new Slack app <https://api.slack.com/apps?new_app=1&track=hello-world-bolt>`_
+
+   1. Create your new app "from scratch".
+   2. Set a meaningful name, such as ``machine-access-control`` and create the app in your Workspace.
+   3. In the left menu, navigate to ``OAuth & Permissions``.
+   4. In the "Scopes" pane, under "Bot Token Scopes", click "Add an OAuth Scope" and add scopes for ``app_mentions:read``, ``canvases:read``, ``canvases:write``, ``channels:read``, ``chat:write``, ``groups:read``, ``groups:write``, ``incoming-webhook``, ``users.profile:read``, and ``users:read``.
+
+2. In your workspace, create a new private channel for admins to interact with MAC in, and MAC to post status updates to.
+3. In the left menu, navigate to ``Install App``. Click on the button to install to your workspace. When prompted for a channel for the app to post in, select the private channel that you created in the previous step.
+4. On the next screen, ``Installed App Settings``, copy the ``Bot User OAuth Token`` and set this as the ``SLACK_BOT_TOKEN`` environment variable for the MAC server.
+5. Go back to the main settings for your app and navigate to ``Socket Mode`` under ``Settings`` on the left menu; toggle on ``Enable Socket Mode``. For ``Token Name``, enter ``socket-mode-token`` and click ``Generate``. Copy the generated token and set it as the ``SLACK_APP_TOKEN`` environment variable for the MAC server. If you need to retrieve this token later, it can be found in the ``App-Level Tokens`` pane of the ``Settings -> Basic Information`` page.
+6. Go back to the main settings for your app and navigate to ``Basic Information`` under ``Settings`` on the left menu; in the ``App Credentials`` pane click ``Show`` in the ``Signing Secret`` box and then copy that value; set it as the ``SLACK_SIGNING_SECRET`` environment variable for the MAC server.
+7. Go back to the main settings for your app and navigate to ``Event Subscriptions`` under ``Features`` on the left menu; click the toggle in the upper left of the panel to Enable Events; under ``Subscribe to bot events`` add a subscription for ``app_mention``.
+
+.. _slack.configuration:
+
+Configuration
+-------------
+
+1. Set :ref:`configuration.env-vars` as described in :ref:`slack.setup`, above.
+2. If you don't already have one, create a private channel for the people who will be allowed to control MAC (i.e. clear Oopses and lock-out/unlock machines).
+3. Invite your bot user to that channel by at-mentioning the bot username.
+4. In that channel, click on the channel name to pull up the channel information tab, and copy the Channel ID (a string beginning with "C") from the bottom of that panel. Set this as the ``SLACK_CONTROL_CHANNEL_ID`` environment variable.
+5. If you don't already have one, create a public channel for the bot to post Oops/maintenance notices in. Invite the bot to that channel via an at-mention. Get the Channel ID and set it as the ``SLACK_OOPS_CHANNEL_ID`` environment variable. Users in this channel will also be able to check machine status.
+
+
+.. _slack.usage:
+
+Usage
+-----
+
+The slack bot is controlled by mentioning its name (``@your-bot-name``) along with a command and optional arguments, in the ``SLACK_CONTROL_CHANNEL_ID`` channel (or, for the status command, any channel that the bot is in).
+
+Using an example bot name of ``@machine-access-control``, the supported commands are:
+
+* ``@machine-access-control status`` - List all machines and their current status. This command is the only one that is usable from channels other than the control channel.
+* ``@machine-access-control oops <machine-name>`` - Set Oops'ed status on the machine with name ``machine-name``. This takes effect immediately, even if the machine is currently in use.
+* ``@machine-access-control lock <machine-name>`` - Set maintenance lock-out status on the machine with name ``machine-name``. This takes effect immediately, even if the machine is currently in use.
+* ``@machine-access-control clear <machine-name>`` - Clear all Oops and/or maintenance lock-out states on the machine with name ``machine-name``.
+
+In addition, changes to all machines' Oops and maintenance lock-out states will be posted as messages in the ``SLACK_OOPS_CHANNEL_ID`` channel.

esphome-configs/2024.6.4/no-current-input.yaml

@@ -1,7 +1,7 @@
 # This config expects the following hardware:
 #
 # - pcf8574 16x2 I2C character LCD connected with SDA on GPIO22 and SCL on GPIO23
-# - wiegand RFID reader connected with d0 on GPIO16, d1 on GPIO4, and card present on GPIO25
+# - wiegand RFID reader connected with d0 on GPIO16, d1 on GPIO4, and card present on GPIO18
 # - oops button connected between GPIO32 and ground, no external resistors (internal pullup)
 # - oops button LED connected directly to GPIO5
 # - output relay on GPIO33
@@ -36,6 +36,8 @@ logger:
   level: DEBUG
 
 api:
+  # don't reboot just because ESPHome isn't connected
+  reboot_timeout: 0s
   encryption:
     key: !secret api_encryption_key
 
@@ -109,15 +111,17 @@ http_request:
 i2c:
   sda: GPIO22
   scl: GPIO23
+  frequency: 400kHz
 
 sensor:
   - platform: uptime
     name: Uptime
     id: uptime_sensor
+    update_interval: 5s
   - platform: wifi_signal # Reports the WiFi signal strength/RSSI in dB
     name: "WiFi Signal dB"
     id: wifi_signal_db
-    update_interval: 60s
+    update_interval: 15s
     entity_category: "diagnostic"
   - platform: copy # Reports the WiFi signal strength in %
     source_id: wifi_signal_db
@@ -134,7 +138,7 @@ sensor:
 
 binary_sensor:
   - platform: gpio
-    pin: GPIO25
+    pin: GPIO18
     name: "Card Present"
     id: card_present
     on_release:

hardware/v1_mcu/README.md

@@ -20,7 +20,7 @@ The connector used for power and control is a GX16-8 style round connector as sp
 
 * M3x4x5mm or M3x6x5mm threaded inserts, qty 4, to secure lid to base.
 * M3x??? socket head cap screws, qty 4, to secure lid to base.
-* M4x16 flat head screws and M4 nylon lock nuts, qty 6 each, to secure RFID pocket to front of enclosure.
+* M4x16 flat head or button head screws and M4 nylon lock nuts, qty 6 each, to secure RFID pocket to front of enclosure.
 * M2.5x6 flat head screws, qty 10
   * 2 each to mount RFID reader to standoffs.
   * 4 each to mount ESP32 carrier board to standoffs.