Skip to content

Common Patterns

This directory contains proven implementation patterns for common adapter scenarios.

Each pattern is documented in a separate file for easy navigation and reference.

Pattern Index

Core Patterns

Pattern Description File
1. Access Synchronization Offline access control with address allocation 01-access-synchronization.md
2. Event Translation Device events → PQ events mapping 02-event-translation.md
3. Connection Management IDeviceConnection, retry, monitoring 03-connection-management.md
4. Command Handling Typed commands, signature-based detection 04-command-handling.md

Advanced Patterns

Pattern Description File
5. Custom Functions Device-specific capabilities 05-custom-functions.md
6. Shared Resources SDK processes, connection pools 06-shared-resources.md
7. Address Resolution Map protocol addresses to Things, IThingQuery for hierarchy queries 07-address-resolution.md
8. Biometric Enrollment Template capture and storage 08-biometric-enrollment.md

Best Practices

Pattern Description File
9. Event Publishing Function methods vs PqEvent classes 09-event-publishing.md
10. Error Handling Retry, circuit breaker, degradation 10-error-handling.md
11. Testing Without Hardware Mock SDK for development 11-testing-without-hardware.md
12. Status Polling Poll device state with StatusBatch 12-status-polling.md
13. Optimistic Commands Instant UI feedback with async device confirmation 13-optimistic-commands.md
14. Device Configuration Import Root-driven discovery and import of child subtree into PQ 14-device-config-import.md
15. Enrollment Process Shared process for card and biometric enrollment 15-enrollment-process.md
16. Video Event Mapping PQ video event taxonomy, stale analytics, NVR vs channel routing 16-video-events.md
17. Event Replay Deduplication Replay cursor for at-least-once vendor event streams 17-event-replay-deduplication.md
18. Multi-Step Protocol Sequences Exclusive request→ACK→repeat drains via channel sequence policies 18-protocol-sequences.md
19. Stream Registration & Reconciliation CCTV alias register/teardown lifecycle, RTSP-URL strategy, server-owned idle sweep 19-stream-registration.md

Guides

Guide Description File
Event Mapping Systematic vendor event -> PQ event mapping process event-mapping-guide.md

Quick Reference

Most Common Patterns

If you're implementing a typical access control adapter, you'll need:

  1. Pattern 4: Command Handling - Handle open/lock commands
  2. Pattern 2: Event Translation - Translate access events
  3. Pattern 7: Address Resolution - Route events to correct Things
  4. Pattern 3: Connection Management - Connect to device
  5. Pattern 9: Event Publishing - Publish events correctly

Optional Patterns

Depending on device capabilities:

Development Patterns

Always useful:

Pattern Dependencies

Some patterns build on others:

Pattern 2 (Event Translation)
  ↓ requires
Pattern 7 (Address Resolution)  ← find Things by protocol address
  ↓ uses
Pattern 9 (Event Publishing)    ← publish events from resolved Things

Pattern 1 (Access Sync)
  ↓ uses
Pattern 7 (Address Resolution)  ← allocate protocol addresses

Pattern 3 (Connection Management)
  ↓ uses
Pattern 10 (Error Handling)

Pattern 13 (Optimistic Commands)
  ↓ extends
Pattern 4 (Command Handling)        ← adds optimistic UI layer

Pattern 14 (Device Configuration Import)
  ↓ extends
Pattern 4 (Command Handling)        ← adds explicit root import command surface
  ↓ uses
Pattern 3 (Connection Management)   ← temporary root connection for discovery

How to Use This Guide

For First-Time Adapter Developers

  1. Start with 01-step-by-step.md (not this file)
  2. Come back here when you need specific patterns
  3. Read patterns in order: 4 → 2 → 3 → 9 (most common)
  4. Add other patterns as needed

For Experienced Developers

  • Use as quick reference
  • Jump directly to pattern you need
  • Copy code examples and adapt to your SDK

For Troubleshooting

Contributing Patterns

Found a new pattern worth documenting?

  1. Create new file: patterns/XX-pattern-name.md
  2. Follow existing structure:
  3. Clear use case
  4. Code examples
  5. Best practices
  6. See Also links
  7. Add to this index
  8. Update README.md

See Also

Note: These patterns cover most adapter implementation scenarios. When a scenario is still unclear, extend this documentation set with a new generalized pattern or archetype rather than relying on external adapter implementations.