Mac Driver for USITT DMX 512 via USBDMX

This chapter is obsolete ! See PIOS from Root Home.

USITT DMX 512 ./. Mac

Driver for the "USBDMX" USB Device by Lighting Solutions.
Alpha-Release

You need to put this driver into system folder:system extensions. Otherwise the Mac always will bother you with a dialog saying that there is no suitable driver when you connect the USBDMX.

If you are an user there is nothing more to do - you may directly launch an application that makes use of the USBDMX via this driver.

If you are a developer you'll need to study the drivers' api to see what you can do in your code.

Genral Information :
The driver does all the communication between the USBDMX and the Mac. As you know it does not present any user interface to the uus.
The driver is fully buffered so that you cannot halt the system with an call. Therefore the driver instantiates a own cycle that does all the usb-communication for you and presents some nice accessors API to the user.
All communication and accessor calls are buffered and don't need to be flushed ; Also the driver prevents you from accessing data in the middle of a usb transaction which would give you false endians on a Mac.
For convinience the driver gives you pointers to two 512 byte blocks in its heap (which is in the system heap) where the DMXdata is present. So if you want to read DMX just read from the pointer, but be aware that the driver constantly updates this memory. Writing is the same. Thanks to the Mac multitasking this can happen without waiting on each other cause the USB transactions are block transactions which are thread and interrupt safe.
You can, if you need, set the driver to use other pointers in your application heap; Be aware of the usual gotchas like moved memory at interrupt time and so on.

All functions do exactly what their name says. The neccassery headers are included in the packages on the download page. The functions upto 'getRUNMODE' are fixed but for further inventions the struct definitely will expanded more or less.

Notes about the API use :

In first keep in mind that the driver runs in the system heap and so its not the place to waste cycles cause the driver already puts a constant load on the system.
Second, based on first, there is done no checking about the put in pointers and sizes of buffers. If you are a child trying to do a so called hack for your personal fame you are completely wrong here. This software is intended to be used by professionals who respect the directions of the author cause they want a silently working machine. The author does not give any support to modifications in the driver or on how to implement other functionality. Therefore you have to write an appl.

General Information special functions :
Cause in most cases you place the USBDMX in the DMX512 line the driver has a copy function that copies received data directly to the transmitter to pass it along the DXM line. The copy function can be used with a selector-table that rises the work to be done in the drivers cycle to at least 512 more instructions cause this copy decision has to be checked (if/else) on every single char while in the usb transaction completition of a data read in ! (see blow)
Same applies to the limit in the output cycle where the if/else does two comparisons and one change at 44Hz...

These functions are implemented slight easy. Initially the driver only exports a second symbol called "cen". cen is declared as struct dmxcensor in dmx512.h. If, at load/init, there are resources present in the driver file ('Copy',128 / 'Limi',128, preload, system heap, locked) they are stuffed into the corresponding cen.boundaries, cen.channels. Otherwise the handles are 0. You can change them later by your appl as you like - do not release the resources if they were loaded ! If you alter these values keep a local copy of the original handle to set the values back, if.

The ranged limit function in the driver

cen.boundaries takes a Handle to a list of values where you can assign each channel a minimum and a maximum value. It's an array of 512 shorts. HiByte is lower limit, LoByte is higher limit. If you want to park a channel set them both to the same value.

The 'Limi',128 is 1024 bytes long. Which is the 512 shorts to be set via ResEdit.
The driver checks in every transaction to the transmitter if cen.boundaries != 0 and if works it down. So if you want to toggle it set the cen.boundaries to 0 or back to the / a handle.
The gotcha is that this limiting cannot be overridden by software because it is done just before sending the values to the device. In other words you can set the driver to copymode in->out to have a writethrough from your desk. The limiting could be done directly after receiving the data and transferring it to the machines' ram. Then it would be correct limited written into ram and your appl could stamp in values out of range.
So the limiting is placed before sending that even stamping out of range values by the appl is catched and the values are limited within their range.

The copy function in the driver

Note that the copymode in->out still maintains two ram areas which hold their counterparts of the device (tx / rc mem). If you don't need to alter data and just want a fast writethrough you also can set both rampointers via the accessors to the same address. This has the disadvantage that you cannot alter the values cause the receiver always overwrites the entire ram with new data - and your appl written data never gets sended.
cen.channels is used within the copymode in->out to specify the channels that have to be copied. Here you can specify which channels of the receivers memory are copied to the transmitters memory. This is useful if you want to filter out channels. Though the copy is done directly after receiving data you still can write your appl values into transmitter ram and limit them. Of course copy still overwrites, if.
'Copy',128 is a list of chars (guess 512) where a value !=0 means that the channel is copied. Keep in mind that other values than 1 or 0 can be other functionality in future !
Understand that the Copy In->Out is controlled by an acessor. If Copy In->Out is turned on the value of cen.channels decides if this copy is done by a BlockMove (cen.channels==0) or by selector values defined in cen.channels!=0.

Alpharelease Note : The copy counter in the appl counts backwards if cen.channels!=0. Limit has no graphical representation in the appl. If you changed the resources you'll have to unplug/plug the device to load the resources. Leave them preloaded, system heap and locked !
The above functions and functionalty is contained by the USBDMX Driver file in your system extensions folder.

This means limiting and copy does work without an application. Ongoing you have to have a application that makes use of the driver and the device. For your convinience I provide you a simple application that shows you how to use the driver and device. If you need other functions you need to type it on your own or buy it from me or another Mac developer.

Drivers API

Look in the System Heap for an exported symbol by the 'ndrv' named "apicmds".

struct dmxacc {
		dmx_pP		setTXmemaddr;// so you say where the data is
		dmx_pP		setRXmemaddr;// and you say whereto write
		dmx_rP		getTXmemaddr;
		dmx_rP		getRXmemaddr;
		
		dmx_r16		getTXslots;
		dmx_p16		setTXslots;
		dmx_r8		getTXstartcode;
		dmx_p8		setTXstartcode;
		dmx_r32		getTXframecount;
		
		dmx_r16		getRXslots;
		dmx_r8		getRXstartcode;
		dmx_p8		setRXstartcode;
		dmx_r32		getRXframecount;
		
		dmx_r16		getSTATUS;
		dmx_r16		getRUNMODE;
		dmx_p16		setCOPYMODE; /* 0 means copy off - rest is on - boolean short*/
		dmx_p16		setBLOCKING; /* guess */
	}; // apicmds in code for api commands

For more information about programming or purchasing the USB2DMX Interface please refer to www.lighting-solutions.de. Information on how to get an Apple Computer with usb should be obvious.

Please note that I only develop software for a device that is built by someone else. This means I do not sell this equipment, neither I do the support for it. I only bring it to the MacOS.
USB2DMX Device Download Page ; read the licence agreement and then download the software to let your Mac talk to your lighting gear. Enjoy !

Ask me for different versions or drivers for other interfaces. I do custom-built-to-order.