Z9/Open Community Profile

This repository contains the Google Protobuf specification for the Z9/Open binary protocol - Community Profile.

Overview

The Community Profile is a profile of Z9 Security's Z9/Open protocol, designed to be an efficient, binary socket communications between an access control panel and a host.

See Also

• Z9/Flex Community Profile - OpenAPI specification for the Z9/Flex JSON/REST API Community Profile

Z9/Flex and Z9/Open

For more information about the commercial version of Z9/Flex, visit z9flex.com.

For more information about the commercial version of Z9/Open, visit z9open.com.

Z9/FL=X is a registered trademark of Z9 Security. z9/op=n is a registered certification mark of Z9 Security.

License

Apache 2.0 - see LICENSE for details.

Files

• SpCoreProto.proto - Top-level protocol messages (identification, events, database changes, device actions)
• SpCoreProtoData.proto - Data model definitions (credentials, devices, schedules, etc.)
• SpCoreProtoElements.proto - Common element definitions
• SpCoreProtoEnums.proto - Enumeration definitions

Usage

The .proto files can be used with Google Protobuf tools (protoc) to:

• Generate serialization/deserialization code in various languages, for either side of the communications (host, panel)

.NET SDK

The dotnet/ folder contains a C# SDK for Z9/Open Community Profile:

• Z9.Protobuf.Community - .NET Standard 2.0 library with protobuf-generated classes, host-side connection management, and controller-side SpCoreHostConnection
• Z9.Protobuf.Community.Test - Unit tests

Controller-Side Connection

SpCoreHostConnection provides controller-side TCP/TLS connection, identification, ping, message dispatch, and reconnection with exponential backoff (5s to 160s, resets after successful identification). Implement ISpCoreHostConnectionObserver (or extend SpCoreHostConnectionObserverBase) to receive callbacks.

Logging

The library logs internally via log4net. The consuming application must configure log4net — without configuration, library log output is silently discarded.

Publishing to NuGet

Pushing a version tag triggers the CI pipeline to build, test, and publish the Z9.Protobuf.Community package to nuget.org:

Find the latest version and tag the next:

git tag --sort=-v:refname | head -1

git tag v1.0.2
git push origin v1.0.2

Note: This requires a NUGET_API_KEY secret configured in the repository's GitHub Actions settings.

Verify the package is published:

curl -s https://api.nuget.org/v3-flatcontainer/z9.protobuf.community/index.json