311 lines
15 KiB
HTML
311 lines
15 KiB
HTML
|
<!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>
|