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

v0.8.9 - 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