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.
C/C++ API


Enumerating Devices

RDrMXEnum DrMXEnum_New();
Creates an enumerator for available interface hardware.

void DrMXEnum_Delete(RDrMXEnum aE);
Deletes an enumerator.

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.

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.

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.

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.

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.).

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.).

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)