nodejs-pixelcolor-led-ctrl

A TypeScript/JavaScript library for controlling iPixel Color LED displays via Bluetooth Low Energy (BLE). Display text, images, clock modes, and more on your LED panels.

Features

🎨 Text Display - Show custom text with animations, colors, and effects
🖼️ Image Display - Send images (PNG, JPG, GIF, BMP, WebP) to your LED panel
🕒 Clock Mode - Built-in clock display with multiple styles
🎵 Rhythm Mode - Music visualizer with 8 different styles
⚡ Device Control - Power, brightness, orientation, and more
📱 BLE Support - Seamless Bluetooth Low Energy connectivity
🔍 Device Discovery - Automatic scanning for nearby devices
💪 TypeScript - Full type safety and IntelliSense support

Installation

npm install nodejs-pixelcolor-led-ctrl

System Requirements

This package uses Bluetooth Low Energy (BLE) and requires:

macOS: Works out of the box
Linux: Install libbluetooth-dev (e.g., sudo apt-get install libbluetooth-dev)
Windows: Bluetooth 4.0+ compatible adapter required

Quick Start

import IPixelColorLedController, { scanDevices } from 'nodejs-pixelcolor-led-ctrl'

// Scan for devices
const devices = await scanDevices()
console.log('Found devices:', devices.map(d => d.advertisement.localName))

// Connect to device
const controller = new IPixelColorLedController(devices[0].advertisement.localName)
await controller.connect()

// Power on and send text
await controller.powerOn()
await controller.sendText({
  text: 'Hello World!',
  color: 'ff0000', // Red
  animation: 1, // Scroll left
  speed: 80,
})

// Cleanup
await controller.disconnect()

API Reference

Controller

Constructor

new IPixelColorLedController(targetDeviceName: string, options?: ControllerOptions)

Options:

logHandler?: (level: LogLevel, context: string, message: string) => void - Custom log handler

Connection Methods

await controller.connect()           // Connect to the device
await controller.disconnect()         // Disconnect from the device
await controller.getDeviceInfo()      // Get device dimensions and type

Power & Display Control

await controller.powerOn()                    // Turn on the display
await controller.powerOff()                   // Turn off the display
await controller.setBrightness(level)         // Set brightness (0-100)
await controller.setOrientation(orientation)  // Set orientation (0-3: 0°, 90°, 180°, 270°)
await controller.clear()                      // Clear the display
await controller.deleteScreen(screenIndex)    // Delete a saved screen

Text Display

await controller.sendText({
  text: string,              // Text to display
  animation?: number,        // Animation type (default: 1)
  speed?: number,            // Animation speed (default: 80)
  color?: string,            // Text color in hex (default: 'ffffff')
  bgColor?: string | null,   // Background color in hex (default: null)
  rainbowMode?: number,      // Rainbow effect mode (default: 0)
  saveSlot?: number,         // Save to slot (default: 0)
  fontFamily?: string,       // Font family (default: 'Arial')
  fontSize?: number | null,  // Font size (default: auto)
  varWidth?: boolean,        // Variable width characters (default: false)
  chunkWidth?: number,       // Chunk width (default: 16)
  rtl?: boolean,            // Right-to-left text (default: false)
})

Animation Types:

0 - Static
1 - Scroll Left
2 - Scroll Right
5 - Blink
6 - Breath
7 - Laser

Image Display

await controller.sendImage({
  imagePath: string,                    // Path to image file
  resizeMethod?: ResizeMethod,          // 'crop' or 'fit' (default: 'crop')
})

Supported formats: PNG, JPG, JPEG, GIF, BMP, WebP

Clock Mode

await controller.setClockMode({
  style: number,        // Clock style (1-11)
  showDate?: boolean,   // Show date (default: false)
  format24?: boolean,   // 24-hour format (default: false)
  date: string,        // Date in YYYY-MM-DD format
})

Rhythm Mode (Music Visualizer)

await controller.setRhythmMode({
  style: number,           // Visualizer style (0-7)
  levels: number[],        // Array of 11 level values
  simplified?: boolean,    // Use simplified mode (default: false)
})

Fun Mode

await controller.setFunMode(enabled: boolean)

Utility Functions

import { scanDevices } from 'nodejs-pixelcolor-led-ctrl'

// Scan for nearby BLE devices
const devices = await scanDevices(timeoutMs?: number) // default: 5000ms

Enums

import { LogLevel, AnimationType, ResizeMethod } from 'nodejs-pixelcolor-led-ctrl'

// Log levels
LogLevel.Trace
LogLevel.Info
LogLevel.Warn
LogLevel.Error

// Animation types
AnimationType.Static
AnimationType.ScrollLeft
AnimationType.ScrollRight
AnimationType.Blink
AnimationType.Breath
AnimationType.Laser

// Resize methods
ResizeMethod.CROP
ResizeMethod.FIT

Examples

Display Text with Animation

import IPixelColorLedController from 'nodejs-pixelcolor-led-ctrl'

const controller = new IPixelColorLedController('iPixel-XXXX')
await controller.connect()
await controller.powerOn()

await controller.sendText({
  text: 'Hello, World!',
  animation: 1,      // Scroll left
  speed: 80,
  color: '00ff00',   // Green
  fontSize: 14,
})

await controller.disconnect()

Display an Image

import IPixelColorLedController, { ResizeMethod } from 'nodejs-pixelcolor-led-ctrl'
import path from 'path'

const controller = new IPixelColorLedController('iPixel-XXXX')
await controller.connect()
await controller.powerOn()

await controller.sendImage({
  imagePath: path.resolve('./my-image.png'),
  resizeMethod: ResizeMethod.FIT,
})

await controller.disconnect()

Set Clock Display

import IPixelColorLedController from 'nodejs-pixelcolor-led-ctrl'

const controller = new IPixelColorLedController('iPixel-XXXX')
await controller.connect()
await controller.powerOn()

await controller.setClockMode({
  style: 5,
  showDate: true,
  format24: true,
  date: '2025-12-08',
})

await controller.disconnect()

Custom Logging

import IPixelColorLedController, { LogLevel } from 'nodejs-pixelcolor-led-ctrl'

const controller = new IPixelColorLedController('iPixel-XXXX', {
  logHandler: (level, context, message) => {
    console.log(`[${LogLevel[level]}] ${context}: ${message}`)
  },
})

Development

Setup

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Lint code
pnpm lint

# Format code
pnpm format

Running Examples

# Send text example
pnpm example:send-text

# Send image example
pnpm example:send-image

Troubleshooting

Bluetooth Permission Issues

macOS: Grant Bluetooth permissions to your terminal/IDE in System Preferences → Security & Privacy → Bluetooth

Linux: May require running with sudo or adding your user to the bluetooth group:

sudo usermod -a -G bluetooth $USER

Device Not Found

Ensure your LED device is powered on and in pairing mode
Make sure Bluetooth is enabled on your system
Try increasing the scan timeout: scanDevices(10000)

Connection Drops

Keep the device within Bluetooth range (typically 10 meters)
Avoid obstacles between your computer and the LED device
Ensure no other devices are connected to the LED panel

Credits

This library is inspired by the excellent pypixelcolor Python library by lucagoc.

License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Support

🐛 Report bugs
💡 Request features
⭐ Star this repo if you find it helpful!

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.vscode		.vscode
examples		examples
src		src
tests		tests
.gitignore		.gitignore
.prettierrc.json		.prettierrc.json
README.md		README.md
eslint.config.ts		eslint.config.ts
index.ts		index.ts
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

ezypeeze/nodejs-pixelcolor-led-ctrl

Folders and files

Latest commit

History

Repository files navigation