Instances Container

The Instances container (spx_core/system/instances.py) creates and manages nested components inside your model. Use it to wire multiple devices together or to reuse the same blueprint several times.

Configuration Example

YAML

instances:
  - sensor:
      type: library/temperature_sensor
      parameters:
        attributes.temperature.default: 25.0
  - controller:
      type: library/pid_controller
      parameters:
        parameters.setpoint: 80.0
  - fleet:
      type: library/device_cluster
      instances:
        - node:
            type: library/edge_node

JSON

Configuration options

Field	Description
type	Required class or template name registered in the core.
parameters	Mapping applied after instantiation. Keys can reference nested attributes (see examples).
meta_parameters	Values for template meta parameters. Useful when the template exposes $param(...) knobs (for example unit id, port, setpoint seeds).
instances	Embedded list that creates grandchildren under this instance.
(no type)	If an entry omits type, the container treats it as an update to an existing child.

Behavior details

• List or dict: You can provide a list of single-key dicts (recommended) or a plain mapping; the container normalizes the format internally.

• Limit enforcement: You can set instance_limit when creating the container programmatically to prevent runaway instantiations.

• Updates: Supplying an entry without type (only parameters) updates an existing child instead of creating a new one. This is useful for hot reconfiguration via API.

• Nested sections: Additional keys in the same mapping (after the first) are treated as sub-containers to attach under the new instance.

• Meta-parameter resolution: If meta_parameters are provided, the runtime resolves template parameters before instantiation and stores resolved values in the instance definition for observability/snapshots.

Example: updating an instance at runtime

YAML

instances:
  - sensor:
      type: library/temperature_sensor
  - sensor:
      calibration:
        offset: 0.5

JSON

The second entry finds the existing sensor child and applies the calibration block without recreating the object.

Tips for junior engineers / QA

• Start with one instance at a time; confirm it loads before adding nested devices.

• When something fails to load, check server logs—the container will raise a descriptive error if the class name is missing from the registry.

• Use meaningful names; they appear in diagnostics paths (models.plant.instances.sensor).

• Pair instances with connections to route signals between them.