From Nutcracker Wiki
Jump to: navigation, search




  • It is useful to have separate show directories for each major event i.e. one for Halloween, one for Christmas or one for the next year. Start a new year directory by copying sequences from the Show Directory of the previous year.
  • You can start with a default set of network configuration values and then come back to change or update the details before testing your lights physical output.


  • You can save the windows that you normally have open as your default perspective. These windows will then be opened when you load xLights.
  • Dropping an effect on a Model group will give different results to dropping the same model on all elements of the group (because in the former case the canvas is treated as a whole matrix and then the effect is applied to the models within it). Some effects work at the Group level better than others.
  • When on the sequencer tab, If you right click on a Model group, the window will display a ‘Toggle Models’ option which will display all the models under the Model group (or hide them if you select the option again). You can also double click on the Model Group to obtain the same results.
  • Double Clicking on the any of the color icons opens up a Palette window, where the standard colors can then be replaced with a new standard color or a custom color can be selected.
  • Effects can be stretched by using the Alt key and dragging one edge of the effect highlighted (most commonly the bottom right corner) to provide a Chase effect.You may need to use Toggle Nodes to view the nodes so as to be able to strect an effect.
  • Many, but not all effect actions can be ‘Undone’ by Right Clicking on the Grid and selecting the Undo action i.e. Undo effect move or Undo delete.. etc
  • Tip for using color palettes. Just click on an existing effect that has the palette you want and that will lock in the palette so that the next effect you drag and drop will inherit that palette.
  • In order to control the sequence in which multiple layers are rendered, you can change the order of data layers by moving them up or down. You can similarly change the order of layers within a model. And you can also change the order of models in the master view.


  • A simple way to do a chase effect is to select a block of cells and hit 'd' for a fade down or 'u' for a fade up. If you then need to adjust it, drag the end line.
  • You can create Random Effects by selecting an area on the grid, Right click and selecting the option to Create Random effects. Effects will be randomly selected (along with different colors and options) and effects created in the area highlighted, each between consecutive timing marks.
  • All lights off for 1/2 to a full second during an appropriate time in a sequence is powerful. When all lights come back on- KaPow! Ka-pow! as in the interpretation of the effect and not your controllers.
  • Layers are your friend. Complimentary effects. I used 11 layers for this effect and followed up with bars for a complimentary transition. From here this could go to Fan/Spiral/Chase,Curtain. Example


  • Pressing F10 anytime, anywhere will backup your XML files for your and store them in a zip file with the date and time the backup was created. You can press F10 as many times as you like and should do this at least once per sequencing session.

LOR Imports

  • Please do not use !@#$%^&*()<>/\}{, characters in your model names. Dash works fine though. I'm helping a user move over 150 models from LOR to NC and was having issues. Getting rid of those characters solved the issue. I don't know which one of those was causing the issue but he had ,/&\ in some of the model names.

Custom Colors

From time to time you may need to tweak a color to get the lights to display a desired color. Here are some known good RGB values to start with.

  • Orange1 245,48,0
  • Dark Orange 255,25,0
  • Purple1 102,0,60
  • Purple2 75,0,130
  • Purple3 105,0,255

Coming over from LOR

  • Running LOR Controller in DMX Mode

LOR to DMX Channel conversion

The following table describes the conversion of a LOR Unit id to a DMX address. As an example, if you have a controller with a Unit id of 03, then when converted to run under DMX , the channel ranges will be 33 to 48.

LOR Unit ID DMX Address LOR Unit ID DMX Address
01 1 11 257
02 17 12 273
03 33 13 289
04 49 14 305
05 65 15 321
06 81 16 337
07 97 17 353
08 113 18 369
09 129 19 385
0A 145 1A 401
0B 161 1B 417
0C 177 1C 433
0D 193 1D 449
0E 209 1E 465
0F 225 1F 481
10 241 20 497

Running LOR in DMX mode

The following diagram shows an example of how LoR controllers can be connected in DMX mode. Refer to the table above of Unit ids to DMX channel conversions


RunningLOrinDMXMode 2.png

You must use the LOR hardware utility to set the DMX start address on a LOR controller if the controller doesn’t have on board channel selection. The next diagram shows an example of how LOR controller addresses are set in a DMX universe. The controllers do not need to be physically connected in order of the controllers start address. The controllers can be put in any order.

RunningLOrinDMXMode 3.png

Convert a LOR LMS file to play using non LOR hardware

This section is based on a video created by Steve Giron

The item to be converted is a purchased 12 leg CCR tree sequence. The input file should be in LMS format. Within xLights/Nutcracker, go to the Convert tab and from there Select Convert, navigate to where the LMS file is and select it. Select the ‘Show Verbose Channel Map’ attribute. ‘Click on Start Conversion. Error messages are expected for the first run in the status window on the right side. Scroll to top of error messages and look at messages that says “LOR Network”.

Convert 2.png

The messages tell us that two networks are required: One with zero channels – (this was a star where channels were deleted from) , one with 1800 channels. Go to the Setup tab and define these. Setup tab (Existing layout)

LOR CL2.png

Add two entries: Network type of LOR, any baud rate, however the last channel must map correctly. Then move them to the top using the green UP arrows.

Ensure that ‘Map Empty LMS Channels’ is not selected (else you may get errors as the CCR macros do not have effects in them). Reconvert and it should convert with no errors. Open the xseq file that was created and play it to view the effects on the layout window. You may need to click on the ‘Render All’ button. If you are not playing the sequence though LOR hardware, go back to the setup and delete the two LOR entries that you added for the conversion, leaving your previous configuration as it was. If you are using LOR hardware, then these entries will need to be correctly defined.

Converting a LOR sequence and importing into xLights/Nutcracker.

This section is based on a video created by Clyde Lindsey

First ensure that within LOR, all the channels for the controller have been defined and are in sequence . Tools, Channel configuration will display an image similar to the following.

LOR CL1.png

If there are any channels missing use the ‘Add Channels’ function to add the missing (unused) channel. 1. Note that in the image, the Unit id is 03 and the Channels (Circuit) values run from 1 to 16. However, referring to the LOR Unit Id to DMX channel m apping t able Unit id 03 corresponds to Channel number 33. If Units prior to Unit 3 have not been defined, then you need to define them so as to ‘utilise’ the missing channels. Use the ‘Insert Device’ function to ‘Insert Device Above’ the current device (Unit 03) as a LOR 16 channel device – Unit id 01. Repeat this step and add another device Unit id 02.

LOR CL3.png

Therefore Channels 132 (Unit 1 and 2) have been defined – even if not required in LOR, and channels 33 – 48 belonging to Unit 03 are the ones that we are interested in.

LOR CL4.png

On the xLights/Nutcracker setup screen , the corresponding channels must be defined. You can define it as a USB , with a network type of LOR , and set up the COM port (obtained from the LOR device manager) and you will need to try different baud rates.

LOR CL5.png

However, there is sometimes a lag associated with the sequence when you use this option. It is preferable to use a DMX (to E131) bridge if possible and then define the channels as E131.

LOR CL6.png

For the three devices were defined in LOR, only 48 channels need to be defined, but to preserve a buffer for future use, an extra 16 channels corresponding to an additional LOR device, (i.e. a total of 64 channels) will be defined in Universe 1 as E1.31.

  • Model definition

Next create a new Model definition that matches the LOR Channels of Unit 03. Let’s say that this was 16 single channels Trees. In that case create a model ‘Small Tree 1’ , with 1 channel. The start channel must be set to 33 (not 1) as this corresponds to the 1 st channel of Unit 3.

LOR CL7.png

Then you can copy the model, update the name (Small Tree 2) and change the starting channel to 34 and repeat this for all 16 channels, increasing the start channel by 1 each time until the last one is 48.

Tip: If within the LOR Unit 03 definition, there are unused channels, you do not have to create a model for that channel or channel range. For example, let’s say within Unit 03, channels 1014 are not used. In which case, you would create 9 Trees (1 9), and then another 2 trees (for 1516). This is different to the setup tab where you must cover the entire range of channels from 1 onwards. The next step is to use the Layout tab to align

  • Import sequence data

Create a new music sequence, add timing tracks and add the models you have defined to the sequencer tab. Using the Import, Import Effects menu, change the ‘Import file’ file to LOR Music Sequence LMS, navigate to where the LOR LMS file is and select the file to Import. On the Channel mapping screen, add all the xLights/Nutcracker models – these will appear on the left hand side. Do not select the Map by Strand/CCR option in this case.

Double Click in the Channel column – in line with the model name. You will be presented with a list of LOR models (as identified by the labels in LOR). Select the channel and repeat for all the models. Save the mapping first , so that you can reuse it later. Click Ok to start the process. After you which , click on the Render All icon and play the sequence.

Tip: If you were importing data from a Singing face where your model has multiple channels, then you need to double click in the Channel column, but against the node row instead.

Tip: The Convert tab has an option to ‘convert a LOR sequence file with a ‘Show verbose Channel map’ setting that will provide details of the LOR to xLights/Nutcracker channel mappings . You can simulate a conversion and review the mapping details first.

Instead of using the Import tab to import the data as an editable effect, you can also import the data as a Data Layer. The process is much more efficient, however you cannot directly edit the data after your have imported it. That option has also been described in this chapter.

Common Scenarios

Scenario 1

A user is still using LOR for 8 controllers this year. How should he set them up ? Should he run it in DMX if the controller support DMX? The general rule is that you can do 96 channels of LOR with xLights if the LOR controllers are in LOR mode. In this case, put the LOR controllers in DMX mode and then xLights can do it all. The user can can import all the LOR sequences, schedule them play them, edit them, etc.

Scenario 2

A user has an E682 and an E6804 running pixels and 2 CMB16 and 1 CMB24 controllers. How should they be configured and connected ? Is a cross over cable required? Plug in the USB, same com port that would be used, if running it from LOR. No crossover cable is required if running from a LOR network. On the setup screen, add LOR channels via USB device. Put in at least 48 channels. Set the com port as required. After the LOR USB row, add in universes of 510 for the E68x controllers.

Scenario 3

A user is using comm4 and the USB to ethernet dongle. How should they be configured? Network Type – LOR, Port – COM4, Baud rate – 57600, Num channels (160 as example). Note: Baud Rate of 250000 is for DMX only.

Scenario 4

A user is setup is a mixture of LOR and DMX Channels i.e. intermixed LOR DMXLORDMX. LOR Controller 1, LOR Controller 2, LOR Controller 3, DMX Universe 1 ch. 1126, LOR Controller 4, LOR Controller 5, DMX Universe 1 ch. 127183. How should this be configured?

Option 1

Use Universe 1 for all the LOR and DMX channels. Since the DMX is already set (channels 1183), add an LOR entry with Universe 1 starting at 184 until the last channel for controller #5 (16 x 5 = 90), for a total of 274 total channels. You can 'reserve' additional channels should you need them later upto 510/512.

Option 2

Keep it simple with DMX Universe 1, LOR Universe 2 and then start with Universe 3 with the RGB controllers.

Tip: A ll the channels in LOR must be mapped exactly including blank ones in between . Setup your AC LOR channels first in XL4 and then start with your first prop in the same order as your LOR sequences. Otherwise the convert process will indicate that channels are unmapped.

Tip: L MS to xLights/Nutcracker XML via Import Effects is done via model mapping so channel numbers don't matter. However , if using the LMS to xLights/Nutcracker via Data Layer import option, channel numbers need to match models between LMS and xLights/Nutcracker configurations.