GRID Package

What a GRID package holds, how the controller serves it to your browser, and how its model JSON moves a 3D model from live parameters.

4 minute read

A GRID package holds the graphical user interface of your machine. You deploy it to the controller, which serves it to your browser, so you open the interface in a browser without installing anything.

What a GRID package holds

At its centre are one or more .grid files, made in Motorcortex Grid. Each file describes screens full of widgets, and a widget that shows a picture, a 3D model or a program names the file it uses by its path in the package, for example img/warning.png or 3d/robot.json. The resources sit in folders next to the .grid files.

Folder	What goes in it	Used by
`img/`	Logos and pictures	The `Image` widget
`3d/`	`.glb` models and the model JSON that moves them	The `3D` widget, through its `model` property
`programs/`	`.prog` motion programs	The `Program` widget, which also saves programs here
`errors/`	`errors.json` with the error codes, `definitions/` with one help page per error	The error handler in the properties panel
`config/`	`states.json` with the state names, and value maps such as `modes.json`	The states setting, and widgets with a `map` property

A typical package looks like this:

├── gui_operator.grid         # interface for the operator
├── gui_maintenance.grid      # interface for the maintenance crew
├── 3d
│   ├── robot.glb             # 3D model in a GLTF binary file
│   └── robot.json            # model JSON: settings and parameter links
├── config
│   └── states.json           # state numbers mapped to names
├── errors
│   ├── errors.json           # error codes mapped to names
│   └── definitions           # one HTML help page per error
├── img
│   └── mylogo.svg            # an image
└── programs                  # motion programs

The folder names are a convention, not a rule: a widget accepts any path inside the package. The robot interface that ships with the robot application, for instance, also keeps value maps for its safety screens in a safety/ folder.

When you deploy the package, the controller unpacks it into its own folder under /var/www/motorcortex/grid/projects/, next to the packages you deployed before. See File locations for the rest of the controller’s folders.

3D models

Put your GLTF files (.glb or .gltf) in the 3d/ folder, or in a subfolder of it. How to prepare a model so its parts can move is described in 3D models.

model.json

Next to the model goes a model JSON file. It loads one or more model files, sets properties of the objects in them, and links object properties to Motorcortex parameters. You can give it any name; in the stock robot interface it is named after the model, for example 3d/MCX-Articulated-6DOF_Gripper-R01.json next to 3d/MCX-Articulated-6DOF_Gripper-R01.glb. File paths inside the model JSON are relative to the folder the model JSON is in.

A link reads one element of a parameter and drives one property of one object with it:

files loads the model files into the scene.
Each entry in objects finds an object by its name. Only the first object with that name is used.
Each entry in its links subscribes to a parameter, takes element channel of it, multiplies it by gain, adds offset and writes the result to axis.

Name the model JSON <name>.3d.json, for example 3d/robot.3d.json: the portal’s file editor then checks it while you type and suggests the keys. Everything the file can do, from copies of a model and animations to lights and rendering, with every option and its default, is on 3D models. The schema is a download there too.