DoctorMX Library (Windows version)
These are library files to use DoctorMX USB/DMX512 interface hardware from application program.
This requires the device driver is installed by executing a DoctorMX Installer.
include
DDrMXLib.h
C/C++ include file.
DDrMXLib.bas
VisualBasic include file.
(NOTE: We have not tested with VisualBasic.
Let us know if any problem)
sample
DrMXLibTest.cpp
A source file of test application program.
DrMXLTest.cpp
A source file of test application program.
x86, x64
drmxlib.dll
A dynamic link library file.
drmxlib.lib
An import library file.
DrMXLibTest.exe
A test application program which uses drmxlib.dll
.
Run from "Console" (MSDOS prompt) application.
It compares output and input data, then shows whether same or not.
(DMX input and output of DoctorMX USB/DMX512 interface hardware should be connected with a cable to loop back)
DrMXLTest.exe
A test application program which uses drmxlib.dll
.
It uses DrMX_Write()
periodically on WM_TIMER
.
It uses DrMX_Open()
and DrMX_Close()
alternately on a window click.
C/C++ API
Enumerating Devices
RDrMXEnum DrMXEnum_New();
Creates an enumerator for available interface hardware.
void DrMXEnum_Delete(RDrMXEnum aE);
Deletes an enumerator.
aE
An enumerator which is returned by DrMXEnum_New()
.
BOOL WINAPI DrMXEnum_Next(RDrMXEnum aE, TCHAR aID[16]);
Returns a device identifier (string) one by one.
This identifier is a unique (permanent) serial number for each interface hardware.
(earlier product do not have a serial number, thus USB connection ID which is assigned by system is used instead)
Returns TRUE
if a device is available (valid identifier is returned in aID
).
Returns FALSE
if no more device is available.
aE
An enumerator which is returned by DrMXEnum_New()
.
aID
Character array (at least 16 characters).
Returned string is NULL
terminated.
A serial number is 4 digit decimal number.
(alternative identifier for earlier product is 8 characters)
Using a Device
RDrMX WINAPI DrMX_Open();
Opens an any available interface hardware.
Returns an opaque reference to the interface hardware if available.
Returns NULL
if no hardware is available for any reason (not connected, etc.).
VOID WINAPI DrMX_Close(RDrMX aR);
Closes an interface hardware.
aR
A reference returned by DrMX_Open()
.
DWORD WINAPI DrMX_Write(RDrMX aR, const BYTE* aP, DWORD aL, DWORD aT);
Outputs DMX data.
To output DMX signal continuously, repeat DrMX_Write()
periodically.
If previous output by DrMX_Write()
has not completed yet, it waits until timed out.
Returns 1
if output begins.
Returns 0
if output does not begin (for timed out, etc.).
Also returns 0
for other than timed out, for example, there are messages in the queue of the thread.
Note that time out length is merely approximation and depend on system.
aR
A reference returned by DrMX_Open()
.
aP
An array of byte.
The first element (aP[0]
) is a DMX start code (normally 0).
aL
Length of an array, in elements.
Maximum length is 513.
aT
Time out length, in milliseconds [mS].
DWORD WINAPI DrMX_Read(RDrMX aR, BYTE* aP, DWORD aL, DWORD aT);
Inputs DMX data.
If previous input by DrMX_Read()
has not completed yet, it waits until timed out.
Returns a number of bytes read if there are input data.
Extra data more than specified by aL
are silently discarded.
Returns 0
if no input data is available (for timed out, etc.).
Also returns 0
for other than timed out, for example, there are messages in the queue of the thread.
Note that time out length is merely approximation and depend on system.
aR
A reference returned by DrMX_Open()
.
aP
An array of byte.
The first element (aP[0]
) is a DMX start code (normally 0).
aL
Length of an array, in elements.
Maximum length is 513.
aT
Time out length, in milliseconds [mS].
RDrMX WINAPI DrMX_OpenID(LPCTSTR aID);
Opens a specific interface hardware.
Returns an opaque reference to the interface hardware if available.
Returns NULL
if specified hardware is not available for any reason (not connected, etc.).
aID
An identifier (serial number) returned by DrMXEnum_Next()
.
Must be NULL
terminated.
BOOL WINAPI DrMX_SetTiming(RDrMX aR, DWORD aBrk, DWORD aMAB, DWORD aMBS);
Sets output signal timing.
Returns FALSE
if failed for any reason (device is removed, etc.).
aBrk
Specify a break time.
The minimum value of 92μS is added to this value.
Default is 84 (actual break time is 176μS).
Valid range is from 0 to 255 [μS] .
aMAB
Specify "Mark After Break" time.
The minimum value of 12μS is added to this value.
Default is 0 (actual MAB is 12μS).
Valid range is from 0 to 255 [μS] .
aMBS
Specify "Mark Between Slot" time.
Default is 0 (actual MBS is also 0μS).
Valid range is from 0 to 255 [μS] .
Example
TCHAR devid[16];
RDrMXEnum de = DrMXEnum_New();
while (DrMXEnum_Next(de, devid))
{
}
DrMXEnum_Delete(de);
/* ----------- */
BYTE wbuf[513];
BYTE rbuf[513];
DWORD r;
RDrMX drmx = DrMX_Open();
if (drmx != NULL)
{
/* setup output data
|
|
*/
r = DrMX_Write(drmx, wbuf, 513, 30);
if (r == 0)
{
/* retry later */
}
r = DrMX_Read(drmx, rbuf, 513, 30);
if (0 < r)
{
/* process input data */
}
DrMX_Close(drmx);
}
NOTES
DrMX_Write()
and DrMX_Read()
should be used periodically on timer (WM_TIMER
).
If necessary, sets an "output flag" by some operations, check the flag periodically on timer, then output the data (and clear the flag if succeeded).
On Windows, timer is executed if there is no pending message, thus DrMX_Write()
and DrMX_Read()
will succeed in most cases.
Internally, DMX input/output, message queue and time out are waited by
MsgWaitForMultipleObjectsEx(1, &aE, aT, QS_ALLPOSTMESSAGE | QS_ALLINPUT, MWMO_ALERTABLE | MWMO_INPUTAVAILABLE);
and begin output only if WAIT_OBJECT_0
is returned.
Note that even on WM_TIMER
, new message can be enqueued before DrMX_Write()
or DrMX_Read()
is used (thus it may still fail).
As an alternative (and may be better), it is possible to use DrMX_Write()
and DrMX_Read()
on other thread (non user interface thread).
DrMX_Read()
should be called repeatedly as long as it returns other than 0
.
In this way, input buffer is kept empty.
VisualBasic API
For details, see C/C++ API above.
(NOTE: We have not tested with VisualBasic.
Let us know if any problem)
Declare Function DrMXEnum_New Lib "drmxlib.dll" () As Long
Declare Sub DrMXEnum_Delete Lib "drmxlib.dll" (ByVal aR As Long)
Declare Function DrMXEnum_NextW Lib "drmxlib.dll" (ByVal aR As Long, ByRef aID As Integer) As Long
Declare Function DrMXEnum_NextA Lib "drmxlib.dll" (ByVal aR As Long, ByRef aID As Byte) As Long
Declare Function DrMX_Open Lib "drmxlib.dll" () As Long
Declare Sub DrMX_Close Lib "drmxlib.dll" (ByVal aR As Long)
Declare Function DrMX_Write Lib "drmxlib.dll" (ByVal aR As Long, ByRef aP As Byte, ByVal aL As Long, ByVal aT As Long) As Long
Declare Function DrMX_Read Lib "drmxlib.dll" (ByVal aR As Long, ByRef aP As Byte, ByVal aL As Long, ByVal aT As Long) As Long
Declare Function DrMX_OpenIDW Lib "drmxlib.dll" (ByRef aID As Integer) As Long
Declare Function DrMX_OpenIDA Lib "drmxlib.dll" (ByRef aID As Byte) As Long
For any questions, ask via email.
email (uty@kuwatec.co.jp)