Example: First Steps

Preparatory work

Create a new CODESYS project from the Standard project with Application Composer template. Select AC_ModuleBase as the library.

The top-level module Room

Add a new module declaration to the POU pool of the project. Assign the name Room to the module declaration and the associated function block. The function block must also extend the AC.Module function block which is defined in the AC_ModuleBase library. The AC.Module function block already provides numerous methods and properties which do not have to be overwritten.

The declaration starts with the keyword MODULE followed by the module name and the additional keyword IMPLEMENTED_BY, as well as by the function block which implements the module. Specifically, this function block is the Room function block which has just been created. In most cases, the MetaData section is declared now.

For detailed information about all parameters and sections, see: Module editor.

Because the Room module is the top-level module in our example, you declare the Toplevel section next. In this section, you define a name for the global variable list which contains the instance name of the top-level function block after being generated. After that, you still need to define at least one more task in the Toplevel section. This task is Standard_Task in this example. It is defined as a MEDIUM task and contains the CREATE_IF_MISSING and UPDATE_IOS flags.

All icons and strings which are used as placeholders for the descriptions and icons (Desc, Icon_16, and Icon_32 parameters) must be referenced in text lists and image pools. Because of this, you create a corresponding text list TL and an image pool IP in the POU pool which contains the referenced icons and texts.

Submodule: Switch

Create a module declaration and a corresponding function block named Switch. This module is not a top-level module and therefore does not require a Toplevel section. Like all function blocks that represent modules, the Switch function block must also extend AC.modules. Moreover, Switch implements the ISwitch interface which you also need to create. In turn, the ISwitch interface extends AC.IModule but does not add any new methods or properties to it.

Furthermore, the switch requires an input signal in order to recognize when it is pressed. You declare this signal in the IO section, using the xIn input variable of the Switch function block. Furthermore, you need a reference time to distinguish the two functions of the switch: Pressing the switch for the time duration tTimer starts the dimming function – a shorter press only switches the light on or off. You define the input variable tTimer as a parameter of the module (Parameters section). In this way, you can easily set the time later when using the modules.

You define the variables xIn and tTimer as inputs of the Switch function block, where you set an initial value of 500ms for the tTimer parameter.

You also need to extend the text list and image pool in oder to display the descriptions.

Submodule: SwitchSimple

The second switch module which you create is a simple switch with only two states: on and off. To do this, you need to create a module declaration and a function block which differ from the existing switch only in the following points: the parameter and the tTimer variable are not required. In addition, you do not implement ISwitch but ISwitchSimple, which also extends AC.IModule.

Submodule: Light

As before for the switches, for the light you also need to create a module declaration Light with the Light function block and ILight interface.

To insert the Light module below a room, you need to add the Slots section to the Light module declaration. In this section, you declare a subsection Slot_Multi, which you call Lights and which can hold the modules of type ILight. The number of lights that must or can be added to a room is specified by Cardinality. You also define the variables Variable and Var_Count and link these to the module declaration pLights(POINTER TO ILight) and uiNumberOfLights (UINT). This makes sure that only modules whose function blocks implement the ILight interface can be added to the Lights slot.

With the Light module, you also define a slot where a switch can be inserted. Therefore, you need to add a Switch slot to the Light module declaration. Additional parameters of the Light module are the speed of the dimmer rSpeed and the maximum brightness uiMaxValue. Finally, you need to define an output which represents the brightness of the light. You need to add all parameters, slots, and outputs, as well as variables for the Light function block.

Submodule: LightSimple

The last module you create is a simplified light which works with the simple switch. To do this, you need a module declaration and a LightSimple function block which extends AC.Module and implements the existing ILight interface. The differences from the Light module are as follows: the output should be of type BOOL and have the name xSwitchedOn. In addition, the rSpeed parameter is not required.

Implementation

For the implementation of the function for the Switch module, use the CallPrioMediumStart method from AC.Module and override it with its own implementation. This function is selected because the Room top-level module declares a MEDIUM task. This means that the CallPrioMediumStart method of the Switch function block is automatically called in every cycle of the task. However, the main feature of the switch is differentiating between switching on/off and dimming. After pressing the switch, a timer starts with a time which can preset with user parameters. When the timer has elapsed and the switch is still pressed, the dimmer function is applied, which is represented by the variable xPushLong. The variable xPush is TRUE when the switch is pressed only for a short time. For both variables xPushLong and xPush, properties are added in both the Switch function block and the interface so that they can be used from the parent light function block.

Also the Light function block overrides the CallPrioMediumStart method. Depending on the value of the respective input variables, the light is either dimmed or simply switched on/off. For the dimmer, the speed value of the declared parameter rSpeed is used. After the maximum or minimum dim value has been reached, the dimming is stopped. If the light is in a dimmed state and the switch is pressed, then the light is switched on.

You can see a possible implementation in the sample project.

Engineering

You create the module tree in the Modules view. To do this, first add the Room top-level module to the module tree after the modules have been imported. In the Lights slot, add one Light and one LightSimple. To each of these, assign a Switch or a SwitchSimple. Then you can set the parameters and I/Os of the module instances. For testing purposes, it is advisable to link the inputs and outputs to variables in a global variable list.

Finally, use the Composer → Create command to create the project. After downloading to a device, you can test the example however you want. You can also vary the layout of the room without having to modify the code or the modules. You can also modify the values of the module instance parameters and check their effects. The parameter values can be changed both offline and online.