Vitrea Client

A robust TypeScript client for the Vitrea Smart Home ecosystem that handles the complexities of socket communication, connection management, and protocol versioning so you don't have to.

Why Vitrea Client?

Smart home integrations shouldn't be fragile. This client was built from the ground up with real-world reliability in mind:

• Battle-tested connection handling: Automatic retries, exponential backoff, and intelligent reconnection.
• Zero-downtime heartbeats: Keeps your connection alive without manual intervention.
• Thread-safe messaging: Built-in mutex prevents race conditions and message collisions.
• Protocol flexibility: Seamlessly supports both V1 legacy and V2 modern protocols.
• Production-ready logging: Integrates with your existing logging infrastructure.

Quick Start

Installation

npm install vitrea-client

Requires Node.js 18.17+ or 20.5+

Basic Usage

import { VitreaClient, Requests, ProtocolVersion } from 'vitrea-client'

// Connect to your Vitrea system
const client = VitreaClient.create({
    host: '192.168.1.23',
    port: 11501,
    username: 'admin',
    password: 'your-password',
    version: ProtocolVersion.V2
})

await client.connect()

// Get room information
const rooms = await client.send(new Requests.RoomCount())
console.log(`Found ${rooms.count} rooms`)

// Monitor real-time key presses
client.onKeyStatus(status => {
    console.log(`${status.isOn ? 'ON' : 'OFF'}: Room ${status.nodeID}, Key ${status.keyID}`)
})

Configuration

Connection Settings

const client = VitreaClient.create({
    // Required connection details
    host: '192.168.1.23',        // Your Vitrea system IP
    port: 11501,                 // Default Vitrea port
    username: 'admin',           // Your username
    password: 'password',        // Your password
    version: ProtocolVersion.V2  // Use V2 for latest features
}, {
    // Optional socket configuration
    requestBuffer: 250,          // ms between requests (prevents overwhelming)
    requestTimeout: 1000,        // ms to wait for responses
    heartbeatInterval: 2500,     // ms between heartbeat pings
    shouldReconnect: true,       // Auto-reconnect on disconnect
    ignoreAckLogs: false        // Filter out acknowledgment noise
})

Complete Configuration Reference

| Setting | Description | Default | Notes | | ----------------------- | ----------------------------- | -------------- | ------------------------------------------ | | Connection | | | | | host | Vitrea system IP address | 192.168.1.23 | | | port | Connection port | 11501 | | | username | Authentication username | null | Required for most operations | | password | Authentication password | null | Required for most operations | | version | Protocol version | V2 | V2 recommended for new projects | | Reliability | | | | | requestBuffer | Delay between requests (ms) | 250 | Prevents server overload | | requestBufferVariance | Jitter factor (0.0-1.0) | 0.15 | Adds randomness to prevent thundering herd | | requestTimeout | Request timeout (ms) | 1000 | How long to wait for responses | | heartbeatInterval | Heartbeat frequency (ms) | 2500 | Keep-alive interval | | shouldReconnect | Auto-reconnect on failure | true | Recommended for production | | Debugging | | | | | log | Custom logger instance | null | Implement LoggerContract interface | | ignoreAckLogs | Hide acknowledgment logs | false | Reduces log noise |

Environment Variables

For production deployments, use environment variables instead of hardcoding credentials:

export VITREA_VBOX_HOST=192.168.1.23
export VITREA_VBOX_PORT=11501
export VITREA_VBOX_USERNAME=admin
export VITREA_VBOX_PASSWORD=secure-password

The client will automatically pick up any VITREA_VBOX_* environment variables that match configuration keys.

API Reference

Request Types

The Requests namespace provides all available commands:

| Command | Purpose | Example Usage | | ------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------- | | System Information | | | | NodeCount | Get total nodes in system | await client.send(new Requests.NodeCount()) | | RoomCount | Get total rooms in system | await client.send(new Requests.RoomCount()) | | NodeMetaData | Get node details and capabilities | await client.send(new Requests.NodeMetaData({ nodeID: 1 })) | | RoomMetaData | Get room information | await client.send(new Requests.RoomMetaData({ roomID: 1 })) | | Status & Control | | | | KeyStatus | Get current state of a key | await client.send(new Requests.KeyStatus({ nodeID: 1, keyID: 1 })) | | KeyParameters | Get key configuration settings | await client.send(new Requests.KeyParameters({ nodeID: 1, keyID: 1 })) | | ToggleKeyStatus | Control lights/devices | await client.send(new Requests.ToggleKeyStatus({ nodeID: 1, keyID: 1, dimmer: 75 })) | | ToggleNodeStatus | Control node lock and LED backlight | await client.send(new Requests.ToggleNodeStatus(11, LockStatus.UNLOCKED, LEDBackgroundBrightness.NORMAL)) | | NodeStatus | Get comprehensive node status | await client.send(new Requests.NodeStatus({ nodeID: 1 })) | | InternalUnitStatuses | Subscribe to internal status changes | await client.send(new Requests.InternalUnitStatuses()) | | Connection Management | | | | Login | Authenticate with the system | await client.send(new Requests.Login()) | | Heartbeat | Manual heartbeat (auto-handled) | await client.send(new Requests.Heartbeat()) | | ToggleHeartbeat | Enable/disable auto-heartbeat | await client.send(new Requests.ToggleHeartbeat(false)) |

Protocol Versions

• V2 (Recommended): Modern protocol with full feature support.
• V1 (Legacy): Compatibility mode for older systems.

The client automatically handles protocol differences. V2 provides enhanced metadata and improved error handling.

Advanced Features

Custom Logging

Integrate with your existing logging infrastructure:

import { ConsoleLogger, VitreaClient } from 'vitrea-client'

// Built-in console logger
const client = VitreaClient.create(
    { host: '192.168.1.23', username: 'admin', password: 'secret' },
    { log: new ConsoleLogger() }
)

// Your existing logger (must implement LoggerContract)
const client = VitreaClient.create(
    { host: '192.168.1.23', username: 'admin', password: 'secret' },
    { log: yourLogger, ignoreAckLogs: true } // Hide noisy acknowledgments
)

Real-Time Event Monitoring

React to system changes as they happen:

import { VitreaClient, Responses } from 'vitrea-client'

const client = VitreaClient.create({ /* config */ })
await client.connect()

// Monitor all key state changes
client.onKeyStatus((status: Responses.KeyStatus) => {
    console.log(`Room ${status.nodeID}, Key ${status.keyID}: ${status.isOn ? 'ON' : 'OFF'}`)

    // React to specific events
    if (status.nodeID === 1 && status.keyID === 'security-panel' && status.isOn) {
        handleSecurityActivation()
    }
})

// Connection status monitoring
client.on('connected', () => console.log('System connected'))
client.on('disconnected', () => console.log('System disconnected'))
client.on('reconnecting', () => console.log('Attempting reconnection...'))

Contributing

Found a bug or want to contribute? Check out our GitHub repository or open an issue.

License

MIT © Dov Benyomin Sohacheski