Z-bit-Systems-LLC/OSDP.NetPublic

NotificationsYou must be signed in to change notification settings
Fork21
Star53

A .NET Core control panel implementation of the Open Supervised Device Protocol(OSDP)

License

Apache-2.0 license

53 stars 21 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 805 Commits
ci		ci
docs		docs
src		src
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE.txt		LICENSE.txt
README.md		README.md
azure-pipelines.yml		azure-pipelines.yml

Repository files navigation

OSDP.Net

OSDP.Net is a .NET implementation of the Open Supervised Device Protocol (OSDP).This protocol has been adopted by the Security Industry Association (SIA) to standardize access control hardware communication.Further information can be found atSIA OSDP Homepage.

Prerequisites

OSDP.Net supports the following .NET implementations:

.NET Framework 4.6.2 and later
NET 5.0 and later

Getting Started

The OSDP.Net library provides a Nuget package to quickly add OSDP capability to a .NET project.You can install it using the NuGet Package Console window:

PM> Install-Package OSDP.Net

A control panel can be created and started with a few lines.Be sure to register events before start the connection.

varpanel=newControlPanel();panel.ConnectionStatusChanged+=(sender,eventArgs)=>{// NOTE: Avoid blocking the thread so the control panel can continue pollingTask.Run(async()=>{// Handle connection change event});};GuidconnectionId=panel.StartConnection(newSerialPortOsdpConnection(portName,baudRate));

Once the connection has started, add Peripheral Devices (PD).

panel.AddDevice(connectionId,address,useCrc,useSecureChannel,secureChannelKey);

The following code will install a PD with a unique Secure Channel key. The OSDP standard requires that setting the secure key can only occur while communications are secure.

panel.AddDevice(connectionId,address,useCrc,useSecureChannel);// connect using default SC keyboolsuccessfulSet=awaitpanel.EncryptionKeySet(connectionId,address,newEncryptionKeyConfiguration(KeyType.SecureChannelBaseKey,uniqueKey));

The ControlPanel object can then be used to send command to the PD.

varreturnReplyData=awaitpanel.OutputControl(connectionId,address,newOutputControls(new[]{newOutputControl(outputNumber,activate?OutputControlCode.PermanentStateOnAbortTimedOperation:OutputControlCode.PermanentStateOffAbortTimedOperation,0)});

The reader number parameter found in some commands is used for devices with multiple readers attached. If the device has a single reader, a value of zero should be used.

bytedefaultReaderNumber=0;boolsuccess=awaitpanel.ReaderBuzzerControl(connectionId,address,newReaderBuzzerControl(defaultReaderNumber,ToneCode.Default,2,2,repeatNumber))

Common Usage Examples

Reading Card Data

// Register for card read eventspanel.CardRead+=async(sender,eventArgs)=>{awaitTask.Run(()=>{Console.WriteLine($"Card read from device{eventArgs.Address}");if(eventArgs.CardDataisRawCardDatarawData){Console.WriteLine($"Raw card data:{BitConverter.ToString(rawData.Data)}");}elseif(eventArgs.CardDataisFormattedCardDataformattedData){Console.WriteLine($"Formatted card data:{formattedData.CardNumber}");}});};

Handling Device Events

// Monitor device status changespanel.InputStatusReport+=async(sender,eventArgs)=>{awaitTask.Run(()=>{Console.WriteLine($"Input status changed on device{eventArgs.Address}");foreach(varinputineventArgs.InputStatuses){Console.WriteLine($"Input{input.Number}:{(input.Active?"Active":"Inactive")}");}});};// Handle NAK responsespanel.NakReplyReceived+=async(sender,eventArgs)=>{awaitTask.Run(()=>{Console.WriteLine($"NAK received from device{eventArgs.Address}:{eventArgs.Nak.ErrorCode}");});};

Managing Multiple Devices

// Add multiple devices on the same connectionvardevices=new[]{0,1,2,3};// Device addressesforeach(varaddressindevices){panel.AddDevice(connectionId,address,useCrc:true,useSecureChannel:true);}// Send commands to all devicesforeach(varaddressindevices){awaitpanel.ReaderLedControl(connectionId,address,newReaderLedControls(new[]{newReaderLedControl(0,0,LedColor.Green,LedColor.Black,30,30,PermanentControlCode.SetPermanentState)}));}

Error Handling

try{vardeviceId=awaitpanel.IdReport(connectionId,address);Console.WriteLine($"Device ID:{deviceId.VendorCode:X}-{deviceId.ModelNumber}-{deviceId.Version}");}catch(TimeoutException){Console.WriteLine("Device communication timeout");}catch(Exceptionex){Console.WriteLine($"Error communicating with device:{ex.Message}");}

Custom Communication Implementations

OSDP.Net is able to plugin different methods of communications beyond what is included with the default package.It simply requires the installation a new NuGet package. The code needs to be updated by using it's implementation of the IOsdpConnection interface when starting a connection for the ControlPanel.

SerialPortStream
- Author: Fredrik Hall
- Links:GitHub Nuget
- Notes: Requires compilation of native libraries for non-Windows platforms

Test Console

There is compiled version of the test console application for all the major platforms available for download.It has all the required assemblies included to run as a self-contained executable.The latest version of the package can be found athttps://www.z-bitco.com/downloads/OSDPTestConsole.zip

NOTE: First determine the COM port identifier of the 485 bus connected to the computer.This will need to be entered when starting the connection.Be sure to save configuration before exiting.

Documentation

Contributing

The current goal is to properly support all the commands and replies outlined the OSDP v2.2 standard.The document that outlines the specific of the standard can be found on theSIA website. Contact me through my consulting companyZ-bit System, LLC if you're interested in collaborating on the OSDP.Net library.