user/parameters.json

Add your own parameters to the parameter tree, without recompiling the application.

5 minute read

user/parameters.json adds your own parameters to the parameter tree, under root/UserParameters/. Use them for what the application does not have yet: an I/O channel of your own, a value a dashboard needs, or data another program writes in, such as coordinates from a vision system.

The application reads the file named in config.json:

"Path": {
  "UserParameters": "user/parameters.json"
}

All options at a glance

An entry with Children is a branch, a folder in the tree. An entry with a Type is a parameter.

The Type string

Type says what the parameter holds and how it behaves, in one string:

Some examples:

`Type`	Creates	Typical use
`bool,input`	One true/false value that a link or a program writes	A button on an I/O module
`bool`	One true/false value you can switch; `parameter_volatile` by default	A lamp you turn on from Desk
`double[6],input`	Six decimal numbers	A pose sent by a vision system
`int32[3],parameter`	Three whole numbers, kept when you save from Desk	Settings you tune once
`uint8,parameter_persistent`	One whole number from 0 to 255, kept automatically	A selected mode that must survive a restart
`char[20],parameter_volatile`	Text of up to 20 characters	A product name shown on a dashboard

Details

Parameter types

The parameter type decides how the parameter can be linked, and whether its value is kept.

Type	In a link	Kept after a restart	Use it for
`input`	destination only	no	Values coming in: an I/O input, data from another program
`output`	source only	no	Values the application produces for others to read
`parameter`	source and destination	yes, when you save from Desk (in `control.xml`)	Settings you tune and keep
`parameter_volatile`	source and destination	no	Settings and outputs you switch while running. The default.
`parameter_persistent`	source and destination	yes, automatically (in the persistence file)	Values that must survive a restart without saving, such as a counter

A link runs from a source to a destination, so an I/O input channel needs an input parameter, and an output channel is fed from a parameter you can write, such as parameter_volatile.

Start values

Warning

A Value is written at every start, after the values saved from Desk are loaded, so it replaces a saved value. Leave Value out for a parameter whose saved value you want to keep.

Without a Value a number starts at 0.
Arrays take a list: "Value": [1.34, 2.23, 3.57]. A shorter list fills the array from the first element; a longer one is cut off.
Text (char or string) takes a string, and the length is its number of characters: "Type": "char[11]" with "Value": "Hello world".
Force: true locks the start value, so nothing can change it while the application runs.
Enable: false leaves the parameter out of the tree altogether.

A complete file

{
  "Version": "1.0",
  "Children": [
    {
      "Name": "IO",
      "Children": [
        { "Name": "Gripper1", "Type": "int32[1],parameter_volatile", "Value": 0 },
        { "Name": "Gripper2", "Type": "int32[1],parameter_volatile", "Value": 1 }
      ]
    },
    {
      "Name": "Branch2",
      "Children": [
        { "Name": "branch2Param1", "Type": "int32[3],input", "Value": [2, 3, 4] },
        { "Name": "branch2Param2", "Type": "int32[3],input" },
        {
          "Name": "subbranch1",
          "Children": [
            { "Name": "branch2subbranch1Param1", "Type": "char[11],parameter_volatile", "Value": "Hello world" },
            { "Name": "branch2subbranch1Param2", "Type": "int,parameter_volatile", "Value": 123 }
          ]
        }
      ]
    },
    { "Name": "moduleParam1", "Type": "double[6],input", "Value": [1.34, 2.23, 3.5675, 4.0034, 5.5677, 6.2345] },
    { "Name": "moduleParam2", "Type": "bool,input" }
  ]
}

In Desk this file gives the tree below. branch2Param2 has no Value, so its three elements start at 0:

The example in the parameter tree: UserParameters with the branches Branch2 (branch2Param1 with 2, 3, 4; branch2Param2 with 0, 0, 0; subbranch1 with Hello world and 123) and IO, and moduleParam1 with six values and moduleParam2

Using user parameters

Link them to other parameters in the link files, or to the channels of an I/O device.
Read and write them in Motorcortex Desk, on a dashboard, or from your own program through a Motorcortex client library.