node-red-contrib-uhppoted

Node-RED module that implements an API for interacting with a UHPPOTE TCP/IP Wiegand access controller board. The API supports controller and card management as well support for controller events.

PLEASE NOTE

As of v1.1.8 the controllers list in the config is being deprecated in favour of using a controller object in the input message payload to a uhppoted node. The legacy implementation will be supported until at least the next major release but you are encouraged to update your flows.

For more information see the controllers section.

Release Notes

Current Release

v1.1.8 - 2024-09-06

1. Added TCP transport.
2. Replaced ip.js dependency with local module.
3. Deprecating controllers list in config.

Requirements:

• node‑red version 2.2.3+
• node.js version 14.18.3+

For the latest updates see the CHANGELOG.md

Installation

To install the stable version use the Menu - Manage palette option and search for node-red-contrib-uhppoted, or run the following command in your Node-RED user directory (e.g. ~/.node-red on MacOS and Linux):

npm install node-red-contrib-uhppoted

Restart your Node-RED instance and you should have the uhppoted nodes available in the palette.

If you want to try the development version from the node‑red‑contrib‑uhppoted github repository:

cd ~/.node-red/node_modules
git clone https://github.com/uhppoted/node-red-contrib-uhppoted.git
cd node-red-contrib-uhppoted
npm install

Upgrading from v0.x

Please note that updating from node-red-contrib-uhppoted v0.x to v1.x is a breaking change. node-red-contrib-uhppoted v1.0 fixed node name conflicts with other NodeRED modules and unfortunately changing node names throughout requires a breaking change.

Please see:

• Issue #11: config node name conflict for the original cause
• Discussion: prefixing all nodes with uhppoted- to avoid naming conflicts for any comments and further discussion.
• HOWTO: Migrating a NodeRED flow from v0.9.x to v1.0.x

Nodes

Node	Description
get‑devices	Fetches a list of access controllers on the local LAN
get‑device	Retrieves the information for a single access controller
set‑ip	Sets the controller IP address, net mask and gateway address
get‑status	Retrieves the current controller status
get‑time	Retrieves the current controller date and time
set‑time	Sets the controller date and time
get‑door‑control	Retrieves the control configuration for a controller door
set‑door‑control	Sets the control configuration for a controller door
open‑door	Remotely opens a controller door
get‑card	Retrieves a card record from a controller
get‑card-by-index	Retrieves a card record from a controller by record number
put‑card	Adds or updates a card record on a controller
delete‑card	Deletes a card record from a controller
delete‑all‑cards	Deletes all card records stored on a controller
get-time-profile	Retrieve a time profile from a controller
set-time-profile	Defines a time profile on a controller
clear-time-profiles	Deletes all time profiles defined on a controller
clear-task-list	Clears a controller task list
add-task	Adds a new task to a controller's task list
refresh-task-list	Refreshes a controller task list
record-special-events	Enables or disables door events
get‑event‑index	Retrieves the current event index from a controller
set‑event‑index	Sets the current event index on a controller
get‑event	Retrieves a single event from a controller
set-pc-control	Delegates access control to an offboard application
set-interlock	Sets the controller door interlock mode
activate-keypads	Activates/deactivates the reader access keypads
set-door-passcodes	Sets the supervisor keypad passcodes for a door
restore-default-parameters	Resets a controller to the manufacturer default configuration
listen	Establishes a listening connection for controller events

All nodes take a message with JSON object payload as input and send a message with a JSON object payload as output.

Configuration

The nodes can (optionally) accept a configuration that overrides the default settings:

	Description	Default
timeout	Request execution timeout (in milliseconds)	5000
bind	UDP address to bind to for requests	0.0.0.0
broadcast	UDP address for broadcast requests	255.255.255.255
listen	UDP address:port on which to listen for events	0.0.0.0:60000
controllers	List of controller specific IPv4 address:port overrides for systems where a controller is either not located on the same LAN (i.e. cannot receive or respond to UDP broadcasts) or where directed UDP messages are preferred.	(none)
debug	Enables logging of request/response messages to the console	false

Controllers

All nodes (other than get-devices) expect a controller in the input message payload. v1.1.8+ supports two formats for the controller:

• the (legacy) implementation which expects the controller serial number as a device ID:

{
    "deviceId": 405419896
}

• the revised implementation which expects the controller as an object:

{
    "controller": {
        "id": 405419896,
        "address": "192.168.1.100",
        "protocol": "tcp"
    }
}

- id: controller serial number
- address: controller IPv4 address (optional)
- protocol: 'udp' or 'tcp' (optional)

Defaults to UDP broadcast transport if the address is null or the protocol is not 'tcp'.

NOTE:

The legacy implementation will be supported until at least the next major release but any future enhancements will expect the controller object and you are encouraged to update your flows accordingly.

In most cases, this is simply a matter of updating the input message payload to a uhppoted node from e.g.:

{
    "deviceId": 405419896,
    "cardNumber": 10058400
}

to

{
    "controller": {
        "id": 405419896
    },
    "cardNumber": 10058400
}

Examples

The node‑red‑contrib‑uhppoted github repository includes a set of basic examples that demonstrate the usage of each node, as well as a more complex dashboard project that combines the nodes to create a dashboard:

Node	Description
1‑get‑devices	Example flow for the get‑devices node
2‑get‑device	Example flow for the get‑device node
3‑set-ip	Example flow for the set‑ip node
4‑event-listener	Example flow for the listen. get-listener and set‑listener nodes
5‑get-status	Example flow for the get‑status node
6‑time	Example flow for the get‑time and set‑time nodes
7‑doors	Example flow for the get‑door‑control, set‑door‑control, open‑door, activate-keypads and set-interlock nodes
8‑cards	Example flow for the get‑cards, get‑card, get‑card‑by‑index, put‑card, delete‑card and delete‑cards nodes
9-time-profiles	Example flow for the get-time-profile, set‑time-profile and clear-time-profiles nodes
10-tasklist	Example flow for the clear-task-list, add-task and refresh-task-list nodes
11-events	Example flow for the record-special-events, get‑event‑index, set‑event‑index and get‑event nodes
12-set-pc-control	Example flow for the set-pc-control node
13-restore-default-parameters	Example flow for the restore-default-parameters node

The dashboard example requires the following additional components to be installed into the palette:

• node-red-node-ui-list
• node-red-node-ui-table

Issues and Feature Requests

Please create an issue in the node‑red‑contrib‑uhppoted github repository.

License

MIT