Atrium SDK Client

A TypeScript client library that provides a simplified interface for interacting with CDVI Atrium access control systems. This package serves as a user-friendly wrapper around the Atrium SDK, making it easier to integrate access control functionality into your applications.

Purpose

The main purpose of this package is to simplify the usage of the Atrium SDK by providing:

• Type-safe interfaces for all SDK operations
• Simplified authentication and session management
• Easy-to-use methods for common operations
• Built-in logging and error handling
• Modern Promise-based API instead of complex XML handling

Architecture

The library is built with a modular architecture:

src/
├── adapters/          # Pluggable adapters (logging, etc.)
├── helpers/           # XML parsing and encryption utilities
├── types/             # TypeScript type definitions
├── utils/             # Utility functions (RC4, MD5, etc.)
├── atrium-sdk-base.ts # Base class with authentication
├── door.ts            # Door-specific operations
└── index.ts           # Main exports

Installation

npm install atrium-sdk-client
# or
pnpm add atrium-sdk-client
# or
yarn add atrium-sdk-client

Usage

Basic Door Operations

import { Door } from 'atrium-sdk-client';

const door = new Door({
  ip: '192.168.1.100',
  username: 'admin',
  password: 'your-password',
  logEnabled: true, // Optional: enable logging
  https: false, // Optional: use HTTPS (default: false)
});

// Read door status
const status = await door.read(1);
console.log('Door Status:', status);

// Unlock door for 5 seconds
await door.unlock(1, 5000);

Configuration Options

interface AtriumSDKConfig {
  // Required
  ip: string; // Device IP address
  username: string; // Device username
  password: string; // Device password

  // Optional
  https?: boolean; // Use HTTPS (default: false)
  logEnabled?: boolean; // Enable logging (default: false)
  logger?: ILogger; // Custom logger instance
  logLevel?: LogLevel; // Log level (default: 'error')
  hideIpInLogs?: boolean; // Hide IP in logs (default: true)
}

Door Status Response

interface DoorStatusResponse {
  doorId: number;
  doorStatus: DoorStatus; // Open, Close, etc.
  lockStatus: DoorLockStatus; // Locked, Unlocked, etc.
  accessLockStatus: DoorAccessLockStatus;
  accessStatus: DoorAccessStatus; // Denied, Allowed
  bypassStatus: number;
}

Status Enums

enum DoorStatus {
  Unknown = 0,
  Open = 1,
  Close = 2,
  OpenPreAlarm = 3,
  OpenForced = 4,
  OpenTooLong = 5,
  LostComTrouble = 6,
}

enum DoorLockStatus {
  Unknown = 0,
  Locked = 1,
  LockedByUser = 2,
  Unlocked = 3,
  UnlockedByUser = 4,
  Offline = 6,
}

enum DoorAccessStatus {
  Denied = 0,
  Allowed = 1,
}

Development Scripts

# Build the project
pnpm run build

# Build in watch mode
pnpm run build:watch

# Clean dist folder
pnpm run clean

# Type checking
pnpm run typecheck

# Format code
pnpm run format

# Lint code
pnpm run lint

# Prepare package for publishing
pnpm run prepare

Compatible Devices

This library has been tested and verified to work with the following CDVI Atrium access control devices:

Tested Devices

| Device Model | Type | Door Access Features | Status | | ------------ | ---------------------------------- | -------------------------------- | ------------ | | A22K | Single door controller with keypad | Read StatusUnlock Door | Fully Tested |

Door Access Features

The following door access operations have been tested and verified:

Read Door Status

• Door position (Open/Closed)
• Lock status (Locked/Unlocked)
• Access control status
• Bypass status
• Real-time status monitoring

Door Control

• Unlock door with configurable duration
• Immediate unlock command
• Timed unlock (specify seconds)

Tested Configuration

• Device: A22K Single Door Controller
• Firmware: Compatible with standard Atrium SDK protocol
• Connection: HTTP/HTTPS over Ethernet
• Authentication: Username/Password based

Note: While specifically tested on the A22K model, this library should work with other CDVI Atrium-compatible devices (A22, ADH10K, etc.) that support the same SDK protocol. If you test with other models, please consider contributing your findings.

Project Structure

atrium-sdk-client/
├── src/
│   ├── adapters/
│   │   └── logger.ts          # Logging adapter
│   ├── helpers/
│   │   ├── decrypt-xml.ts     # XML decryption utilities
│   │   ├── encrypt-xml.ts     # XML encryption utilities
│   │   └── xml-parser.ts      # XML parsing utilities
│   ├── types/
│   │   └── generic-xml.type.ts # XML type definitions
│   ├── utils/
│   │   ├── md5.ts             # MD5 hashing
│   │   └── rc4.ts             # RC4 encryption
│   ├── atrium-sdk-base.ts     # Base SDK class
│   ├── door.ts                # Door operations
│   └── index.ts               # Main exports
├── examples/
│   └── door.ts                # Usage examples
├── dist/                      # Compiled JavaScript output
├── tsconfig.json              # TypeScript config (development)
├── tsconfig.build.json        # TypeScript config (production)
└── package.json               # Package configuration

Examples

Check the examples/ directory for complete usage examples:

// examples/door.ts
import { Door } from 'atrium-sdk-client';

async function main() {
  const door = new Door({
    ip: '192.168.1.100',
    username: 'admin',
    password: 'password',
    logEnabled: true,
  });

  try {
    // Read door status
    const status = await door.read(1);
    console.log('Door Status:', status);

    // Unlock door
    await door.unlock(1, 5); // Unlock for 5 seconds
    console.log('Door unlocked successfully');
  } catch (error) {
    console.error('Error:', error.message);
  }
}

main();

Building from Source

1. Clone the repository
2. Install dependencies: pnpm install
3. Build the project: pnpm run build
4. Run examples: pnpm run dev

Security Notes

• Always use HTTPS in production environments when possible
• Store credentials securely (environment variables, secure vaults)
• Enable IP hiding in logs for production (hideIpInLogs: true)
• Use appropriate log levels for different environments

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues, questions, or contributions, please open an issue on the project repository.