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
Screenshots
v0.8.9.3 - 2024-12-05
- Fixed deprecation warnings in Home Assistant 2024.11.3.
- Added hacs.json file for HACS v2.0.
- Added sample Docker
compose.ymlscripts.
NOTE: The Alpha release is entirely use at your own risk/discretion. It is functional but not even vaguely pretty and is a long way from finished. It has had very limited testing - nobody has as yet reported being locked out of their own home but that may just be because it wasn't late at night and pouring with rain, 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 enjoy living on the edge.
Installing via HACS is by far the simplest:
- Install the HACS integration.
- Open the HACS tab in the Home Assistant sidebar. and add the uhppoted-app-home-assistant github repository as a custom repository (under the Home Assistant Community Store menu).
- Restart Home Assistant to complete the initial installation.
- Open the Settings tab in the Home Assistant sidebar.
- Open the Devices and Integrations section.
- Select Add integration and choose uhppoted.
- Step through the configuration flow to set up the initial system configuration
- Add/edit the entities to the desktop.
- You may need to restart Home Assistant after completing the initial system configuration.
Alternative installation methods are described in the Installation Guide:
- Open the Home Assistant/Settings page.
- Open the Devices & Services page.
- Select the Integrations tab and then select Add integration.
- Search for uhppoted and open the uhppoted custom integration item.
- Enter the bind, broadcast, listen addresses and (optionally) enable debug.
- Select the controllers to manage with Home Assistant from the list of controllers found on the LAN.
- 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)
- For each controller, select the doors to manage with Home Assistant
- For each selected door:
- choose a unique name e.g. Entrance, Garage, Man Cave
- Select the cards to be managed by Home Assistant from the list of cards found on the controllers
- For each selected card:
- enter the name of the person (or other entity) using that card
- On completion of configuration the uhppoted service will create all the entities for the controllers, doors and cards.
- Add selected information to the dashboard from the entities listed below.
uhppoted.controller.{controller}.infouhppoted.controller.{controller}.datetimeuhppoted.controller.{controller}.event
uhppoted.door.{door}.infouhppoted.door.{door}.openuhppoted.door.{door}.lockuhppoted.door.{door}.buttonuhppoted.door.{door}.modeuhppoted.door.{door}.delayuhppoted.door.{door}.unlockuhppoted.door.{door}.open.eventuhppoted.door.{door}.button.eventuhppoted.door.{door}.unlocked.event
uhppoted.card.{card}.infouhppoted.card.{card}.cardholderuhppoted.card.{card}.start-dateuhppoted.card.{card}.end-dateuhppoted.card.{card}.{door}uhppoted.card.{card}.pinuhppoted.card.{card}.swipe.event
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;
controller: controller serial numberaddress: controller IPv4 addressport: (optional) controller UDP port (defaults to 60000)protocol: (optional) controller transport protocol (UDP or TCP - defaults to UDP)timeout: (optional) controller timeout (default to the global uhppoted timeout of 2.5s)
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.
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
Unlocks a door by name - the name is case- and space-insensitive.
Example:
service: uhppoted.unlock_door
data:
door: Gryffindor
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
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