Skip to content

Cable definition proposal #313

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
petrvanekrobe wants to merge 5 commits into
base: next
Choose a base branch
from
Open

Cable definition proposal #313

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7adb0ec
Add cable definition
petrvanekrobe Jun 18, 2026
1b9f8f7
Define Signal type definition
petrvanekrobe Jun 18, 2026
8c015a9
Add conductorAmount
petrvanekrobe Jun 19, 2026
1129c5a
Adjust Connection node
petrvanekrobe Jun 24, 2026
0ede970
Extend the cable definition to allow defining a cable in GDTF
petrvanekrobe Jun 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
180 changes: 180 additions & 0 deletions gdtf-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -311,6 +311,7 @@ For SVG files defining the `Thumbnail` view must be the view from bottom in Z di
| [Revisions](#user-content-revision-collect ) | No | Describes the history of the fixture type. |
| [FTPresets](#user-content-fixture-type-preset-collect ) | No | Is used to transfer user-defined and fixture type specific presets to other show files. |
| [Protocols](#user-content-fixture-type-preset-collect) | No | Is used to specify supported protocols. |
| [Cables](#cable-collect) | No | Contains available cable definitions for the fixture family. |


</div>
Expand Down Expand Up @@ -2484,6 +2485,185 @@ The Value of DMXPersonality corresponds to the RDM PID 0x00E0 DMX_PERSONALITY.

The DMXPersonality does not have any children.

## Cable Collect

### General

This section defines the available cables as cable assemblies.

Cable compatibility is determined by the fixture type references listed in
`CompatibleFixtureTypes`.

The cable collect does not have any XML attributes (XML node `<Cables>`). As
children, the cable collect has a list of [Cable](#node-definition-cable).

### Node Definition: Cable

This section defines a cable definition (XML node `<Cable>`). The cable
describes a complete physical cable assembly that is available for a fixture.
The defined cable node attributes are specified in [table-cable-attributes](#table-cable-attributes).

Node name: `Cable`

<div id="table-cable-attributes">

#### Table XX. *Cable Attributes*

| XML Attribute Name | Value Type | Description |
|----|----|----|
| Name | [Name](#user-content-attrtype-name ) | Unique name of the cable definition. |
| CableType | [String](#user-content-attrtype-string ) | Cable type, model, or construction. |
| LengthMin | [Float](#user-content-attrtype-float ) | Minimum supported cable length. Unit: meter. Default value: 0. |
| LengthMax | [Float](#user-content-attrtype-float ) | Maximum supported cable length. Unit: meter. Default value: 0. |
| InstallationRating | [String](#user-content-attrtype-string ) | Optional rating such as plenum, riser, outdoor, touring, or manufacturer-specific text. |

</div>

The cable node (Table XX) contains the following children.

##### Table XX — *Cable Node Children*

| Child Node | Allowed Count | Description |
| ---------------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------- |
| [Connectors](#node-definition-connectors) | 2 or any | The connector list that forms the physical cable ends and breakouts. |
| [Signal](#node-definition-signal) | 1 or any | The electrical or data signals that this cable supports. |
| [Connections](#node-definition-connections) | 1 | The internal cable graph linking connectors and signals. |
| [CompatibleFixtureTypes](#node-definition-compatiblefixturetypes) | 0 or 1 | The fixture types that can use this cable. |

### Node Definition: Connectors

This node defines the connector list of the cable. The defined Connectors node
children are specified in [table-connectors-children](#table-connectors-children).

Node name: `Connectors`

<div id="table-connectors-children"></div>

##### Table XX — *Connectors Node Children*

| Child Node | Allowed Count | Description |
| ---------------------------------------------- | ------------- | ---------------------------------------------- |
| [Connector](#node-definition-connector) | 2 or any | One physical connector used by the cable. |

### Node Definition: Connector

This node defines one connector of the cable. The defined Connector node
attributes are specified in [table-connector-attributes](#table-connector-attributes ).

Node name: `Connector`

<div id="table-connector-attributes">

#### Table XX. *Connector Attributes*

| XML Attribute Name | Value Type | Description |
|----|----|----|
| Name | [Name](#user-content-attrtype-name ) | Unique name of the connector within the cable. |
| ConnectorType | [Name](#user-content-attrtype-name ) | The connector type. See [Annex D](#user-content-table-d1 ). |
| Gender | [Enum](#user-content-attrtype-enum ) | The connector side. Defined values are "Male", "Female", "Genderless". |
| PinCount | [Int](#user-content-attrtype-int ) | Number of pins available on the connector. |

</div>

The Connector node does not have any children.

### Node Definition: CompatibleFixtureTypes

This node defines the list of fixture types that may use the cable. If this
node is omitted, the cable may be used by any fixture type. The defined
CompatibleFixtureTypes node children are specified in [table-compatiblefixturetypes-children](#table-compatiblefixturetypes-children).

Node name: `CompatibleFixtureTypes`

<div id="table-compatiblefixturetypes-children"></div>

##### Table XX — *Compatible Fixture Types Node Children*

| Child Node | Allowed Count | Description |
| ----------------------------------------------------------------- | ------------- | ------------------------------------------------- |
| [CompatibleFixtureType](#node-definition-compatiblefixturetype) | 1 or any | A fixture type that is compatible with the cable. |

### Node Definition: CompatibleFixtureType

This node defines one compatible fixture type. The defined
CompatibleFixtureType node attributes are specified in [table-compatiblefixturetype-attributes](#table-compatiblefixturetype-attributes).

Node name: `CompatibleFixtureType`

<div id="table-compatiblefixturetype-attributes">

#### Table XX. *Compatible Fixture Type Attributes*

| XML Attribute Name | Value Type | Description |
|----|----|----|
| FixtureTypeID | [GUID](#user-content-attrtype-guid ) | Unique identifier of the compatible fixture type. |
| Name | [String](#user-content-attrtype-string ) | Optional human readable name of the fixture type. |

</div>

The CompatibleFixtureType node does not have any children.

### Node Definition: Signal

This node defines the signal and conductor characteristics of a cable. The
defined Signal node attributes are specified in [table-signal-attributes](#table-signal-attributes).

Node name: `Signal`

<div id="table-signal-attributes">

#### Table XX. *Signal Attributes*

| XML Attribute Name | Value Type | Description |
|----|----|----|
| Name | [Name](#user-content-attrtype-name ) | Unique name of the signal within the cable. |
| Type | [String](#user-content-attrtype-string ) | Signal type. Predefined values are "Power", "DMX512", "Protocol", "AES", "AnalogVideo", "AnalogAudio". |
| CrossSection | [Float](#user-content-attrtype-float ) | Conductor cross-section where applicable. Unit: mm². Default value: 0. |
| ConductorAmount | [Integer](#user-content-attrtype-integer ) | Amount of conductors. Default value: 0. |
| Impedance | [Float](#user-content-attrtype-float ) | Cable impedance where applicable. Unit: Ohm. Default value: 0. |
| VoltageRating | [Float](#user-content-attrtype-float ) | Optional voltage rating. Unit: volt. Default value: 0. |
| CurrentRating | [Float](#user-content-attrtype-float ) | Optional current rating. Unit: ampere. Default value: 0. |

</div>

### Node Definition: Connections

This node defines the internal connection graph of the cable assembly. The
defined Connections node children are specified in [table-connections-children](#table-connections-children).

Node name: `Connections`

<div id="table-connections-children"></div>

##### Table XX — *Connections Node Children*

| Child Node | Allowed Count | Description |
| ------------------------------------------ | ------------- | --------------------------------------------------------------- |
| [Connection](#node-definition-connection) | 1 or any | One internal cable connection between connectors and signals. |

### Node Definition: Connection

This node defines one internal connection inside the cable assembly. The
defined Connection node attributes are specified in [table-connection-attributes](#table-connection-attributes).

Node name: `Connection`

<div id="table-connection-attributes">

#### Table XX. *Connection Attributes*

| XML Attribute Name | Value Type | Description |
|----|----|----|
| Signal | [Name](#user-content-attrtype-name ) | Name of the signal this internal connection belongs to. |
| FromConnector | [Name](#user-content-attrtype-name ) | Name of the source connector. |
| FromPin | [Int](#user-content-attrtype-int ) | Source pin number on the source connector. |
| ToConnector | [Name](#user-content-attrtype-name ) | Name of the target connector. |
| ToPin | [Int](#user-content-attrtype-int ) | Target pin number on the target connector. |

</div>

The Connection node does not have any children.

### Art-Net Section

#### General
Expand Down
93 changes: 92 additions & 1 deletion mvr-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -368,6 +368,7 @@ The child list (Table 18) contains a list of the following nodes:
| [Truss](#node-definition-truss) | A definition of a truss. |
| [VideoScreen](#node-definition-videoscreen) | A definition of a video screen. |
| [Projector](#node-definition-projector) | A definition of a projector. |
| [Cable](#node-definition-cable) | A definition of a cable. |


## Node Definition for Parametric Objects
Expand Down Expand Up @@ -813,6 +814,96 @@ EXAMPLE An example of a node definition is shown below:
</Projector>
```

### Node Definition: Cable

This node defines a cable object. Cable describes the physical realization of a
connection between two [Connection](#node-definition-connection) nodes. A cable
has one start and one end and may carry one or more signals. The defined Cable
Node Attributes are specified in Table XX.

Node name: `Cable`

Table xx - Cable Node attributes:

| Attribute Name | Value Type | Description |
| ------------------ | ----------------: | --------------------------------------------------------------------------------------- |
| uuid | [UUID](#user-content-attrtype-uuid) | Unique identifier of the cable. |
| name | [String](#user-content-attrtype-string) | Cable name. |
| cableType | [String](#user-content-attrtype-string) | Cable type, model, or construction. |
| length | [Float](#user-content-attrtype-float)| Cable length. Unit: meter. Default value: 0 |
| installationRating | [String](#user-content-attrtype-string) | Optional rating such as plenum, riser, outdoor, touring, or manufacturer-specific text. |
| GDTFSpec | [FileName](#user-content-attrtype-filename) | Optional. The name of the GDTF or `gdtt` file containing a reusable cable catalog. |
| CableName | [String](#user-content-attrtype-string) | Optional. The name of the cable definition inside the GDTF file referenced by `GDTFSpec`. |

If `GDTFSpec` is present, `CableName` shall identify a cable definition in
that file. If `GDTFSpec` is omitted, the cable remains a plain MVR cable
instance and is described only by the attributes on the scene object itself.

The child list (Table XX) contains a list of one of the following nodes. When
`GDTFSpec` is omitted, at least one `Signal` child shall be present. When
`GDTFSpec` is present, the `Signal` child list is optional because the cable
definition can be resolved from the referenced GDTF catalog entry.

##### Table xx — *Cable Node Childs*

| Child Node | Allowed Count | Description |
| ----------------------------------| --------------- | ----------------------------------- |
| [Signal](#node-definition-signal) | 1 or any / 0 or any when `GDTFSpec` is present | The type of the signal used. |

The defined Signal Node Attributes are specified in Table XX.

Table xx - Signal Node attributes:

| Attribute Name | Value Type | Description |
| -------------- | ----------------: | ------------------------------------------------------------------- |
| type | [String](#user-content-attrtype-string) | Signal type, DIN SPEC 15800 [Signal Type](https://github.com/mvrdevelopment/spec/blob/main/gdtf-spec.md#table-50-wiring-object-attributes) where possible.|
| crossSection | [Float](#user-content-attrtype-float) | Conductor cross-section where applicable. Unit: mm², Default: 0 |
| conductorAmount | [Integer](#user-content-attrtype-integer) | Amount of conductors. Default: 0 |
| impedance | [Float](#user-content-attrtype-float) | Cable impedance where applicable. Unit: Ohm, Default: 0 |
| voltageRating | [Float](#user-content-attrtype-float) | Optional voltage rating. Unit: volt, Default: 0 |
| currentRating | [Float](#user-content-attrtype-float) | Optional current rating. Unit: ampere, Default: 0 |

Example:

```xml
<Cable
uuid="7C6B12E5-0AC9-45B2-99EA-5C7C9D9F5A10"
name="Low Voltage PSU Feed 25m Hybrid"
length="25.0"
GDTFSpec="MyFixture.gdtf"
CableName="Low Voltage PSU Feed 25m Hybrid">
</Cable>

<Cable
uuid="7C6B12E5-0AC9-45B2-99EA-5C7C9D9F5A11"
name="Low Voltage PSU Feed 30m Hybrid"
cableType="Plenum rated 2x4mm2 Hybrid"
length="30.0"
installationRating="Plenum">

<Signal
type="Power"
conductorAmount="3"
crossSection="4.0"
voltageRating="60"
currentRating="12.5"/>

<Signal
type="DMX512"
conductorAmount="3"
impedance="50"/>
</Cable>
```

`Connection` with a `cable` UUID attribute linking the logical connection to its physical cable.

```xml
<Connection
own="LowVoltageOutput"
other="LowVoltageInput"
toObject="..."
cable="7C6B12E5-0AC9-45B2-99EA-5C7C9D9F5A10"/>
```

## Other Node Definition

Expand Down Expand Up @@ -1223,6 +1314,7 @@ Node name: `Connection`
| own | [String](#user-content-attrtype-string) | Mandatory | Node Link to the Geometry with DIN SPEC 15800 Type [Wiring Object](https://github.com/mvrdevelopment/spec/blob/main/gdtf-spec.md#geometry-type-wiring-object) . Starting point is the Geometry Collect of the linked GDTF. |
| other | [String](#user-content-attrtype-string) | Mandatory | Node Link to the Geometry with DIN SPEC 15800 Type [Wiring Object](https://github.com/mvrdevelopment/spec/blob/main/gdtf-spec.md#geometry-type-wiring-object) . Starting point is the Geometry Collect of the linked GDTF of the object defined in `toObject`. |
| toObject | [UUID](#user-content-attrtype-uuid) | Mandatory | UUID of an other object in the scene. |
| cable | [UUID](#user-content-attrtype-uuid) | Empty String | UUID of the cable used for this connection. |

### Node Definition: Mappings

Expand Down Expand Up @@ -1811,4 +1903,3 @@ UUIDs are randomly generated numbers which are, practically speaking, unique and
One of the most important aspects of UUIDs in MVR is that they are persistent. A UUID should identify an item throughout its entire life cycle. This means that if a document is exported, then objects should have the same UUID every time an export is performed.
One use case for UUIDs is importing or merging MVRs into an existing document. This is one reason that persistent UUIDs are valuable. If you export an MVR from one program, open it in another, and make modifications, then you may want to incorporate those changes into the original document. By cross referencing UUIDs, you can avoid creating duplicate objects and instead update existing ones.
UUIDs are also used inside of the MVR file format as a form of reference. For example, a symbol instance shall refer to a symbol definition. Because the symbol definition is given a UUID, the symbol instance can reference its symbol through the use of this UUID.