Mapping values to text or images

Show a name or a picture instead of a number, such as a state name or an error text, with a JSON map file in your GRID package.

  3 minute read  

Many parameters hold a number that stands for something: a state, a mode, an error code. A map file turns that number into a name the operator understands, or into a picture. You write the map once, as a JSON file in your GRID package, and select it in each widget that should use it.

How a map works

A widget with a map looks up the parameter’s value in the file and shows the name it finds. A Dropdown works the other way round as well: it lists every name in the map, and when you pick one it writes that name’s number to the parameter.

Parameter Map file Widget root/Logic/state 4 config/states.json config/states.json "3": "Paused", "4": "Engaged", "5": "Homing", Output Output Engaged 4 name …/homing/homingMethod 1 config/homing_modes.json config/homing_modes.json "0": "By-Pass", "1": "Direct Reference", "2": "Move till Trigger", Dropdown Dropdown Direct Reference ▾ pick 1 The Output looks the number up; the Dropdown lists every name and writes the number of the one you pick.

Maps work in these places:

Where What it maps
Output widget, map property The value to a name
Dropdown widget, map property The names to choose from, and the number each one writes
Image widget, map property The value to an image file
Error codes in the Errors settings Error numbers to error names
state codes in the States settings State numbers to state names

Create a map file

  1. In your GRID package on motorcortex.io, create a file with the extension .json. The stock packages keep their maps in a config/ folder.
  2. Open the file and write one entry per value. The key is the number, as a string in quotes; each key appears only once. The value is the name to show.
  3. Save the file.
  4. In Grid, select the widget, click select next to its map property and pick the file.
The map property of a widget, under VALUE, with config/states.json selected and a select button

This map from a stock robot interface names the homing methods of an axis. The numbers are those of the homing block in the control library:

{
  "0": "By-Pass",
  "1": "Direct Reference",
  "2": "Move till Trigger",
  "3": "Move till no Trigger",
  "4": "Move till no Trigger, Reverse Move till Trigger",
  "5": "Move till Trigger, Reverse Move till no Trigger",
  "6": "Manual Jog till Trigger"
}

For an Image widget, each value is the path of an image in the package:

{
  "0": "img/image01.png",
  "1": "img/image02.png",
  "2": "img/image03.png"
}

Leave out the comma after the last entry: JSON does not allow it.

Use one map for many widgets

A map file is not tied to one widget. The stock robot interface shows the error code of each of its six drives with one map, config/somanet_drive_errors.json: six Output widgets use the same map, each with its own prefix, such as root/Ethercat/Robot/Axis1/, in front of the same path SDOs/Error Code.