Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 36 ยท Data Types and Arrays

Clusters and Type Definitions

Group related data into LabVIEW clusters with Bundle and Unbundle by Name, understand cluster order, and keep data consistent with type definitions.

An array holds many values of one type. A cluster holds values of different types in one bundle, like a record or a struct. Clusters keep wires tidy: one wire instead of eight, one connector terminal instead of a dozen. This lesson covers clusters, their functions, and type definitions, which keep a shared cluster (or enum) consistent. LabVIEW cannot run here, so the examples are JavaScript stand-ins, not LabVIEW output.

What a cluster is

A cluster is a fixed collection of elements, each of which can be any type except another non-cluster container with unequal types; you can nest clusters inside clusters, and arrays inside clusters, but an array's elements must be the same type (so an array of clusters is fine).

On the front panel, place a Cluster shell from Controls > Modern > Array, Matrix & Cluster, and drop controls into it. Every element must be either all controls or all indicators within one cluster. The wire is brown if all elements are numeric, and pink otherwise, with a thick patterned look.

Example: a Test Settings cluster holding Sample Rate (Hz) (DBL), Channel (string), Averaging On? (Boolean) and Mode (enum).

Cluster order

Elements have a cluster order, shown by right-click > Reorder Controls In Cluster. Order is the number assigned to each element, starting from 0 (not their visual position). It matters when you use Bundle and Unbundle by position, or compare clusters, or wire two clusters of the same type. Two clusters match only if they have the same number of elements with the same types in the same order. Reordering a cluster can silently break wires that use order, which is why you use names (below).

Bundle and Unbundle

In Programming > Cluster, Class & Variant:

  • Bundle builds a cluster from separate values. Wire its inputs in cluster order. Wire an existing cluster to the middle terminal to modify just some elements and keep the others.
  • Unbundle splits a cluster into its elements, by order.
  • Bundle By Name and Unbundle By Name use element labels instead of order. You can choose which elements to show. They fail safely if a label is missing and are the recommended choice, because reordering does not break them.

Pattern for an update: a shift register carries a cluster; inside the loop, Unbundle By Name to read a field, then Bundle By Name (with the cluster wired through) to write back an altered field.

Array versus cluster

Array Same type, any size
Cluster Mixed types, fixed size

Arrays of clusters are common.

1 / 2

Other cluster functions

  • Cluster To Array converts a cluster whose elements are all the same type (for example all DBL) into an array.
  • Array To Cluster does the reverse; you must set the cluster size by right-click.
  • Build Cluster Array collects clusters into an array.
  • Cluster To Variant and Variant To Data, for flexible data exchange, covered in later work.

Type definitions

Imagine eight VIs all using the Test Settings cluster, each with its own copy. You add a field. Now you must edit eight copies, and every wire would break. A type definition (type def) solves this: it is one master file (.ctl) that defines the control's type, and every instance follows the master.

To create one:

  1. Place the cluster (or enum, or any control) on a front panel.
  2. Right-click it and choose Advanced > Customize... (or Customize Control).
  3. In the Control Editor, change the Type Def. Status dropdown to Type Def. (or Strict Type Def.).
  4. Save as Test Settings.ctl in your project, and use it everywhere.

When you edit the master, every instance updates after the next save. Wires that used Bundle By Name keep working when you add a field.

Type def versus strict type def

  • Type Def. keeps the data type. Instances can differ in appearance, such as size, color or default.
  • Strict Type Def. locks everything (appearance, too). Use it when the control should look identical everywhere.
  • Custom control (no type def status) is only a starting template, and instances are independent copies.

Use type defs for: clusters passed among VIs, enums (state names), and rings.

Enums as type defs

A state machine's state enum should always be a type def. Add a state, and every Case structure that uses it updates: new cases appear, and any structure without a default case flags the missing one. This is one of the best reasons to use type defs. See the later chapter on state machines in the track outline.

Clusters and errors

The error cluster is a built-in cluster of three items: status (Boolean), code (I32) and source (string). It is so important that it gets a lesson of its own: waveforms and error clusters.

Practical tips

  • Keep clusters small and cohesive. A 40-element cluster is a design smell: group related fields in nested clusters.
  • Use names that read well in Unbundle By Name: Sample Rate (Hz).
  • Do not use clusters just to avoid a connector pane; if one VI needs many unrelated inputs, split it.
  • Remember default values: right-click > Data Operations > Make Current Value Default.

Stand-in 1: Bundle and Unbundle by name

Objects model clusters. "Bundle By Name" copies a cluster and changes a field, because LabVIEW data is passed by value and the original stays unchanged.

JS Stand-in: update one field of a cluster

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in 2: the problem a type definition solves

Here "type def" means one shared schema; copies without it drift apart. We check whether each VI's cluster matches the master.

JS Stand-in: copies drift, type defs do not

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Always put type definitions in your project, under a library, and edit them there. A type def edited from an instance's front panel can surprise other VIs that use it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the difference between an array and a cluster?

    Arrays are homogeneous and resizable; clusters are heterogeneous and fixed.
  2. 2. Why prefer Bundle By Name over Bundle?

    Name-based access is robust against changes in cluster order.
  3. 3. What does a type definition do?

    Editing the master type def updates every instance.
  4. 4. Which is the best choice for a state machine's state list?

    A type-defined enum keeps every Case structure in step.

Summary

  • A cluster bundles values of different types into one wire; order is its element index.
  • Use Bundle By Name and Unbundle By Name for robust code.
  • A type definition (.ctl) is one master that all instances follow; strict type defs also lock appearance.
  • Use type defs for shared clusters and for state enums.
  • Keep clusters small and cohesive.

Next: Waveforms and Error Clusters