Frequently Asked Questions

Q. I'm new here. Where do I start?

A. Probably best to start with the draft manual Please let us know if there's anything unclear in there - the manual is intended for new users, so anything unclear is a problem we need to fix.

Q. I'm new here. How do I contribute?

A. See the Contributing to the MatPLC chapter of the manual. Initially, you should probably contribute by testing or by writing a module or two - this will help you gain familiarity with the project. Interfacing with an I/O library is one good option, as it's usually a clear objective.

Q. Has the MatPLC ever been used to control anything "real"?

A. Not yet.

One of the developers, Juan, has a physical demo accessible over the web. There is a tank with level control and a simple three-axis robotic arm, with a webcam so you can see what's happening. (The tank and the trend functions require Java; if you don't have Java, you'll only be able to play with the robot arm.)

Q. We have a super-secret algorithm in our plant. How would that work with the GPL?

A. For internal development, it doesn't matter - GPL only covers distribution. For consulting, there's a bit of asymmetry: the consultant can be subject to an NDA, but not the client.

This is because one of the purposes of the GPL is to protect the client, so the consultant is not allowed to restrict the client. There's no problem having the restriction the other way, protecting the client's IP.

Here's what the GNU FAQ has to say on the topic.

Q. What are modules?

A. Modules are individual pieces of the MatPLC. Several modules work together to provide a useful application. For instance, a Modbus module might connect with the real world, a logic module might do control logic while a HMI module interacts with the user, all within the one application. If you run the basic demo, you'll see that there are four modules: one doing the actual logic (such as it is), one handling the keyboard, one handling the screen, and one taking care of the shutdown.

See also the Module section of the manual.

Q. Does that mean we have to write modules to create an application, or do we simply use the existing modules?

A. Either. Some modules are supplied with the MatPLC, and they may be sufficient for your purposes. If they aren't, you can write your own modules. Often, you might use a mixture - most of the application being done by the off-the-shelf modules, with a couple of special functions written in C or python. We are currently working on an iec61131 IL and ST compiler. It should reach a useful stage by Q2 2003.

Q. I'm writing to a file from one of my modules; how do I protect myself from a sudden shutdown?

A. This is a multi-part question, really...

• Files are automatically closed (by Linux) when a process ends. Thus, leaving a file open is not, in itself, a problem.
• It's possible to have a function called when a process ends, using the atexit(3) function. Note that the MatPLC also takes advantage of this, so if you want your cleanup funtion to be called
  1. before the MatPLC closes down, call atexit() after the call to plcinit()
  2. after the MatPLC closes down, call atexit() before the call to plcinit().
• The functions fflush(3) and fsync(2) or fdatasync(2) may help, as may the O_SYNC flag on the open(2) call. Their limitations are listed in the relevant man pages.
• Closing and re-opening the file is possible, but not necessarily effective as a precaution against power (110V/220V) loss, since data may still be in the (Linux) cache. This is particularly easy to see with floppy disks, which are slow, noisy and smaller than the cache, so it's visible when the file is closed and - later - data is written to disk.
  • Closing and re-opening the file can be useful if another program is to re-name the file while the module is running. As long as the file remains open, the module will keep writing to it even if it is renamed or even deleted. If it is then closed and re-opened, a new file will be created with the original name.
• As far as power (110V/220V) loss is concerned, another problem is that there may also be a cache in the hard disk controller itself, and Linux may or may not be able to do anything to flush that.

1.0) Introduction 2.0) Using a Linux PC with IO modules to act as a PLC 2.1) Supported hardware 2.2) Kernel issues 2.3) Low level programming API 3.0) Programming languages for PLC 3.1) IEC 61131-3 3.1.1) Ladder logic (aka LD) 3.1.2) Instruction language (aka IL) 3.1.3) Structured language (aka ST) 3.1.4) Function Block (aka FBD) 3.2) MAT IL language 3.3) Language editors 4.0) Data acquisition 4.1) Simple historian 4.2) SCADA historian 4.3) Advanced historian 5.0) Man machine interface 5.1) Simple snapshot interface 5.2) Web interface 6.0) "Hardware discusion" 7.0) Comunications to PLC devices 7.1) Hardware communication methods 7.1.1) Serial communications 7.1.2) Ethernet communications 7.2) "Open protocols" 7.2.1) MODBUS 7.3) Proprietry procotols

Old text (mostly belongs elsewhere) The MatPLC (previously also known as the PuffinPLC) is an effort to produce a working PLC-like program runing on Linux, with a GUI for configuring and viewing its current state. The GUI will not be limited to Linux, but hopefuly also run on Windows, Web browsers, etc... We intend to take advantage of the fact that we have an underlying Operating System (OS) and therefore we will use its features to try and make the MatPLC modular, allowing for parallel code development. A running MatPLC consists of modules runing in an infinite loop, and accessing the common MatPLC memory/state. The common MatPLC memory/state is limited to points that can be from 0 to 32 bits wide. One module could be a PID loop, using two points for its input, and a third point for its output. Another possible module could be a plc5 emulator, that executes plc5 code, but using MatPLC points as its variables. Yet another possible module would be an I/O board driver, that would copy the state of some MatPLC points to its outputs, and copy the state of its inputs to other MatPLC points. As already stated, taking advantage of the underlying OS, each module will run as an independent process. This means that each module can be developed independently of each other, in whatever programming language the coder chooses. Access to the common MatPLC memory/state is done through a matplc.a library of functions, written in C, and with C header files available. The plc_set() function that Jiri has just explained, falls into the group of functions that give access to this common memory/state. The matplc.a library currently also supports synchronisation between modules. For example, say we have an I/O module and a PID module running. For the PID module to produce correct results, it must run in lock-step with the I/O module. With the synchronisation between modules, we can guarantee that the PID and I/O modules will run their scanning loops intermingled (i.e. I/O - PID - I/O - PID - ...). This is achieved without any explicit programming effort on the part of the module programmer, other than calling a specific plc funtion at the begining of the scan, and another at the end. Although not yet implemented, we intend to support online changes to the PLC, such as adding a module, removing a module, replacing a module (and guaranteeing that the new module will only start executing once the module being replaced has finished its scan), etc... This has not yet been completely thought out, so the supported semantics may change compared to what I have described. As you may have already noticed, for the MatPLC to work it requires common resources so the modules/processes can communicate and synchronise between them. This is done using shared memmory and semaphores. The use of these IPC (inter-process communication) mechanisms is hidden from the module coders by the matplc.a library. The shared memories and semaphores need to be setup before any module can start executing. This is done by the matplc utility (previously named smm-mgr) with the -g parameter. To shutdown the MatPLC (i.e. delete the common shared memmory and semaphore resources) use the -s parameter. If you want to exercise the MatPLC at a very low level, you may use the plctest utility. The structure of the cvs server: /doc Documentation directory including a main page, this FAQ and other information. /doc/ape an empty directory /doc/hwcompat hardware compatibility /doc/images general usage images /doc/manual manufal pages for users and developers /doc/smm a basic tutorial on the core memory /doc/talks talks given by project developers /demo Demo programs. See the demo section of the manual. /tools the main location for executable, library and configuration files. /tools/run global executable files /tools/lib LPC library files /tools/config configuration files /lib This is where the matplc.a library and source code reside. Please read the README and check the header files to better understand this code. /lib/cmm The configuration memory manager library /lib/conffile The configuration file parse library /lib/gmm The global memory manager library (a description and a tutorial are available) /lib/gnu /lib/io /lib/log The common logging services library /lib/logic /lib/lpc /lib/misc Miscelaneous libraries used without the other libraries (shared memory, internet sockets, semaphores, string handling, data structures, ...) /lib/period /lib/smm /lib/synch The synchronisation library /lib/util Old location of the smm-mgr and plctest utilities, now in /tools/run. Still contains their source code. /logic logic interpreters and compilers /logic/classicladder a GUI based ladder logic editing, simulation and execution /logic/dsp A digital signal processing module. Currently I only have the main framework implemented, and a very basic PID function. Hoping other more PID knowlegeable people are willing to help me out with this. I have some well defined header files you can write standard C (OS independent code) for this. Please email me if you are willing to help out. /logic/iec the begining of an IEC61131 compiler (not fully functional) /logic/il A basic instruction language compiler, that generates a MatPLC module. Written in perl. A language manual is available. /logic/ladder_lib LPC ladder logic engine library /logic/plc5 a PLC5 ladder logic engine /mmi man-machine interface utilities /mmi/curses basic ASCII screen interface also known as the vitrine. /mmi/curses_lib LPC library for the curses interface /mmi/hmi_gtk a GTK basic GUI /mmi/kbd low level keyboard interface /mmi/kbd_lib LPC library for kbd /mmi/tcl a TCL GUI /drivers kernel level dirvers for various devices /drivers/8255 a basic parallel IO chip found on many digital IO boards /drivers/modbus a sensor networking network /comm/plc_parport parallel port driver /io drivers for basic IO (point oriented) hardware /io/cif drivers for a variety of sensor networks; devicenet, profibus, etc. /io/das08 a basic IO board with digital, analog and counter IO /io/das08_lib LPC library for the DAS08 card /io/logger a logger for basic PLC events /io/modbus modbus drivers /io/parport parallel port IO /io/simple-udp network based communication to point IO /comm This directory contins drivers oriented to data communication (not to be confused with point oriented IO). /comm/network_io basic wrappers for tcp/ip networking /comm/rs232c_lib lpc library for serial interfacing /comm/tcpip_lib lpc library for network interfacing /service communication based services /service/email_lib LPC library for sending email /service/matd_lib LPC library for a network interface accessible via telnet /lang code for using other languages /lang/python a powerful scripting language /lang/tcl a graphics oriented language language /scada tools for remotely monitoring controllers /scada/visualview a python based tool /hardware This directory contains designs for actual (open source) hardware /hardware/dio a digital IO board with optoisolation 1.0) Introduction 2.0) Using a Linux PC with IO modules to act as a PLC 2.1) Supported hardware 2.2) Kernel issues 2.3) Low level programming API The global map is the common data area for the MatPLC. It contains all of the data that is used by all parts of the MatPLC, including physical I/O, internal coils, and any data to be shared between modules. This is how data is shared between logic engines, IO, HMI modules, debugging tools, etc. Each module, upon being started, is given a private copy of the global memory map. All functions performed by a module are done to this private memory map which is then synchronized back to the global memory map through a function call in the MatPLC library. This synchronization is semaphore controlled, which provides atomic updates. When run with a single logic engine, this allows the MatPLC to mimic the behaviour of a traditional PLC. The library contains various functions for access to the private and global memory maps, a few of which are listed on the right. Consult the detailed description and the tutorial for more details. plc_init() Connect to PLC plc_done() Disconnect from PLC plc_pt_by_name() Obtain point handle plc_get() Read a value from a point plc_set() Write a value to a point plc_update() Sync PLC memory maps 3.0) Programming languages for PLC 3.1) IEC 61131-3 In the MatPLC CVS tree under the /logic/iec directory is the first workings of a program to translate IEC 61131-3 Instruction list (IL) and Structured Text (ST) files into a form that can be integrated with MatPLC. The code at this stage is strictly "under-development", there is no guarantee that even simple programs will even translate, let alone generate correct code. For more info on the IEC 61131-3 standard you could check ftp://ftp.cle.ab.com/stds/iec/sc65bwg7tf3/document/ for an old draft when they last revised the standard (eg: use this at your own risk). 3.1.1) Ladder logic (aka LD) 3.1.2) Instruction List language (aka IL) Work in progress 3.1.3) Structured Text language (aka ST) Work in progress 3.1.4) Function Block (aka FBD) 3.2) MAT IL language This is a simple Instruction List style language. The program is written in a plain text file with the extension .il and compiled into a full-fledged MatPLC module. As the language is compiled rather than interpreted, execution is very efficient. The language is described in a language manual. LD X001 AND Y002 LD X002 ANI Y001 ORB OUT Y004 3.3) Language editors 4.0) Data acquisition (data historian) 4.1) Simple historian ("snapshots") 4.2) SCADA historian (snapshots, averages, archiving) 4.3) Advanced historian (above + MMI + trending +...+) 5.0) Man machine interface 5.1) Simple snapshot interface 5.2) Web interface 6.0) "Hardware discusion" 7.0) Comunications to PLC devices This section covers as many aspects as possible when attempting to communicate to a PLC device. A quick bit of network theory is required first before we launch into the discussion. The ISO/OSI model of a network is as follows: Layer Description FAQ Section Physical Transmits and receives bits over the physical media Hardware Data link Adds error-checking information and organizes bits into frames Hardware Network Handles internetwork sequencing, addressing and routing Hardware Transport Adds identifiers to processes and deals with error-handling information Protocol Session Sets up and tears down connections or sessions. Administers sessions. Protocol Presentation Translates data formats and adds encryption User Interface Application Provides services that directly support user applications User Interface 7.1) Hardware communication methods 7.1.1) Serial communications 7.1.2) Ethernet communications 7.2) "Open Protocols" This section is dedicated to various protocols which are widely used and the specifications are available in the public domain. This does not mean the protocol is not "proprietry" (the copyright is still held by a company, consortium or standards body), it just means that a web search or literature search in a library (*gasp*, yes, paper books) you will find the definition of the protocol. 7.2.1) MODBUS Wayne Johnston wrote: Anyone interested in Modbus can find specifications at http://www.modicon.com/techpubs/TechPubNew/index.html. The serial protocols are described in http://www.modicon.com/techpubs/TechPubNew/PI_MBUS_300.pdf The Modbus/TCP protocol is described in http://www.modicon.com/openmbus/ BTW: there are two serial protocols called ASCII and RTU. They differ only at what you might call the data link layer. The higher layers are the same. (Though you won't find any description of layers in the protocol specification, it can be implemented as a layered protocol.) ASCII is easier to implement, but RTU is about twice as efficient. As a result most low bandwidth applications use the RTU protocol. I'd recommend implementing both, but if you have to choose, pick the RTU protocol. 7.3) Proprietry procotols $Date: 2006/05/13 05:23:29 $