<!DOCTYPE html>
<html>
<head>
<title>Ether Dream - User Guide</title>
<link rel="stylesheet" type="text/css" href="main.css" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
</head>
<body>
<img src="etherdream.png" width="298" height="75" alt="ether dream">
<div id="header"><a href="protocol.html">Ether Dream</a></div>
<div id="content">
<h1>Ether Dream - User Guide</h1>
<h2 style="color:red"><em>NOTE</em> - This page is for the original Ether Dream 1. Check the <a href="/">current website</a>.</h2>
<h2>Contents</h2>
<ul>
<li><a href="#intro">Introduction</a></li>
<li><a href="#quick">Quick Start</a></li>
<li><a href="#hw">Hardware</a></li>
<li><a href="#setup">Setup</a></li>
<li><a href="#live">Live Playback</a></li>
<li><a href="#dmx">DMX</a></li>
<li><a href="#parameters">Parameters</a></li>
<li><a href="#dev">Development</a></li>
</ul>
<h2 id="intro">Introduction</h2>
<p>
Congratulations! Ether Dream is the most flexible, powerful, and open DAC available
today. It is designed to enable easy live playback from PC software and to serve
as a platform for experimentation and development.
</p>
<h2 id="quick">Quick Start</h2>
<p>
To get started with your Ether Dream, just connect its output to your
projector, its Ethernet connection to your network or computer, and then
the power supply to a source of 9-25v DC or to the included adapter.
The green LED next to the USB connector will light to
indicate that power is on, and the yellow LED next to the ILDA connector
will light to indicate that the interlock is now closed.
</p>
<p>
If you're connecting to a home network with a router or DHCP server, no
other configuration will be needed - any computer on the network will
be able to reach the Ether Dream. If you connect the Ether Dream directly
to your computer, make sure that it is set to obtain its IP address
automatically.
</p>
<p>
To make sure that your computer can communicate properly with your Ether
Dream, a <a href="downloads.html">diagnostic tool</a> is available on the
Downloads page.
</p>
<p>Note: you may need to disable or adjust the settings on your firewall
software to be able to communicate with the Ether Dream. The driver DLL
uses TCP port 7765 and UDP port 7654.
</p>
<p>
LSX, ILD SÔS, and other software using the
<a href="http://www.photonlexicon.com/forums/showthread.php/15653-Happy-programmer-s-day!-Does-your-DAC-have-an-SDK-DAC-interface-library-released.">universal DAC interface library</a> written by drlava have native
Ether Dream support. However, a software update may be needed - support was only added to the library
in late October 2011. Contact drlava for an updated build of LSX or ILD SÔS. Other software that works with ezauddac.dll can be set up to use an Ether Dream by making a backup of
its ezauddac.dll and renaming EtherDream.dll (from <a href="/downloads.html">the Downloads page</a>) to ezauddac.dll.
</p>
<p>Once the driver DLL is installed, just start up the software and the Ether Dream will
automatically be detected.
</p>
<h2 id="hw">Hardware</h2>
<img src="etherdreamboard.png" alt="Ether Dream board diagram" width="700" height="357">
<p>
Starting at the Ethernet connector on the board and moving counterclockwise, the
indicators and connectors on the board are:
</p>
<ul>
<li>Ethernet connector - includes link and activity LEDs.</li>
<li>USB connector. This is currently used only for firmware upgrades.</li>
<li>Status LED. This LED blinks when the board is in bootloader mode, and
is on normally.</li>
<li>MicroSD slot. This is used for configuration and for playback of stored
content.</li>
<li>External power jack. This is a 2.1mm/5.5mm barrel connector, center-positive,
accepting 8V-25V DC at 300mA.</li>
<li>Power supply screw terminals. Ground is on the left (towards the outside of
the board), positive is on the right (towards the inside of the board).
The two power inputs are isolated from one another with diodes; if both
are connected, power will be drawn only from the one with the higher voltage.</li>
<li>GPIO header. This connects extra pins from the microcontroller.</li>
<li>Serial header for future expansion (#2).</li>
<li>Interlock LED (yellow). This LED is on whenever the interlock relay is closed.</li>
<li>ILDA DB-25 connector.</li>
<li>Behind the DB-25 connector: 2x13 pin header wired identically to the DB-25. This
can be used when the Ether Dream is built into a projector.</li>
<li>Emission LED (green). Whenever the DAC is producing output, this LED is on.</li>
<li>2x10-pin programming/debug header (JTAG).</li>
<li>1x6 pin programming/debug header (serial).</li>
<li>Serial header for future expansion (#1).</li>
<li>Serial header for future expansion (#3).</li>
</ul>
<h2 id="live">Live Playback</h2>
<p>
Ether Dream supports a standard frame-based API and should work "out of the box" with existing
playback software, once drivers are installed.
</p>
<p>
In the event of a momentary glitch in its data stream, the Ether Dream driver will automatically
restart playback. If an Ether Dream unit detects that its network link is physically
disconnected, it will go into an 'emergency-stop' mode and stop output until the network is
restored.
</p>
<h2 id="dmx">DMX</h2>
<p>
With an extra adapter board, the expansion connectors on the Ether Dream can transmit and receive
DMX signals to interface with lighting equipment. The Ether Dream can simultaneously drive three
DMX universes, relaying commands from Ethernet to DMX, and also receive on one universe, sending
information from DMX to Ethernet.
</p>
<p>
Each of the serial expansion headers on the diagram above can connect to a DMX adapter board. The
firmware supports both transmitting and receiving DMX from connector #1, and transmitting only
from conectors #2 and #3.
</p>
<p>
DMX output is enabled and controlled with OSC messages. When the Ether Dream receives a message
for a given DMX universe, it will enable output for that universe and start continuously sending
DMX data to an attached interface board. The DMX output can be controlled in any of several ways:
</p>
<ul>
<li><code>/dmx</code><i>n</i><code>/</code><i>channel</i><code> </code><i>value...</i>
<p>
Update one or more channels. For example, to set DMX channel 42 on universe 1 to 200, send an
OSC message to <code>/dmx1/42</code> containing the number 200. If multiple values are sent, they
will be assigned to sequential DMX channels: for instance, sending 200, 250 to <code>/dmx1/10</code>
will set channel 10 to 200 and channel 11 to 250. One OSC message can change up to 50 channels. The
rest of the channels in the universe will not be changed.
</p></li>
<li><code>/dmx</code><i>n</i> <i>channel</i><code> </code><i>value...</i>
<p>
Alternately, the first channel to update can be sent as a numerical parameter, instead of in the
target path of the OSC message. Send 7, 100, 100 to <code>/dmx2</code> to set channels 7 and 8
of universe 2 both to 100. As above, up to 50 channels can be specified, and only the specified
channels will be changed.
</p></li>
<li><code>/dmx</code><i>n</i><code> </code><i>blob</i>
<p>
To change all 512 channels in a universe with a single OSC command, the Ether Dream will accept an OSC
<i>blob</i> (data) parameter. The first byte (index 0) in the blob sets DMX channel 0, the next sets
channel 1, and so on. The blob must be the only parameter and must be exactly 512 bytes long.
</p></li>
</ul>
<p>
DMX input is enabled by sending a message with a string and a number to <code>/dmx1/input</code>. The
string specifies the IP address (must be a numeric IP address, not a hostname) to relay DMX updates to,
and the number is a port number. DMX updates will be sent as OSC messages to <code>/dmx1</code> containing
a single blob - the same format as described above for DMX output.
</p>
<p>
If the address given is "<code>me</code>" and the port is 0, then messages will be sent back to the same
host and port that the <code>/dmx1/input</code> command was received one. If the address is blank and
the port is 0, then DMX input will be disabled.
</p>
<p>
This code will set the first four channels of an Ether Dream's DMX universe 1 to 255:
<blockquote><pre>import liblo
liblo.send(liblo.Address("192.168.1.11", 60000), "/dmx1/1", 255, 255, 255, 255)</pre></blockquote>
</p>
<p>
To receive input over DMX, raw sockets can be used easily:
<blockquote><pre>sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
sock.sendto("/dmx1/input\x00,si\x00me\x00\x00\x00\x00\x00\x00", ("192.168.1.11", 60000))
while True:
data, addr = sock.recvfrom(1024)
print "DMX channels: %d %d %d %d" % map(ord, data[16:20]))</pre></blockquote>
</p>
<p>
Or liblo's server functionality can be used instead:
<blockquote><pre>import liblo
class DMXServer(liblo.Server):
@liblo.make_method('/dmx1', 'b')
def dmx1_callback(self, channel_blob):
chanenls = map(ord, channel_blob)
print "DMX channels: %d %d %d %d" % channels[:4]
server = DMXServer(32123)
liblo.send(liblo.Address("192.168.1.11", 60000), "/dmx1/input", "me", 32123)
while True:
server.recv(100)</pre></blockquote>
</p>
<h2 id="parameters">Parameters</h2>
<p>
The other capabilites of the Ether Dream are accessed via its <i>parameters</i>. Parameters can be
set and actions invoked in two ways:
<ol>
<li>The DAC listens for <a href="http://opensoundcontrol.org/">OSC</a> packets on a UDP port.</li>
<li>On startup, commands are loaded from the <code>autoplay.txt</code> on the SD card, if present.</li>
</ol>
</p>
<p><a href="http://opensoundcontrol.org/">OSC</a> is a simple UDP-based protocol for
sending control messages; it is usually used for audio, to control synthesizers, mixers,
etc., but is flexible enough to support laser applications as well. Bridges exist
between OSC and MIDI or DMX. An OSC message is sent to an <i>address</i>, like
<code>/channel/1/volume</code> or <code>/ilda/pps</code>, and contains some <i>data</i>:
zero or more numbers, strings, True/False values, etc.
</p>
<p>
The Ether Dream listens for OSC messages on UDP port 60000. When it sends a response to
a message, it will send that response to port 60001 on the originating host. There
are many OSC-handling programs and OSC plugins, as well as libraries for most programming
languages, available on the Internet.
</p>
<p>
Most of the OSC parameter endpoints implemented on the Ether Dream take some
sort of data. Those labeled as "integer" or "float" expect a value in the given range.
OSC endpoints specified as "message" can be sent a message with either no data or with an
integer value, but will ignore the message if the value is zero. This allows them to
be controlled by a pushbutton on a control surface that sends OSC messages - a pushbutton
will send a nonzero value when it is pressed, and then send 0 when it is released.
</p>
<ul>
<li><code>/ilda/play</code> <i>filename</i> - string
<p>Writing a string to this address causes the DAC to switch to file playback mode and
begin playing <i>filename</i> from the SD card.</p>
<p><b>NOTE:</b> Playing a file by name can currently only be done via autoplay.txt, not
via OSC.</p>
</li>
<li><code>/ilda/</code><i>n</i><code>/play</code> - message
<p>As <code>/ilda/play</code> <i>filename</i>, but plays the <i>n</i>th file found on the SD card.
Works over OSC.</p>
</li>
<li><code>/ilda/fps</code> <i>fps</i> - integer
<p>Switch to file playback mode and set the frame rate limit to <i>fps</i>.
</li>
<li><code>/ilda/pps</code> <i>pps</i> - integer
<p>Switch to file playback mode and set the point rate to <i>pps</i>.
</li>
<li><code>/ilda/repeat</code> <i>value</i> - integer
<p>Switch to file playback mode. If <i>value</i> is nonzero, then files played will be repeated
until a stop command is received; if zero, playback stops at the end of a file.</p>
</li>
<li><code>/stop</code> - message
<p>Stop playing the current file.</p>
</li>
<li><code>/geom/tl</code>, <code>/geom/tr</code>, <code>/geom/bl</code>, <code>/geom/br</code> <i>x</i> <i>y</i> - float, range [-1, 1]
<p>Set the position of a corner of the image within the overall projection field. Values range from -1 to 1. This
can apply any arbitrary perspective transform to the input image.</p>
<p>The output bottom left is (-1, -1); the output top right is (1, 1). For example, to leave the image
unchanged, set the values as:
<ul><li><code>/geom/tl</code> -1 1</li>
<li><code>/geom/tr</code> 1 1</li>
<li><code>/geom/bl</code> -1 -1</li>
<li><code>/geom/br</code> 1 -1</li></ul></p>
</li>
<li><code>/geom/size</code> <i>size</i>, <code>/geom/offset</code> <i>offset-x</i> <i>offset-y</i>
<p>These parameters provide a shortcut to setting per-corner positions when only size
and position adjustments are needed. To set the image at 50% size and in the top right
corner of the projection field, set:
<ul><li><code>/geom/size</code> 0.5</li>
<li><code>/geom/offset</code> 0.5 0.5</li></ul></p>
</li>
<li><code>/geom/rdelay</code>, <code>/geom/gdelay</code>, <code>/geom/bdelay</code> <i>points</i> - integer, 0 to 15
<p>Set the delay on the red, green, or blue color channel to <i>points</i> points.
</li>
</ul>
<p>
As an example, the following <code>autoplay.txt</code> file might be used to play a prerecorded show
automatically when the DAC is powered up:
<blockquote><pre>/ilda/pps 30000
/ilda/fps 30
/geom/size 0.3
/geom/offset 0.4 -0.2
/ilda/play show.ild</pre></blockquote>
</p>
<p>
The following Python code, using <a href="http://das.nasophon.de/pyliblo/">liblo</a>, will play the first ILDA
file on the SD card:
<blockquote><pre>import liblo
dac = liblo.Address("192.168.1.107", 60000)
liblo.send(dac, "/ilda/1/play")</blockquote>
</p>
<p>Control layout files for TouchOSC, a third-party iPhone/iPad app, are available
in the Ether Dream source repository under the <a href="https://github.com/j4cbo/j4cDAC/tree/master/tools">tools/</a> directory - <code>j4cDAC.touchosc</code> is for iPad, and
<code>j4cDAC-phone.touchosc</code> is for iPhone.</p>
<h2 id="dev">Development</h2>
The Ether Dream firmware, available <a href="https://github.com/j4cbo/j4cDAC">on github</a>,
builds on a standard Linux system with the free CodeSourcery ARM toolchain. The README in the
repository describes the needed tools.
</div>
<div id="footer">
© 2010-2021 Jacob Potter.
</div>
<div id="menu">
<ul>
<li><a href="../index.html">LJ doc</a></li>
<li><a href="protocol.html">Protocol</a></li>
<li><a href="userguide.html">V1 User Guide</a></li>
<li><a href="manual.html">V1 Developer Manual</a></li>
<li><a href="dmx.html">V1 DMX Board</a></li>
</ul>
</div>
</body>
</html>