DMX Configuration

The basis of hardware configuration is hardware.ini file. It is used to configure lights, sounds, smoke and such systems to be triggered by events in the game or changes of the game state. For example illuminate the room of blue color when shields are up or blink lights when your ship takes hull damage.

This article shows the basics of configuration but doesn't cover DMX device setup.

Table of Contents

• hardware.ini
• Sections
  • [hardware]
  • [channels]
  • [state]
  • [event]
  • condition/trigger values (DMX cues)
• hardware.ini example

hardware.ini

The file is not created by game so it needs to be created manually. The table below shows where hardware.ini must be created.

Operation system	Location of hardware.ini
Linux, Mac OS X	~/.emptyepsilon/hardware.ini
Windows	hardware.ini is in the same directory where EmptyEpsilon.exe is.

Sections

hardware.ini consists of sections. Each section starts with [...] and ends with an empty line. Comment lines start with #.

[hardware]

You can have multiple hardware definitions and thus more than just one hardware device connected. Below are all supported device types:

• DMX512SerialDevice
• EnttecDMXProDevice
• sACNDevice
• VirtualOutputDevice

VirtualOutputDevice is for debugging as it draws device blocks on top of the game.

Port is the serial port where your dmx device is connected. For using VirtualOutputDevice port name doesn't need to be valid. The serial port can be defined with a "pseudo" name. For example in windows you can say port = \Device\USBSER@@@ to connect to any Arduino connected to the system, no matter the port number. You can also have multiple hardware definitions.

You can also define how many channels are available for device via channel -parameter. This defaults to 512 if not defined.

[hardware]
device = DMX512SerialDevice
port = COM1

[hardware]
device = DMX512SerialDevice
port = COM2
channels = 32

[channels]

To use a channel a name must be assigned to it. In this case we're configuring three lamps. 4channelSpot represents generic RGB device that needs four channels, one for intensity and three for each color channel. MainCabinLights and WarningLights need one channel.

If a device needs multiple channels supply a comma separated list instead of a single value. See the example below.

There are 512 channels available to use.

[channels]
MainCabinLights  = 1
WarningLights    = 2

# This device has four channels (intensity, red, blue, green)
4channelSpot = 10, 11, 12, 13

[state & event]

States and events blocks defines what our previously defined DMX devices should do when different actions are taken in game.

value

DMX protocol defines that channel can have values ranging from 0 to 255. We can configure this value in three ways.

1. Float (default)

• value can be any float point number between 0 and 1.
• Values above 1 are treated as 1.
• Easy to set something forexample in half power value = 0.5

2. Hexadecimal number

• Two digit hexadecimal number. For example: $AF, $3F , $2B.
• Hexadecimals need to be prefixed with $ as # is already reserved for comments in configuration file.
• Very usable for configuring colors as they are many times displayed as 6 digit hex numbers. For example #F5F686 id hex value for yellow color and we can split this value to three groups of two digit hex values and map these to our DMX devices RGB channels. Like $F5, $F6, $86

3. as decimal numbers

• Values between 0 and 255 are accepted.
• Decimal numbers needs to be wrapped in square brakets [100].
• Nice and clean way to trigger that specific channel on your DMX devices.

[state]

To simply turn lights on give a value to some channel. The value is float.

[state]
condition = Always       # The simplest condition
target = MainCabinLight  # Channel
value = 1                # value as float between 0..1

To change 4channelSpot output simply define comma separated list of values. The following example makes the device output purple color at 50% intensity.

[state]
condition = Always
target = 4channelSpot
value = 0.5, $ff, $00, $ff  # intensity as float and (red, green, blue) as hex values

condition can of course be more complex. This section set's cabin light to 50% when the game is not yet started.

[state]
condition = HasShip == 0
target = MainCabinLight
value = 0.5

It's possible to light up warning lights when the ship has taken quite a lot of damage.

[state]
condition = Hull < 50
target = WarningLight
value = 0.5

State can also have effects. three different effects are supported, Glow, Blink, and Variable.

Glow value goes from min_value to max_value in time, then back down.

[state]
condition = ShieldsUp
target = WarningLights
effect = Glow               # Effect name
min_value = 0.3
max_value = 1
time = 1.0                  # Seconds

Blink value turns on (255) for on_time, then off for off_time

[state]
condition = Hull < 50
target = WarningLights
effect = Blink          # Effect name
on_time = 0.1           # Seconds
off_time = 0.1          # Seconds

Variable value follows a condition value, mapping values between min_input and max_input to min_output and max_output

[state]
condition = HasShip
target = ShieldsLevel
effect = variable
input = Shield0, Shield1
min_input = 0
max_input = 100
min_output = 0.0
max_output = 1.0

[event]

Events are one time only type of things. For example when the ship takes a hit lights blink.

trigger is a parameter to look for. When it changes the event fires. Before trigger it's possible to have operator < or >. Couple of examples:

[event]
trigger = HasShip
target = WarningLights
runtime = 1.0             # Seconds
value = 1.0

[event]
trigger = Energy          # Energy level changes
target = MainCabinLights
runtime = 1.0
value = 1.0

[event]
trigger = <Hull           # Hull takes damage
target = WarningLights
runtime = 1.0
value = 1.0

[event]
trigger = <FrontShield   # Front shield absorbs damage
target = WarningLights
runtime = 0.25
value = 1.0

condition/trigger values (DMX cues)

Conditions for states, or triggers for events can be based of the following properties. All these properties are based on the current ship that you are flying.

Property	Description	Value
Always	Always active	1.0
HasShip	1 when you have a ship or it's selected. Otherwise 0.	0 / 1
Hull	0 to 100 hull percentage.	0..100
FrontShield	0 to 100 shield percentage.	0..100
RearShield	0 to 100 shield percentage.	0..100
Shield0	0 to 100 shield percentage. Same as Front shield.	0..100
Shield1	0 to 100 shield percentage. Same as Rear shield.	0..100
Shield[2-7]	0 to 100 shield percentage. Additional shields, not yet supported.	0..100
Energy	Amount of energy your ship has. Up to 1000 for most player ships.	float
ShieldsUp	1 when your shields are up, 0 when they are down.	0 / 1
Impulse	Amount of impulse output in -1 (full reverse) to 1 (full forward)	-1..1
Warp	Amount of warp, from 0 to 4	0..4
Docking	While docking, or docked, this is 1. Else it is 0.	0 / 1
Docked	If we are actually docked, this is 1. Else it is 0.	0 / 1
InNebula	If we are in a nebula, this is 1, else it is 0.	0 / 1
IsJammed	If we are being jammed, this is 1. Else it is 0.	0 / 1
Jumping	If we are counting down to jump, this is 1. Else it is 0.	0 / 1
Jumped	After jump this is 1 for 1 second.	0 / 1
Alert	True if no alert.	0 / 1
YellowAlert	True if alert level is yellow.	0 / 1
RedAlert	True if alert level is red.	0 / 1
TubeLoaded[0-16]	If we have a weapon loaded in this tube it is 1. Else it is 0.	0 / 1
TubeLoading[0-16]	When loading this tube, this property is 1. Else it is 0.	0 / 1
TubeUnloading[0-16]	When unloading this tube, this property is 1. Else it is 0.	0 / 1
TubeUnloading[0-16]	When unloading this tube, this property is 1. Else it is 0.	0 / 1
TubeFiring[0-16]	When firing a tube, this property is 1. Else it is 0.	0 / 1

(If you need more options. Feel free to file an issue)