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.
-
node.js
version 14.18.3+ -
ip.js
version 1.1.5+
For the latest updates see the CHANGELOG.md
npm install uhppoted
-
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, followed by the function specific parameters and returns a Promise
that resolves to a response.
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.getDevices(ctx)
.then(response => {
console.log('\nget-devices:\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 ..
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 iftrue
. Defaults tofalse
.
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.
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'
}
},
...
]
Retrieves the information for a single access controller.
uhppoted.getDevice(ctx, deviceId)
-
deviceId
: serial number of controller
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'
}
}
Sets the controller IP address, net mask and gateway address.
uhppoted.setIP (ctx, deviceId, address, netmask, gateway)
-
deviceId
: serial number of controller -
address
: IPv4 address of controller -
netmask
: IPv4 subnet mask of controller -
gateway
: IPv4 address of the LAN gateway
Returns an empty object, e.g.:
{}
Retrieves the current controller date and time.
uhppoted.getTime (ctx, deviceId)
-
deviceId
: serial number of controller
Returns a datetime
object, e.g.:
{ deviceId: 405419896, datetime: '2021-06-04 14:29:08' }
Sets the controller date and time.
uhppoted.setTime (ctx, deviceId, datetime)
-
deviceId
: serial number of controller -
datetime
: YYYY-mm-dd HH:mm:ss
Returns a datetime
object, e.g.:
{ deviceId: 405419896, datetime: '2021-06-04 14:29:08' }
Retrieves the controller door delay and control mode for a door.
uhppoted.getDoorControl (ctx, deviceId, door)
-
deviceId
: serial number of controller -
door
: 1-4
Returns a door-control
object, e.g.:
{
deviceId: 405419896,
doorControlState: {
door: 3,
delay: 7,
control: { value: 3, state: 'controlled' }
}
}
Sets the delay and control mode for a door.
uhppoted.setDoorControl (ctx, deviceId, door, delay, mode)
-
deviceId
: serial number of controller -
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' }
}
}
Retrieves the host:port IP address to which controller events are sent.
uhppoted.getListener (ctx, deviceId)
-
deviceId
: serial number of controller
Returns a listener
object, e.g.:
{ deviceId: 405419896, address: '192.168.1.100', port: 60001 }
Sets the host:port IP address to which controller events are sent.
uhppoted.setListener (ctx, deviceId, address, port)
-
deviceId
: serial number of controller -
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 }
Enables or disables door open and close input events.
uhppoted.recordSpecialEvents (ctx, deviceId, enable)
-
deviceId
: serial number of controller -
enable
: enables door open and closed events if true
Returns an updated
result object, e.g.:
{ deviceId: 405419896, updated: true }
Retrieves a controller status.
uhppoted.getStatus (ctx, deviceId)
-
deviceId
: serial number of controller
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:
- The event field will contain only the index field (0) if the response does not contain an event.
- The event timestamp field will be blank if the event timestamp in the response is a zero value.
Retrieves the number of card records stored on a controller. The returned may include deleted records.
uhppoted.getCards (ctx, deviceId)
-
deviceId
: serial number of controller
Returns the a cards
object, e.g.:
{ deviceId: 405419896, cards: 37 }
Retrieves a single card record from a controller.
uhppoted.getCard (ctx, deviceId, cardNumber)
-
deviceId
: serial number of controller -
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
}
}
Retrieves a single card record from a controller by record number.
uhppoted.getCardByIndex (ctx, deviceId, index)
-
deviceId
: serial number of controller -
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:
- A card number of 0 is returned if the card at the index does not exist.
- 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)
Adds or updates a single card record on a controller.
uhppoted.putCard (ctx, deviceId, cardNumber, validFrom, validUntil, doors)
-
deviceId
: serial number of controller -
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 betrue
,false
or a time profile in the range [2..254].
Returns a stored
result object, e.g.:
{ deviceId: 405419896, stored: true }
Deletes a single card record from a controller.
uhppoted.deleteCard (ctx, deviceId, cardNumber)
-
deviceId
: serial number of controller -
cardNumber
: card number
Returns a deleted
result object, e.g.:
{ deviceId: 405419896, deleted: true }
Deletes all card records stored on a controller.
uhppoted.deleteCards (ctx, deviceId)
-
deviceId
: serial number of controller
Returns a deleted
result object, e.g.:
{ deviceId: 405419896, deleted: true }
Retrieves a time profile from a controller.
uhppoted.getTimeProfile (ctx, deviceId, profileId)
-
deviceId
: serial number of controller -
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
}
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, deviceId, profile)
-
deviceId
: serial number of controller -
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 }
Deletes all time profiles from a controller.
uhppoted.clearTimeProfiles (ctx, deviceId)
-
deviceId
: serial number of controller
Returns a cleared
result object, e.g.:
{ deviceId: 405419896, cleared: true }
Clears the task list on controller.
uhppoted.clearTaskList (ctx, deviceId)
-
deviceId
: serial number of controller
Returns a cleared
result object, e.g.:
{ deviceId: 405419896, cleared: true }
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, deviceId, task)
-
deviceId
: serial number of controller -
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
}
Refreshes the task list on controller, activating any tasks added with addTask
.
uhppoted.refreshTaskList (ctx, deviceId)
-
deviceId
: serial number of controller
Returns a refreshed
result object, e.g.:
{ deviceId: 405419896, refreshed: true }
Retrieves the indices of the first and last event records stored on a controller.
uhppoted.getEvents (ctx, deviceId)
-
deviceId
: serial number of controller -
index
: index of event (1-100000)
Returns an events
record, e.g.:
{ deviceId: 405419896, first: 1, last: 70 }
Retrieves a single event from a controller.
uhppoted.getEvent (ctx, deviceId, index)
-
deviceId
: serial number of controller -
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:
- The event timestamp field will be blank if the event timestamp in the response is a zero value.
Retrieves the current event index user value from a controller.
uhppoted.getEventIndex (ctx, deviceId)
-
deviceId
: serial number of controller
Returns an event-index
object, e.g.:
{ deviceId: 405419896, index: 29 }
Sets the current event index user value on a controller.
uhppoted.setEventIndex (ctx, deviceId, index)
-
deviceId
: serial number of controller -
index
: 1-100000
Returns an updated
result object, e.g.:
{ deviceId: 405419896, updated: true }
Remotely unlocks a door.
uhppoted.openDoor (ctx, deviceId, door)
-
deviceId
: serial number of controller -
door
: 1-4
Returns an opened
result object, e.g.
{ deviceId: 405419896, opened: true }
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, deviceId, enable)
-
deviceId
: serial number of controller -
enable
: enables remote host access control if true
Returns an ok
result object, e.g.:
{ deviceId: 405419896, ok: true }
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, deviceId, 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 }
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, deviceId, 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 }
Assigns up to four passcodes for supervisor access to a door.
uhppoted.setDoorPasscodes (ctx, deviceId, 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 }
Resets the controller configuration to the manufacturer default settings.
uhppoted.restoreDefaultParameters (ctx, deviceId)
-
deviceId
: serial number of controller
Returns an ok
result object, e.g.:
{ deviceId: 405419896, ok: true }
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 }
}
}
Please create an issue in the uhppoted-nodejs github repository.