Tews Technologies TPMC551-SW-95 User manual

The Embedded I/O Company
TPMC551-SW-95
QNX6 - Neutrino Device Driver
8/4 Channel 16 Bit DAC PMC
Version 1.0.x
User Manual
Issue 1.0.0
December 2015
TEWS TECHNOLOGIES GmbH
Am Bahnhof 7 25469 Halstenbek, Germany
Phone: [phone] Fax: [phone]
e-mail: [e-mail] www.tews.com

TPMC551-SW-95 – QNX6 - Neutrino Device Driver Page 2 of 30
TPMC551-SW-95
QNX6-Neutrino Device Driver
8/4 Channel 16 Bit DAC PMC
Supported Modules:
TPMC551
This document contains information, which is
proprietary to TEWS TECHNOLOGIES GmbH. Any
reproduction without written permission is forbidden.
TEWS TECHNOLOGIES GmbH has made any
effort to ensure that this manual is accurate and
complete. However TEWS TECHNOLOGIES GmbH
reserves the right to change the product described
in this document at any time without notice.
TEWS TECHNOLOGIES GmbH is not liable for any
damage arising out of the application or use of the
device described herein.
¤2015 by TEWS TECHNOLOGIES GmbH
Issue Description Date
1.0 First Issue December 7, 2015

TPMC551-SW-95 – QNX6 - Neutrino Device Driver Page 3 of 30
Table of Contents
1 INTRODUCTION......................................................................................................... 4
2 INSTALLATION.......................................................................................................... 5
Build the Device Driver...................................................................................................................52.1
Build the API Library.......................................................................................................................52.2
Build the Example Application ......................................................................................................62.3
Start the Driver Process .................................................................................................................62.4
3 API DOCUMENTATION ............................................................................................. 7
General Functions...........................................................................................................................73.1
3.1.1 tpmc551Open ......................................................................................................................7
3.1.2 tpmc551Close ......................................................................................................................9
3.1.3 tpmc551GetModuleInfo......................................................................................................11
DAC Output Functions .................................................................................................................133.2
3.2.1 tpmc551DacWrite ..............................................................................................................13
3.2.2 tpmc551DacWriteMulti.......................................................................................................15
Sequencer Functions....................................................................................................................173.3
3.3.1 tpmc551SeqSetup .............................................................................................................17
3.3.2 tpmc551SeqStart ...............................................................................................................20
3.3.3 tpmc551SeqStop ...............................................................................................................22
3.3.4 tpmc551SeqWrite ..............................................................................................................24
3.3.5 tpmc551SeqFlush ..............................................................................................................27
3.3.6 tpmc551SeqStatus.............................................................................................................29

TPMC551-SW-95 – QNX6 - Neutrino Device Driver Page 4 of 30
1 Introduction
TheTPMC551-SW-95QNX-NeutrinodevicedriverallowstheoperationoftheTPMC551onQNX-
Neutrino operating systems.
The TPMC551 device driver is basically implemented as a user installable Resource Manager. An
Application Programming Interface (API) provides access to the driver functionality, and wraps the
standard file (I/O) functions (open, close and devctl).
The TPMC551-SW-95 device driver includes the following functions:
¾Setting DAC output value
¾Configure, start, and stop DAC-sequencer
¾Write data for sequencer cycle
¾Use of data correction for simple conversion and in sequencer mode
¾Use of latched writes for synchronous output
¾Reading TPMC551 configuration (number of channels and uni-/bipolar output)
The TPMC551-SW-95 device driver supports the modules listed below:
TPMC551 8/4 Channels of Isolated 16 bit D/A PMC
To get more information about the features and use of supported devices it is recommended to read the
manuals listed below.
TPMC551 User Manual

TPMC551-SW-95 – QNX6 - Neutrino Device Driver Page 5 of 30
2Installation
Following files are located in the directory TPMC551-SW-95 on the distribution media:
TPMC551-SW-95-SRC.tar.gz GZIP compressed archive with driver source code
TPMC551-SW-95-1.0.0.pdf This manual in PDF format
ChangeLog.txt Release history
Release.txt Information about the Device Driver Release
The GZIP compressed archive TPMC551-SW-95-SRC.tar.gz contains the following files and directories:
Directory path ‘tpmc551’:
/api/tpmc551api.c API source code
/api/tpmc551api.h API definitions for driver and application
/driver/tpmc551.c Driver source code
/driver/tpmc551.h Definitions and data structures for driver and application
/driver/tpmc551def.h Device driver include
/driver/node.c Queue management source code
/driver/node.h Queue management definitions
/example/tpmc551exa.c Example application
For installation copy the tar-archive into the /usr/src directory and unpack it
(e.g. tar –xzvf TPMC551-SW-95-SRC.tar.gz). After that the necessary directory structure for the
automatic build and the source files are available underneath the new directory called tpmc551.Copythe
files /driver/tpmc551.h and /api/tpmc551api.h into the directory /usr/include.
It is absolutely important to extract the TPMC551 driver archive in the /usr/src directory. Otherwise
the automatic build with make will fail.
BuildtheDeviceDriver2.1
Change to the /usr/src/tpmc551/driver directory
Execute the Makefile:
# make install
After successful completion the driver binary (tpmc551) will be installedinthe/bindirectory.
Build the API Library2.2
Change to the /usr/src/tpmc551/api directory
Execute the Makefile:
# make install
After successful completion the API library will be installed and available for later usage.

TPMC551-SW-95 – QNX6 - Neutrino Device Driver Page 6 of 30
Build the Example Application2.3
Change to the /usr/src/tpmc551/example directory
Execute the Makefile:
# make install
After successful completion the example binary (tpmc551exa) will be installed in the /bin directory.
Start the Driver Process2.4
To start the TPMC551 device driver, you have to enter the process name with optional parameters from
the command shell or in the startup script.
Possible parameters are:
-v
For debugging purposes you can start the TPMC551 Resource Manager with the –v option. The
Resource Manager will print versatile information about TPMC551 configuration and command
execution on the terminal window.
Example:
The following startup call will start the TPMC551 device driver in verbose mode:
# tpmc551 –v &
After the TPMC551 Resource Manager is started, it creates and registers a device for each found
hardware module. The devices are named /dev/tpmc551_x,wherexis the number of the found
module.
/dev/tpmc551_0, /dev/tpmc551_1, ...
This pathname must be used in the application program to open a path to the desired TPMC551 channel
device. Please refer to the corresponding description within this document.

TPMC551-SW-95 – QNX6 - Neutrino Device Driver Page 7 of 30
3 API Documentation
General Functions3.1
3.1.1 tpmc551Open
NAME
tpmc551Open – opens a device
SYNOPSIS
TPMC551_HANDLE tpmc551Open
(
char *DeviceName
)
DESCRIPTION
Before I/O can be performed to a device, a device descriptor must be opened by a call to this function.
PARAMETERS
DeviceName
This parameter points to a null-terminated string that specifies the name of the device. The following
device naming must be used:
Device Number Device Name
1 /dev/tpmc551_0
2 /dev/tpmc551_1

TPMC551-SW-95 – QNX6 - Neutrino Device Driver Page 8 of 30
EXAMPLE
#include <tpmc551api.h>
TPMC551_HANDLE hdl;
/*
** open the specified device
*/
hdl = tpmc551Open(“/dev/tpmc551_0”);
if (hdl == NULL)
{
/* handle open error */
}
RETURNS
A device handle, or NULL if the function fails. An error code will be stored inerrno.
ERROR CODES
The error codes are stored in errno.
The error code is a standard error code set by the I/O system.

TPMC551-SW-95 – QNX6 - Neutrino Device Driver Page 9 of 30
3.1.2 tpmc551Close
NAME
tpmc551Close – closes a device
SYNOPSIS
TPMC551_STATUS tpmc551Close
(
TPMC551_HANDLE hdl
)
DESCRIPTION
This function closes previously opened devices.
PARAMETERS
hdl
This value specifies the device handle to the hardware module retrieved by a call to the
corresponding open-function.
EXAMPLE
#include <tpmc551api.h>
TPMC551_HANDLE hdl;
TPMC551_STATUS result;
/*
** close the device
*/
result = tpmc551Close(hdl);
if (result != TPMC551_OK)
{
/* handle close error */
}

TPMC551-SW-95 – QNX6 - Neutrino Device Driver Page 10 of 30
RETURNS
On success, TPMC551_OK is returned. In the case of an error, the appropriate error code is returned by
the function.
ERROR CODES
Error Code Description
TPMC551_ERR_INVALID_HANDLE The specified device handle is invalid

TPMC551-SW-95 – QNX6 - Neutrino Device Driver Page 11 of 30
3.1.3 tpmc551GetModuleInfo
NAME
tpmc551GetModuleInfo – Get module information
SYNOPSIS
TPMC551_STATUS tpmc551GetModuleInfo
(
TPMC551_HANDLE hdl,
int *NumChan,
int bipolar[TPMC551_MAX_CHAN],
int OffsCorr[TPMC551_MAX_CHAN],
int GainCorr[TPMC551_MAX_CHAN]
)
DESCRIPTION
This function reads module information data from the specified device.
PARAMETERS
hdl
This argument specifies the device handle to the hardware module retrieved by a call to the
corresponding open-function.
NumChan
This argument is a pointer to an int variable where the number of available DAC channels is
returned.
bipolar
This argument is a pointer to an int array where the configured voltage range of each DAC channel
is returned as boolean value. The array element bipolar[0] contains the range stetting for DAC
channel 1, bipolar[1] for DAC channel 2 and so forth. If the corresponding value is TRUE then the
voltage range of the channel is configured to +/- 10V output (bipolar); otherwise it is configured to
0…10V output voltage range.
OffsCorr
This argument is a pointer to an int array where the factory programmed offset correction data is
returned. OffsCorr[0] contains correction data for DAC channel 1, OffsCorr[1] for DAC channel 2
and so forth.
GainCorr
This argument is a pointer to an int array where the factory programmed gain correction data are
returned. GainCorr[0] contains correction data for DAC channel 1, GainCorr[1] for DAC channel 2
and so forth.

TPMC551-SW-95 – QNX6 - Neutrino Device Driver Page 12 of 30
EXAMPLE
#include <tpmc551api.h>
TPMC551_HANDLE hdl;
TPMC551_STATUS result;
int NumChan;
int bipolar[TPMC551_MAX_CHAN];
int OffsCorr[TPMC551_MAX_CHAN];
int GainCorr[TPMC551_MAX_CHAN];
/* Get module information data */
result = tpmc551GetModuleInfo(hdl, &NumChan, bipolar, OffsCorr, GainCorr);
if (result != TPMC551_OK)
{
/* handle error */
}
RETURNS
On success, TPMC551_OK is returned. In the case of an error, the appropriate error code is returned by
the function.
ERROR CODES
Error Code Description
TPMC551_ERR_INVALID_HANDLE The specified TPMC551_HANDLE is invalid.

TPMC551-SW-95 – QNX6 - Neutrino Device Driver Page 13 of 30
DAC Output Functions3.2
3.2.1 tpmc551DacWrite
NAME
tpmc551DacWrite – write D/A value to specified channel
SYNOPSIS
TPMC551_STATUS tpmc551DacWrite
(
TPMC551_HANDLE hdl,
int channel,
unsigned int flags,
int value
)
DESCRIPTION
This function writes a new value to a specific channel and starts D/A conversion immediately in
transparent mode
PARAMETERS
hdl
This argument specifies the device handle to the hardware module retrieved by a call to the
corresponding open-function.
channel
This argument specifies the DAC channel which shall be updated. Possible values are 1 up to the
number of available DAC channels of the specific module.
flags
This argument specifies a set of bit flags that control the D/A conversion:
Value Description
TPMC551_CORR Perform an offset and gain correction with factory calibration
data stored in the TPMC551 EEPROM.
value
This argument specifies the new 16-bit D/A value. Valid data range depends on the voltage range of
the specified channel (0…65535 for 0...10V voltage range and -32768…32767
for +/-10V voltage range).

TPMC551-SW-95 – QNX6 - Neutrino Device Driver Page 14 of 30
EXAMPLE
#include <tpmc551api.h>
TPMC551_HANDLE hdl;
TPMC551_STATUS result;
result = tpmc551DacWrite(hdl, 1, TPMC551_CORR, 12345);
if (result != TPMC551_OK)
{
/* handle error */
}
RETURNS
On success, TPMC551_OK is returned. In the case of an error, the appropriate error code is returned by
the function.
ERROR CODES
Error Code Description
TPMC551_ERR_INVALID_HANDLE The specified TPMC551_HANDLE is invalid.
TPMC551_ERR_RANGE Invalid channel number
TPMC551_ERR_TIMEOUT Timeout during D/A conversion
TPMC551_ERR_BUSY This error occurs if the sequencer is still running. Please
stop the sequencer before executing this function.

TPMC551-SW-95 – QNX6 - Neutrino Device Driver Page 15 of 30
3.2.2 tpmc551DacWriteMulti
NAME
tpmc551DacWriteMulti – write D/A value to multiple channels
SYNOPSIS
TPMC551_STATUS tpmc551DacWriteMulti
(
TPMC551_HANDLE hdl,
unsigned int ChannelMask,
unsigned int flags,
int values[TPMC551_MAX_CHAN]
)
DESCRIPTION
This function writes new values to specified channels and starts D/A conversion immediately (transparent
mode) or simultaneously (latched mode).
PARAMETERS
hdl
This argument specifies the device handle to the hardware module retrieved by a call to the
corresponding open-function.
ChannelMask
This argument selects DAC channels which shall be updated. A set (1) bit specifies that the
corresponding channel shall be updated. Bit 0 corresponds to the first DAC channel, bit 1
corresponds to the second DAC channel and so on.
flags
This argument specifies a set of bit flags that control the D/A conversion:
Value Description
TPMC551_CORR Perform an offset and gain correction with factory calibration
data stored in the TPMC551 EEPROM for all selected
channels.
TPMC551_SIMCONV Start conversion of selected channels in latched mode and
update analog outputs simultaneously.
values
This array contains the new 16-bit D/A values. Valid data range depends on thevoltagerangeof
the specified channel (0…65535 for 0...10V voltage range and -32768…32767 for +/-10V voltage
range).
Array index 0 corresponds to the first DAC channel, array index 1 correspondstothesecondDAC
channel and so on. Only channels selected for update (ChannelMask) will be modified.

TPMC551-SW-95 – QNX6 - Neutrino Device Driver Page 16 of 30
EXAMPLE
#include <tpmc551api.h>
TPMC551_HANDLE hdl;
TPMC551_STATUS result;
unsigned int ChannelMask;
unsigned int flags;
int values[TPMC551_MAX_CHAN];
/* Update channel 1, 4 and 8 simultaneously with corrected D/A values */
ChannelMask = (1<<0) | (1<<3) | (1<<7);
flags = TPMC551_CORR | TPMC551_SIMCONV;
value[0] = 1111; /* channel 1 */
value[3] = 4444; /* channel 4 */
value[7] = 8888; /* channel 8 */
result = tpmc551DacWriteMulti(hdl, ChannelMask, flags, values);
if (result != TPMC551_OK)
{
/* handle error */
}
RETURNS
On success, TPMC551_OK is returned. In the case of an error, the appropriate error code is returned by
the function.
ERROR CODES
Error Code Description
TPMC551_ERR_INVALID_HANDLE The specified TPMC551_HANDLE is invalid.
TPMC551_ERR_RANGE Invalid channel number
TPMC551_ERR_TIMEOUT Timeout during D/A conversion
TPMC551_ERR_BUSY This error occurs if the sequencer is still running. Please
stop the sequencer before executing this function.

TPMC551-SW-95 – QNX6 - Neutrino Device Driver Page 17 of 30
Sequencer Functions3.3
3.3.1 tpmc551SeqSetup
NAME
tpmc551SeqSetup – Setup sequencer facility
SYNOPSIS
TPMC551_STATUS tpmc551SeqSetup
(
TPMC551_HANDLE hdl,
int CycleTime,
int NumActiveChannels,
int NumBufTuples,
int ChannelAllocation[TPMC551_MAX_CHAN],
unsigned int flags
)
DESCRIPTION
This function configures the sequencer facility and allocates memory for the sequencer software ring
buffer. The behaviour of the sequencer facility is controlled by a set of bit flags which are described below.
Basically the sequencer will perform a D/A conversion on active channels in a deterministic time period
controlled by a cycle timer or the duration of the conversion itself. To be sure that D/A data will be
available for the next cycle just in-time, data for the sequencer will be provided by a configurable ring
buffer. The ring buffer can be asynchronously filled by the application program.
The sequencer facility provides two operating modes. In loop mode (TPMC551_LOOP)thebufferwillbe
filled completely with new data (e.g. wave form). The contents of the buffer will be output continuously in a
loop. In normal mode (TPMC551_LOOP is not set) the application program must provide new data for
every cycle. If the buffer is empty then the sequencer will stop and it holds the last output value until new
data arrives.
PARAMETERS
hdl
This argument specifies the device handle to the hardware module retrieved by a call to the
corresponding open-function.
CycleTime
This argument specifies the sequencer cycle time in steps of 100 μs. This argument is only relevant
if the flag TPMC551_TIMERMODE is set.

TPMC551-SW-95 – QNX6 - Neutrino Device Driver Page 18 of 30
NumActiveChannels
This argument specifies the number of active channels. Valid range is 1 up to the number of
available channels (4 or 8).
NumBufTuples
This argument specifies the size of the sequencer software ring buffer. In this case size is not the
number of bytes to allocate but rather the number of tuples (data for all active channels per cycle).
ChannelAllocation
This argument specifies the channel number of active channels and their enumeration inside a
tuple. The function tpmc551SeqWrite awaits new data for active channels in this order. The first
array element contains the channel number (1...n) of the first active channel. The second array
element the channel number of the second active channel and so forth. Unused array elements can
be left undefined.
flags
This argument specifies a set of bit flags that control the sequencer operation:
Value Description
TPMC551_TIMERMODE If set, the cycle of D/A conversions will be controlled by the
sequencer timer in steps of 100 microseconds; otherwise the
sequencer will run in continuous mode as fast as possible
(based on the conversion time).
TPMC551_LOOP If this flag is set (loop mode) the ring buffer never becomes
empty. Once completely filled the sequencer will continuously
get data out of the buffer for the next conversion.
If this flag is not set (normal mode) and the buffer becomes
empty then the sequencer will stop and it holds the last output
value until new data arrives.
TPMC551_CORR Perform an offset and gain correction with factory calibration
data stored in the TPMC551 EEPROM for all selected
channels.
TPMC551_SIMCONV Start conversion of active channels in latched mode and
update analog outputs simultaneously.

TPMC551-SW-95 – QNX6 - Neutrino Device Driver Page 19 of 30
EXAMPLE
#include <tpmc551api.h>
TPMC551_HANDLE hdl;
TPMC551_STATUS result;
int ChannelAllocation[TPMC551_MAX_CHAN];
unsigned int flags;
/* Setup the sequencer with 2 active channels (1 and 4) in timer mode */
/* with 1 ms cycle time. The sequencer buffer shall store data tuples */
/* for up to 100 cycles. */
ChannelAllocation[0] = 1;
ChannelAllocation[1] = 4;
flags = TPMC551_TIMERMODE | TPMC551_CORR | TPMC551_SIMCONV;
result = tpmc551SeqSetup(hdl, 10, 2, 100, ChannelAllocation, flags);
if (result != TPMC551_OK)
{
/* handle error */
}
RETURNS
On success, TPMC551_OK is returned. In the case of an error, the appropriate error code is returned by
the function.
ERROR CODES
Error Code Description
TPMC551_ERR_INVALID_HANDLE The specified TPMC551_HANDLE is invalid.
TPMC551_ERR_RANGE Invalid channel number or invalid number of channels.
TPMC551_ERR_NOMEM Unable to allocate memory for the ring buffer.
TPMC551_ERR_BUSY This error occurs if the sequencer is still running. Please
stop the sequencer before executing this function.

TPMC551-SW-95 – QNX6 - Neutrino Device Driver Page 20 of 30
3.3.2 tpmc551SeqStart
NAME
tpmc551SeqStart – start sequencer facility
SYNOPSIS
TPMC551_STATUS tpmc551SeqStart
(
TPMC551_HANDLE hdl
)
DESCRIPTION
This function starts the sequencer facility. Before calling this function the sequencer must be setup with
tpmc551SeqSetup und the ring buffer must be filled with tpmc551SeqWrite.
PARAMETERS
hdl
This argument specifies the device handle to the hardware module retrieved by a call to the
corresponding open-function.
EXAMPLE
#include <tpmc551api.h>
TPMC551_HANDLE hdl;
TPMC551_STATUS result;
/* start the seuencer */
result = tpmc551SeqStart(hdl);
if (result != TPMC551_OK)
{
/* handle error */
}