Hardware Input / Output Library for Matlab / Simulink

Copyright (C) 2000-2007 Werner.Zimmermann|AT|hs-esslingen.de


Overview

This library allows port and memory IO for Matlab and Simulink under Windows NT/2000/XP. Matlab functions for use in Matlab command scripts and Simulink blocks for use in Simulink block diagrams are provided. Additionally commands to install Matlab functions as timer and interrupt callback functions and to realize TCP/IP communication in Matlab scripts are available.

A special Simulink block RTCsim allows Simulink to be used as a soft real time data acquisition or control system. By using Simulink block IntTrig this real time simulation can be synchronized to external interrupts.

Additionally, using the block RemoteIO, a Simulink block diagram can send or receive data via a TCP/IP connection.

The most recent version of IOlib can be downloaded from www.it.hs-esslingen.de/~zimmerma/software

Note: Sorry, this package works under Windows operating systems only, Unix is not supported. If you want to add Unix support and have the appropriate knowledge in writing Unix device drivers, please contact the author.


Installation

This library is distributed as a zip file. To install, unzip it into your desired installation directory. Then do the following, if you are using

... and copy the respective files to IOlib's main directory typing 'copy *.* ..'. You need to do this, even if you do not have Simulink!

All Matlab script files (*.m), the IO library (IOlib.mdl) and the support files (all DLLs, crackNT.sys) must be in one directory. This directory must be accessible via the Matlab path. Files 'Crack.dll', and 'CrackNT.sys' should be copied to your Windows directory.

Under Windows NT/2000/XP, if you do not have administrator rights, the IO functions readIOx, writeIOx, readMx, writeMx (x=b, w or dw) and interrupt functions will not work, unless your administrator has installed and started the Windows kernel driver crackNT.sys, included in this package. To install the driver, the admin may run 'crackIns.bat' (from a command window), to remove the driver he may use 'crackRem.bat'.
If you get an error message "CrackNT.sys not found" or a message "Invalid mex file", please copy files 'CrackNT.sys' and 'Crack.dll' to your windows directory or to your current working directory.


Command line Matlab functions

The following Matlab commands are available:

To get more detailed usage information, have a look at the examples below and type 'help xxx' from the Matlab command line. For xxx set the respective command.


Simulink block library IOlib

Input/output blocks

For the Matlab input/output commands described above, respective Simulink blocks are provided. If you need more complicated input/output sequences in a Simulink block diagram, write a respective Matlab script using these commands and wrap it into a Simulink block (block Matlab-function in Simulink's nonlinear blocks library).

To get more detailed usage information, double click on the respective block's icon.


Simulink real time operation: Block RTCsim

The block 'RTCsim' allows Simulink to run under real time conditions, i.e. the simulation time tracks the real time as good as possible. This allows Simulink to be used as a soft-realtime system. However, the typical restrictions of Windows for control applications do apply, i.e. latency times cannot be guaranteed.

A 'real time' Simulink block diagram may contain any type of Simulink blocks (continuous and discrete), but must use a Fixed-Step integration solver and set the step width (sampling time of the real time system) must be 10ms minimum (set under menu item 'Simulation-Parameters'). For more complicated block diagrams higher values for the step size must be set.

To get more detailed usage information, double click on the block icon.

Please note: This block should only be used once in a Simulink model.


Synchronization to external interrupts: Block IntTrig

This block allows to synchronize a Simulink simulation to external events signaled by interrupts. The block takes an IRQ (interrupt request) number as parameter, e.g. IRQ=12 for PS/2 mouse interrupts or IRQ=3 or IRQ=4 for serial port interrupts. (Please note: Don't mix IRQ numbers with INT (interrupt) numbers!). The block sets its output signal to the number of interrupt requests, which occurred in the last sampling period. Maximum interrupt latency is one sampling period.

Note:
This function does not work under Windows 2000/XP with those interrupts, which are already used by Windows own drivers, e.g. the mouse driver, because Windows 2000/XP does not allow to share those interrupts between the Windows 2000/XP driver and another (your) program.


TCP/IP coupling of Simulink simulations: Block Remote IO

Your Simulink block diagram can be coupled to non-Simulink programs via TCP/IP by inserting the Simulink block 'RemoteIO' into your block diagram. This block acts as a TCP/IP server daemon, listening for client connections at the TCP/IP port specified in the block parameter mask. All signals connected to the inputs of this block will be sent to a remote client. All data received by this block via TCP/IP appear as output signals of this block. Only one client at a time can be connected. This block should only be used in combination with the real time simulation block RTCsim, as the data rate for send operations, which is a parameter of this block, only corresponds with real time values, if the simulation is running in real time.

There is no limit for the number of input (send) channels. The number of output (receive) channels is limited to a maximum of 16.

Block RemoteIO can also be used to connect to a second Simulink simulation running on another computer on the net or on the same computer in another Matlab instance. In that case one of the RemoteIO blocks acts as server, the other one as client. To enable client operation, set the client block's host address parameter field to the address of the Matlab host computer. If your running on the same computer, use 'localhost' as host address. To enable server operation, the field host address must be set to an empty string, i.e. ''.

To get more detailed usage information and a description of the data format used for transmission, double click on the block icon.

Please note: This block should only be used once in a Simulink model.


Examples

The package comes with some demo files:

Details about the examples follow:

IoDemo.m

This Matlab script shows, how the command line input/output functions can be used to read the date and time from the real time clock chip of your PC.


TimerDemo.m

This Matlab scripts shows, how to use the itimer function. It sets up 4 counters using periodical timers. The counters will be incremented periodically and the respective counter values will be shown. By means of one shot timers, these timers are stopped again after some time. For details use 'help TimerDemo'.


IntDemo.m

This Matlab scripts shows, how to use the interrupt function (and the timers). It sets up a counter as a callback routine for the mouse interrupt and periodically displays the number of mouse interrupts within the last 5 sec. After 30 sec the program removes the interrupt callback routine again. For details use 'help IntDemo'.

Note:
This demo program does not run under Windows 2000/XP, because Windows 2000/XP does not allow to share the mouse interrupt between the Windows 2000/XP driver and another (our) program.

IntDemo2.m

This example does the same as IntDemo, but uses the LPT printer port interrupt. This interrupt can be triggered, by connecting printer port pin 10 to GND.


ServerDemo.m and ClientDemo.m

These two Matlab scripts show, how to use the TCP function. The scripts must run in two different instances of Matlab on the same computer, with ServerDemo started first. ClientDemo will sent data to the server, the server will do some computation and resent the result, which will be displayed by the client. For details use 'help ClientDemo'.


Example.m and ExampleModel.mdl

The Matlab script 'Example.m' loads the Simulink demo 'ExampleModel.mdl', which shows how to run a simulation in real time by using the RTCsim block. It reads the real time clock chip of your PC and displays date and time using the Matlab script 'time.m' (see above), which is wrapped in a Matlab function block.

If you compare the time value of the real time clock chip in the display in the upper right corner with the simulation time display in the center of the block diagram, you'll see that the simulation time advances in 'real time'. A scope shows the sample time error during the simulation.

In the lower half you can see a normal Simulink model, containing time continuous and time discrete blocks. By clicking on the associated scope, you can see that the block diagrams signals also advance in real time.


Example.bat and ExampleApplet (requires Microsoft Internet Explorer with Java plugin)

Execute the Matlab script example.m (see above) from the Matlab command line to load the Simulink model 'ExampleModel.mdl'.

Then switch to a DOS command window and start the batch file 'example.bat' by typing 'example'. This batch file will start the Java applet 'ExampleApplet.java'. In the Java applet click on the 'Connect' button, this will connect the applet to your Simulink model. When connected, in the Simulink block diagram start the Simulink simulation.

If you have another web browser with Java plug in installed, instead of using the DOS batch file 'example.bat', open the HTML-page 'ExampleApplet.htm'.

The block RemoteIO in the Simulink model will transmit the model's date and time values (see above) via TCP/IP to the Java applet, where they should show up in the 'Received values' fields. Via the 'Pause' and 'Cont' buttons you can control the Simulink simulation. (Note: Due to an unsolved problem starting and stopping the simulation may only work from the Simulink window, but not from the remote client).

If you type some numbers in the Java applets 'Enter value field' and click on the send button, these numbers will be transferred via TCP/IP to the Simulink model and show up in the 'Received Data' display (if the display does not update immediately, click on the Simulink model window).

Note: If something fails in this step, you may have to restart Matlab and/or the Java applet before you can reconnect.


Example.m, ExampleModel.mdl and your web browser

If you don't have Java installed, you can at least view a textual representation of data transmitted via the TCP/IP connection. Start Example.m as described above. Then open your web browser and as URL type 'http://localhost:4660'. In the Matlab window you should see a message 'RemoteIO INFO: Client has connected' and after some seconds in your web browsers window you should see text of the form 't=... ch1=... ch3=...' showing the transmitted values. RemoteIO is not a real HTTP web server, so some error messages will occur, which you can safely ignore.


ServerExample.mdl and ClientExample.mdl

These two Simulink models show server and client communication using TCP/IP. The two Simulink models must run in two different instances of Matlab on the same computer, with ServerExample started first. ClientExample will generate a ramp function and sent it to the server, where the received values will be displayed in an oscilloscope. The server will square the received value and sent back the ramp data and the squared value to the client, where these values will be displayed in another oscilloscope. The client can be arbitrarily stopped and restarted, as long as the server is running.


Matlab / Simulink V6 (R12) and (R13) compatibility

IOlib was developed and tested with Matlab 5.0, 5.3, 6.1 and Simulink 2.0, 3.0 and 4.1, which were distributed as Matlab R11 and R12. Matlab 6 does run much slower than Matlab 5, due to its new Java based GUI. This might cause problems with IOlib, because IOlib heavily relies on its callback functions being processed fast enough. If IOlib crashes in Matlab 6, try to deactivate the Java GUI by starting Matlab with 'matlab -nojvm'.

The only function which is known to really cause problems with Matlab's 6 Java GUI is the IOlib function iTimer. If you want to use it, turn Java support off. If you need Java support, instead of using IOlib's iTimer function, use the Matlab timer object functions introduced with Matlab 6.5.


Matlab 7 (R14) compatibility

Depending on the Java Virtual Machine delivered with the various Matlab service packs, the problems observed with Matlab 6 have disappeared and reappeared again. These problems are related with iTimer.m and tcp.m and affect all Matlab functions using callback functions which do issue Matlab commands, especially which output text or data into the Matlab console. The callback functions seem to be called in an inappropriate context sometimes, which may cause Matlab to crash. If you need to use the Matlab related functions, consider to run Matlab without its Java GUI (start with "matlab -nojvm"). The Simulink related blocks are not affected by this problem. Your feedback on this issue is welcome, if you are willing to help on this!


Windows Vista compatibility

IOlib has not sufficiently been tested under Windows Vista yet, so your mileage may vary. Please report problems and success via email.


Release Notes

IOlib V4.0: User interface changed
The Simulink blocks RTCsim and RemoteIO have new block parameters to set the number of input and output ports. There is no longer the need to use a multiplexer at the input or a demultiplexer at the output.

IOlib V4.2: IOlib function timer changed
As Matlab 6.5 now comes with its own timer function, the IOlib function timer was renamed to iTimer. If you used the timer function in your own script files, you have to rename it to itimer. Sorry for this inconvience.

IOlib V4.3: Allow usage of RemoteIO(), iTimer() and Tcp() without CrackNT.sys
Now these functions can be used even if CrackNT.sys is not installed. Crack.dll still is needed.

IOlib V4.4: Recompiled to resolve compatibility issues with Matlab 7.0.X service packs

IOlibV4.5: New release of kernel mode driver CrackNT.sys, no change (except recompilation) in IOlib itself


Disclaimer and copyright information

All files are provided in the hope, they might be useful, but without any warranty or support. You may use them on your own risk in non-commercial applications. Even if this software is provided free of charge, it is no freeware. It is copyrighted by Werner.Zimmermann|AT|hs-esslingen.de, details see file 'Copying'. The mex-files (all DLLs) are only distributed in binary form.

If you want to use this software in commercial applications, contact the author.

In case you have problems, you may email a detailed description of the problem to Werner.Zimmermann|AT| hs-esslingen.de. But the author does not guarantee, that he will answer your mail or solve the problem.

Matlab, Simulink, Windows and other product names mentioned here may be trademarks or registered trademarks of their respective companies.