API Documentation - CUSS2 React

Cuss2Connector

Provider component that connects to CUSS2 platform and makes device hooks available.

Props

options Cuss2ConnectionOptions

CUSS2 connection options (cussUrl, clientId, clientSecret)

manualConnect boolean

If true, connection will not be established automatically. Use connect() method instead

children ReactNode

Child components that will have access to CUSS2 hooks

onConnect() () => void

Optional callback when connection is established

onError() () => void

Optional callback when connection fails

onDisconnect() () => void

Optional callback when disconnected

Example

import { Cuss2Connector, Cuss2ConnectionOptions } from '@elevationai/cuss2-react';

const options: Cuss2ConnectionOptions = {
  cussUrl: 'https://cloudsandbox.azurewebsites.net',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret'
};

function App() {
  return (
    <Cuss2Connector options={options}>
      <KioskApp />
    </Cuss2Connector>
  );
}

useCuss2

Hook for accessing CUSS2 platform state and connection status.

Returns: Cuss2ContextValue

cuss2 Cuss2 | null

CUSS2 platform instance

state ApplicationStateCodes | null

Current platform state (INITIALIZE, UNAVAILABLE, AVAILABLE, ACTIVE, etc.)

connected boolean

Connection status to platform

platformData PlatformData | null

Platform data stream

components Record

Available components

environment EnvironmentLevel | null

Environment level

connect() () => Promise

Connect to CUSS2 platform

disconnect() () => Promise

Disconnect from CUSS2 platform

Example

import { useCuss2 } from '@elevationai/cuss2-react';

function KioskStatus() {
  const { cuss2, connected, state } = useCuss2();

  if (!connected) {
    return Connecting to platform...;
  }

  return (
    <div>
      Platform state: {state}
    </div>
  );
}

useBarcodeReader

Hook for barcode and QR code scanning with real-time data updates.

Returns: DeviceHookResult<BarcodeReader>

device BarcodeReader | null

Barcode reader device instance

data any

Most recent scan data

ready boolean

Device is ready for use

enabled boolean

Device is currently enabled

pending boolean

Operation is in progress

status MessageCodes | null

Current device status code

state ComponentState | null

Device component state

Example

import { useBarcodeReader } from '@elevationai/cuss2-react';

function ScannerComponent() {
  const { device, data, ready, enabled } = useBarcodeReader();

  useEffect(() => {
    if (device && ready && !enabled) {
      device.enable();
    }
  }, [device, ready]);

  useEffect(() => {
    if (data) {
      console.log('Scanned:', data);
    }
  }, [data]);

  return (
    <div>
      {ready ? 'Scan barcode now' : 'Scanner not available'}
    </div>
  );
}

useCardReader

Hook for magnetic stripe card reading with payment support.

Returns: DeviceHookResult<CardReader>

device CardReader | null

Card reader device instance

data any

Most recent scan data

ready boolean

Device is ready for use

enabled boolean

Device is currently enabled

pending boolean

Operation is in progress

status MessageCodes | null

Current device status code

state ComponentState | null

Device component state

Example

import { useCardReader } from '@elevationai/cuss2-react';

function PaymentComponent() {
  const { device, data, ready, enabled } = useCardReader();
  const [timeout, setTimeout] = useState(10000);

  const handleRead = async () => {
    if (device && enabled) {
      try {
        await device.read(timeout);
      } catch (error) {
        console.error('read failed:', error);
      }
    }
  };

  useEffect(() => {
    if (data) {
      console.log('Read data:', data);
    }
  }, [data]);

  return (
    <button onClick={handleRead} disabled={!ready || !enabled}>
      Read
    </button>
  );
}

useDocumentReader

Hook for passport and ID document scanning with MRZ support.

Returns: DeviceHookResult<DocumentReader>

device DocumentReader | null

Document reader device instance

data any

Most recent scan data

ready boolean

Device is ready for use

enabled boolean

Device is currently enabled

pending boolean

Operation is in progress

status MessageCodes | null

Current device status code

state ComponentState | null

Device component state

Example

import { useDocumentReader } from '@elevationai/cuss2-react';

function PassportScanner() {
  const { device, data, ready, enabled } = useDocumentReader();
  const [timeout, setTimeout] = useState(10000);

  const handleRead = async () => {
    if (device && enabled) {
      try {
        await device.read(timeout);
      } catch (error) {
        console.error('read failed:', error);
      }
    }
  };

  useEffect(() => {
    if (data) {
      console.log('Read data:', data);
    }
  }, [data]);

  return (
    <button onClick={handleRead} disabled={!ready || !enabled}>
      Read
    </button>
  );
}

useBagTagPrinter

Hook for baggage tag printing with automatic asset management.

Returns: PrinterHookResult<BagTagPrinter>

device BagTagPrinter | null

Bag Tag Printer device instance

data any

Most recent scan data

ready boolean

Device is ready for use

enabled boolean

Device is currently enabled

pending boolean

Operation is in progress

status MessageCodes | null

Current device status code

state ComponentState | null

Device component state

Example

import { useBagTagPrinter } from '@elevationai/cuss2-react';

function BagTagPrinter() {
  const { device, ready, enabled } = useBagTagPrinter();
  const [result, setResult] = useState(null);

  // Example company logo (hexadecimal encoded - truncated for brevity)
  const COMPANY_LOGO =
  'LT0146940A0201010000000100163006400640000000000000000000000000000000000000000000FFFFFFFFFFFFFFFFFFFFFF000124001001E0164' +
  '000000000000000000000000000000000000000000000000000000000000000000000000000000000000C0EF0BDE0A000000000000C2FC2F03' +
  'DCFFC1FCC3FFC1E7C1FF81C1FE07DBFFC1FCC3FF9FC1FC7FC1FFC1F87FDAFFC1FCC2FFC1FE7FC1E3C3FFF9DAFFC1FCC2FFC1FDAFFC1FCC2F';

  // Example bag tag data
  const bagTagData = useMemo(() => ({
    assets: 'BTT0801~J 500262=#01C0M5493450304#02C0M5493450304#03B1MA020250541=06#04B1MK200464141=06#05L0 A258250000#\n'
      + COMPANY_LOGO,
    coupon: 'BTP080101#01THIS IS A#02BAG TAG#03123#04456#0501#'
  }), []);

  const printBagTag = async () => {
    if (device && enabled) {
      try {
        // Two-phase print: setup() then print()
        await device.setupITPS([bagTagData.assets]);
        const res = await device.sendITPS([bagTagData.coupon]);
        setResult({ action: 'Print', result: res });
      } catch (error) {
        console.error('Failed to print:', error);
        setResult({ action: 'Print', error: String(error) });
      }
    }
  };

  return (
    <button onClick={() => printBagTag()} disabled={!ready || !enabled}>
      Print Bag Tag
    </button>
  );
}

useBoardingPassPrinter

Hook for boarding pass printing with ITPS format support.

Returns: PrinterHookResult<BoardingPassPrinter>

device BoardingPassPrinter | null

Boarding Pass Printer device instance

data any

Most recent scan data

ready boolean

Device is ready for use

enabled boolean

Device is currently enabled

pending boolean

Operation is in progress

status MessageCodes | null

Current device status code

state ComponentState | null

Device component state

Example

import { useBoardingPassPrinter } from '@elevationai/cuss2-react';

function BoardingPassPrinter() {
  const { device, ready, enabled } = useBoardingPassPrinter();
  const [result, setResult] = useState(null);

  // Example boarding pass data
  const boardingPassData = useMemo(() => ({
    assets: 'PT##$S6A#@;#TICK#CHEC#BOAR#0101110112011301210122012301C#0201A34#03BRB061661#0430G25F',
    coupon: 'CP#A#01S#CP#C01#02@@01#03M1THIS IS A BARCODE#04THIS IS A BOARDING PASS#'
  }), []);

  const printBoardingPass = async (passenger: any) => {
    if (device && enabled) {
      try {
        // Two-phase print: setup() then print()
        await device.setupITPS([boardingPassData.assets]);
        const res = await device.sendITPS([boardingPassData.coupon]);
        setResult({ action: 'Print', result: res });
      } catch (error) {
        console.error('Failed to print:', error);
        setResult({ action: 'Print', error: String(error) });
      }
    }
  };

  return (
    <button onClick={() => printBoardingPass(passenger)} disabled={!ready}>
      Print Boarding Pass
    </button>
  );
}

useKeypad

Hook for navigation keypad events for accessibility.

Returns: KeypadHookResult<Keypad>

device Keypad | null

Keypad device instance

data any

Most recent scan data

ready boolean

Device is ready for use

enabled boolean

Device is currently enabled

pending boolean

Operation is in progress

status MessageCodes | null

Current device status code

state ComponentState | null

Device component state

keypadData KeypadData

Keypad Data

Example

import { useKeypad } from '@elevationai/cuss2-react';

function NavigationComponent() {
  const { device, data, ready, enabled, keypadData } = useKeypad();

  useEffect(() => {
    if (device && ready && !enabled) {
      device.enable();
    }
  }, [device, ready]);

  useEffect(() => {
    if (keypadData) {
      console.log('Keypad event:', keypadData);
    }
  }, [keypadData]);

  return <div>Keypad navigation enabled</div>
}

useScale

Hook for luggage weighing with real-time updates.

Returns: DeviceHookResult<Scale>

device Scale | null

Scale device instance

data any

Most recent scan data

ready boolean

Device is ready for use

enabled boolean

Device is currently enabled

pending boolean

Operation is in progress

status MessageCodes | null

Current device status code

state ComponentState | null

Device component state

Example

import { useScale } from '@elevationai/cuss2-react';

function WeightDisplay() {
  const { device, data, ready, enabled } = useScale();

  useEffect(() => {
    if (data) {
      console.log('Weight data:', data);
    }
  }, [data]);

  const checkWeight = async () => {
    if (device && enabled) {
      try {
        await device.read(15000);
      } catch (error) {
        console.error('Weight read failed:', error);
      }
    }
  };

  return (
    <div>
      <div>Current weight: {weight.toFixed(1)} kg</div>
      <button onClick={checkWeight} disabled={!ready || !enabled}>
        Weigh Bag
      </button>
    </div>
  );
}

useAnnouncement

Hook for text-to-speech announcements and audio playback.

Returns: DeviceHookResult<Announcement>

device Announcement | null

Announcement device instance

data any

Most recent scan data

ready boolean

Device is ready for use

enabled boolean

Device is currently enabled

pending boolean

Operation is in progress

status MessageCodes | null

Current device status code

state ComponentState | null

Device component state

Example

import { useAnnouncement } from '@elevationai/cuss2-react';

function AnnouncementComponent() {
  const { device, ready, enabled } = useAnnouncement();

  useEffect(() => {
    if (device && ready && !enabled) {
      device.enable();
    }
  }, [device, ready]);

  const say = async (message: string) => {
    if (device && enabled) {
      try {
        await device.say(message);
      } catch (error) {
        console.error('Announcement say failed:', error);
      }
    }
  };

  const pause = async () => {
    if (device && enabled) {
      try {
        await device.pause();
      } catch (error) {
        console.error('Announcement pause failed:', error);
      }
    }
  };

  const resume = async () => {
    if (device && enabled) {
      try {
        await device.resume();
      } catch (error) {
        console.error('Announcement resume failed:', error);
      }
    }
  };

  const stop = async () => {
    if (device && enabled) {
      try {
        await device.stop();
      } catch (error) {
        console.error('Announcement stop failed:', error);
      }
    }
  };

  return (
    <button onClick={() => say('Please scan your boarding pass')}>
      Say
    </button>
    <button onClick={() => pause()}>
      Pause
    </button>
    <button onClick={() => resume()}>
      Resume
    </button>
    <button onClick={() => stop()}>
      Stop
    </button>
  );
}

useHeadset

Hook for audio headset management for accessibility features.

Returns: DeviceHookResult<Headset>

device Headset | null

Headset device instance

data any

Most recent scan data

ready boolean

Device is ready for use

enabled boolean

Device is currently enabled

pending boolean

Operation is in progress

status MessageCodes | null

Current device status code

state ComponentState | null

Device component state

Example

import { useHeadset } from '@elevationai/cuss2-react';

function HeadsetComponent() {
  const { cuss2 } = useCuss2();
  const { device, ready, enabled } = useHeadset();

  useEffect(() => {
    if (device && ready && !enabled) {
      device.enable();
    }
  }, [device, ready]);

  useEffect(() => {
    if (cuss2) {
      device.enable();
    }
  }, [cuss2]);

  return (
    <div>
      {cuss2?.accessibleMode ? 'Accessible Mode On' : 'Accessible Mode Off'}
    </div>
  );
}

useCamera

Hook for camera capture for photo documentation.

Returns: DeviceHookResult<Camera>

device Camera | null

Camera device instance

data any

Most recent scan data

ready boolean

Device is ready for use

enabled boolean

Device is currently enabled

pending boolean

Operation is in progress

status MessageCodes | null

Current device status code

state ComponentState | null

Device component state

Example

import { useCamera } from '@elevationai/cuss2-react';

function CameraComponent() {
  const { device, data, ready, enabled } = useCamera();

  useEffect(() => {
    if (device && ready && !enabled) {
      device.enable();
    }
  }, [device, ready]);

  const capturePhoto = async () => {
    if (device && enabled) {
      try {
        await device.read(10000);
      } catch (error) {
        console.error('Photo capture failed:', error);
      }
    }
  };

  useEffect(() => {
    if (data) {
      console.log('Photo captured:', data);
    }
  }, [data]);

  return (
    <button onClick={capturePhoto} disabled={!ready || !enabled}>
      Take Photo
    </button>
  );
}

useBiometric

Hook for biometric verification (fingerprint, face recognition).

Returns: DeviceHookResult<Biometric>

device Biometric | null

Biometric device instance

data any

Most recent scan data

ready boolean

Device is ready for use

enabled boolean

Device is currently enabled

pending boolean

Operation is in progress

status MessageCodes | null

Current device status code

state ComponentState | null

Device component state

Example

import { useBiometric } from '@elevationai/cuss2-react';

function BiometricComponent() {
  const { device, data, ready, enabled } = useBiometric();

  useEffect(() => {
    if (device && ready && !enabled) {
      device.enable();
    }
  }, [device, ready]);

  const dataObj: CommonUseBiometricMessage = {
    documentType: 'CHARACTERISTICS' | 'BIOMETRIC_PROVIDER_MESSAGE' | 'ERROR_RESPONSE';
    /**
     * An arbitrary tracking value that the CUSS application chooses and assigns when starting a biometric provider function. The CUSS platform must then echo this requested value in all subsequent responses or asynchronous event messages related to that biometric provider function. This correlation permits a CUSS application to match and associate request and response messages and is critical for the case where an application has more than one multi-step biometric provider function ongoing concurrently.
     */
    sessionID?: string;
    /**
     * Component characteristics.
     */
    characteristics?: {
        characteristicsDocumentType: CharacteristicsDocumentType;
        characteristicsDocumentReturnType: CharacteristicsDocumentType;
        characteristicsRequest?: BiometricAnyType;
    };
    biometricProviderMessage?: BiometricProviderMessage;
    /**
     * Error code as reported from the CUSS platform.
     */
    errorResponse?: 'DATA_ERROR' | 'FORMAT_ERROR' | 'ILLOGICAL';
  };

  const verifyIdentity = async () => {
    if (device && enabled) {
      try {
        await device.send(dataObj);
      } catch (error) {
        console.error('Verification failed:', error);
      }
    }
  };

  useEffect(() => {
    if (data) {
      console.log('Biometric data:', data);
      verifyWithBackend(data);
    }
  }, [data]);

  return (
    <button onClick={verifyIdentity} disabled={!ready || !enabled}>
      Verify Identity
    </button>
  );
}