@novastar-dev/coex

A TypeScript library for controlling NovaStar COEX video wall processors via HTTP API, targeting COEX firmware v1.5+.

Features

Full TypeScript support with strict type checking
Promise-based API with async/await
Comprehensive input validation using type guards
142 tests with 91%+ coverage
MSW 2.x for API mocking in tests

Installation

npm i @novastar-dev/coex

Quick Start

import { COEX } from "@novastar-dev/coex";

const device = new COEX("192.168.1.100", 8001);

async function main() {
  try {
    // Get available input sources
    const sources = await device.apiInstance.sources();
    console.log("Sources:", sources);

    // Set brightness
    await device.brightness(80);

    // Apply a preset
    await device.apiInstance.applyPreset("screen1", 1);
  } catch (error) {
    console.error("Error:", error);
  }
}

main();

API Overview

High-Level Methods (on `COEX` class)

Method	Description
`blackout()`	Set display to blackout mode
`normal()`	Set display to normal mode
`freeze()`	Freeze the current frame
`brightness(value)`	Set screen brightness (0-100)
`input(name)`	Switch input source by name
`summary()`	Get cabinet count

Screen API

Method	Description
`screen()`	Get screen information
`getScreenProperties()`	Get screen properties
`getCabinetCount()`	Get cabinet count
`displaymode(value)`	Set display mode (0=normal, 1=blackout, 2=freeze)
`brightness(value, screenIds?)`	Set brightness
`colortemperature(value, screenIds?)`	Set color temperature (1000-12000K)
`gamma(value, screenIds?)`	Set gamma (1.0-4.0)
`getDisplayState()`	Get display state
`getDisplayParams()`	Get display parameters
`switchLayerSource(screenId, layers)`	Switch layer source
`setMapping(canvasId, mappingData)`	Set canvas mapping
`getScreenList()`	Get all screens

Preset API

Method	Description
`getPreset()`	Get all presets
`applyPreset(screenID, sequenceNumber)`	Apply a preset
`modifyPreset(screenID, options)`	Modify preset settings

Device API

Method	Description
`sources()`	Get available input sources
`monitor()`	Get real-time monitoring info
`cabinet()`	Get cabinet information
`setHdrMode(id, hdrMode)`	Set HDR mode
`setInternalSource(options)`	Set internal source
`setSendingCardTestPattern(mode, params?)`	Set test pattern
`setShadow(inputIdList, type, shadow)`	Adjust shadow
`setHighlight(inputIdList, type, value)`	Adjust highlight
`setSaturation(inputIdList, value)`	Set saturation
`setContrast(inputIdList, value)`	Set contrast
`setHue(inputIdList, value)`	Set hue
`setEdid(inputId, options)`	Configure EDID
`setOutputAudio(enable, source)`	Set output audio
`getAudioSettings()`	Get audio settings
`controllerIdentify(enable, color)`	Identify controller
`getDeviceBackupStatus()`	Get backup status
`exportLog()`	Export device logs
`setSystemTime(options)`	Set system time
`setTimeZone(timezone)`	Set timezone
`setControllerName(name)`	Set controller name
`getSnmpStatus()`	Get SNMP status
`setSnmpOnOff(state)`	Enable/disable SNMP
`deviceIdentify(enable)`	Identify device

Cabinet API

Method	Description
`setNoDataSignal(idList, sourceType, imageType)`	Set no-data signal behavior
`setThermalCompensationOnOff(idList, enable)`	Toggle thermal compensation
`setThermalCompensationIntensity(idList, amount)`	Set compensation intensity
`setCabinetRgbBrightness(idList, r, g, b)`	Set RGB brightness
`setCabinetBrightness(idList, ratio, nit?)`	Set brightness
`adjustCabinetColorTemperature(idList, value)`	Adjust color temperature
`setReceivingCardTestPattern(idList, mode)`	Set test pattern
`enableCabinetMapping(idList, enable)`	Enable/disable mapping
`moveCabinet(screenID, canvases)`	Move cabinet

Error Handling

All methods throw typed errors with descriptive messages:

try {
  await device.brightness(150); // Invalid: 0-100 range
} catch (error) {
  if (error instanceof Error) {
    console.log(error.message); // "brightness must be between 0 and 100"
  }
}

TypeScript

The library exports all relevant types:

import {
  COEX,
  createCoexApi,
  type Screen,
  type Cabinet,
  type Preset,
  type InputSource,
  type ApiResponse,
} from "@novastar-dev/coex";

Testing

npm test        # Run tests
npm run test:coverage  # Run with coverage

License

MIT

@novastar-dev/coex

Package Exports

Readme

@novastar-dev/coex

Features

Installation

Quick Start

API Overview

High-Level Methods (on COEX class)

Screen API

Preset API

Device API

Cabinet API

Error Handling

TypeScript

Testing

License

High-Level Methods (on `COEX` class)