A node.js controller and animater for dmx lightning and devices
npm install dmx-animate
npm i dmx-animate --save
`
Get started
Create a new javascript file in your folder and require dmx-animate:
`js
const dmxAnimate = require('dmx-animate')
var dmx = new dmxAnimate({
universes: [
{name: 'demo', driver: null, serialPath: 'COM7'}
]
})
`
Then initialize an universe like that.
* name - String : The name of the universe
* device- String, referring a registered driver
* device_id - Number or Object(windows: COM[number], linux: '/dev/cu.usbserial-6AVNHXS8')
These drivers are registered by default currently:
- null: a development driver that prints the universe to stdout
- artnet: driver for EnttecODE
- bbdmx: driver for BeagleBone-DMX
- dmx4all: driver for DMX4ALL devices like the "NanoDMX USB Interface"
- enttec-usb-dmx-pro: a driver for devices using a Enttec USB DMX Pro chip like the "DMXKing ultraDMX Micro".
- enttec-open-usb-dmx: driver for "Enttec Open DMX USB". This device is NOT recommended, there are known hardware limitations and this driver is not very stable. (If possible better obtain a device with the "pro" chip)
- dmxking-utra-dmx-pro: driver for the DMXKing Ultra DMX pro interface. This driver support multiple universe specify the options with Port = A or B
Once you have created the instance of dmx-animate and choosen the driver, you can start adding devices:
Devices
The dmx universe is made of devices. Register a new device by...
* calling a new instance of new dmx.Device(options)
* adding it using the function dmx.addDevice(options,(universe))
* adding multiple using dmx.addDevices([options1,options2,...],(universe))
(optionally add the universe to dmx.addDevice)
options is a object with some necessary keys: [optional]
| options | explanation |
|--|--|
| name | String - the unique name for the device |
|startChannel| number - the channel number on witch the device is registered |
|channels|Array - a list of labeled channels the device uses|
|[type]|String - use a preset|
|[programs]|Object - adds javascript functions to the device instance|
|[universe]|insert the universe index, name or instance; default to 0|
$3
`js
var rgbDevice = dmx.addDevice({
name: 'basic-rgb',
startChannel: 4,
channels: ['r','g','b']
})
`
There are a few functions and properties on this new object. Take a look at Functionality
$3
I made some preset devices already for you to use.
You can inherit a preset by using the type property. The presets can be found at devices.js
Important: The channels property is no longer required, but the name and startChannel obviously are. You can still overwrite channels, programs etc.
Example:
`js
var rgbDevice = dmx.addDevice({
type: 'basic-rgb',
name: 'basic-rgb',
startChannel: 4
})
`
| device name | description |
|--|--|
| rbg-led-par56 | A 5 channel rgb par |
|basic-rgb|basic 3 channel rgb device |
|basic-dimmer|basic 1 channel device|
|4ch-dimmer|dimmer with 4 channels, used for dimmer packs|
|mania-scx500|a scanner with some color functionality|
Feel free to commit to this device list via pull Request.
And you can add presets yourself at the top of the code to use it elsewhere:
`js
dmx.deviceTemplates[name] = {
channels: ['r','g','b'],
programs: {
}
...
}
`
$3
Programs are ways to add shortcuts for certain actions to a device.
They are defined as a function in the programs object like this:
`js
var dimmer = dmx.addDevice({
channels: ['value'],
programs: {
dimIn: function(time = 2000){
return this.dim(0,255,time).run()
}
}
})
`
You can then run this program by:
`js
dimmer.dimIn(1000)
`
In the function you have access to the device and its native functions by using this and you can insert arguments like time.
Important : For the http api it is important to return the current state (consider return this.getState() too)
Groups
Groups are a way to group multiple devices together and control them all at once.
Initialize an instance with new dmx.Group(devices, options)
or dmx.addDevice(new dmx.Group(devices, options)) to use it with the http api.
The group must have its own name property and can have seperate programs
Example:
`js
var group = dmx.addDevice( new Group([rgbDevice, dimmer], {
name: 'device-group',
programs: {
allOneOn: function(){
this.devices[0].setChannels([255,255,255])
}
}
}) )
`
In the programs you can access the whole group with this again and then an array of devices with this.devices.
The groups have the same methods as the devices, but just apply it to every device.
Methods and Functionality
Enough of setting up! Here we'll talk about controlling your set up devices and universes actually.
dmx.getUniverse(name)
Returns the node-dmx universe object
dmx.getUniverse(name).update(object)
Update single channels of a universe
* object - Object containing the channels as keys and values
dmx.nodeDmx
Get the original node-dmx instance and perform actions: node-dmx
Device.setChannels(channels)
Updates the channels of a device.
channels can be:
* an Array of values in Order of the device channels
* a Object with channel-value pairs
Device.set(channel, value)
Sets a channel or more to a value or more. Part of animation.
channel can be:
* String - the channel name
* Number - the channels index in Device.channels
* Array - an Array of values in Order of the device channels (value argument does not matter)
* Object - with channel-value pairs(value argument does not matter)
Device.dim(channel, value,duration,[easing])
Animates a channel/channels from the previous value to another in a given duration. Part of animation.
* channel - look at Device.set
* durationNumber - the time it takes to animate in ms
* easingone of the following easing methods (optional)
All easing methods:
- inear (default)
- inQuad
- outQuad
- inOutQuad
- inCubic
- outCubic
- inOutCubic
- inQuart
- outQuart
- inOutQuart
- inQuint
- outQuint
- inOutQuint
- inSine
- outSine
- inOutSine
- inExpo
- outExpo
- inOutExpo
- inCirc
- outCirc
- inOutCirc
- inElastic
- outElastic
- inOutElastic
- inBack
- outBack
- inOutBack
- inBounce
- outBounce
- inOutBounce
Device.delay(duration)
Delays the next step of the animation by the given duration in ms. Part of animation.
Device.execute(callback)
Executes a javascript function callback when reached in animation. Part of animation.
This can be used to animate multiple devices at one, log the progress or whatever.
Example: see below
"Part of animation"
Everything labeled "Part of animation" is not ran on run call, but can be chained e.g:
`js
dimmer
.set(0,255)
.dim(0, 130, 2000)
.execute(() => {
console.log('dim finished')
})
.delay(1000)
.dim(0, 0,5000)
`
And to execute the whole chain of actions step by step, you need to run
Device.run(callback)
Part of animation. This starts the previous defined animation chain and calls the callback on Finish:
`js
dimmer.run(function() {
console.log("Finished")
})
`
Device.stopAnimation()
Stops the current animation.
Device.blackout()
Sets all channels to 0.
Device.getChannelState()
Returns the current values for the given channels as Object.
Device.getPrograms()
Returns all defined programs for the device.
Sequences
You can define a sequence of different actions, animations and programs with
dmx.addSequence(name,function,[config])
name String - The name of the sequence
function Javascript Function - This runs on sequence call
config Object - (optional) configuration e.g {duration: 2000}`