linking/*.link.json

Link parameters to each other and set start-up values, per system mode, with the link files of a configuration package.

  8 minute read  

A configuration package keeps its link files in the linking/ folder. Each file sets up the parameters and links for one part of the application.

Which files are loaded

The application only reads a link file that config.json names. It does not scan the folder, so a file that is not named, or that belongs to a disabled feature, is never loaded.

config.json linking/ "Path": { "Linking": [ "linking/base.link.json", "linking/referencing.link.json" ] } always loaded "ManipulatorControl" "Enable": true "Joystick" "Enable": false …and 10 more features "Enable": false base.link.json ✓ referencing.link.json ✓ manipulator-control.link.json ✓ joystick.link.json ✗ 10 more files ✗
  • Always loaded: the files listed under "Path": { "Linking": [...] }. In the standard robot configuration these are base.link.json and referencing.link.json.
  • Per feature: each feature names its own file in its Linking key. The file only loads when the feature is enabled.
"Path": {
  "Linking": ["linking/base.link.json", "linking/referencing.link.json"]
},
"ManipulatorControl": {
  "Enable": true,
  "Linking": "linking/manipulator-control.link.json"
}
All fourteen link files of the standard robot configuration
File Loaded by
base.link.json Path (always)
referencing.link.json Path (always)
manipulator-control.link.json ManipulatorControl
machine-control.link.json MachineControl
agv-control.link.json AGVControl
motion-player.link.json MotionPlayer
safety-selector.link.json SafetyChannelSelector
joystick.link.json Joystick
space-nav.link.json SpaceNav
collision-detector.link.json CollisionDetector
setpoint-generator.link.json SetpointGenerator
signal-generator.link.json SignalGenerator
force-dimension.link.json ForceDimension: named, but the current application does not load it
weaving-motion.link.json WeavingMotion

A link file does two things when the application starts:

  • Links connect a source parameter to a destination parameter. From then on the destination follows the source every cycle, also across tasks.
  • SetParameters write a value to a parameter once, or lock it there.

Both are organised in groups, and each group can be limited to one system modeThe system mode is set with "Mode" in config.json: Production runs on the real hardware, Simulation runs without it. A group with "SystemMode": "All" applies in both. . At start-up the application applies the groups that match its mode and skips the rest. Here is what that does with three groups of the standard base.link.json, in production mode:

config.json"Mode": "Production" base.link.json Parameter tree at start-up Drive Mode All SetParameters ✓ applies writes once Window Detectors and Actuator Control Loops All Links ✓ applies links Simulation Simulation SetParameters ✗ skipped not applied DriveLogic/driveMode = 8 8 8 8 8 8 DriveLogic/driveOpMode → …/actuatorControlLoop%02d/driveMode …/EL6910-01/Outputs/oSTONotActive stays as it was In simulation the Simulation group applies too, and writes true to oSTONotActive.

All options at a glance

These are all the options a link file accepts, with their defaults. Click a card to open its tab below.

Go to Groups Group one item of the file's Groups [ ] list Name optional SystemMode All Production · Simulation Enable true and two lists of items: Go to Links Links [ ] each is a Link Source required Path · Index · Length Destination required Path · Index · Length Gain 1.0 Offset 0.0 Invert false Enable true Go to SetParameters SetParameters [ ] each is a SetParameter Path required Value required number, true/false or list Force false Enable true Index 0 only with %02d Length all only with %02d

To have your editor check a link file as you type, point it at the JSON schema linking.schema.v4.json.

This example combines two entries from the standard robot configuration’s base.link.json. It sets the drive mode of all axes, and passes the mode on to each axis control loop:

{
  "Version": "1.0.0",
  "Groups": [
    {
      "Name": "Drive Mode",
      "SystemMode": "All",
      "Enable": true,
      "SetParameters": [
        {
          "Path": "root/DriveLogic/driveMode",
          "Value": [8, 8, 8, 8, 8, 8]
        }
      ]
    },
    {
      "Name": "Drive mode to the control loops",
      "SystemMode": "All",
      "Links": [
        {
          "Source": {
            "Path": "root/DriveLogic/driveOpMode"
          },
          "Destination": {
            "Path": "root/AxesControl/actuatorControlLoops/actuatorControlLoop%02d/driveMode",
            "Index": 1
          }
        }
      ]
    }
  ]
}

Start with Groups: links and SetParameters always sit inside a group.


Groups

Field What it does Default
Name A name for the group, used in log messages. none
SystemMode When the group applies; see below. All
Enable false skips the whole group. true
Links The group’s links. none
SetParameters The group’s start-up values. none

Version at the top of the file is for the schema; the application does not read it.

SystemMode

The system mode in config.json decides which groups apply:

Application mode Groups that apply
Production All and Production
Simulation All and Simulation

Use a Simulation group for what has no hardware behind it in simulation, such as a safety output; see the SetParameters example below.


Source OUTPUT or PARAMETER Path · Index · Length Destination INPUT or PARAMETER Path · Index · Length × Gain + Offset or Invert for true/false Converted to the destination type every cycle, and clamped to its range. One source can feed many destinations; a destination takes one source.
Field What it does Default
Source Where the value comes from: an OUTPUT or a PARAMETER. required
Destination Where it goes: an INPUT or a PARAMETER. required
Gain The source is multiplied by this. 1.0
Offset Added after the gain. 0.0
Invert For a true/false destination: flips the value. false
Enable false skips this link. true

Source and Destination each take:

Field What it does Default
Path The parameter, for example root/DriveLogic/driveOpMode. required
Index The first array element to use; 0 is the first. 0
Length How many elements to use. all

The two ends do not need the same data type. The destination receives source × Gain + Offset, converted to its own type and clamped to that type’s range. A true/false destination becomes true when the source is not zero. A link copies as many elements as both ends have room for.

A source can feed any number of destinations, but give each destination one source. With two, the application warns and the destination takes whichever was written last.

This link from the standard joystick.link.json takes element 1 of the joystick’s axes, flips its sign, and writes it to element 0 of the AGV’s target velocity. Gain sits next to Source and Destination, not inside them:

{
  "Source": {
    "Path": "root/Joysticks/Joystick01/axes",
    "Index": 1,
    "Length": 1
  },
  "Destination": {
    "Path": "root/AGVControl/hidInTargetVelocity",
    "Index": 0
  },
  "Gain": -1
}
See a link in action

Many parameters come in numbered sets, such as actuatorControlLoop01 to actuatorControlLoop06. Instead of writing one link per member, put a number pattern in the path. %02d stands for a two-digit number with a leading zero: 01, 02, 03 and so on.

The entry then becomes one link per member. Element 0 of the source goes to the first number, element 1 to the next, and so on. The first number is the Index of the end that has the pattern.

In the example file at the top of this page, the destination has the pattern and "Index": 1, so the six elements of driveOpMode go to control loops 01 to 06:

Source: one array Destination: %02d, Index 1 root/DriveLogic/driveOpMode …/actuatorControlLoop%02d/driveMode [0] …/actuatorControlLoop01/driveMode [1] …/actuatorControlLoop02/driveMode [2] …/actuatorControlLoop03/driveMode [3] …/actuatorControlLoop04/driveMode [4] …/actuatorControlLoop05/driveMode [5] …/actuatorControlLoop06/driveMode

The links stop at the first number whose path does not exist, or when the source has no more elements.


SetParameters

Field What it does Default
Path The parameter to write. required
Value The value: a number, true/false, or a list for an array. A shorter list fills the array from the first element. none
Force true locks the value, so nothing else can change it. false
Enable false skips this entry. true
Index, Length Only with a %02d pattern in Path: the first number and how many to write. 0, all

Without Force, the value is written once at start-up and can change afterwards. Values saved from Desk are loaded after the link files, so a saved value replaces a SetParameters value. Use Force for a value that must hold, such as a safety signal in simulation.

The standard robot configuration uses this group in simulation, where there is no safety PLC or collision hardware:

{
  "Name": "Simulation",
  "SystemMode": "Simulation",
  "Enable": true,
  "SetParameters": [
    {
      "Path": "root/Ethercat/GCC/EL6910-01/Outputs/oSTONotActive",
      "Value": true
    },
    {
      "Path": "root/CollisionDetectors/CollisionDetector%02d/collisionDetector/disable",
      "Index": 0,
      "Value": true
    }
  ]
}

The second entry uses %02d to disable every collision detector, from CollisionDetector00 up.

See SetParameters in action