                 Notes on Using NMCLIB.DLL

NMCLIB.DLL is a library of functions for using NMC (Networked Modular Control) compatible modules.  Currently, only PIC-SERVO motor control modules and PIC-IO multi-function I/O modules are supported.  The example NmcExamp.cpp (and associated files) show a very simple test application using this library.  For a description of NMC devices and operation of the NMC communications protocol, please refer to the PIC-SERVO or the PIC-IO data sheets.

NMCLIB.DLL consists of three levels of functions.  At the lowest level is the group of serial I/O functions listed in SIO_UTIL.H.  These functions provide basic (non-overlapped) COM port support independent of the NMC communication protocol.  It includes functions for opening and closing COM ports, sending and receiving characters, etc.  Typically, you will never need to call these functions directly.

The next level of functions, listed in NMCCOM.H, provide basic support of the NMC communication protocol.  The functions at this level are independent of the types of modules used.  They include initialization and reset functions for the entire network of modules, module control functions common to all module types, and functions for retrieving data common to all module types.

The last level of functions are those specific to particular types of modules.  These are described in PICSERVO.H and PICIO.H.  They include functions for operations specific to each module type, and functions for retrieving module-type specific data.

The functions in each header file are descibed below:

**********
SIO_UTIL.H (listed for reference):
-int SimpleMsgBox(char *msgstr)
Dislpays a simple message box with the null-terminated string pointed to by 'msgstr'.  (This has nothing to do with serial I/O, but it is a generically useful function.)

-HANDLE SioOpen(char *name, unsigned int baudrate)
Opens a COM port at the specified baud rate.  Valid com port names are "COM1:", "COM2:", "COM3:" or "COM4:".  Valid baud rates for use with NMC modules are 19200, 57600 or 115200.  Returns a handle for the COM port stream.

-BOOL SioPutChars(HANDLE ComPort, char *stuff, int n)
Shoves n characters out the COM port specified by the handle ComPort.

-DWORD SioGetChars(HANDLE ComPort, char *stuff, int n)
Read in n characters from the specified COM port and puts them in the
array pointed to by 'stuff'.  This function has a timeout value of approximately 100 millisec.  It returns the number of characters actually read.

-DWORD SioTest(HANDLE ComPort)
Returns the number of characters in the ComPort's input buffer.

-BOOL SioClrInbuf(HANDLE ComPort)
Clears all of the characters in ComPort's input buffer.

-BOOL SioChangeBaud(HANDLE ComPort, unsigned int baudrate)
Changes the baud rate of ComPort.  Valid baud rates for use with NMC modules are 19200, 57600 or 115200.

-BOOL SioClose(HANDLE ComPort)
Closes a COM port.

**********
NMCCOM.H:
-int NmcInit(char *portname, unsigned int baudrate)
Opens the COM port specified by 'portname' ("COM1:", "COM2:", "COM3:", or "COM4:") at the specified baud rate (19200, 57600 or 115200) and initializes the network of motor controllers.  Controller addresses are dynamically assigned, starting with the furthest controller with address 1.  All group addresses are set to 0xFF.  Returns the number of controllers found on in the network.

-BOOL NmcSendCmd(byte addr, byte cmd, char *datastr, byte n, byte stataddr)
Sends to controller 'addr' the command byte 'cmd' followed by n additional data bytes in 'datastr'.  'stataddr' is the address of the module to which the returning status data belongs.  Normally stataddr is the same as addr.  For group commands with no group leader, addr is the group address and stataddr = 0.  For group commands with a group leader, addr is the group address and stataddr is the individual address of the group leader.  Returns true on success, false of failure.

-void NmcShutdown(void)
Querries the user if the network of controllers should be reset, resets if necessary, and then closes the COM port in use.

-BOOL NmcSetGroupAddr(byte addr, byte groupaddr, BOOL leader)
Sets the group address of a controller from the default of 0xFF.  Valid group addresses are between 0x80 and 0xFF.  If 'leader' is true, the specified controller becomes the group leader.  Only one leader should be specified for any group address.  Returns true on success, false on failure.

-BOOL NmcDefineStatus(byte addr, byte statusitems)
For module 'addr', defines which status data will always be sent back with each command.  'statusitems' should be set to the bitwise OR of the status items listed in PICSERVO.H or PICIO.H.  Returns true on success, false on failure.

-BOOL NmcReadStatus(byte addr, byte statusitems)
Reads status data from a module without chaning the default status data.  'statusitems' should be set to the bitwise OR of the status items listed in PICSERVO.H or PICIO.H.  Returns true on success, false on failure.

-BOOL NmcChangeBaud(byte groupaddr, unsigned int baudrate)
Sends a group command to all modules on the network to change their baud rate, and also changes the COM port's baud rate.  'groupaddr' should be 0xFF, unless the default group address has been changed.  All modules must have the same group address (with no group leader) before calling this function.  Returns true on success, false on failure.

-BOOL NmcNoOp(byte addr)
Issued a NO-OP command to module 'addr', simply causing its currently defined items of status data to be returned.  Returns true on success, false on failure.

-BOOL NmcHardReset(byte addr)
Resets a controller to its powerup state.  Under almost all circumstances, this is issued to a group address including all control modules.  Returns true on success, false on failure.

-byte NmcGetStat(byte addr)
Returns the current status byte of a controller.

-byte NmcGetStatItems(byte addr)
Returns the byte specifying the default status items to be returned in the status data packet.

-byte NmcGetModType(byte addr)
Returns the module type of a particular module.  This value will either be SERVOMODTYPE (0) or IOMODTYPE (2).

-byte NmcGetModVer(byte addr)
Returns the firmware version number of a particular module.

-byte NmcGetGroupAddr(byte addr)
Returns the group address of a particular module.

-BOOL NmcGroupLeader(byte addr)
Returns true if the specified module is a group leader, false if not.

-BOOL NmcSynchOutput(byte addr, byte leaderaddr)
Causes a group of modules to synchronously output their previously buffered output commands.  This will cause a PIC-SERVO module to execute a previously loaded trajectory and it will cause a PIC-IO module to output previously stored output bit and PWM values.  'leaderaddr' should be the individual address of the group leader, or 0 if there is no group leader.

-BOOL NmcSynchInput(byte groupaddr, byte leaderaddr)
Causes a group of modules to synchronously capture input values.  This will cause a PIC-SERVO module to store its current position as the home position and it will cause a PIC-IO module to store its input bits and timer values.  'leaderaddr' should be the individual address of the group leader, or 0 if there is no group leader.

**********
PICSERVO.H:
-long ServoGetPos(byte addr)
Returns the current motor position of a PIC-SERVO module.  Note: this data is only valid if the SEND_POS bit has been set in the most recently issued NmcDefineStat() command.

-byte ServoGetAD(byte addr)
Returns the current A/D value of a PIC-SERVO module.  Note: this data is only valid if the SEND_AD bit has been set in the most recently issued NmcDefineStat() command.

-short int ServoGetVel(byte addr)
Returns the current motor velocity of a PIC-SERVO module.  Note: this data is only valid if the SEND_VEL bit has been set in the most recently issued NmcDefineStat() command.

-byte ServoGetAux(byte addr)
Returns the current auxilliary status byte of a PIC-SERVO module.  Note: this data is only valid if the SEND_AUX bit has been set in the most recently issued NmcDefineStat() command.

-long ServoGetHome(byte addr)
Returns the current motor home position of a PIC-SERVO module.  Note: this data is only valid if the SEND_HOME bit has been set in the most recently issued NmcDefineStat() command.

-long ServoGetCmdPos(byte addr)
Returns the most recently issued command position for a PIC-SERVO module.

-long ServoGetCmdVel(byte addr)
Returns the most recently issued command velocity for a PIC-SERVO module.

-long ServoGetCmdAcc(byte addr)
Returns the most recently issued command acceleration for a PIC-SERVO module.

-long ServoGetStopPos(byte addr)
Returns the most recently issued stop position ( by a 'stop here' command) for a PIC-SERVO module.

-byte ServoGetCmdPwm(byte addr)
Returns the most recently issued command PWM value for a PIC-SERVO module.

-long ServoGetMoveCtrl(byte addr)
Returns the most recently issued move command control byte for a PIC-SERVO module.

-long ServoGetStopCtrl(byte addr)
Returns the most recently issued stop command control byte for a PIC-SERVO module.

-long ServoGetHomeCtrl(byte addr)
Returns the most recently issued home command control byte for a PIC-SERVO module.

-long ServoGetIoCtrl(byte addr)
Returns the most recently issued I/O command control byte for a PIC-SERVO module.

-void ServoGetGain(byte addr, short int * kp, short int * kd, short int * ki, short int * il, byte * ol, byte * cl, short int * el, byte * sr, byte * dc)
Returns the most recently issued servo gain values for a PIC-SERVO module.

-BOOL ServoSetGain(byte addr, short int kp, short int kd, short int ki,
short int il, byte ol, byte cl, short int el, byte sr, byte dc)
Sets the servo gains for a PIC-SERVO module.  Returns true on success, false on failure.

-BOOL ServoResetPos(byte addr)
Resets the position counter for a PIC-SERVO module.  Returns true on success, false on failure.

-BOOL ServoClearBits(byte addr)
Clears the sticky status bits (OVERCURRENT, POS_ERR) in a PICSERVO module.  Returns true on success, false on failure.

-BOOL ServoStopMotor(byte addr, byte mode)
Stops a motor in the manner specified by mode.  Mode is the stop control byte, and should be set to the bitwise OR of the stop control bits defined in PICSERVO.H.  Returns true on success, false on failure.

-BOOL ServoLoadTraj(byte addr, byte mode, long pos, long vel, long acc, byte pwm)
Loads motion trajectory information for a PIC-SERVO module.  'mode' is the load trajectory control byte, and should be set to the bitwise OR of the trajectory control byte bits defined in PICSERVO.H.  Note that if the START_NOW bit is set, the motion will begin immediately; if it is not set, the motion will be started when NmcSynchOutput() is called with the module's address.  Returns true on success, false on failure.

-BOOL ServoSetHoming(byte addr, byte mode)
Starts the homing for PIC-SERVO module.  'mode' is the homing control byte and should be set to the bitwise OR of the homing control bits defined in PICSERVO.H.  This command sets the homing conditions but does not start any motion.  The HOME_IN_PROG bit of the status byte should be monitored to detect when the home position has been captured.  Returns true on success, false on failure.

-BOOL ServoSetPhase(byte addr, int padvance, int poffset)
Sets the phase advance and phase offset values for an SS-Drive type controller.  This command should be issued to initialize the SS-Drive after the "amplifier enable" bit has been set using the ServoStopMotor() function.

**********
PICIO.H:
-BOOL IoInBitVal(byte addr, int bitnum)
Returns the value of an input bit (0 - 11) from a PIC-IO module.  Note: this data is only valid if the SEND_INPUTS bit has been set in the most recently issued NmcDefineStat() command.

-BOOL IoInBitSVal(byte addr, int bitnum)
Returns the value of a synchronously captured input bit (bitnum = 0 - 11) from a PIC-IO module.  Note: this data is only valid if the SEND_SYNCH_IN bit has been set in the most recently issued NmcDefineStat() command.

-byte IoGetADCVal(byte addr, int channel)
Returns the A/D value from channel 0, 1 or 2 from a PIC-IO module.  Note: this data is only valid if the SEND_ADn (n=1,2 or 3) bit has been set in the most recently issued NmcDefineStat() command.

-unsigned long IoGetTimerVal(byte addr)
Returns the timer value from a PIC-IO module.  Note: this data is only valid if the SEND_TIMER bit has been set in the most recently issued NmcDefineStat() command.

-unsigned long IoGetTimerSVal(byte addr)
Returns the synchronously captured timer value from a PIC-IO module.  Note: this data is only valid if the SEND_SYNC_TMR bit has been set in the most recently issued NmcDefineStat() command.

-BOOL IoGetBitDir(byte addr, int bitnum)
Returns 0 if a PIC-IO module I/O bit (bitnum = 0 - 11) is defined as an output, 1 if defined as an input.

-BOOL IoOutBitVal(byte addr, int bitnum)
Returns the most recently set state of an output bit (bitnum = 0 - 11) of a PIC-IO module.

-byte IoGetPWMVal(byte addr, int channel)
Returns the most recently set PWM value for channel 0 or 1 of a PIC-IO module.

-byte IoGetTimerMode(byte addr)
Returns the most recently set timer control byte for a PIC-IO module.

-BOOL IoSetOutBit(byte addr, int bitnum)
Sets the value of a PIC-IO module output bit (bitnum = 0 - 11) to 1.  This has no effect if the bit is defined as an input.  Returns true on success, false on failure.

-BOOL IoClrOutBit(byte addr, int bitnum)
Clears the value of a PIC-IO module output bit (bitnum = 0 - 11) to 0.  This has no effect if the bit is defined as an input.  Returns true on success, false on failure.

-BOOL IoBitDirIn(byte addr, int bitnum)
Sets the direction of a PIC-IO module I/O bit (bitnum = 0 - 11) to be an input bit.  Returns true on success, false on failure.

-BOOL IoBitDirOut(byte addr, int bitnum)
Sets the direction of a PIC-IO module I/O bit (bitnum = 0 - 11) to be an output bit.  Returns true on success, false on failure.

-BOOL IoSetPWMVal(byte addr, byte pwm1, byte pwm2)
Sets the PWM values for the two channels of a PIC-IO module.  pwm1 and pwm2 should be between 0 and 255.  Returns true on success, false on failure.

-BOOL IoSetTimerMode(byte addr, byte tmrmode)
Sets the counter/timer mode for a PIC-IO module.  'tmrmode' is the timer control byte and should be set to the bitwise OR of the timer control bits defined in PICIO.H.  Returns true on success, false on failure.

-BOOL IoSetSynchOutput(byte addr, short int outbits, byte pwm1, byte pwm2)
Specify the output bit values and the PWM values to be output at a later time when NmcSynchOutput() is called.
