Kissbox

KissBox DMX-512 is an Ethernet DMX adapter that allows HSYCO to control any DMX-512 standard bus.

Multiple transceivers can be set up to work together and distribute several universes of DMX across the network. The DMX-512 Transceiver has to be set to use the TCP/IP protocol.

Each KISSBOX I/O Server controls one DMX universe. Add one I/O Server for each transceiver.

Check the KissBox site for additional information.

note

Up to HSYCO 4.1, DMX gateways were configured in a dedicated DMX section and controlled through the DMX EVENTS keyword and the dmxSet() family of methods. From 4.2.0 they are standard I/O Servers with standard datapoints, and the previous configuration, keywords and APIs have been removed. See Migrating from the DMX gateways below.

Connections

The KissBox DMX-512 connects to an Ethernet port on HSYCO Server, and is powered through the Ethernet, so there is no need for an external power supply.

The device uses two consecutive ports: a TCP port for control and status, and the next port number for the UDP channel output. Only the TCP port is configured in HSYCO; the UDP port is derived from it.

You can connect multiple KissBox DMX-512 devices or other DMX controllers to an HSYCO Server.

HSYCO Configuration

Add a KISSBOX I/O Server in the I/O Servers section of the Settings and set its parameters.

Communication

• IP Address: host name or IP address of the KissBox DMX-512
• IP Port: TCP/IP port of the KissBox DMX-512. The KissBox has no factory default port, so this parameter is required; the driver will not start without it. The UDP output port is always the TCP port plus one

High Availability

• Shutdown when inactive: defaults to true.

Options

ID	Default	Values	Description
channels	512	1 ... 512	number of channels of this universe. Reducing it shortens every frame, which can be useful on a lightly populated bus
refreshmillis	1000	100 ... 10000	milliseconds between two consecutive refresh frames when nothing is changing. A change is always sent immediately, so this only sets how often the bus is refreshed while idle
discovery	true	true	datapoints are automatically added to the list of detected devices in the catalog.json file as DIMMER devices, so that they can be picked in the Project Editor and drive sliders, knobs and colorpickers
		false	datapoints are published but not added to the catalog

Datapoints

DMX channels only become datapoints when you use them: a datapoint is created the first time it is written, or the first time it is refreshed. Datapoints are not persisted, so after a restart a channel is unknown again until it is written or refreshed.

ID	Value	R/W	Description
connection	online	R	the gateway is answering
	offline	R	the gateway is not reachable. Channel levels and datapoints are kept, and the driver reconnects on its own
<channel>	0 ... 255	RW	one DMX channel, from 1 to the configured number of channels
rgb.<channel>	<r>,<g>,<b>	RW	three consecutive channels, starting at <channel>
range.<low>.<high>	see below	RW	every channel from <low> to <high>, inclusive

Writing values

Every channel, rgb and range datapoint accepts the same set of values. N is the number of channels the datapoint spans: 1 for a channel, 3 for an rgb, and high - low + 1 for a range.

Value	Description
0 ... 255	a channel level. When the datapoint spans more than one channel, the same level is set on all of them
<n>/<m>	a fraction of full output, for example 128/255 or 3/4
<n>%	a percentage of full output, for example 50%
a list of N values	one level per channel, in order. Any of the formats above can be used for each element
on	restores the level each channel had before it was last taken to zero
off	sets every channel to zero, remembering the level it had
flip	toggles: see on, off and flip below
refresh	re-reads the gateway and publishes every datapoint of this I/O Server again

Values in a list can be separated by a comma, a semicolon, a space or an asterisk, so 255,128,0, 255;128;0, 255 128 0 and 255*128*0 are all the same command. A value that cannot be parsed, or a list whose length is neither 1 nor N, is rejected with an error in the log and changes nothing; it does not create the datapoint either.

IO dmx1.10 = 200
IO dmx1.10 = 78%
IO dmx1.rgb.20 = 255,128,0
IO dmx1.range.1.24 = off
IO dmx1.range.1.24 = FLIP

Reading values

A channel datapoint reads back as its level, from 0 to 255.

An rgb datapoint reads back as <r>,<g>,<b>.

A range datapoint reads back as a single level when every channel in it holds the same value, and as a comma-separated list of N levels when they differ.

note

In the catalog, and therefore in the User Interface, values are published in the <level>/255 fractional format, or as off at zero, so that sliders and knobs show the correct position without any conversion. An rgb datapoint is published as <r>*<g>*<b>, which is the format the colorpicker object reads. A range holding different levels has no single level the GUI could show, so it is published as unknown.

On, off and flip

Each channel remembers the last level it held before going to zero. on restores that level, and off saves it. A channel that has never been dimmed remembers 255, so on on a fresh channel gives full output. The level is remembered whatever took the channel to zero, so dmx1.10 = 0 followed by dmx1.10 = on also restores it.

flip on a datapoint spanning more than one channel follows a three-state rule:

• if any channel is on, every channel is set to zero
• otherwise, if any channel has a remembered level, every channel is restored to its own remembered level
• otherwise every channel is set to 255

Overlapping datapoints

Channels, not datapoints, hold the state, so several datapoints can address the same channel and they always agree. When a write changes a channel, every datapoint that covers that channel is published again.

For example, with dmx1.range.1.10, dmx1.rgb.4 and dmx1.5 all in use, writing dmx1.5 = 200 also updates the range and the rgb datapoint, and each of them fires its own IO event.

Refresh

refresh re-reads the gateway's DMX OUT registers and then publishes every datapoint of this I/O Server again, whether it changed or not.

The driver reads the whole universe every time it starts, so at start-up the levels HSYCO reports are the levels the bus is actually holding, even if they were set before HSYCO was running.

note

Once started, HSYCO is the master of the bus and retransmits the whole universe, so a level set on the bus by anything else is overwritten by the next frame. What a refresh reads back after start-up is therefore what HSYCO itself last sent. Its lasting use is to force every datapoint to be published again.

User Interface

Use the standard datapoint-driven objects:

• slider and knob: set action to datapoint, the datapoint to a channel or range datapoint, and the range to 0,255
• colorpicker: set action to datapoint and the datapoint to an rgb.<channel> datapoint
• button: set action to datapoint and use the on, off and flip values

<colorpicker action="datapoint" datapoint="dmx1.rgb.10" hsv="true" onoffbutton="true" />

Migrating from the DMX gateways

The dmxServers, dmxServersIP, dmxServersPort, dmxServersComm and dmxServersId parameters are no longer read. Replace each gateway with a KISSBOX I/O Server, then re-point projects, EVENTS and user code at the new datapoints.

Removed	Replacement
DMX 10 = 200	IO dmx1.10 = 200
DMX 10 = ON / OFF / FLIP	IO dmx1.10 = on / off / flip
DMX 100-120 = ON	IO dmx1.range.100.120 = on
DMX 1010 = 200 (second gateway)	IO dmx2.10 = 200, with an I/O Server per universe
DMX 10 as a trigger	IO dmx1.10 as a trigger
DMXSTART	IOSTART dmx1, or the dmx1.connection datapoint
dmxSet(10, 200)	ioSet("dmx1.10", "200")
dmxOn(10) / dmxOff(10)	ioSet("dmx1.10", "on") / ioSet("dmx1.10", "off")
dmxGet(10)	ioGet("dmx1.10")
DmxEvent(channel, state)	IOEvent(name, value)
DmxStartupEvent(index)	IOStartupEvent(index)
<colorpicker action="dmx" dmxaddress="10">	<colorpicker action="datapoint" datapoint="dmx1.rgb.10">

The channel address no longer carries the gateway number: each universe is a separate I/O Server with its own ID, and channels are always 1 to 512.

DMX channel merging and the DmxFilter callback have been removed and have no replacement.

warning

An I/O Server whose ID starts with dmx is matched by an existing deny; *; *; *; dmx* rule in acl.ini, which used to apply to the retired DMX web commands. Check the Access Control List after adding the I/O Servers, and remove or narrow that rule.

Release Notes

4.2.0

• KissBox gateways are now standard I/O Servers, with datapoints for single channels, rgb triplets and channel ranges
• merge mode and channel value filtering removed

3.1.0

• initial release

---

KissBox DMX-512 is a registered trademark of Kissbox.