uhppoted / uhppoted-rest Goto Github PK

8.0 4.0 0.0 674 KB

Go REST API for the UHPPOTE UT0311 TCP/IP access controller boards

License: MIT License

Go 96.44% Makefile 3.07% Dockerfile 0.49%

uhppoted-rest's Introduction

uhppoted (juː hɒp ɪt eɪd)

uhppoted implements a set of cross-platform building blocks for access control systems based on the UHPPOTE UT0311-L0x TCP/IP Wiegand access control boards. Currently available components include:

controller API
CLI for scripting and system administration
REST service for integration with HTTP servers and mobile clients
MQTT endpoint for integration with IOT systems e.g.
AWS S3 integration for file managed access control lists
Google Sheets integration for spreadsheet managed access control lists
Integration with the Wild Apricot member management system
uhppoted-app-db SQL DB integration for access control lists managed in a database
Node-RED low code environment integration
uhppoted-nodejs NodeJS package
uhppoted-python Python package
Home Assistant custom component

The components supplement the manufacturer supplied application which is 'Windows-only' and provides limited support for integration with other systems.

FYA, after much discussion it has been decided that uhppoted is pronounced u-hop-id-ay-d (juː hɒp ɪt eɪd).

Operating systems

Supported operating systems:

Linux
MacOS
Windows
ARM and ARM7 (e.g. RaspberryPi)

Language Bindings

The primary development language for this repository is Go, but code generated native bindings for the following languages also exist:

shared-lib/dylib/DLL

uhppoted-dll implements a shared-lib/DLL for interop with languages other than Go. The implementation includes bindings to:

C
C++
C#
Python
Clozure Common Lisp

3rd party integrations

ioBroker - kBrausew/ioBroker.wiegand-tcpip
Andre Becker has written a short guide to getting up and running with uhppoted-mqtt and OpenHAB using Docker.

Compatible Hardware

As per this issue [Question] Compatible Hardware, UHPPOTE appears to be a specific branding (or distributor) for the access control boards manufactured by Shenzhen Wiegand Industrial Co., Ltd.

The software in this repository has been tested and is known to work with these specific boards:

Source	Item
Amazon	UHPPOTE Professional Wiegand 26-40 Bit TCP IP Network Access Control Board with Software For 4 Door 4 Reader
AliExpress	TCP/IP RFID ACCESS CONTROL SYSTEM Wiegand 26

Firmware versions

Version	Notes
6.56	Minimum firmware version (cf. carbonsphere/UHPPOTE
6.62	Lowest firmware version in use
8.92	Latest tested firmware version

Notes:

Firmware v6.62 sends anomalous listen events with 0x19 as the start of message identifier. This appears to have been fixed in later firmware versions but patches to support these events are included in:

Readers

Almost any reader with a Wiegand-26 interface should probably work (there have been reports of offbrand readers that don't) but the readers below are in active use:

Reader	Notes
HID ProxPoint Plus 6500	Old stock and/or refurbished readers are often available on ebay
IKeys barcode and QR code scanner	Ref. Put Card - Date with Time
Newland FM430L barcode and QR code scanner	Ref. Put Card - Date with Time

Release Notes

Current Release

v0.8.8 - 2024-03-28

Added uhppoted-app-home-assistant experimental Home Assistant integration.
restore-default-parameters function across all subprojects.
Added public Docker images for uhppote-simulator, uhppoted-rest, uhppoted-mqtt, and uhppoted-httpd to ghcr.io.
Bumped Go version to 1.22.
Reworked uhppoted-app-wild-apricot member/group resolution logic.

Modules

Module	Description
uhppote-core	core library, implements the UP interface to UT0311-L0x controllers
uhppoted-lib	common utility function library
uhppote-simulator	UT0311-L04 simulator for development use
uhppote-cli	command line interface
uhppoted-rest	daemon/service with REST API for remote access to UT0311-L0x controllers
uhppoted-mqtt	daemon/service with MQTT endpoint for remote access to UT0311-L0x controllers
uhppoted-app-s3	cron'able utility to download/upload access control lists from/to AWS S3
uhppoted-app-sheets	cron'able utility to download/upload access control lists from/to Google Sheets
uhppoted-app-db	cron'able utility to download/upload access control lists from/to a SQL DB
uhppoted-app-wild-apricot	cron'able utility to manage access control lists from Wild Apricot
uhppoted-app-home-assistant	Home Assistant custom component
node-red-contrib-uhppoted	NodeJS nodes for Node-RED low code environment
uhppoted-nodejs	Standalone NodeJS module
uhppoted-python	Standalone Python package for PyPI
uhppoted-dll	shared-lib/DLL for cross-language interop
uhppoted-codegen	Model based code generator for native language bindings
uhppoted-tunnel	UDP tunnel for remote access

Integrations

Module	Description
uhppoted-app-db	cron'able utility to download/upload access control lists from/to a SQL DB
uhppoted-app-s3	cron'able utility to download/upload access control lists from/to AWS S3
uhppoted-app-sheets	cron'able utility to download/upload access control lists from/to Google Sheets
uhppoted-app-wild-apricot	cron'able utility to manage access control lists from/t Wild Apricot
uhppoted-app-home-assistant	Home Assistant custom component
node-red-contrib-uhppoted	NodeJS nodes for Node-RED low code environment
kBrausew/ioBroker.wiegand-tcpip	ioBroker

UI

Module	Description
uhppote-cli	Command line interface
uhppoted-httpd	HTML browser interface

Installation

Binaries for Linux, Windows, MacOS and Raspbian/ARM7 are distributed in the tarball for each release. To install the binaries, download and extract the tarball to a directory of your choice.

The NodeRED, NodeJS and Python packages are installable from the public repositories:

Building from source

uhppoted is the parent project for the individual components which are referenced as git submodules - to clone the entire source tree:

git clone --recurse-submodules https://github.com/uhppoted/uhppoted.git

The supplied Makefile has targets to build binaries for all the supported operating systems:

make build

make release

To pull upstream changes for all submodules:

git submodule update --remote

Donations

If you like the project and you really want to 🙂:

References and Related Projects

uhppoted-rest's People

Contributors

Stargazers

Watchers

uhppoted-rest's Issues

Rename uhppoted-rest master branch

Rename default branch from master to main in line with current practice.

Open Door API

Thanks for the great project you are making here.
How can I add an endpoint to be able to open a door with the REST API via a simple HTTP GET command?

What would you suggest to do to add authentication to the API before being able to access it?

Thanks!

Expose Put Card in REST API

Put Card appears to be implemented in the core but not the rest API. Any plans to implement that ?

Testing API after install

I downloaded the package and started it

root@door:/home/door/uhppoted_v0.8.6# ./uhppoted-rest -console
2023/10/18 00:13:06 INFO                uhppoted-rest daemon v0.8.x - Linux (PID 4447)
2023/10/18 00:13:06 INFO                START
2023/10/18 00:13:06 INFO   RESTD        ... listening on port 8080
2023/10/18 00:13:11 INFO   watchdog     OK
2023/10/18 00:13:16 INFO   watchdog     OK
2023/10/18 00:13:21 INFO   watchdog     OK
2023/10/18 00:13:26 INFO   watchdog     OK

But when I hit the endpoint, I get
http://10.10.4.7:8080/

Unsupported API

Is this normal? I haven't configured my device ID's or IPs yet. Here is my config:

# SYSTEM
bind.address = 10.10.4.7:0
broadcast.address = 10.10.4.255:60000
listen.address = 10.10.4.7:60001
monitoring.healthcheck.interval = 19s
monitoring.healthcheck.idle = 1m5s
monitoring.healthcheck.ignore = 4m19s
monitoring.watchdog.interval = 6s

# REST
rest.http.enabled = true
rest.http.port = 8080
rest.https.enabled = false
; rest.https.port = 8443
; rest.tls.key = /usr/local/etc/com.github.uhppoted/rest/uhppoted.key
; rest.tls.certificate = /usr/local/etc/com.github.uhppoted/rest/uhppoted.cert
; rest.tls.ca = /usr/local/etc/com.github.uhppoted/rest/ca.cert
; rest.tls.client.certificates = true
rest.CORS.enabled = false
rest.auth.enabled = false
; rest.auth.users = /usr/local/etc/com.github.uhppoted/rest/users
; rest.auth.groups = /usr/local/etc/com.github.uhppoted/rest/groups
; rest.auth.hotp.range = 8
; rest.auth.hotp.secrets =
; rest.auth.hotp.counters = /usr/local/etc/com.github.uhppoted/rest/counters

# OPEN API
# openapi.enabled = false
# openapi.directory = ./openapi

# DEVICES
UT0311-L0x.405419896.name = Alpha
UT0311-L0x.405419896.address = 192.168.1.100:60000
UT0311-L0x.405419896.door.1 = Gryffindor
UT0311-L0x.405419896.door.2 = Hufflepuff
UT0311-L0x.405419896.door.3 = Ravenclaw
UT0311-L0x.405419896.door.4 = Slytherin
UT0311-L0x.405419896.timezone = PDT

UT0311-L0x.303986753.name = Beta
UT0311-L0x.303986753.address = 192.168.1.100:60000
UT0311-L0x.303986753.door.1 = Great Hall
UT0311-L0x.303986753.door.2 = Kitchen
UT0311-L0x.303986753.door.3 = Dungeon
UT0311-L0x.303986753.door.4 = Hogsmeade
UT0311-L0x.303986753.timezone = UTC

Update uhppoted-rest
Update uhppoted-lib healthcheck and watchdog
Update uhppoted-mqtt for reworked healthcheck and watchdog
Check daemonized logging

GetDevices call crashes with "panic: Cannot unmarshal field with type 'types.DateTime'"

uhppoted-rest -config "C:\\ProgramData\\uhppoted\\uhppoted.conf" -console -debug

2021/04/08 09:58:01 uhppoted-rest daemon v0.6.x - Microsoft Windows (PID 9124)
2021/04/08 09:58:01 ... listening on port 8080

... request
...          00000000  17 94 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
...          00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
...          00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
...          00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
...
... sent 64 bytes to 192.168.1.255:60000
... received 64 bytes from 192.168.1.131:60000
...          00000000  17 94 00 00 e5 d8 4f 0d  c0 a8 01 8d ff ff ff 00  |......O.........|
...          00000010  c0 a8 01 01 00 66 0d 4f  d8 e5 08 98 20 19 05 21  |.....f.O.... ..!|
...          00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
...          00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
...
... request
...          00000000  17 20 00 00 e5 d8 4f 0d  00 00 00 00 00 00 00 00  |. ....O.........|
...          00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
...          00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
...          00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
...
... sent 64 bytes to 192.168.1.255:60000
... received 64 bytes from 192.168.1.131:60000
... response
...          00000000  17 20 00 00 e5 d8 4f 0d  00 00 00 00 00 00 00 00  |. ....O.........|
...          00000010  00 00 00 00 00 00 00 00  00 00 00 00 01 01 00 00  |................|
...          00000020  00 00 00 00 00 16 03 34  00 00 00 00 00 00 00 00  |.......4........|
...          00000030  00 00 00 21 04 08 00 00  00 00 00 00 00 00 00 00  |...!............|
...
panic: Cannot unmarshal field with type 'types.DateTime'

goroutine 8 [running]:
github.com/uhppoted/uhppote-core/encoding/UTO311-L0x.unmarshal(0xc00016d800, 0x40, 0x800, 0xb78640, 0xc000076300, 0x199, 0x1c1, 0x380)
       .../github.com/uhppoted/[email protected]/encoding/UTO311-L0x/UT0311-L0x.go:297 +0x1505
       .../github.com/uhppoted/uhppote-core/encoding/UTO311-L0x.Unmarshal(0xc00016d800, 0x40, 0x800, 0xaf0160, 0xc000076300, 0x3, 0x3)
       .../github.com/uhppoted/[email protected]/encoding/UTO311-L0x/UT0311-L0x.go:159 +0x1de
       .../github.com/uhppoted/uhppote-core/uhppote.(*UHPPOTE).receive(0xc000117c20, 0xc000006120, 0xaf0160, 0xc000076300, 0xc0000177c8, 0x0)
       .../github.com/uhppoted/[email protected]/uhppote/uhppote.go:292 +0x350
       .../github.com/uhppoted/uhppote-core/uhppote.(*UHPPOTE).Execute(0xc000117c20, 0xc00d4fd8e5, 0xb32f40, 0xc0000177c8, 0xaf0160, 0xc000076300, 0x0, 0x0)
       .../github.com/uhppoted/[email protected]/uhppote/uhppote.go:154 +0x1e7
       .../github.com/uhppoted/uhppote-core/uhppote.(*UHPPOTE).GetStatus(0xc000117c20, 0xc00d4fd8e5, 0xc0001a3d88, 0xc0001a3d20, 0x1)
       .../github.com/uhppoted/[email protected]/uhppote/get_status.go:16 +0xb2
       .../github.com/uhppoted/uhppoted-rest/commands.healthcheck(0xc000117c20, 0xc000076200, 0xc0000463c0)
       .../uhppoted-rest/commands/run.go:247 +0x3e5
       .../github.com/uhppoted/uhppoted-rest/commands.(*Run).listen.func2(0xc000046410, 0xc000117c20, 0xc000076200, 0xc0000463c0)
       .../uhppoted-rest/commands/run.go:196 +0x65
       created by github.com/uhppoted/uhppoted-rest/commands.(*Run).listen
       .../uhppoted-rest/commands/run.go:193 +0x717

uhppoted.conf

# SYSTEM  THE REST SERVER IP
bind.address = 192.168.1.130:0
broadcast.address = 192.168.1.255:60000
listen.address = 192.168.1.130:60001

# REST
rest.http.enabled = true
rest.http.port = 8080
rest.https.enabled = false
rest.https.port = 8443
rest.CORS.enabled = true
rest.auth.enabled = false