Skip to content

INTEGRATION_GUIDE.md

Latest commit

 

History

History
657 lines (502 loc) · 15.1 KB

INTEGRATION_GUIDE.md

File metadata and controls

657 lines (502 loc) · 15.1 KB

Complete Integration and Testing Guide

Overview

This guide walks you through the complete setup, from hardware connections to software testing, ensuring everything works together.

Table of Contents

  1. Hardware Setup
  2. Power Connections
  3. LED Tube Connection
  4. Network Configuration
  5. Controller Configuration
  6. Software Installation
  7. Testing Procedure
  8. Troubleshooting

1. Hardware Setup

Required Components

  • ✅ Raspberry Pi (any model with Ethernet port)
  • ✅ T-790K LED Controller
  • ✅ DMX512 LED Tube (24 pixels/meter)
  • ✅ Mean Well LRS-350-24 Power Supply (24V, 350W)
  • ✅ Ethernet cable
  • ✅ Power cables
  • ✅ LED tube connection cable
  • ✅ MicroSD card (for Raspberry Pi, 8GB minimum)
  • ✅ Power adapter for Raspberry Pi

Physical Layout

┌─────────────┐
│ Power Outlet│
└──────┬──────┘
       │
       ├─────────────────┐
       │                 │
┌──────▼──────┐   ┌──────▼──────┐
│ Power       │   │ Power       │
│ Supply      │   │ Adapter     │
│ (24V)       │   │ (5V)        │
└──────┬──────┘   └──────┬──────┘
       │                 │
       │                 │
┌──────▼──────┐   ┌──────▼──────┐
│ T-790K      │   │ Raspberry   │
│ Controller  │   │ Pi          │
└──────┬──────┘   └──────┬──────┘
       │                 │
       │                 │
       │            Ethernet Cable
       │                 │
       │            ┌────▼────┐
       │            │ Network  │
       │            │ Switch/  │
       │            │ Router   │
       │            └────┬─────┘
       │                 │
       │            (Same Network)
       │                 │
       └─────────────────┘
              │
       ┌──────▼──────┐
       │ LED Tube   │
       └────────────┘

2. Power Connections

2.1 Power Supply Setup (Mean Well LRS-350-24)

⚠️ SAFETY FIRST: Disconnect all power before making connections!

  1. Input Power (AC)

    • Connect AC power cord to power supply
    • Ensure voltage switch matches your region (110V or 220V)
    • Power supply has screw terminals labeled:
      • L (Line/Hot) - Connect to one AC wire
      • N (Neutral) - Connect to other AC wire
      • FG (Ground) - Connect to ground wire

  2. Output Power (DC 24V)

    • Locate DC output terminals:
      • V+ or + (Positive)
      • V- or - (Negative/Common)
    • DO NOT connect LED tube yet - we'll do this after controller setup

  3. Power Supply Verification

    • Turn on power supply
    • Check LED indicator (should light up)
    • Measure output voltage with multimeter (should read ~24V DC)
    • Turn off power supply before proceeding

2.2 Raspberry Pi Power

  1. Connect Raspberry Pi power adapter (5V, 2-3A)
  2. Insert microSD card with Raspberry Pi OS
  3. Connect to monitor/keyboard or use SSH (headless setup)

3. LED Tube Connection

3.1 Understanding LED Tube Connections

The LED tube has connection points at both ends:

  • Input end: Receives power and data
  • Output end: Can connect to next tube (if chaining)

3.2 Connection Steps

  1. Identify Connection Points

    • LED tube typically has 4 wires:
      • Red: +24V (Power positive)
      • Black: GND (Power ground)
      • Green/White: Data signal
      • Blue/Yellow: Clock signal (if applicable)

  2. Connect to Controller

    • Connect LED tube to Port 1 of T-790K controller
    • Controller ports have screw terminals or connectors
    • Match wire colors to controller labels:
      • Power: V+ and V- (or GND)
      • Data: D+ or Data
      • Clock: C+ or Clock (if needed)

  3. Power Connection

    • Connect power supply output to controller:
      • Power supply V+ → Controller V+ input
      • Power supply V- → Controller V- input
    • Controller distributes power to LED ports

  4. Verify Connections

    • Double-check all connections are secure
    • Ensure no loose wires
    • Check for short circuits

4. Network Configuration

4.1 Raspberry Pi Network Setup

Option A: Wired Connection (Recommended)

  1. Connect Ethernet Cable

    • Connect Raspberry Pi to router/switch
    • Connect T-790K controller to same router/switch

  2. Find Raspberry Pi IP Address

    # On Raspberry Pi, run:
hostname -I
# Example output: 192.168.1.50

  3. Configure Static IP (Optional but Recommended)

    # Edit network configuration
sudo nano /etc/dhcpcd.conf

# Add at the end:
interface eth0
static ip_address=192.168.1.50/24
static routers=192.168.1.1
static domain_name_servers=192.168.1.1

# Save and reboot
sudo reboot

Option B: WiFi Connection

  1. Configure WiFi

    sudo raspi-config
# Navigate to: System Options > Wireless LAN
# Enter SSID and password

  2. Find IP Address

    hostname -I

4.2 Controller Network Setup

  1. Connect Controller to Network

    • Connect Ethernet cable to controller
    • Controller should get IP via DHCP automatically

  2. Find Controller IP Address

    Method 1: Controller LCD Display

    • Power on controller
    • Check LCD screen for IP address
    • Note the IP (e.g., 192.168.1.100)

    Method 2: Router Admin Panel

    • Log into router (usually 192.168.1.1)
    • Check DHCP client list
    • Look for device named "T-790K" or similar

    Method 3: Network Scan

    # On Raspberry Pi, scan network
nmap -sn 192.168.1.0/24
# Look for devices on the network

    Method 4: Ping Test

    # Try common IP ranges
ping 192.168.1.100
ping 192.168.1.101
# Controller should respond if IP is correct

  3. Set Static IP on Controller (Recommended)

    • Access controller web interface (if available)
    • Or use controller's LCD menu to set static IP
    • Recommended IP: 192.168.1.100 (or similar)

4.3 Network Verification

# From Raspberry Pi, test connectivity
ping 192.168.1.100  # Replace with controller IP

# Should see:
# 64 bytes from 192.168.1.100: icmp_seq=1 ttl=64 time=1.23 ms

If ping fails:

  • Check Ethernet cables
  • Verify both devices on same network
  • Check router/switch connections
  • Verify controller is powered on

5. Controller Configuration

5.1 Controller Setup Steps

  1. Power On Controller

    • Connect power supply to controller
    • Turn on power supply
    • Controller should boot up (LED indicators)

  2. Check Controller Display

    • LCD should show:
      • Model: T-790K
      • IP address
      • Status information

  3. Configure Protocol

    • Controller should support Art-Net by default
    • If needed, access configuration:
      • Use controller buttons/menu
      • Or web interface (if available)
    • Set to Art-Net mode

  4. Configure DMX Universe

    • Set Universe to 1 (default)
    • Verify port configuration
    • Ensure Port 1 is enabled

  5. Test Controller

    • Controller may have built-in test mode
    • Check manual for test button/function
    • LEDs should respond if working

6. Software Installation

6.1 Install Node.js on Raspberry Pi

# Update system
sudo apt update
sudo apt upgrade -y

# Install Node.js (version 18)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify installation
node --version  # Should show v18.x.x or higher
npm --version   # Should show 9.x.x or higher

6.2 Install Project Files

# Navigate to project directory
cd led-control

# Install dependencies
npm install

# Verify installation
ls node_modules  # Should show installed packages

6.3 Configure Project

# Edit the example files to set correct IP
nano examples/simple-test.js

# Change this line:
host: '192.168.1.100',  # Replace with your controller IP

7. Testing Procedure

7.1 Pre-Test Checklist

  • Power supply connected and verified (24V output)
  • LED tube connected to controller Port 1
  • Controller powered on and showing IP address
  • Raspberry Pi powered on and connected to network
  • Both devices on same network
  • Network connectivity verified (ping test successful)
  • Node.js installed on Raspberry Pi
  • Project dependencies installed
  • Controller IP address configured in code

7.2 Test 1: Basic Connectivity

# On Raspberry Pi, test network connection
ping 192.168.1.100  # Your controller IP

# Should get responses
# Press Ctrl+C to stop

Expected Result: Successful ping responses

If Failed: Check network connections, IP addresses

7.3 Test 2: Simple Color Test

# Run simple test
cd led-control
node examples/simple-test.js

What to Expect:

  1. Console shows "Starting LED test..."
  2. LEDs turn RED (2 seconds)
  3. LEDs turn GREEN (2 seconds)
  4. LEDs turn BLUE (2 seconds)
  5. LEDs turn WHITE (2 seconds)
  6. LEDs turn OFF (1 second)
  7. Console shows "Test complete!"

If LEDs Don't Respond:

  • Check LED tube power connection
  • Verify controller is receiving data
  • Check DMX address settings
  • Verify port 1 is enabled

7.4 Test 3: Rainbow Effect

# Run rainbow effect
node examples/rainbow-effect.js

What to Expect:

  • Smooth rainbow animation across LED strip
  • Colors continuously cycling
  • No flickering
  • Smooth transitions

To Stop: Press Ctrl+C

If Not Working:

  • Check update rate (may be too fast/slow)
  • Verify all pixels are responding
  • Check for network latency

7.5 Test 4: Chase Effect

# Run chase effect
node examples/chase-effect.js

What to Expect:

  • Moving light effect
  • Smooth motion across strip
  • Consistent brightness

To Stop: Press Ctrl+C

7.6 Test 5: Manual Control

Create a test file:

nano test-manual.js

Paste this code:

const LEDController = require('./index');

const leds = new LEDController({
  protocol: 'artnet',
  host: '192.168.1.100', // Your controller IP
  pixelsPerMeter: 24,
  tubeLength: 1
});

console.log('Setting pixel 0 to red...');
leds.setPixel(0, 255, 0, 0);
leds.update();

setTimeout(() => {
  console.log('Setting pixel 5 to green...');
  leds.setPixel(5, 0, 255, 0);
  leds.update();
  
  setTimeout(() => {
    console.log('Setting pixel 10 to blue...');
    leds.setPixel(10, 0, 0, 255);
    leds.update();
    
    setTimeout(() => {
      console.log('Setting all to white...');
      leds.setAll(255, 255, 255);
      leds.update();
      
      setTimeout(() => {
        console.log('Clearing...');
        leds.clear();
        process.exit(0);
      }, 2000);
    }, 2000);
  }, 2000);
}, 2000);

Run it:

node test-manual.js

Expected Result: Individual pixels light up in sequence

8. Troubleshooting

8.1 LEDs Not Lighting Up

Check Power:

  • Verify power supply is on
  • Measure voltage at LED tube (should be ~24V)
  • Check power connections are secure
  • Verify controller is receiving power

Check Data Connection:

  • Verify data wire is connected
  • Check wire polarity (if applicable)
  • Try different port on controller
  • Check for loose connections

Check Controller:

  • Verify controller is powered on
  • Check controller status LEDs
  • Verify port is enabled
  • Check DMX address settings

8.2 Network Connection Issues

Ping Fails:

# Check if devices are on same network
ip addr show  # On Raspberry Pi
# Compare network addresses (should match first 3 numbers)

# Check router/switch
# Verify both devices connected to same network device

Solutions:

  • Use wired connection (more reliable)
  • Check Ethernet cables
  • Restart router/switch
  • Set static IPs on both devices
  • Check firewall settings

8.3 Wrong Colors

RGB Channel Order:

  • Some LED strips use different channel order
  • Try swapping RGB values
  • Check LED tube documentation

DMX Address:

  • Verify starting DMX address
  • Check if address offset needed
  • Some controllers start at channel 1, others at 0

8.4 Flickering or Unstable

Network Issues:

  • Check network latency: ping -c 10 192.168.1.100
  • Use wired connection instead of WiFi
  • Check for network congestion

Power Issues:

  • Verify adequate power supply capacity
  • Check for voltage drops
  • Ensure proper grounding

Update Rate:

  • Reduce update frequency if too fast
  • Increase delay between updates

8.5 Code Errors

"Cannot find module":

# Reinstall dependencies
npm install

"Connection refused":

  • Verify controller IP address
  • Check network connectivity
  • Verify controller is powered on

"Port already in use":

  • Close other instances
  • Check for background processes
  • Restart Raspberry Pi

8.6 Debug Mode

Enable verbose logging by modifying index.js:

// Add at the beginning of update() method
console.log('Sending data:', this.ledBuffer);
console.log('Host:', this.host);
console.log('Universe:', this.universe);

9. Verification Checklist

After complete setup, verify:

  • Power supply provides 24V DC
  • LED tube receives power
  • Controller is powered and shows IP
  • Raspberry Pi is on network
  • Ping test successful
  • Node.js installed and working
  • Project dependencies installed
  • Simple test runs successfully
  • LEDs respond to commands
  • Colors are correct
  • Effects work smoothly

10. Next Steps

Once everything is working:

  1. Experiment with Colors

    leds.setAll(255, 128, 0); // Orange
leds.update();

  2. Create Custom Effects

    • Modify existing effects
    • Create new patterns
    • Combine multiple effects

  3. Expand System

    • Add more LED tubes
    • Use multiple controller ports
    • Create complex patterns

  4. Integrate with Other Systems

    • Web interface
    • Sensor input
    • Audio visualization
    • Time-based scheduling

Safety Reminders

⚠️ Always:

  • Disconnect power before making connections
  • Double-check wire polarities
  • Use appropriate wire gauges
  • Ensure proper grounding
  • Don't exceed power supply capacity
  • Keep connections secure and protected

Quick Reference

Controller IP: 192.168.1.100 (change as needed)
Raspberry Pi IP: 192.168.1.50 (change as needed)
Universe: 1
Port: 1
Protocol: artnet
Pixels: 24 per meter

Test Command:

node examples/simple-test.js

Network Test:

ping 192.168.1.100

Support

If issues persist:

  1. Review troubleshooting section
  2. Check all connections
  3. Verify network settings
  4. Test with minimal configuration
  5. Consult controller manual
  6. Check LED tube specifications