# Xlights/Nutcracker User Manual

By Sean Meighan

Version: 1.0

Last Updated: 04/29/14

Table of Contents

Xlights/Nutcracker User Manual 1

1 Introduction 3

Xlights 3

1.3 Nutcracker 3

1.4 Xlights+Nutcracker 3

1.5 Xlights+Nutcracker is free! 4

2 Download and Installation 5

2.3 Download 5

2.4 Installation 6

3 SETUP 6

3.3.5 Hardware Controllers, USB 6

3.3.5.7 DMX 6

3.3.5.8 OpenDMX 6

3.3.5.9 Pixelnet 7

3.3.5.10 LOR 7

3.3.5.11 D-Light 7

3.3.5.12 Renard 7

3.3.6 Hardware Controllers, E1.31 7

3.4 Verify 8

4 TEST 9

4.3 How to Select/Unselect Channels 9

4.4 Testing Channels 9

4.4.5 regular lights 9

4.4.6 dumb rgb 9

4.4.7 smart rgb 9

4.5 Save Test Group 9

5 CONVERT 10

6 PREVIEW 10

7 NUTCRACKER 10

7.3 Effect Classes 10

7.3.5 None 10

7.3.6 Bars 10

7.3.7 Butterfly 11

7.3.8 Circles 12

7.3.9 Color Wash 12

7.3.10 Curtain 13

7.3.11 Fire 13

8 The Fire effect will create a fire that you can control its height 14

8.3.5 Fireworks 15

8.3.6 Garlands 15

8.3.7 Life 15

8.3.8 Meteors 15

8.3.9 Piano 15

8.3.10 Pictures 15

8.3.11 Snowflakes 15

8.3.12 Snowstorm 15

8.3.13 Spirals 15

8.3.14 Spirograph 15

8.3.15 Text 15

8.3.16 Tree 15

8.3.17 Twinkle 15

8.3.18 SingleStrand 15

8.3.19 Faces 15

8.3.20 Wave 15

9 SCHEDULE 15

# 1 Introduction

Xlights was written by Matt Brown. Nutcracker was written by Sean Meighan.

## Xlights

Xlights was created in 2010 by Matt Brown. Matt, a LOR user, wanted a show player that would have low system requirements and high performance. Xlights has been a reliable player used by hundreds of Christmas Light enthusiasts over the last 4 years.

## 1.3 Nutcracker

Nutcracker was written by Sean Meighan in 2012. Sean, who was new to Christmas Lights, wanted an easier way of creating effects on smart RGB devices. Sean came up with the concept of defining a model (Megatree, matrix, arches, .etc.) and then dropping effects (butterfly, spirals, text, .etc.) onto the model. Nutcracker 1 and 2 were developed as a web application. To create effects you would log into the web , define models, drop effects.

## 1.4 Xlights+Nutcracker

In January 2013 , Matt Brown took the web based code that Sean had written and re-wrote into C++ and made Nutcracker part of xLights. This produced a real time Nutcracker product. An Example: The snowflake effect took 5 minutes to generate effects using Nutcracker 2 , in Nutcracker 3 (The xLights port) , that same effect now took less than 5 seconds.

Amazing work by Matt!

llustration 1: Matt Brown and Sean Meighan at The Academy show in 2012

## 1.5 Xlights+Nutcracker is free!

Both Matt and Sean have always believed their software should be made available free to the lighting community. The sources of xLights/Nutcracker is available to download from github. You can download the free sources from https://github.com/smeighan/xLights.

Hardware Controllers, USB

Easy configuration to any hardware controller. Choose from USB driven data or E1.31. These are the current choices: DMX, OpenDMX, Pixelnet, LOR, D-Light, Renard

Hardware Controllers, E1.31

The other harware controller you can choose is E1.31. This is the ethernet port on your computer. You would choose E1.31 if you had controllers from SanDevices (E6804, E682, .etc.), J1SYS devices (P12r, p12s,.etc.), Falcon Christmas (FPD, Falcon-16, Falcon-8), DLA Etherdongle.

Any DMX device can also be driver through E1.31, Ray Wu 27 channel controller.

# 2 Download and Installation

## 2.3 Download

To download the latest software go to http://nutcracker123.com/nutcracker/releases

The most recent release is on the top of the list. Click to download the 13mbyte file. When downloading a new version you just overlay the previous version. No sequences will be modified with each download. You will not lose any work!

## 2.4 Installation

When you go to install, your anti-virus software (here SpyHunter) may give a warning |  | Take the defaults |
Take the default for installation directory |  | Take default |
|  | Installation is complete. |

# 3 SETUP

### 3.3.5 Hardware Controllers, USB

Easy configuration to any hardware controller. Choose from USB driven data or E1.31. These are the current choices: DMX, OpenDMX, Pixelnet, LOR, D-Light, Renard

#### 3.3.5.7 DMX

DMX controllers (or LOR or D-Light controllers in DMX mode) attached to an Entec DMX USB Pro, Lynx DMX dongle, DIYC RPM, DMXking.com, or DIY Blinky dongle.

Last Channel should be 512 or less, unless you are using a DIY Blinky dongle (in which case it can be up to 3036).

#### 3.3.5.8 OpenDMX

DMX controllers (or LOR or D-Light controllers in DMX mode) attached to an LOR dongle, D-Light dongle, HolidayCoro programming cable, or Entec Open DMX dongle

#### 3.3.5.9 Pixelnet

Pixelnet hub attached to a Lynx Pixelnet dongle.

#### 3.3.5.10 LOR

LOR controllers attached to any LOR dongle.

Max of 8 channels at 9600 baud.

Max of 48 channels at 57600 baud.

Max of 96 channels at 115200 baud.

Run your controllers in DMX mode for higher throughput.

#### 3.3.5.11 D-Light

D-Light controllers attached to a D-Light dongle.

Max of 8 channels at 9600 baud.

Max of 48 channels at 57600 baud.

Max of 96 channels at 115200 baud.

Run your controllers in DMX mode for higher throughput.

#### 3.3.5.12 Renard

Renard controllers connected to a serial port or a USB dongle with virtual comm port. 2 stop bits are set automatically.

Max of 42 channels at 9600 baud.

Max of 260 channels at 57600 baud.

### 3.3.6 Hardware Controllers, E1.31

The other harware controller you can choose is E1.31. This is the ethernet port on your computer. You would choose E1.31 if you had controllers from SanDevices (E6804, E682, .etc.), J1SYS devices (P12r, p12s,.etc.), Falcon Christmas (FPD, Falcon-16, Falcon-8), DLA Etherdongle.

Any DMX device can also be driver through E1.31, Ray Wu 27 channel controller.

## 3.4 Verify

# 4 TEST

## 4.3 How to Select/Unselect Channels

## 4.4 Testing Channels

### 4.4.5 regular lights

### 4.4.6 dumb rgb

### 4.4.7 smart rgb

## 4.5 Save Test Group

# 5 CONVERT

# 6 PREVIEW

# 7 NUTCRACKER

## 7.3 Effect Classes

### 7.3.5 None

### 7.3.6 Bars

You can create horizontal or vertical bars. The direction of travel can be specified. You can ask for a 3D effect from them.

First BAR effect.

Layering: Effect 1. Just show Effect 1

Sparkles: 200. Sparkles are turned off

Brightness: 100%. Brightness is shown as it was calculated by the effect

Contract: 0%. No enhancement to Contrast that was generated.

| Effect shown on 20x120 Megatree, 180 degrees | Effect Shown on 32x32 Vertical Matrix
Bar effect with direction set to “up”. Notice how the same effect looks like on different models. |  |

| Effect shown on 20x120 Megatree, 180 degrees | Effect Shown on 32x32 Vertical Matrix
Bar effect with 3D turned on. 3D causes a fading of the bar. We are using the direction called “compress”. |  |

###

### 7.3.7 Butterfly

| Effect shown on 20x120 Megatree, 180 degrees | Effect Shown on 32x32 Vertical Matrix
Butterfly effect with colors set to “rainbow”. With the “rainbow” color, checked colors are ignored. |  |

| Effect shown on 20x120 Megatree, 180 degrees | Effect Shown on 32x32 Vertical Matrix
Butterfly effect effect with colors set to “palette”. 3 colors have been checked, Red, Green, Blue. The checked colors are used to color the butterfly effect using the “palette” color process. |  |

###

### 7.3.8 Circles

The circle effects draw circles going in various directions. You control the number, the size, the speed of the circles. |  |

### 7.3.9 Color Wash

Color Wash allows setting the entire object to a single color. If you give 2 or more colors, the effect will morph between the colors. |  |

### 7.3.10 Curtain

Curtain is an effect that opens and closes the edges of your display. Using the Layering effect “! revels 2”, it can be used to open on your effect2. |  |

### 7.3.11 Fire

# 8 The Fire effect will create a fire that you can control its height

Here we lowered the height of the fire, changed the color of the fire to green, set the fire to grow automatically and set the speed slider to make the growth rapid. |  |

### 8.3.5 Fireworks

### 8.3.6 Garlands

### 8.3.7 Life

### 8.3.8 Meteors

### 8.3.9 Piano

### 8.3.10 Pictures

### 8.3.11 Snowflakes

### 8.3.12 Snowstorm

### 8.3.13 Spirals

### 8.3.14 Spirograph

### 8.3.15 Text

### 8.3.16 Tree

### 8.3.17 Twinkle

### 8.3.18 SingleStrand

### 8.3.19 Faces

### 8.3.20 Wave

# 9 SCHEDULE

Alphabetical Index

Author

Nutcracker

Sean Meighan 3

XLights

Matt Brown 3

Introduction 3

Page 17