Closes #20788: Cable profiles and and position mapping (#20802)

Author: jeremystretch

docs/models/dcim/cable.md

@@ -21,6 +21,21 @@ The cable's operational status. Choices include:
 * Planned
 * Decommissioning
 
+### Profile
+
+!!! note "This field was introduced in NetBox v4.5."
+
+The profile to which the cable conforms. The profile determines the mapping of termination between the two ends and enables logical tracing across complex connections, such as breakout cables. Supported profiles are listed below.
+
+* Straight (single position)
+* Straight (multi-position)
+* Shuffle (2x2 MPO8)
+* Shuffle (4x4 MPO8)
+
+A single-position cable is allowed only one termination point at each end. There is no limit to the number of terminations a multi-position cable may have. Each end of a cable must have the same number of terminations, unless connected to a pass-through port or to a circuit termination.
+
+The assignment of a cable profile is optional. If no profile is assigned, legacy tracing behavior will be preserved.
+
 ### Type
 
 The cable's physical medium or classification.

netbox/circuits/filtersets.py

@@ -346,7 +346,7 @@ class Meta:
         model = CircuitTermination
         fields = (
             'id', 'termination_id', 'term_side', 'port_speed', 'upstream_speed', 'xconnect_id', 'description',
-            'mark_connected', 'pp_info', 'cable_end',
+            'mark_connected', 'pp_info', 'cable_end', 'cable_position',
         )
 
     def search(self, queryset, name, value):

netbox/circuits/migrations/0054_cable_position.py

@@ -0,0 +1,23 @@
+import django.core.validators
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ('circuits', '0053_owner'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='circuittermination',
+            name='cable_position',
+            field=models.PositiveIntegerField(
+                blank=True,
+                null=True,
+                validators=[
+                    django.core.validators.MinValueValidator(1),
+                    django.core.validators.MaxValueValidator(1024),
+                ],
+            ),
+        ),
+    ]

netbox/dcim/api/serializers_/cables.py

@@ -25,15 +25,16 @@ class CableSerializer(PrimaryModelSerializer):
     a_terminations = GenericObjectSerializer(many=True, required=False)
     b_terminations = GenericObjectSerializer(many=True, required=False)
     status = ChoiceField(choices=LinkStatusChoices, required=False)
+    profile = ChoiceField(choices=CableProfileChoices, required=False)
     tenant = TenantSerializer(nested=True, required=False, allow_null=True)
     length_unit = ChoiceField(choices=CableLengthUnitChoices, allow_blank=True, required=False, allow_null=True)
 
     class Meta:
         model = Cable
         fields = [
-            'id', 'url', 'display_url', 'display', 'type', 'a_terminations', 'b_terminations', 'status', 'tenant',
-            'label', 'color', 'length', 'length_unit', 'description', 'owner', 'comments', 'tags', 'custom_fields',
-            'created', 'last_updated',
+            'id', 'url', 'display_url', 'display', 'type', 'a_terminations', 'b_terminations', 'status', 'profile',
+            'tenant', 'label', 'color', 'length', 'length_unit', 'description', 'owner', 'comments', 'tags',
+            'custom_fields', 'created', 'last_updated',
         ]
         brief_fields = ('id', 'url', 'display', 'label', 'description')
 
@@ -60,10 +61,12 @@ class Meta:
         model = CableTermination
         fields = [
             'id', 'url', 'display', 'cable', 'cable_end', 'termination_type', 'termination_id',
-            'termination', 'created', 'last_updated',
+            'termination', 'position', 'created', 'last_updated',
         ]
         read_only_fields = fields
-        brief_fields = ('id', 'url', 'display', 'cable', 'cable_end', 'termination_type', 'termination_id')
+        brief_fields = (
+            'id', 'url', 'display', 'cable', 'cable_end', 'position', 'termination_type', 'termination_id',
+        )
 
 
 class CablePathSerializer(serializers.ModelSerializer):

netbox/dcim/cable_profiles.py

@@ -0,0 +1,108 @@
+from django.core.exceptions import ValidationError
+from django.utils.translation import gettext_lazy as _
+
+from dcim.models import CableTermination
+
+
+class BaseCableProfile:
+    # Maximum number of terminations allowed per side
+    a_max_connections = None
+    b_max_connections = None
+
+    def clean(self, cable):
+        # Enforce maximum connection limits
+        if self.a_max_connections and len(cable.a_terminations) > self.a_max_connections:
+            raise ValidationError({
+                'a_terminations': _(
+                    'Maximum A side connections for profile {profile}: {max}'
+                ).format(
+                    profile=cable.get_profile_display(),
+                    max=self.a_max_connections,
+                )
+            })
+        if self.b_max_connections and len(cable.b_terminations) > self.b_max_connections:
+            raise ValidationError({
+                'b_terminations': _(
+                    'Maximum B side connections for profile {profile}: {max}'
+                ).format(
+                    profile=cable.get_profile_display(),
+                    max=self.b_max_connections,
+                )
+            })
+
+    def get_mapped_position(self, side, position):
+        """
+        Return the mapped position for a given cable end and position.
+
+        By default, assume all positions are symmetrical.
+        """
+        return position
+
+    def get_peer_terminations(self, terminations, position_stack):
+        local_end = terminations[0].cable_end
+        qs = CableTermination.objects.filter(
+            cable=terminations[0].cable,
+            cable_end=terminations[0].opposite_cable_end
+        )
+
+        # TODO: Optimize this to use a single query under any condition
+        if position_stack:
+            # Attempt to find a peer termination at the same position currently in the stack. Pop the stack only if
+            # we find one. Otherwise, return any peer terminations with a null position.
+            position = self.get_mapped_position(local_end, position_stack[-1][0])
+            if peers := qs.filter(position=position):
+                position_stack.pop()
+                return peers
+
+        return qs.filter(position=None)
+
+
+class StraightSingleCableProfile(BaseCableProfile):
+    a_max_connections = 1
+    b_max_connections = 1
+
+
+class StraightMultiCableProfile(BaseCableProfile):
+    a_max_connections = None
+    b_max_connections = None
+
+
+class Shuffle2x2MPO8CableProfile(BaseCableProfile):
+    a_max_connections = 8
+    b_max_connections = 8
+    _mapping = {
+        1: 1,
+        2: 2,
+        3: 5,
+        4: 6,
+        5: 3,
+        6: 4,
+        7: 7,
+        8: 8,
+    }
+
+    def get_mapped_position(self, side, position):
+        return self._mapping.get(position)
+
+
+class Shuffle4x4MPO8CableProfile(BaseCableProfile):
+    a_max_connections = 8
+    b_max_connections = 8
+    # A side to B side position mapping
+    _a_mapping = {
+        1: 1,
+        2: 3,
+        3: 5,
+        4: 7,
+        5: 2,
+        6: 4,
+        7: 6,
+        8: 8,
+    }
+    # B side to A side position mapping (reverse of _a_mapping)
+    _b_mapping = {v: k for k, v in _a_mapping.items()}
+
+    def get_mapped_position(self, side, position):
+        if side.lower() == 'b':
+            return self._b_mapping.get(position)
+        return self._a_mapping.get(position)

netbox/dcim/choices.py

@@ -1717,6 +1717,19 @@ class PortTypeChoices(ChoiceSet):
 # Cables/links
 #
 
+class CableProfileChoices(ChoiceSet):
+    STRAIGHT_SINGLE = 'straight-single'
+    STRAIGHT_MULTI = 'straight-multi'
+    SHUFFLE_2X2_MPO8 = 'shuffle-2x2-mpo8'
+    SHUFFLE_4X4_MPO8 = 'shuffle-4x4-mpo8'
+
+    CHOICES = (
+        (STRAIGHT_SINGLE, _('Straight (single position)')),
+        (STRAIGHT_MULTI, _('Straight (multi-position)')),
+        (SHUFFLE_2X2_MPO8, _('Shuffle (2x2 MPO8)')),
+        (SHUFFLE_4X4_MPO8, _('Shuffle (4x4 MPO8)')),
+    )
+
 
 class CableTypeChoices(ChoiceSet):
     # Copper - Twisted Pair (UTP/STP)

netbox/dcim/constants.py

@@ -20,6 +20,14 @@
 RACK_STARTING_UNIT_DEFAULT = 1
 
 
+#
+# Cables
+#
+
+CABLE_POSITION_MIN = 1
+CABLE_POSITION_MAX = 1024
+
+
 #
 # RearPorts
 #

netbox/dcim/filtersets.py

@@ -1699,7 +1699,7 @@ class ConsolePortFilterSet(ModularDeviceComponentFilterSet, CabledObjectFilterSe
 
     class Meta:
         model = ConsolePort
-        fields = ('id', 'name', 'label', 'speed', 'description', 'mark_connected', 'cable_end')
+        fields = ('id', 'name', 'label', 'speed', 'description', 'mark_connected', 'cable_end', 'cable_position')
 
 
 class ConsoleServerPortFilterSet(ModularDeviceComponentFilterSet, CabledObjectFilterSet, PathEndpointFilterSet):
@@ -1710,7 +1710,7 @@ class ConsoleServerPortFilterSet(ModularDeviceComponentFilterSet, CabledObjectFi
 
     class Meta:
         model = ConsoleServerPort
-        fields = ('id', 'name', 'label', 'speed', 'description', 'mark_connected', 'cable_end')
+        fields = ('id', 'name', 'label', 'speed', 'description', 'mark_connected', 'cable_end', 'cable_position')
 
 
 class PowerPortFilterSet(ModularDeviceComponentFilterSet, CabledObjectFilterSet, PathEndpointFilterSet):
@@ -1723,6 +1723,7 @@ class Meta:
         model = PowerPort
         fields = (
             'id', 'name', 'label', 'maximum_draw', 'allocated_draw', 'description', 'mark_connected', 'cable_end',
+            'cable_position',
         )
 
 
@@ -1748,6 +1749,7 @@ class Meta:
         model = PowerOutlet
         fields = (
             'id', 'name', 'status', 'label', 'feed_leg', 'description', 'color', 'mark_connected', 'cable_end',
+            'cable_position',
         )
 
 
@@ -2055,7 +2057,7 @@ class Meta:
         fields = (
             'id', 'name', 'label', 'type', 'enabled', 'mtu', 'mgmt_only', 'poe_mode', 'poe_type', 'mode', 'rf_role',
             'rf_channel', 'rf_channel_frequency', 'rf_channel_width', 'tx_power', 'description', 'mark_connected',
-            'cable_id', 'cable_end',
+            'cable_id', 'cable_end', 'cable_position',
         )
 
     def filter_virtual_chassis_member_or_master(self, queryset, name, value):
@@ -2107,6 +2109,7 @@ class Meta:
         model = FrontPort
         fields = (
             'id', 'name', 'label', 'type', 'color', 'rear_port_position', 'description', 'mark_connected', 'cable_end',
+            'cable_position',
         )
 
 
@@ -2120,6 +2123,7 @@ class Meta:
         model = RearPort
         fields = (
             'id', 'name', 'label', 'type', 'color', 'positions', 'description', 'mark_connected', 'cable_end',
+            'cable_position',
         )
 
 
@@ -2316,6 +2320,9 @@ class CableFilterSet(TenancyFilterSet, PrimaryModelFilterSet):
     status = django_filters.MultipleChoiceFilter(
         choices=LinkStatusChoices
     )
+    profile = django_filters.MultipleChoiceFilter(
+        choices=CableProfileChoices
+    )
     color = django_filters.MultipleChoiceFilter(
         choices=ColorChoices
     )
@@ -2465,7 +2472,7 @@ class CableTerminationFilterSet(ChangeLoggedModelFilterSet):
 
     class Meta:
         model = CableTermination
-        fields = ('id', 'cable', 'cable_end', 'termination_type', 'termination_id')
+        fields = ('id', 'cable', 'cable_end', 'position', 'termination_type', 'termination_id')
 
 
 class PowerPanelFilterSet(PrimaryModelFilterSet, ContactModelFilterSet):
@@ -2582,7 +2589,7 @@ class Meta:
         model = PowerFeed
         fields = (
             'id', 'name', 'status', 'type', 'supply', 'phase', 'voltage', 'amperage', 'max_utilization',
-            'available_power', 'mark_connected', 'cable_end', 'description',
+            'available_power', 'mark_connected', 'cable_end', 'cable_position', 'description',
         )
 
     def search(self, queryset, name, value):

netbox/dcim/forms/bulk_edit.py

@@ -780,6 +780,12 @@ class CableBulkEditForm(PrimaryModelBulkEditForm):
         required=False,
         initial=''
     )
+    profile = forms.ChoiceField(
+        label=_('Profile'),
+        choices=add_blank_choice(CableProfileChoices),
+        required=False,
+        initial=''
+    )
     tenant = DynamicModelChoiceField(
         label=_('Tenant'),
         queryset=Tenant.objects.all(),
@@ -808,11 +814,11 @@ class CableBulkEditForm(PrimaryModelBulkEditForm):
 
     model = Cable
     fieldsets = (
-        FieldSet('type', 'status', 'tenant', 'label', 'description'),
+        FieldSet('type', 'status', 'profile', 'tenant', 'label', 'description'),
         FieldSet('color', 'length', 'length_unit', name=_('Attributes')),
     )
     nullable_fields = (
-        'type', 'status', 'tenant', 'label', 'color', 'length', 'description', 'comments',
+        'type', 'status', 'profile', 'tenant', 'label', 'color', 'length', 'description', 'comments',
     )
 
 

netbox/dcim/forms/bulk_import.py

@@ -1461,6 +1461,12 @@ class CableImportForm(PrimaryModelImportForm):
         required=False,
         help_text=_('Connection status')
     )
+    profile = CSVChoiceField(
+        label=_('Profile'),
+        choices=CableProfileChoices,
+        required=False,
+        help_text=_('Cable connection profile')
+    )
     type = CSVChoiceField(
         label=_('Type'),
         choices=CableTypeChoices,
@@ -1491,8 +1497,8 @@ class Meta:
         model = Cable
         fields = [
             'side_a_site', 'side_a_device', 'side_a_type', 'side_a_name', 'side_b_site', 'side_b_device', 'side_b_type',
-            'side_b_name', 'type', 'status', 'tenant', 'label', 'color', 'length', 'length_unit', 'description',
-            'owner', 'comments', 'tags',
+            'side_b_name', 'type', 'status', 'profile', 'tenant', 'label', 'color', 'length', 'length_unit',
+            'description', 'owner', 'comments', 'tags',
         ]
 
     def __init__(self, data=None, *args, **kwargs):