search

uhppoted / uhppoted-app-home-assistant

UHPPOTE controller integration with Home Assistant
MIT License
8 stars 1 forks source link
access-control home-assistant uhppote

readme

build nightly

uhppoted-app-home-assistant

UHPPOTE controller custom component for Home Assistant.

Development status: ALPHA

uhppoted-app-home-assistant is an experimental Home Assistant custom component for the UHPPOTE access controllers, leveraging the uhppoted-python library. It turns out that an access control system has quite a lot more moving parts than e.g. your average thermostat, and the current implementation, although functional and usable, is intended more for the (brave) early adopter.

The current version is most suited to a small'ish home ACS i.e. a couple of controllers with half a dozen doors and maybe a ten or so access cards - so, not a large mansion or an office building.

Contents

  1. Screenshots
  2. Installation
  3. Configuration
  4. Service API

Screenshots

Release Notes

Current Release

v0.8.9 - 2024-09-06

  1. Added support for (optional) TCP connections to controllers.
  2. Fixed support for multiple uhppoted instances.
  3. Removed port from config- and option-flow UI (can still be configured in configuration.yaml).

Installation

Alpha Release

NOTE: The Alpha release is a first release and is entirely use at your own risk/discretion. It has had very limited testing - you probably won't lock yourself out of your own home (unless of course it's late at night and pouring with rain, in which case it's inevitable) but please do have a backup plan (which may or may not include a fire axe). It is also reasonably likely that future releases may require you to reconfigure your system again i.e. it is for the brave and adventurous who like living on the edge.

The installation below is entirely manual and installs the project as a Home Assistant custom component.

  1. Create the config/custom_components subdirectory under the Home Assistant folder (if it does not already exist) and create the __init.py__ file:
cd <Home Assistant>
mkdir -p config/custom_components
touch config/custom_components/__init.py__
  1. Download the .tar.gz archive from the [Releases]() section of the repository (or the most recent nightly build) and extract it to the config/custom_components folder under the Home Assistant folder, e.g.:
cd <Home Assistant>
cd config/custom_components
tar xvzf uhppoted-app-homeassistant.tar.gz .

  1. (Optionally), add the default configuration to the configuration.yaml file in the config folder of Home Assistant, e.g.:

    ...
uhppoted:
bind_address: 192.168.1.100
broadcast_address: 192.168.1.255:60000
listen_address: 192.168.1.100:60001
timezone: LOCAL
debug: false
max_cards: 10
preferred_cards: 
    - 10058400
    - 10058401
card_PINs: false
controllers_poll_interval: 30
doors_poll_interval: 30
cards_poll_interval: 30
events_poll_interval: 30
...

  2. Start (or restart) Home Assistant and confirm there are no errors in the logs.

  3. Configure your UHPPOTE controllers:

    • Open the Settings page
    • From the Settings page, open the Devices and Services page
    • Click on the Add Integration button
    • Search for uhppoted
    • Step through the configuration flow to set up the initial system configuration
    • Add the entities to cards on the desktop (examples in the screenshots above)

Building from source

The suggested installation for the development version installs the cloned project as a symbolic link under the Home Assistant config/custom_components folder. Be warned - the development version changes almost daily and is completely NOT guaranteed to be any kind of stable. You could quite conceivably lock yourself out of your apartment, your house, the planet or possibly the entire galaxy. At the very least expect to have to reconfigure your system often. You have been warned :-).

  1. Clone the uhppoted-app-home-assistant repo to a folder that is NOT under the Home Assistant folder, e.g.:
cd ~/experimental-stuff
git clone https://github.com/uhppoted/uhppoted-app-home-assistant
  1. Create the config/custom_components subdirectory under the Home Assistant folder, if it does not already exist and create the __init.py__ file:
cd <Home Assistant>
mkdir -p config/custom_components
touch config/custom_components/__init.py__
  1. Create a symbolic link to the uhppoted-add-home-assistant folder in the config/custom_components folder.
ln -s ~/experimental-stuff/uhppoted-app-home-assistant/custom_components/uhppoted config/custom_components/uhppoted

(for Windows users: https://superuser.com/questions/1020821/how-can-i-create-a-symbolic-link-on-windows-10)

  1. (Optionally), add the default configuration to the configuration.yaml file in the config folder of Home Assistant, e.g.: 
    ...
uhppoted:
bind_address: 192.168.1.100
broadcast_address: 192.168.1.255:60000
listen_address: 192.168.1.100:60001
timezone: LOCAL
debug: false
max_cards: 10
preferred_cards: 
    - 10058400
    - 10058401
card_PINs: false
controllers_poll_interval: 30
doors_poll_interval: 30
cards_poll_interval: 30
events_poll_interval: 30
...

Configuration

  1. Open the Home Assistant/Settings page.
  2. Open the Devices & Services page.
  3. Select the Integrations tab and then select Add integration.
  4. Search for uhppoted and open the uhppoted custom integration item.
  5. Enter the bind, broadcast, listen addresses and (optionally) enable debug.
  6. Select the controllers to manage with Home Assistant from the list of controllers found on the LAN.
  7. For each controller:
    • choose a unique name e.g. Main, Controller #1, etc.
    • (optional) set the controller IP address
    • (optional) set the controller protocol (defaults to UDP).
    • (optional) set the controller timezone (defaults to Local)
  8. For each controller, select the doors to manage with Home Assistant
  9. For each selected door:
    • choose a unique name e.g. Entrance, Garage, Man Cave
  10. Select the cards to be managed by Home Assistant from the list of cards found on the controllers
  11. For each selected card:
    • enter the name of the person (or other entity) using that card
  12. On completion of configuration the uhppoted service will create all the entities for the controllers, doors and cards.
  13. Add selected information to the dashboard from the entities listed below.

Entities

Controllers

  1. uhppoted.controller.{controller}.info
  2. uhppoted.controller.{controller}.datetime
  3. uhppoted.controller.{controller}.event

Doors

  1. uhppoted.door.{door}.info
  2. uhppoted.door.{door}.open
  3. uhppoted.door.{door}.lock
  4. uhppoted.door.{door}.button
  5. uhppoted.door.{door}.mode
  6. uhppoted.door.{door}.delay
  7. uhppoted.door.{door}.unlock
  8. uhppoted.door.{door}.open.event
  9. uhppoted.door.{door}.button.event
  10. uhppoted.door.{door}.unlocked.event

Cards

  1. uhppoted.card.{card}.info
  2. uhppoted.card.{card}.cardholder
  3. uhppoted.card.{card}.start-date
  4. uhppoted.card.{card}.end-date
  5. uhppoted.card.{card}.{door}
  6. uhppoted.card.{card}.pin
  7. uhppoted.card.{card}.swipe.event

Off-LAN controllers

Controllers that are not on the local LAN segment are not discoverable and have to be added manually to the uhppoted section of the Home Assistant configuration.yaml file (in the config folder), e.g.:

...
uhppoted:
    ...
    controllers:
        - 
            controller: 504030201
            address: 192.168.1.100
        - 
            controller: 605040302
            address: 192.168.1.100
            port: 60000
            protocol: UDP
        - 
            controller: 706050403
            address: 192.168.1.100
            port: 54321
            protocol: TCP
            timeout: 0.56
...

The controllers subsection is a YAML array/list of controllers with the following properties;

The controllers listed in configuration.yaml are included in the list of discovered controllers and can be configured from the Home Assistant user interface in the same way as local controllers i.e. controllers listed in configuration.yaml are NOT automatically added to the list of managed controllers - they do still need to be configured.

configuration.yaml

The operational configuration can be customised by the (entirely optional) setttings in the uhppoted section of the Home Assistant configuration.yaml file (in the Home Assistant config folder). The full list of configurable settings comprises:

Setting Description Default value
bind_address Default IPv4 UDP bind address 0.0.0.0
broadcast_address Default IPv4 UDP broadcast address 255.255.255.255
listen_address Default IPv4 UDP listen address (for events) 0.0.0.0
timezone Default controller timezone local
timeout Default timeout for controller requests/responses (seconds) 2.5
debug Enables/disables logging of controller packets false
max_cards Max. cards to 'discover' for configuration 10
preferred_cards YAML list of of cards that take priority for 'discovery' - none -
card_PINs Enables/disables retrieving/setting card PINs false
controllers_poll_interval Interval at which to fetch controller information (seconds) 30
doors_poll_interval Interval at which to fetch door information (seconds) 30
cards_poll_interval Interval at which to fetch card information (seconds) 30
events_poll_interval Interval at which to fetch missed/synthetic events (seconds) 30
controllers List of off-LAN controllers (see above) -none-

e.g.

uhppoted:
    bind_address: 192.168.1.100
    broadcast_address: 192.168.1.255:60000
    listen_address: 192.168.1.100:60001
    debug: false
    timezone: CEST
    timeout: 1.23
    max_cards: 7
    preferred_cards: 
        - 10058400
        - 10058401
    card_PINs: true
    controllers_poll_interval: 29
    doors_poll_interval: 31
    cards_poll_interval: 33
    events_poll_interval: 35
    controllers:
        - 
            controller: 504030201
            address: 192.168.1.100
            port: 54321
        - 
            controller: 605040302
            address: 192.168.1.100
            port: 54321
        - 
            controller: 706050403
            address: 192.168.1.100
            port: 54321
            protocol: TCP
            timeout: 0.56

Service API

unlock-door

Unlocks a door by name - the name is case- and space-insensitive.

Example:

service: uhppoted.unlock_door
data:
  door: Gryffindor

add-card

Adds a card to all the controllers configured by the uhppoted service. The card is not added to the list of configured cards - to include the card in the managed cards, open the CONFIGURE section for the uhppoted service (under Settings/Devices & Services/uhppoted).

Example:

service: uhppoted.add_card
data:
  card: 10058400

delete-card

Delets a card from all the controllers configured by the uhppoted service. The card is not removed from the list of configured cards - to remove the card from the managed cards, open the CONFIGURE section for the uhppoted service (under Settings/Devices & Services/uhppoted).

Example:

service: uhppoted.delete_card
data:
  card: 10058400