Uhppoted NPM | npm.io

NPM

NodeJS module that implements an API for interacting with a UHPPOTE TCP/IP Wiegand access controller board. The API supports device and card management as well as handling for events.

Requirements:

node.js version 14.18.3+

For the latest updates see the CHANGELOG.md

Installation

npm install uhppoted

Release Notes

Current Release

v0.8.9 - 2024-09-06

Added support for TCP connections to controllers.
Removed dependency on ip.js.

API

getDevices fetches a list of access controllers on the local LAN
getDevice retrieves the information for a single access controller
setIP sets the controller IP address, net mask and gateway address
getTime retrieves the current controller date and time
setTime sets the controller date and time
getDoorControl retrieves the controller door delay and control
setDoorControl sets the delay and control mode for a door
getListener retrieves the IP address:port to which controller events are sent
setListener sets the IP address:port to which controller events are sent
recordSpecialEvents enables or disables door open and close input events
getStatus retrieves a controller status
getCards retrieves the number of card records on a controller
getCard retrieves a card record from a controller
getCardByIndex retrieves a card record by record number
putCard creates or updates a card record on a controller
deleteCard deletes a card record from a controller
deleteCards deletes all card records from a controller
getTimeProfile retrieves a time profile from a controller
setTimeProfile creates or updates a time profile on a controller
clearTimeProfiles deletes all time profiles from a controller
clearTaskList clears the task list on a controller
addTask adds a new task to the task list on a controller
refreshTaskList refreshes the task list on a controller
getEvents retrieves the indices of the first and last event records stored on a controller
getEvent retrieves an event from a controller
getEventIndex retrieves the event index user value from a controller
setEventIndex sets the event index user value on a controller
openDoor remotely unlocks a door
setPCControl enables or disables remote access management
setInterlock sets controller door interlock mode
activateKeypads activates and deactivates controller reader access keypads
setDoorPasscodes sets door supervisor passcodes
restoreDefaultParameters resets the controller configuration to the manufacturer default settings
listen establishes a listening connection for controller events

Each API call:

takes a context object as the first argument
takes a controller argument as the second argument
takes the function specific parameters
returns a Promise that resolves to a response.

NOTE: getDevices is the sole function that does not take a controller argument.

Example

const uhppoted = require('uhppoted')

const bind = '0.0.0.0'
const broadcast = '255.255.255.255:60000'
const listen = '0.0.0.0:60001'
const timeout = 2500
const debug = true

const ctx = {
  config: new uhppoted.Config('example', bind, broadcast, listen, timeout, [], debug)
}

uhppoted.getDevice(ctx, 405419896)
  .then(response => {
    console.log('\nget-device:\n', response)
  })
  .catch(err => {
    console.log(`\n   *** ERROR ${err.message}\n`)
  })

A minimal example showing the usage for each API can be found in the examples folder. The examples have uhppoted as a dependency - install either the published uhppoted module in the examples folder:

cd examples
npm install uhppoted

or if working from a cloned repository, install the development version:

cd examples
npm install ..

Context

A context object comprises:

   {
      config: { ... },
      locale: string,
      logger: function
   }

All context fields are optional and defaults will be used if not provided. The config field is a configuration object comprising:

   {
      name: string,
      bind: string,
      broadcast: string,
      listen: string,
      timeout: integer,
      devices: [..],
      debug: bool
   }

where:

name is an identifying string. Defaults 'uhppoted'.
bind is the IP address:port to which to bind for requests. Defaults to '0.0.0.0:0'.
broadcast is the IP address:port to which to send requests. Defaults to '255.255.255.255:60000'.
listen is the IP address:port on which to listen for events. Defaults to '0.0.0.0:60001'.
timeout is maximum time to wait for a response, in milliseconds. Default to 5000.
devices is an optional list of controller specific configuration information.
debug displays debugging information if true. Defaults to false.

The devices list comprises an array of device specific information for controllers that are not reachable using UDP broadcast on the local LAN:

   {
     deviceId: integer,
     address: string,
     forceBroadcast: bool
   }

where:

deviceId is the serial number of the controller
address is the device IP address and port, formatted as address:port
forceBroadcast ensures the use of UDP broadcast to send requests to the controller

The locale string corresponds to one of the supported locales:

en-US

and defines the translation of string literals in the responses and error messages. It defaults to en-US if not supplied or if the provided locale is not supported.

The logger function takes a single message parameter and logs it as appropriate to the application. The default implementation prepends the date and time to the message and writes it to the console.

`controller`

The controller parameter may be either:

a uint32 value corresponding to the controller serial number (e.g. 405419896)
a { controller, address, protocol } object, where:
- controller is a uint32 value corresponding to the controller serial number
- address is an address:port string corresponding to the controller IPv4 address and port or an {address,port} object. The port is optional and defaults to port 60000 if not specified.
- protocol may be either 'udp' or 'tcp'. The protocol is optional and defaults to 'udp' if not specified.

Some examples:

getDevice(ctx,405419896)
getDevice(ctx,{ controller:405419896 })
getDevice(ctx,{ controller:405419896, address:'192.168.1.100' })
getDevice(ctx,{ controller:405419896, address:'192.168.1.100:60000' })
getDevice(ctx,{ controller:405419896, address:'192.168.1.100:60000', protocol:'tcp' })
getDevice(ctx,{ controller:405419896, address:{ address:'192.168.1.100' }})
getDevice(ctx,{ controller:405419896, address:{ address:'192.168.1.100', port:60000 }})
getDevice(ctx,{ controller:405419896, address:{ address:'192.168.1.100', port:60000 }, protocol:'tcp'})

{controller, address, protocol } is required for TCP connections to controllers. The legacy controller ID form only supports UDP connections.

`getDevices`

Fetches a list of access controllers on the local LAN.

uhppoted.getDevices(ctx)

Returns a list of device objects, e.g.:

[
  {
    deviceId: controller ,
    device: {
      serialNumber: 201020304,
      address: '192.168.1.101',
      netmask: '255.255.255.0',
      gateway: '192.168.1.1',
      MAC: '52:fd:fc:07:21:82',
      version: '0662',
      date: '2020-01-01'
    }
  },
  ...
]

`getDevice`

Retrieves the information for a single access controller.

uhppoted.getDevice(ctx, controller)

controller: serial number of controller or {controller,address,protocol} object

Returns a device object, e.g.:

{
  deviceId: controller ,
  device: {
    serialNumber: 201020304,
    address: '192.168.1.101',
    netmask: '255.255.255.0',
    gateway: '192.168.1.1',
    MAC: '52:fd:fc:07:21:82',
    version: '0662',
    date: '2020-01-01'
  }
   }

`setIP`

Sets the controller IP address, net mask and gateway address.

uhppoted.setIP (ctx, controller, address, netmask, gateway)

controller: serial number of controller or {controller,address,protocol} object
address: IPv4 address of controller
netmask: IPv4 subnet mask of controller
gateway: IPv4 address of the LAN gateway

Returns an empty object, e.g.:

{}

`getTime`

Retrieves the current controller date and time.

uhppoted.getTime (ctx, controller)

controller: serial number of controller or {controller,address,protocol} object

Returns a datetime object, e.g.:

{ deviceId: 405419896, datetime: '2021-06-04 14:29:08' }

`setTime`

Sets the controller date and time.

uhppoted.setTime (ctx, controller, datetime)

controller: serial number of controller or {controller,address,protocol} object
datetime: YYYY-mm-dd HH:mm:ss

Returns a datetime object, e.g.:

{ deviceId: 405419896, datetime: '2021-06-04 14:29:08' }

`getDoorControl`

Retrieves the controller door delay and control mode for a door.

uhppoted.getDoorControl (ctx, controller, door)

controller: serial number of controller or {controller,address,protocol} object
door: 1-4

Returns a door-control object, e.g.:

{
  deviceId: 405419896,
  doorControlState: { 
    door: 3, 
    delay: 7, 
    control: { value: 3, state: 'controlled' } 
  }
}

`setDoorControl`

Sets the delay and control mode for a door.

uhppoted.setDoorControl (ctx, controller, door, delay, mode)

controller: serial number of controller or {controller,address,protocol} object
door: 1-4
delay: seconds
mode: normally open, normally closed or controlled

Returns a door control object, e.g.:

{
  deviceId: 405419896,
  doorControlState: {
    door: 3,
    delay: 4,
    control: { value: 2, state: 'normally closed' }
  }
}

`getListener`

Retrieves the host:port IP address to which controller events are sent.

uhppoted.getListener (ctx, controller)

controller: serial number of controller or {controller,address,protocol} object

Returns a listener object, e.g.:

{ deviceId: 405419896, address: '192.168.1.100', port: 60001 }

`setListener`

Sets the host:port IP address to which controller events are sent.

uhppoted.setListener (ctx, controller, address, port)

controller: serial number of controller or {controller,address,protocol} object
address: IPv4 address of event listener
port: UDP port on which event listener is expecting events

Returns an updated result object, e.g.:

{ deviceId: 405419896, updated: true }

`recordSpecialEvents`

Enables or disables door open and close input events.

uhppoted.recordSpecialEvents (ctx, controller, enable)

controller: serial number of controller or {controller,address,protocol} object
enable: enables door open and closed events if true

Returns an updated result object, e.g.:

{ deviceId: 405419896, updated: true }

`getStatus`

Retrieves a controller status.

uhppoted.getStatus (ctx, controller)

controller: serial number of controller or {controller,address,protocol} object

Returns a status object, e.g.:

{
  deviceId: 405419896,
  state: {
    serialNumber: 405419896,
    event: {
      index: 69,
      type: [Object],
      granted: true,
      door: 1,
      direction: [Object],
      card: 0,
      timestamp: '2019-08-10 10:28:32',
      reason: [Object]
    },
    doors: { '1': false, '2': false, '3': false, '4': false },
    buttons: { '1': false, '2': false, '3': false, '4': false },
    system: { status: 0, date: '2021-06-04', time: '15:48:07' },
    specialInfo: 0,
    relays: { state: 0, relays: [Object] },
    inputs: { state: 0, forceLock: false, fireAlarm: false }
  }
}

Notes: 1. The event field will contain only the index field (0) if the response does not contain an event. 2. The event timestamp field will be blank if the event timestamp in the response is a zero value.

`getCards`

Retrieves the number of card records stored on a controller. The returned may include deleted records.

uhppoted.getCards (ctx, controller)

controller: serial number of controller or {controller,address,protocol} object

Returns the a cards object, e.g.:

{ deviceId: 405419896, cards: 37 }

`getCard`

Retrieves a single card record from a controller.

uhppoted.getCard (ctx, controller, cardNumber)

controller: serial number of controller or {controller,address,protocol} object
cardNumber: card number

Returns the card record for the card number, e.g.:

{
  deviceId: 405419896,
  card: {
    number: 10058400,
    valid: { from: '2023-01-01', to: '2023-12-31' },
    doors: { '1': true, '2': false, '3': false, '4': true }
    PIN: 0
  }
}

`getCardByIndex`

Retrieves a single card record from a controller by record number.

uhppoted.getCardByIndex (ctx, controller, index)

controller: serial number of controller or {controller,address,protocol} object
index: record index of card

Returns the card record at the index, e.g.:

{
  deviceId: 405419896,
  card: {
    number: 10058400,
    valid: { from: '2023-01-01', to: '2023-12-31' },
    doors: { '1': false, '2': false, '3': false, '4': false },
    PIN: 0
  }
}

Notes: 1. A card number of 0 is returned if the card at the index does not exist. 2. A card number of 0xffffffff (4294967295) is returned if the card at the index has been deleted. (e.g. see examples/get-card-by-index.js)

`putCard`

Adds or updates a single card record on a controller.

uhppoted.putCard (ctx, controller, cardNumber, validFrom, validUntil, doors)

controller: serial number of controller or {controller,address,protocol} object
cardNumber: card number
validFrom: date from which card is valid (YYYY-mm-dd)
validUntil: date after which which card is no longer valid (YYYY-mm-dd)
doors: map of doors to access permissions for the card e.g. { 1: true, 2: false, 3: 29, 4: true }. A permission may be true, false or a time profile in the range 2..254.

Returns a stored result object, e.g.:

{ deviceId: 405419896, stored: true }

`deleteCard`

Deletes a single card record from a controller.

uhppoted.deleteCard (ctx, controller, cardNumber)

controller: serial number of controller or {controller,address,protocol} object
cardNumber: card number

Returns a deleted result object, e.g.:

{ deviceId: 405419896, deleted: true }

`deleteCards`

Deletes all card records stored on a controller.

uhppoted.deleteCards (ctx, controller)

controller: serial number of controller or {controller,address,protocol} object

Returns a deleted result object, e.g.:

{ deviceId: 405419896, deleted: true }

`getTimeProfile`

Retrieves a time profile from a controller.

uhppoted.getTimeProfile (ctx, controller, profileId)

controller: serial number of controller or {controller,address,protocol} object
profileId: time profile ID (in the range 2..254)

Returns the time profile defined (if any) for the profile ID, e.g.:

{
  deviceId: 405419896,
  profile: {
    id: 29,
    valid: { from: '2021-01-01', to: '2021-12-31' },
    weekdays: [ 'Monday', 'Wednesday', 'Friday' ],
    segments: [ 
      { start:'08:30', end:'11:45' },
      { start:'13:15', end:'17:30' }
    ],
    linkedTo: 3
  }

`setTimeProfile`

Creates or updates a time profile on a controller. The time profile may have up to 3 segments and may optionally be linked to another profile to extend the definition.

uhppoted.setTimeProfile (ctx, controller, profile)

controller: serial number of controller or {controller,address,protocol} object
profile: time profile e.g.

{
  deviceId: 405419896,
  profile: {
    id: 29,
    valid: { from: '2021-01-01', to: '2021-12-31' },
    weekdays: [ 'Monday', 'Wednesday', 'Friday' ],
    segments: [ 
      { start:'08:30', end:'11:45' },
      { start:'13:15', end:'17:30' }
    ],
    linkedTo: 3
  }

Returns an updated result object, e.g.:

{ deviceId: 405419896, updated: true }

`clearTimeProfiles`

Deletes all time profiles from a controller.

uhppoted.clearTimeProfiles (ctx, controller)

controller: serial number of controller or {controller,address,protocol} object

Returns a cleared result object, e.g.:

{ deviceId: 405419896, cleared: true }

`clearTaskList`

Clears the task list on controller.

uhppoted.clearTaskList (ctx, controller)

controller: serial number of controller or {controller,address,protocol} object

Returns a cleared result object, e.g.:

{ deviceId: 405419896, cleared: true }

`addTask`

Creates a new task definion on a controller.or updates a time profile on a controller. The task will be activated once refreshTaskList is invoked.

A task definion comprises the following fields:

task type: numeric or string task type from the list below
door: door to which the task is assigned
valid: from/to dates (inclusive) between which the task is active
weekdays: days of the week on which the task is active
start: time at which to run task
cards: (for enable more cards only) number of more cards to allow

Valid task type IDs and the corresponding task types are:

1: door controlled
2: door normallyopen
3: door normallyclosed
4: disable time profile
5: enable time profile
6: card + no password
7: card + IN password
8: card + password
9: enable more cards
10: disable more cards
11: trigger once
12: disable push button
13: enable push button

(the addTask function accepts both numeric and string task types)

uhppoted.addTask (ctx, controller, task)

controller: serial number of controller or {controller,address,protocol} object
task: task definition e.g.

{
  deviceId: 405419896,
  task: {
    task: 'enable time profile',
    door: 3,
    valid: { from: '2021-01-01', to: '2021-12-31' },
    weekdays: [ 'Monday', 'Wednesday', 'Friday' ],
    start:'08:30',
    cards: 3
  }

`refreshTaskList`

Refreshes the task list on controller, activating any tasks added with addTask.

uhppoted.refreshTaskList (ctx, controller)

controller: serial number of controller or {controller,address,protocol} object

Returns a refreshed result object, e.g.:

{ deviceId: 405419896, refreshed: true }

`getEvents`

Retrieves the indices of the first and last event records stored on a controller.

uhppoted.getEvents (ctx, controller)

controller: serial number of controller or {controller,address,protocol} object
index: index of event (1-100000)

Returns an events record, e.g.:

{ deviceId: 405419896, first: 1, last: 70 }

`getEvent`

Retrieves a single event from a controller.

uhppoted.getEvent (ctx, controller, index)

controller: serial number of controller or {controller,address,protocol} object
index: index of event (1-100000)

Returns an event record, e.g.:

{
  deviceId: 405419896,
  event: {
    index: 29,
    type: { code: 2, event: 'door' },
    granted: true,
    door: 1,
    direction: { code: 1, direction: 'in' },
    card: 0,
    timestamp: '2019-08-03 10:34:29',
    reason: { code: 0, reason: '(reserved)' }
  }
}

Notes: 1. The event timestamp field will be blank if the event timestamp in the response is a zero value.

`getEventIndex`

Retrieves the current event index user value from a controller.

uhppoted.getEventIndex (ctx, controller)

controller: serial number of controller or {controller,address,protocol} object

Returns an event-index object, e.g.:

{ deviceId: 405419896, index: 29 }

`setEventIndex`

Sets the current event index user value on a controller.

uhppoted.setEventIndex (ctx, controller, index)

controller: serial number of controller or {controller,address,protocol} object
index: 1-100000

Returns an updated result object, e.g.:

{ deviceId: 405419896, updated: true }

`openDoor`

Remotely unlocks a door.

uhppoted.openDoor (ctx, controller, door)

controller: serial number of controller or {controller,address,protocol} object
door: 1-4

Returns an opened result object, e.g.

{ deviceId: 405419896, opened: true }

`setPCControl`

Enables or disables remote host access control.

When remote host access control is enabled, the controller defers access control decisions to the host - the remote host is expected to listen for card swipe events and open the associated door after verifying the card access permissions.

The controller will revert to local access control if it hasn't received any communication from the host within the last 30 seconds (any command is sufficient - a setPCControl command is not required), but will reassert remote access control mode on receipt of any subsequent message from the host.

Remote access control mode is not volatile and persists across controller restarts.

uhppoted.setPCControl (ctx, controller, enable)

controller: serial number of controller or {controller,address,protocol} object
enable: enables remote host access control if true

Returns an ok result object, e.g.:

{ deviceId: 405419896, ok: true }

`setInterlock`

Sets the controller door interlock mode.

The door interlock prevents a door from opening unless the interlock condition is valid for that door. The controllers support the following modes:

Mode	Description
0 (none)	Any door can opened subject to access restrictions
1 (1&2)	Door 1 can be opened if door 2 is closed and vice versa
2 (3&4)	Door 3 can be opened if door 4 is closed and vice versa
3 (1&2,3&4)	Door 1 can be opened if door 2 is closed and vice versa, Door 3 can be opened if door 4 is closed and vice versa
4 (1&2&3)	Door 1 can be opened if 2 and 3 are both closed, door 2 if 1 and 3 are closed and door 3 if 1 and 2 are closed
8 (1&2&3&4)	A door can only be opened if all the other doors are closed

uhppoted.setInterlock (ctx, controller, 3)

deviceId: serial number of controller
interlock: 0,1,2,3,4 or 8

Returns an ok result object, e.g.:

{ deviceId: 405419896, ok: true }

`activateKeypads`

Activates and deactivates controller reader access keypads. The controller does not provide the functionality to activate or deactivate keypads individually so any keypads not explicitly listed as activated will be deactivated.

uhppoted.activateKeypads (ctx, controller, keypads)

deviceId: serial number of controller
keypads: { 1: true/false, 2: true/false, 3: true/false, 4: true/false }

Returns an ok result object, e.g.:

{ deviceId: 405419896, ok: true }

`setDoorPasscodes`

Assigns up to four passcodes for supervisor access to a door.

uhppoted.setDoorPasscodes (ctx, controller, door, passcodes)

deviceId: serial number of controller
door: door ID 1..4
passcodes: array of up to 4 passcodes in the range 0..999999 (0 corresponds to 'no code')

Returns an ok result object, e.g.:

{ deviceId: 405419896, ok: true }

`restoreDefaultParameters`

Resets the controller configuration to the manufacturer default settings.

uhppoted.restoreDefaultParameters (ctx, controller)

deviceId: serial number of controller

Returns an ok result object, e.g.:

{ deviceId: 405419896, ok: true }

`listen`

Establishes a listening connection for controller events.

uhppoted.listen (ctx, onEvent, onError)

onEvent: function that accepts and processes a received event object
onError: function that accepts and processes an Error object

Example event object:

{
  deviceId: 405419896,
  state: {
    serialNumber: 405419896,
    event: {
      index: 72,
      type: [Object],
      granted: false,
      door: 3,
      direction: [Object],
      card: 8165538,
      timestamp: '2021-06-04 16:37:01',
      reason: [Object]
    },
    doors: { '1': false, '2': false, '3': false, '4': false },
    buttons: { '1': false, '2': false, '3': false, '4': false },
    system: { status: 0, date: '2021-06-04', time: '16:37:01' },
    specialInfo: 0,
    relays: { state: 0, relays: [Object] },
    inputs: { state: 0, forceLock: false, fireAlarm: false }
  }
}