A basic custom module

As far as a module is concerned, the MatPLC is a library. It provides various functions, of which only about five or seven are the most important. The others provide things like retrieving values from the config file - useful, but not vital.

Usual usage

Classical scan

This is the template for a classical-scan module:

#include <plc.h>

int main(int argc,char *argv[])
{
  plc_init("modulename",argc,argv);

  /* initialization goes here */

  while (1) {
    plc_scan_beg();
    plc_update();

    /* body of loop goes here */

    plc_update();
    plc_scan_end();
  }
}

Data interface

One advantage is that the module doesn't need to keep track of which points are read-only and which are read-write in the MatPLC; in the first half, all points may be written, and in the second half all points may be read. The plc_update() discards values for which the module lacks write permission.

This is the template for a data-interface module:

#include <plc.h>

int main(int argc,char *argv[])
{
  plc_init("modulename",argc,argv);

  /* initialization goes here */

  while (1) {
    plc_scan_beg();

    /* process data going to MatPLC from the "other" */

    plc_update();

    /* process data coming from MatPLC to the "other" */

    plc_scan_end();
  }
}

Filling in the template

Initialization

One of the main things you need to do here is to get handles to all the points your program will access.
foo = plc_pt_by_name("foo");
bar = plc_pt_by_name("bar");

foo and bar should be declared as variables of type plc_pt_t. If you want to be safe, you should also check that foo.valid and bar.valid are non-zero after the above initialization.

Throughout the rest of the program, you will then use the variables foo and bar to refer to those two points.

Body of loop

The two most important functions here:

plc_get(point)

read point

plc_set(point,value)

write the value to the point

These are used both for coils and for integer registers. When used for coils, 0 means OFF and 1 means ON.

When used for registers, value is treated as unsigned 32-bit integer (MAT defines the type u32 for this purpose). Narrower points can also be treated as unsigned integers - for instance, a plc_get() on an 8-bit point will return a number between 0 and 255.

As usual with PLC-style logic, points are read from outside the module at the top of the loop and written to the outside at the bottom (that's what the plc_update() does). Last value written wins.

Remember that for plc_set(), the module needs point ownership in the matplc.conf file. There is no warning if you try to write to a point you don't own; the changes are simply discarded and the point value remains unchanged.

Processing data going to/from MatPLC

Other than this separation, the previous section applies.

Summary of the basic functions

The five most important functions are:

plc_init(module_name,argc,argv)

Initializes the library. The module_name should be a string. If argc and argv are not available, pass 0 and NULL instead.

pt_handle = plc_pt_by_name(pt_name)

Obtains a handle to a MatPLC point, required for the plc_get() and plc_set() functions. The pt_name should be a string, while pt_handle should be of type plc_pt_t. The success or failure of this function is indicated by pt_handle.valid; non-zero means OK. This function, like plc_init(), should be called before the time-critical part begins.

plc_update()

Updates the local (buffered) copy of all the MatPLC points. It should be called before reading MatPLC points or after writing them. If the module runs in a repeated "scan", this function will usually be called once at the beginning of the scan, and once at the end.

value = plc_get(pt_handle)

Reads a MatPLC point (as it was at the time of the last plc_update(), or as changed by this module), returning it as an unsigned 32-bit integer. A 32-bit float version of this function is also available.

plc_set(pt_handle, new_value)

Writes an unsigned 32-bit integer to a MatPLC point. A 32-bit float version of this function is also available. The write will not be seen by the other MatPLC modules until plc_update() is called.

The two additional functions should be used if the module runs in a repeated scan, like a traditional PLC. They enable the MatPLC to enforce execution periods, sequencing of modules, RUN/STOP modes and the like. They take no arguments.

plc_scan_beg()

Beginning of scan. This should precede the plc_update() call, as shown in the templates.

plc_scan_end()

End of scan. This should follow the plc_update() call, as shown in the templates.

These functions are explained in more detail in the general reference and GMM reference chapters.

Other functions

As noted, there are floating-point equivalents to plc_get() and plc_set(); they are called plc_get_f32() and plc_set_f32(), work with the type f32 instead of u32, but otherwise behave exactly like the integer versions.

Notes

$Date: 2005/05/15 09:37:00 $