@imperosoft/cris-webui-core

CRIS - Crestron React Impero Soft WebUI integration core package

Provides WebSocket communication with Crestron processors, join state management, and utilities for React applications.

Installation

npm install @imperosoft/cris-webui-core

Using Granular Access Token

To install from npm registry with a granular access token, configure npm:

npm config set //registry.npmjs.org/:_authToken=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

Or add to your .npmrc file:

//registry.npmjs.org/:_authToken=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

Quick Start

import { useEffect } from 'react';
import {
  connectToCrestron,
  useConnectionStore,
  useJoinsStore
} from '@imperosoft/cris-webui-core';

function App() {
  const isOnline = useConnectionStore((state) => state.isOnline);
  const dVal = useJoinsStore((state) => state.dVal);
  const dSet = useJoinsStore((state) => state.dSet);

  useEffect(() => {
    connectToCrestron({
      production: false,
      processorIp: '192.168.1.20',
      processorAppNumber: 1,
      debug: true,
    });
  }, []);

  if (!isOnline) {
    return <div>Connecting to Crestron...</div>;
  }

  return (
    <button onClick={() => dSet(1, !dVal(1))}>
      Toggle Digital Join 1
    </button>
  );
}

API Reference

Connection

import { connectToCrestron, disconnectFromCrestron, getCrestronApi } from '@imperosoft/cris-webui-core';

// Connect with config
connectToCrestron({
  production: false,        // true = use window.location, false = use processorIp
  processorIp: '192.168.1.20',
  processorAppNumber: 1,    // Port = 10000 + appNumber
  ipid: '03',               // Optional panel IPID
  reconnectInterval: 5000,  // Reconnect interval in ms
  debug: true,              // Enable console logging
});

// Disconnect
disconnectFromCrestron();

Connection Store

import { useConnectionStore } from '@imperosoft/cris-webui-core';

function StatusIndicator() {
  const status = useConnectionStore((state) => state.status);
  const isOnline = useConnectionStore((state) => state.isOnline);

  // status: 'disconnected' | 'connecting' | 'connected' | 'error'
  // isOnline: boolean (true when status === 'connected')
}

Joins Store

import { useJoinsStore } from '@imperosoft/cris-webui-core';

function Controls() {
  // Digital joins (boolean)
  const dVal = useJoinsStore((state) => state.dVal);      // Get value
  const dSet = useJoinsStore((state) => state.dSet);      // Set value
  const dToggle = useJoinsStore((state) => state.dToggle); // Toggle
  const dPulse = useJoinsStore((state) => state.dPulse);  // Pulse (true then false)
  const dIsOn = useJoinsStore((state) => state.dIsOn);    // Check if true
  const dIsOff = useJoinsStore((state) => state.dIsOff);  // Check if false

  // Analog joins (0-65535)
  const aVal = useJoinsStore((state) => state.aVal);      // Get value
  const aSet = useJoinsStore((state) => state.aSet);      // Set value
  const aToPercent = useJoinsStore((state) => state.aToPercent);   // Get as 0-100%
  const aSetPercent = useJoinsStore((state) => state.aSetPercent); // Set from 0-100%

  // Serial joins (string)
  const sVal = useJoinsStore((state) => state.sVal);      // Get value
  const sSet = useJoinsStore((state) => state.sSet);      // Set value

  // Examples
  const lightOn = dVal(10);           // Get digital join 10
  dSet(10, true);                     // Set digital join 10 to true
  dToggle(10);                        // Toggle digital join 10
  dPulse(11);                         // Pulse digital join 11

  const volume = aVal(5);             // Get analog join 5
  aSet(5, 32767);                     // Set analog join 5
  const volumePercent = aToPercent(5); // Get as percentage

  const roomName = sVal(1);           // Get serial join 1
  sSet(1, 'Hello');                   // Set serial join 1
}

GUI Store

import { useGuiStore } from '@imperosoft/cris-webui-core';

function ResponsiveComponent() {
  const { width, height, isMobile, fontSize, setDimensions } = useGuiStore();

  useEffect(() => {
    const handleResize = () => setDimensions(window.innerWidth, window.innerHeight);
    handleResize();
    window.addEventListener('resize', handleResize);
    return () => window.removeEventListener('resize', handleResize);
  }, []);
}

Utilities

import { Converters, Cip, useCipDecode } from '@imperosoft/cris-webui-core';

// Value conversions
const percent = Converters.toPercent(32767, 0, 65535);  // 50
const value = Converters.fromPercent(50, 0, 65535);     // 32767.5

// CIP text decoding (for encoded serial strings)
const decoded = Cip.decodeString(encodedValue);

// React hook for CIP decoding
function Display() {
  const sVal = useJoinsStore((state) => state.sVal);
  const text = useCipDecode(sVal(1));
}

Peer Dependencies

• react >= 18.0.0
• zustand >= 4.0.0

License

MIT