Crestron CIP Library for Node.js

A robust TypeScript/Node.js library for communicating with Crestron processors via the CIP (Cresnet over IP) protocol.

Features

• Full CIP Protocol Support: Complete implementation of Crestron's CIP protocol
• TypeScript First: Written in TypeScript with full type definitions
• Event-Driven: Built on Node.js EventEmitter for reactive programming
• Auto Reconnection: Automatic reconnection handling with configurable retry intervals
• Digital/Analog/Serial Joins: Support for all three types of Crestron joins
• Client & Server Modes: Can act as both CIP client and server
• Debug Support: Comprehensive debug logging using the debug package

Installation

npm install crestron-cip

Quick Start

Client Example

import { CIP, CIPOptions, CIPOutputHelper } from "crestron-cip";

const options: CIPOptions = {
  ipid: 0x21, // Your IPID
  host: "10.1.0.200", // Crestron processor IP
  port: 41794, // CIP port (typically 41794)
  debug: true, // Enable debug logging
  reconnect: true, // Enable auto-reconnection
  timeout: 10000, // Connection timeout in ms
};

const cip = new CIP(options);
cip.connect();

// Listen for events
cip.on("event", (event) => {
  console.log(`Received ${event.type} join ${event.join}:`, event.data);
});

cip.on("accepted", () => {
  console.log("Connection accepted by Crestron processor");

  // Send some data
  cip.write(CIPOutputHelper.digital({ join: 1, data: true }));
  cip.write(CIPOutputHelper.analog({ join: 1, data: 32768 }));
  cip.write(CIPOutputHelper.serial({ join: 1, data: "Hello Crestron!" }));
});

cip.on("error", (error) => {
  console.error("CIP Error:", error);
});

Server Example

import { CIPServer, CIPOptions } from "crestron-cip";

const options: CIPOptions = {
  ipid: 0x08,
  host: "0.0.0.0", // Listen on all interfaces
  port: 41794,
  debug: true,
  type: "server",
};

const server = new CIPServer(options);

server.on("event", (event) => {
  console.log(`Client sent ${event.type} join ${event.join}:`, event.data);
});

API Reference

CIP Class

The main client class for connecting to Crestron processors.

Methods

• connect(options?: CIPOptions): boolean - Connect to the Crestron processor
• disconnect(): void - Disconnect from the processor
• write(buffer: Buffer): boolean - Send raw data
• sendUpdateRequest(): boolean - Request status update from processor

Events

• connect - Connection established
• close - Connection closed
• error - Connection or protocol error
• accepted - IPID registration accepted
• refused - IPID registration refused
• event - Received join event (digital/analog/serial)
• update - Update status change

CIPOutputHelper

Utility class for creating CIP output messages.

Methods

• digital(event: {join: number, data: boolean}): Buffer - Create digital join message
• analog(event: {join: number, data: number}): Buffer - Create analog join message
• serial(event: {join: number, data: string}): Buffer - Create serial join message

CIPInputHelper

Utility class for parsing CIP input messages.

Methods

• parseDigitalInput(payload: Buffer): CIPEventData - Parse digital join data
• parseAnalogInput(payload: Buffer): CIPEventData - Parse analog join data
• parseSerialInput(payload: Buffer): CIPEventData - Parse serial join data

Types

CIPOptions

interface CIPOptions {
  host: string; // IP address or hostname
  port: number; // Port number (typically 41794)
  ipid: number; // IP identification number
  debug?: boolean; // Enable debug logging
  reconnect?: boolean; // Enable auto-reconnection
  timeout?: number; // Connection timeout in ms
  type?: "client" | "server"; // Connection type
}

CIPEventData

interface CIPEventData {
  join: number; // Join number (1-based)
  data: Buffer | boolean | number | string; // Join data
  type: "digital" | "analog" | "serial" | "unicode"; // Join type
}

Protocol Details

The CIP (Cresnet over IP) protocol is Crestron's proprietary protocol for communication between processors and other devices over IP networks. This library implements:

• Message Types: ACK, SIGNON, CONNECTION, JOIN_EVENT, PING/PONG, WHOIS
• Join Types: Digital (boolean), Analog (16-bit integer), Serial (text/binary data)
• Heartbeat: Automatic ping/pong to maintain connection
• Registration: IPID-based device registration

Debug Logging

Enable debug logging by setting the DEBUG environment variable:

DEBUG=CIP,socket-reconnect npm start

Or programmatically:

const options: CIPOptions = {
  // ... other options
  debug: true,
};

Examples

See the examples/ directory for complete working examples:

• client-example.ts - Basic CIP client
• server-example.ts - Basic CIP server

Development

# Install dependencies
npm install

# Build the library
npm run build

# Run client example
npm run dev

# Run with debug logging
DEBUG=CIP npm run dev

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

GPL-3.0-or-later

Author

Motaz Abuthiab

Support

For issues and questions, please use the GitHub issue tracker.