uhppoted 0.8.10

uhppoted

.NET package for the UHPPOTE UT0311-L0x* TCP/IP Wiegand access controller API.

The API is described in detail in the API documentation and examples in F#, C# and VB.NET are included to illustrate the use of the API.

• Release Notes
• Installation
  • Installing from nuget.org
  • Installing from Github Packages
  • Building from source
  • C#
  • VB.NET
• API summary
• API documentation
• Examples
• Notes
  • Ephemeral ports

Release Notes

Current Release

v0.8.10 - 2025-01-30

1. Initial release.

Installation

The package can be installed from either the NuGet registry or Github Packages:

Installing from the NuGet Registry

Use either the dotnet CLI or Package Manager:

• CLI:

dotnet add package uhppoted --version 0.8.10

• Package Manager (console):

NuGet\Install-Package uhppoted -Version 0.8.10

After installing the package it should be referenced in the project file, e.g.:

  ...
  <ItemGroup>
    <PackageReference Include="uhppoted" Version="0.8.10" />
  </ItemGroup>
  ...

Installing from Github Packages

Installing from the Github Packages NuGet registry requires a Personal Access Token (classic) with at least package: read permissions.

• dotnet CLI:

  dotnet nuget add source --username <username> --password <personal-access-token> --store-password-in-clear-text --name uhppoted "https://nuget.pkg.github.com/uhppoted/index.json"
  dotnet nuget add source https://nuget.pkg.github.com/uhppoted/index.json
  dotnet add package uhppoted --version 0.8.10
  
  

• Package Manager (console):

  NuGet\Set-Source -Name "uhppoted" -Source "https://nuget.pkg.github.com/uhppoted/index.json" -Username "<username>" -Password "<personal-access-token>"
  NuGet\Install-Package uhppoted -Version 0.8.10
  

After installing the package it should be referenced in the project file, e.g:

  ...
  <ItemGroup>
    <PackageReference Include="uhppoted" Version="0.8.10" />
  </ItemGroup>
  ...

Building from source

Requirements:

• .NET SDK 7.0+
• (optional) make

git clone https://github.com/uhppoted/uhppoted-lib-dotnet.git
cd uhppoted-lib-dotnet/uhppoted
make build

If you prefer to build without make:

   git clone https://github.com/uhppoted/uhppoted-lib-dotnet.git
   cd uhppoted-lib-dotnet/uhppoted
   dotnet build

C#

C# applications may additionally require installing the FSharp.Core package:

dotnet add package FSharp.Core

VB.NET

VB.NET applications may additionally require installing the FSharp.Core package:

dotnet add package FSharp.Core

API summary

FindControllers

Discovers all controllers accessible via a UDP broadcast on the local LAN.

GetController

Retrieves the IPv4 configuration, MAC address and version information for an access controller.

SetIPv4

Sets a controller IPv4 address, netmask and gateway address.

GetListener

Gets a controller event listener address:port and auto-send interval.

SetListener

Sets a controller event listener endpoint and auto-send interval.

GetTime

Gets a controller current date and time.

SetTime

Sets a controller current date and time.

GetDoor

Gets a controller door operational mode and unlocked delay.

SetDoor

Sets a controller door operational mode and unlocked delay.

SetDoorPasscodes

Sets up to 4 passcodes for a controller door.

OpenDoor

Unlocks a door controlled by a controller.

GetStatus

Retrieves a controller status and most recent event (if any).

GetCards

Retrieves the number of card records stored on a controller.

GetCard

Retrieves a card record by card number.

GetCardAtIndex

Retrieves the card record (if any) at the index from a controller.

PutCard

Adds or updates a card record on a controller.

DeleteCard

Deletes a card record from a controller.

DeleteAllCards

Deletes all card records from a controller.

GetEvent

Retrieves the event record (if any) at the index from a controller.

GetEventIndex

Retrieves the current event index from a controller.

SetEventIndex

Sets a controller event index.

RecordSpecialEvents

Enables (or disables) events for door open/close, button press, etc.

GetTimeProfile

Retrieves an access time profile from a controller.

GetTimeProfile

Adds or updates an access time profile on a controller.

ClearTimeProfiles

Clears all access time profiles stored on a controller.

AddTask

Adds or updates a scheduled task on a controller.

ClearTaskList

Clears all scheduled tasks from a controller tasklist.

RefreshTaskList

Schedules added tasks.

SetPCControl

Enables/disables remote access control management.

SetInterlock

Sets the door interlock mode for an access controller.

ActivateKeypads

Activates/deactivates the access reader keypads attached to an access controller.

RestoreDefaultSettings

Restores the manufacturer default settings.

Listen

Listens for access controller events.

Examples

F#

• hello world
• CLI

C#

• hello world
• CLI

VB.NET

• hello world
• CLI

Notes

Ephemeral ports and binding to 0.0.0.0:0

As per Microsoft Knowledgebase Article 929851, the default Windows ephemeral port range extends from 49152 to 65535, which includes the default UHPPOTE UDP port (60000). Present-day BSD and Linux have similar ranges.

If an application is assigned port 60000 when binding to e.g. 0.0.0.0:0 it will receive the any outgoing UDP broadcast requests and interpret them as replies - which will be, uh, a little confusing, e.g.:

request:
   17 94 00 00 00 00 00 00  00 00 00 00 00 00 00 00
   00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00
   00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00
   00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00

reply:
   17 94 00 00 78 37 2a 18  c0 a8 01 64 ff ff ff 00
   c0 a8 01 01 00 12 23 34  45 56 08 92 20 18 11 05
   00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00
   00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00
      
get-all-controllers:
   controller: 0
      address: 0.0.0.0
      netmask: 0.0.0.0
      gateway: 0.0.0.0
          MAC: 00:00:00:00:00:00
      version: v0.00
         date: ---

   controller: 405419896
      address: 192.168.1.100
      netmask: 255.255.255.0
      gateway: 192.168.1.1
          MAC: 00:12:23:34:45:56
      version: v8.92
         date: 2018-11-05

In general this doesn't seem to have been a problem (or at least nobody has raised it as an issue) and the implementation will return an error if the bind port for a UDP broadcast is 60000. It can be mitigated by:

• Excluding port 60000 from the ephemeral range using whatever method is recommended for your platform of choice.
• (OR) Reduce (or move) the ephemeral port range (again using whatever method is recommended for your platform of choice).
• (OR) (really not recommended except as a quick hack) Bind a netcat listener to port 60000 before running the application:

nc -lu 600000

References:

1. The Ephemeral Port Range
2. How to change/view the ephemeral port range on Windows machines?
3. You cannot exclude ports by using the ReservedPorts registry key in Windows Server 2008 or in Windows Server 2008 R2
4. Listen to UDP data on local port with netcat