Skip to main content

TaskConfiguration.json

Each CODESYS 4 application has a TaskConfiguration.json file. It is automatically added when a device project is created. This file describes the tasks which the runtime system executes, as well as the programs which are called by the individual tasks.

Important

CODESYS 4 also supports single-core controllers. The format of TaskConfiguration.json is the same as with multicore targets, but there are two restrictions:

  • Only one task group is allowed.

  • For coreConfig, only FixedPinned and 0 are allowed. FreeFloating, SequentiallyPinned, and every core index as of 1 are rejected during compile.

JSON dialect

  • Format: UTF-8

  • The key names are written in camelCase.

  • Concluding commas are allowed after the last element of an object or array.

  • Line comments with // and block comments with /* ... */ are allowed.

Top level

{ "taskGroups": [ … ], // required 
  "systemEvents": [ ], // required — must be empty 
  "v3Meta": { … } // optional 
}

Key

Type

Required

Description

taskGroups

array of Task Group

Yes

List of task groups

Array can be empty

systemEvents

array

Yes (must be empty: [])

Reserved for future support of event tasks. Currently, an error is returned for all elements.

v3Meta

object

No

Migration metadata derived from CODESYS 3-projects have been applied. Free form. Displays notifications in the application, but does not change the behavior of the task. This key should be omitted for new files.

Task group: taskGroups

A task group assigns a set of tasks to a core configuration.

{
  "groupName": "IEC-Tasks", 
  "coreConfig": "FixedPinned", 
  "tasks": { 	
      "MainTask": { … }, 
      "BackgroundTask": { … } 
}
}

Key

Type

Required

Description

groupName

string

Yes

Freely chosen display name for the group

coreConfig

string

Yes

Core configuration

For a more detailed description, see "Values for the core configuration" below.

tasks

object map (task name → task)

Yes

The keys are the task names. The tasks are processed in alphabetical order by their name, regardless of their order in the file.

. Values for the core configuration

  • "FreeFloating": All IEC tasks in the group are dynamically distributed to the processor cores by the operating system via load balancing. Under some circumstances, the tasks may frequently switch kernels. The user has no control over the assignment.

    This value is recommended for most applications because the operating system automatically handles load balancing.

  • "SequentiallyPinned": All IEC tasks in the group are permanently bound to different processor cores. If there are fewer cores than tasks, then the binding starts at core 1, continues with core 2, core 3, etc. and jumps back to core 1, core 2, etc. in case of an overflow. The user has no control over which task is bound to which core.

  • "FixedPinned": All IEC tasks in the group are permanently bound to a single processor core. The runtime system selects the core (usually core 1). If multiple task groups use FixedPinned, then each task group is bound to a different core. The assignment usually starts with core 1.

  • "0", "1", "2", ...: All IEC tasks in the group are permanently bound to the specified processor core. If the controller does not have this core, then the compile will fail with an error.

    For more information, see the following: CODESYS V3: Task Groups

Task

This is a single task. The key of the entry in the enclosing "tasks" object is the name of the task. The name must be a valid IEC identifier and unique within the configuration. The task-specific symbols are generated from it.

Example of a "tasks" object

{
 "calls": ["PLC_PRG"],
 "priority": 1,
 "type": "Cyclic",
 "interval": 200000,
 "watchdogEnable": false,
 "watchdogTime": 0,
 "watchdogSensitivity": 0
}

Key

Type

Required

Default Value

Description

calls

array of string

Yes

-

Names of the programs which are called sequentially each time the task is executed. May be empty

priority

int

Yes

-

Priority of the task. Lower values indicate a higher priority.

type

string enum

Yes

-

Cyclic or Freewheeling

For a more detailed description, see "Task types" below.

interval

int

No

0

Cycle time (in microseconds)

Relevant only for Cyclic tasks

For Freewheeling tasks, the value is set to 0.

watchdogEnable

bool

No

false

Activates the watchdog for the task

Note: The watchdog task is not yet available.

watchdogTime

int

No

0

Watchdog timeout (in microseconds)

Relevant only when watchdogEnable has the value true

watchdogSensitivity

int

No

0

Number of consecutive overflows which are tolerated before the watchdog is triggered. Relevant only when watchdogEnable has the value true

. Task types

Valid values for type

  • "Cyclic": The task runs every number of microseconds as defined in the interval key.

  • "Freewheeling": The task runs continuously and restarts as soon as the previous cycle is complete. The value in interval is ignored.

. Currently unacceptable task types

  • The following task types are currently not accepted: Event, External, and ParentSynchron

  • All task properties listed in CODESYS 3 tasks are currently not accepted, except for those listed in the "Task types" section of this help page.

Important

When comparing keys and types, case sensitivity is important.

Default values for a new application

When TaskConfiguration.json does not exist, a new application starts with the following equivalent:

{
  "taskGroups": [
    {
      "groupName": "IEC-Tasks",
      "coreConfig": "FixedPinned",
      "tasks": {
        "DefaultTask": {
          "calls": ["PLC_PRG"],
          "priority": 1,
          "type": "Cyclic",
          "interval": 200000
        }
      }
    }
  ],
  "systemEvents": []
}

Example

Below is an example of a TaskConfiguration.json file with a task group and multiple tasks:

{
  "taskGroups": [
    {
      "groupName": "IEC-Tasks",
      // "FreeFloating" | "FixedPinned" | "SequentiallyPinned"
      // or a quoted core index, e.g. "0"
      "coreConfig": "FixedPinned",
      // Tasks run in alphabetical order of their key — not file order.
      "tasks": {
        "MainTask": {
          "calls": ["PLC_PRG", "MyProgram"],
          "priority": 1,
          "type": "Cyclic",
          "interval": 200000,        // microseconds
          "watchdogEnable": true,
          "watchdogTime": 1000000,   // microseconds
          "watchdogSensitivity": 1
        },
        "BackgroundTask": {
          "calls": ["Diagnostics"],
          "priority": 15,
          "type": "Freewheeling"
          // interval is ignored for Freewheeling tasks
        }
      }
    }
  ],
  // Must be present, must be empty (events are not yet supported).
  "systemEvents": []
}
In this section: