This is the README file for the uDMX - USB-DMX Interface
version 1.2


uDMX is a tiny USB-DMX512 Interface to control light dimmmers, fog machines etc 
from your computer

It has the following features:
	- fits in your pocket
	- bus powered - no need for a wall-wart
	- can send DMX packets of arbitrary size from 1 to 512 channels. 
		Only got 12 dimmers ?  Don't waste time sending 500 additional zeros 
		200 times a second...
	- command line tool for Mac/Linux
	- external for Max/MSP (Macintosh only)
	- bootloader for future firmware upgrades over USB
	
uDMX is based on Objective Development's USB driver an uses bery few external components

Objective Development's USB driver is a firmware-only implementation of the
USB 1.1 standard (low speed device) on cheap single chip microcomputers of
Atmel's AVR series, such as the ATtiny2313 or even some of the small 8 pin
devices. It implements the standard to the point where useful applications
can be implemented. See the file "firmware/usbdrdv/usbdrv.h" for features
and limitations.



------------------------

WARNING

Building uDMX is AT YOUR OWN RISK. 
uDMX draws all its power from the host computer's USB bus and, as of now, the DMX and USB 
lines aren't galvanically isolated. It may destroy your computer. It may make you lose your job.
It may cause your wife divorce you. In no way we will be liable for any mischief uDMX puts on you.
Use at your own risk or don't use it at all! 
And read the license...


------------------------

BUILDING AND INSTALLING

Both, the firmware and Unix command line tool are built with "make". You may
need to customize both makefiles.

Firmware:
The firmware for uDMX requires avr-gcc and avr-libc (a C-library for
the AVR controller). Please read the instructions at
http://www.nongnu.org/avr-libc/user-manual/install_tools.html for how to
install the GNU toolchain (avr-gcc, assembler, linker etc.) and avr-libc.
If you are on Windows, download WinAVR (see http://winavr.sourceforge.net/).

Once you have the GNU toolchain for AVR microcontrollers installed, you can
run "make" in the subdirectory "firmware". You may have to edit the Makefile
to use your preferred downloader with "make flash". Our current version is
built for uisp with the STK500 connected through a USB to
serial adapter to a Mac running Mac OS X.

Command Line Tool on Unix/MacOSX:
The command line tool requires libusb. Please download libusb from
http://libusb.sourceforge.net/ and install it before you compile. Change to
directory "commandline", check the Makefile and edit the settings if required
and type "make". This will build the unix executable "uDMX" which can
be used to control the device.

- We didn't test uDMX to compile on Windows
- For information about the bootloader, see the Readme.txt in sources/bootloader



------------------------

WORKING WITH uDMX

Once you have compiled and flashed the firmware and compiled the command line
tool, you can move on to the fun part: Connect the device to a free USB port
of your computer or USB-hub. You should now be able to find the device in
any USB analyzer tool, e.g. SystemProfiler on Mac OS X.
Connect The device to a DMX light dimmer.

The next step is to try the command line tool, e.g.:

    ./uDMX 1 255 127 255

this sets dimmers starting at channel 1 to the corresponding levels.
(channels are numbered 0 to 511)

Please note, that the device sends only the minimum needed data over DMX:
if, for example, you'd do: .

	./uDMX 3 255, uDMX 
	
will send 0 0 0 255. this allows for 
very rapid udates when not all channels are needed.

when you set more channels, all subsequent changes will use that amount of channels
example: 
	
	./uDMX 4 255 -> the device will start sending 0 0 0 0 255

then you do 
	
	./uDMX 0 255 127 -> the device will send 255 127 0 0 255 over DMX

if you want to send standard DMX512 packets you'd want to begin with

	./uDMX 511 0

-> subsequently the device will always send 512 frames (channels)


For usage of the Max/MSP external please see the uDMX.help file.


------------------------

FILES IN THE DISTRIBUTION

Readme.txt ................... The file you are currently reading.
ReleaseNotes.txt ............. Version History
sources/firmware ............. Source code of the controller firmware.
sources/firmware/usbdrv ...... USB driver -- See Readme.txt in this directory for info
sources/commandline .......... Source code of the host software (needs libusb).
sources/MaxMSP_external ...... Source code for the Max/MSP external (Xcode, needs the Max/MSP sdk)
sources/bootloader/firmware .. optional bootloader firmware
sources/bootloader/software	.. Command line tool to upload any .hex file over USB

circuit ........... Circuit diagrams in PDF and EAGLE 4 format. A free version
                    of EAGLE is available for Linux, Mac OS X and Windows from
                    http://www.cadsoft.de/.
binaries/...........compiled Max/MSP external & help file, downloadable firmware .hex file, 
					commandline tool compiled for MacOS X
License.txt ....... Public license for all contents of this project.




------------------------

MORE INFORMATION

For more information about uDMX please visit 
	http://www.anyma.ch/research/udmx/ 
	or contact research@anyma.ch


For more information about Objective Development's firmware-only USB driver
for Atmel's AVR microcontrollers please visit the URL

    http://www.obdev.at/products/avrusb/

A technical documentation of the driver's interface can be found in the file
"firmware/usbdrv/usbdrv.h".


uDMX is (c) 2006 [ a n y m a ], developed by Max & Michael Egger

avrusb is (c) 2005, 2006 by OBJECTIVE DEVELOPMENT Software GmbH.
http://www.obdev.at/
