flync_4_signal

The flync_4_signal module contains the building blocks for describing communication data at every level of abstraction: from individual Signals (raw bit-level data elements), through PDUs (Protocol Data Units that group signals), up to Frames (the protocol-specific transport units that carry PDUs on a bus).

Expand for Schematic

        classDiagram

    class Category {
        <<Enumeration>>
        VALUE_RANGE: int = 1
        REQUIRED: int = 2
        CONSISTENCY: int = 3
        UNIQUENESS: int = 4
        REFERENCE: int = 5
        FORMAT: int = 6
        COMPATIBILITY: int = 7
        STRUCTURAL: int = 8
        LIFECYCLE: int = 9
    }

    class Signal {
        name: str
        description: str | None = None
        bit_length: int
        data_type: SignalDataType
        factor: float = 1.0
        offset: float = 0.0
        lower_limit: float | None = None
        upper_limit: float | None = None
        unit: str | None = None
        initial_value: float | int | bytes | str | None = None
        value_encoding: TextTable | BitfieldTextTable | BitmaskFlags | None = None
        spn: int | None = None
    }

    class SignalGroup {
        name: str
        description: str | None = None
        signals: list[SignalInstance]
    }

    class BitmaskFlags {
        type: Literal['bitmask_flags'] = 'bitmask_flags'
        flags: list[BitmaskFlag]
    }

    class SignalDataType {
        <<Enumeration>>
        UINT8: str = 'uint8'
        UINT16: str = 'uint16'
        UINT32: str = 'uint32'
        UINT64: str = 'uint64'
        INT8: str = 'int8'
        INT16: str = 'int16'
        INT32: str = 'int32'
        INT64: str = 'int64'
        FLOAT32: str = 'float32'
        FLOAT64: str = 'float64'
        CHAR: str = 'char'
        BYTEARRAY: str = 'bytearray'
    }

    class BitmaskFlag {
        mask: int
        label: str
    }

    class SignalInstance {
        bit_position: int | None = None
        update_indication_bit_position: int | None = None
        endianness: Literal['BE', 'LE'] = 'LE'
        signal: Signal
    }

    class TextEntry {
        value: int | None = None
        from_value: int | None = <lambda>
        to_value: int | None = <lambda>
        label: str
    }

    class BitfieldTextTable {
        type: Literal['bitfield_text_table'] = 'bitfield_text_table'
        groups: list[BitfieldGroup]
    }

    class FLYNCBaseModel {
    }

    class TextTable {
        type: Literal['text_table'] = 'text_table'
        entries: list[TextEntry]
    }

    class BitfieldGroup {
        name: str
        mask: int
        states: list[BitfieldState]
    }

    class BitfieldState {
        label: str
        value: int | None = None
        from_value: int | None = <lambda>
        to_value: int | None = <lambda>
    }

    class InstancePlacement {
        bit_position: int | None = None
        update_indication_bit_position: int | None = None
        endianness: Literal['BE', 'LE'] = 'LE'
    }

    class SignalGroupInstance {
        bit_position: int | None = None
        update_indication_bit_position: int | None = None
        endianness: Literal['BE', 'LE'] = 'LE'
        signal_group: SignalGroup
    }

    BitfieldGroup ..> BitfieldState
    BitfieldTextTable ..> BitfieldGroup
    BitmaskFlags ..> BitmaskFlag
    TextTable ..> TextEntry
    Signal ..> bytes
    Signal ..> BitmaskFlags
    Signal ..> SignalDataType
    Signal ..> TextTable
    Signal ..> BitfieldTextTable
    SignalInstance ..> Signal
    SignalGroup ..> SignalInstance
    SignalGroupInstance ..> SignalGroup


    

Signal

A Signal is the smallest data element in FLYNC. It describes a physical or logical value that is transmitted on a bus, including how raw bits are scaled and interpreted. Signals are bus-agnostic: the same signal definition can be reused across CAN, LIN, or Ethernet transport layers.

Signals are not placed directly into PDUs; instead a SignalInstance wraps a signal with its placement information (bit offset, byte order, and, for J1939 signals, an optional spn — a reference into SAE J1939-71).

class SignalDataType

Bases: str, Enum

Supported signal base data types for CAN, LIN, FlexRay, and Ethernet.

Enumeration of valid signal data types: UINT8, UINT16, UINT32, UINT64, INT8, INT16, INT32, INT64, FLOAT32, FLOAT64, CHAR, BYTEARRAY. Each variant exposes the helpers natural_bit_width(), is_float(), is_unsigned_integer(), is_signed_integer(), and is_complex_datatype().

class Signal

Bases: FLYNCBaseModel

Logical or physical data element transmitted within a communication message.

Parameters

namestr

Name of the signal.

descriptionstr, optional

Optional textual description of the signal.

bit_lengthint

Length of the signal in bits. Must be greater than 0.

data_typeSignalDataType

Base data type of the signal.

factorfloat

Multiplication factor applied to the raw value to obtain the physical value. Defaults to 1.0.

offsetfloat

Additive offset applied after scaling to obtain the physical value. Defaults to 0.0.

lower_limitfloat, optional

Minimum physical value of the signal.

upper_limitfloat, optional

Maximum physical value of the signal.

unitstr, optional

Physical unit of the signal (e.g. "km/h", "°C").

initial_valuefloat | int | bytes | str, optional

Optional initial value of the signal at startup, expressed as the raw wire value (no factor/offset applied). For char signals pass a str; for bytearray signals pass bytes.

value_encodingValueEncoding, optional

Optional conversion from raw values to text labels. One of TextTable (inclusive range → label; omit to_value for a single value, it defaults to from_value), BitfieldTextTable (named bitfield groups, one active state per group), or BitmaskFlags (independent on/off flags, multiple may be active simultaneously). May be combined with factor/offset/unit to express a mixed linear-and-text-table conversion.

spnint, optional

J1939 Suspect Parameter Number (SPN). Identifies the parameter from the SAE J1939-71 database that this signal represents. Only meaningful for signals carried by J1939 Parameter Groups; a PDU packed by a non-J1939 frame must not contain a signal with an SPN.

class SignalInstance

Bases: InstancePlacement

Placement of a Signal at a specific bit offset within a PDU.

Parameters

signalSignal

Signal being instantiated.

class InstancePlacement

Bases: FLYNCBaseModel

Shared placement metadata for signal and signal-group instances within a PDU.

Parameters

bit_positionint, optional

Non-negative bit offset in the PDU.

update_indication_bit_positionint, optional

Bit position used to indicate that the value has been updated.

endiannessLiteral[“BE”, “LE”]

Byte order for this instance. Defaults to "little_endian".

Value Encodings

A Signal may carry an optional ValueEncoding that converts raw integer values into text labels.

Three variants are supported, selected by the type discriminator:

type	Description
text_table	Maps single raw values as well as inclusive raw value ranges to text labels. Use this for ordinary enumerated signals, for reserved sentinel codes such as Signal_Not_Available or when one label spans many contiguous raw values (e.g. 0..9 = Low).
bitfield_text_table	Decodes the signal as a set of named bit-region groups, each with its own enum of mutually exclusive states. Use this when several unrelated small enums are packed into one signal.
bitmask_flags	Decodes the signal as a set of independent on/off flags, each identified by a disjoint BitmaskFlag mask. Multiple flags may be active simultaneously. Use this for function relevance vectors and similar feature-flag registers.

A signal can combine factor/offset/unit with any of the text-table encodings to express the common “linear conversion plus reserved sentinel values” pattern (e.g. a speed signal in km/h with raw 65535 mapped to Signal_Not_Available).

Examples

Expand for a YAML example — enumerated signal (text_table)

A purely enumerated signal — every raw value maps to one label.

signal:
  name: CurrentGear
  description: Currently engaged gear.
  bit_length: 8
  data_type: uint8
  value_encoding:
    type: text_table
    entries:
      - value: 0
        label: Park
      - value: 1
        label: Reverse
      - value: 2
        label: Neutral
      - value: 3
        label: Drive

Expand for a YAML example — linear signal with reserved codes (text_table)

The most common automotive pattern: a physical signal with linear scaling that also reserves one or more raw codes for special meaning (Signal_Not_Available, Sensor_Error). factor, offset, unit and the limits apply to every raw value except those matched by an entry in value_encoding.

signal:
  name: EngineCoolantTemp
  description: Engine coolant temperature.
  bit_length: 8
  data_type: uint8
  factor: 1.0
  offset: -40.0
  lower_limit: -40.0
  upper_limit: 215.0
  unit: degC
  value_encoding:
    type: text_table
    entries:
      - value: 254
        label: Sensor_Error
      - value: 255
        label: Signal_Not_Available

Expand for a YAML example — value ranges (text_table)

When one label covers many contiguous raw values, give the text_table entry distinct inclusive from_value/to_value bounds. Ranges must not overlap.

signal:
  name: Severity
  description: Severity bucket derived from raw severity code.
  bit_length: 8
  data_type: uint8
  value_encoding:
    type: text_table
    entries:
      - from_value: 0
        to_value: 9
        label: Low
      - from_value: 10
        to_value: 99
        label: Medium
      - from_value: 100
        to_value: 200
        label: High
      - value: 255
        label: Signal_Not_Available

Expand for a YAML example — packed status word (bitfield_text_table)

Several unrelated sub-enums packed into one integer signal. Each BitfieldGroup owns a disjoint region of bits via its mask and contributes exactly one active state at a time; matching is state.from_value <= (raw & group.mask) <= state.to_value. The example below decodes a 16-bit status word into two groups — Problem in the low byte and Mode in the high byte.

signal:
  name: StatusWord
  description: Packed problem indicator and operating mode.
  bit_length: 16
  data_type: uint16
  value_encoding:
    type: bitfield_text_table
    groups:
      - name: Problem
        mask: 0x00FF
        states:
          - label: ProblemNone
            value: 0x0000
          - label: ProblemFailure
            value: 0x0008
          - label: ProblemMajor
            value: 0x0018
      - name: Mode
        mask: 0xFF00
        states:
          - label: ModeIdle
            value: 0x0000
          - label: ModeActive
            value: 0x0100

Expand for a YAML example — function relevance bitmask (bitmask_flags)

A relevance vector where each bit names one vehicle function as currently active; several flags can be set simultaneously. Masks must be pairwise disjoint. A flag is active when (raw & flag.mask) == flag.mask, so the decoded value is the set of active labels (e.g. raw 0b00001011 → {MirrorLeft, MirrorRight, EngineStatus}).

signal:
  name: FunctionRelevance
  description: >-
    Per-function relevance bitmask.  Each bit
    marks one vehicle function as currently relevant or awake;
    several bits may be set at the same time.
  bit_length: 8
  data_type: uint8
  value_encoding:
    type: bitmask_flags
    flags:
      - mask: 0x01
        label: MirrorLeft
      - mask: 0x02
        label: MirrorRight
      - mask: 0x04
        label: CabinLight
      - mask: 0x08
        label: EngineStatus
      - mask: 0x10
        label: TransmissionStatus
      - mask: 0x20
        label: VehicleDynamics

class TextTable

Bases: FLYNCBaseModel

Decodes the signal as a set of TextEntries.

Parameters

typeLiteral[“text_table”]

Discriminator selecting this value-encoding variant.

entrieslist of TextEntry

Non-empty list of range-to-label mappings. Ranges must not overlap and labels must be unique within the table.

class TextEntry

Bases: FLYNCBaseModel

Mapping of an inclusive raw value range to a label.

• For a value range: Use the keys from_value and to_value to define upper and lower bounds.

• For a single value: Either define from_value and to_value with the same value or simply use the key value.

Parameters

valueint

Single value. Optional; defaults to None for range entries.

from_valueint

Inclusive lower bound of the raw value range. Optional; defaults to value for single-value entries.

to_valueint

Inclusive upper bound of the raw value range. Optional; defaults to value for single-value entries.

labelstr

Human-readable label for this range (e.g. "Low", "Medium").

class BitfieldTextTable

Bases: FLYNCBaseModel

Decodes a signal as a set of independent BitfieldGroup regions.

Each group occupies a disjoint mask of the signal’s bits and carries its own enum of mutually exclusive states. Use BitmaskFlags instead when the bits represent independent on/off flags rather than sub-enums.

Parameters

typeLiteral[“bitfield_text_table”]

Discriminator selecting this value-encoding variant.

groupslist of BitfieldGroup

Non-empty list of bitfield groups. Group names must be unique and group masks must be pairwise disjoint (no shared bits).

class BitfieldGroup

Bases: FLYNCBaseModel

One named region of bits within a signal, with its own enum of states.

Matching logic for a state s of this group is s.from_value <= (raw & mask) <= s.to_value. Exactly one state is active per group at any time.

Parameters

namestr

Name of the bitfield group (e.g. "Problem").

maskint

Bitmask selecting the bits that belong to this group. Must be strictly positive and fit within the owning signal’s bit_length (checked at signal level).

stateslist of BitfieldState

Non-empty list of states defined for this group. State values must lie inside mask and may not overlap; labels must be unique within the group.

class BitfieldState

Bases: FLYNCBaseModel

Mapping of an inclusive bitfield range to a label of states.

• For a bitfield range: Use the keys from_value and to_value to define upper and lower bounds.

• For a single bit: Either define from_value and to_value with the same value or simply use the key value.

Parameters

labelstr

Symbolic name of this state (e.g. "ProblemFailure").

valueint, optional

Single bit. Defaults to None for range entries.

from_valueint, optional

Inclusive lower bound for (raw & group.mask). Defaults to value for single-bit entries. Must be greater or equal to 0.

to_valueint, optional

Inclusive upper bound for (raw & group.mask). Defaults to value for single-bit entries. Must be greater or equal to 0.

class BitmaskFlags

Bases: FLYNCBaseModel

Decodes a signal as a set of independent on/off flags.

Each BitmaskFlag is active if (raw & flag.mask) == flag.mask; the decoded value of the signal is the set of active flag labels. Several flags can be active at the same time.

Typical use case: a function relevance vector where each bit names one vehicle function as currently relevant or awake.

Use BitfieldTextTable instead when the bits represent mutually exclusive sub-enums rather than independent flags.

Parameters

typeLiteral[“bitmask_flags”]

Discriminator selecting this value-encoding variant.

flagslist of BitmaskFlag

Non-empty list of flags. Labels must be unique and masks must be pairwise disjoint (no shared bits).

class BitmaskFlag

Bases: FLYNCBaseModel

One named on/off flag inside a BitmaskFlags encoding.

A flag is considered active when (raw & mask) == mask — i.e. every bit of mask is set in the raw signal value. A single BitmaskFlag may cover one bit (the common case) or several bits that must all be set together.

Parameters

maskint

Bitmask identifying this flag. Must be strictly positive and fit within the owning signal’s bit_length (checked at signal level).

labelstr

Human-readable name of the flag (e.g. "MirrorLeft").

Signal Groups

A SignalGroup collects several SignalInstance placements that are always transmitted together. Each contained SignalInstance carries a bit_position interpreted as an offset relative to the group’s origin — i.e. the bit_position where the group is placed inside a PDU; the absolute PDU offset of a signal in a placed group is therefore group_instance.bit_position + signal_instance.bit_position.

A SignalGroupInstance places the entire group at a single bit offset within a PDU, analogous to how SignalInstance places a single signal. The group’s footprint inside a PDU is the largest end-bit reached by any of its placed signal instances; instances without a bit_position are treated as unplaced and skipped during footprint and overlap checks. Signal instances inside the same group are also checked for mutual overlap, mirroring the placement checks performed at the PDU level.

class SignalGroup

Bases: FLYNCBaseModel

A reusable group of signal instances transmitted together within a PDU.

Each contained SignalInstance carries a bit_position interpreted as an offset relative to the group’s origin — that is, relative to the SignalGroupInstance.bit_position where the group is placed inside a PDU. Signal instances without a bit_position are treated as unplaced and skipped during overlap and footprint checks.

Parameters

namestr

Name of the signal group.

descriptionstr, optional

Optional textual description of the group.

signalslist of SignalInstance

Non-empty list of placed signal instances contained in this group.

class SignalGroupInstance

Bases: InstancePlacement

Placement of a SignalGroup at a specific bit offset within a PDU.

Parameters

signal_groupSignalGroup

Signal group being instantiated.

PDU

A PDU (Protocol Data Unit) is the container that groups signals for transmission. PDUs are defined independently of any specific bus and stored in communication/channels/pdus/. A PDUInstance then places a named PDU at a given bit offset inside a frame.

Expand for Schematic

        classDiagram

    class Category {
        <<Enumeration>>
        VALUE_RANGE: int = 1
        REQUIRED: int = 2
        CONSISTENCY: int = 3
        UNIQUENESS: int = 4
        REFERENCE: int = 5
        FORMAT: int = 6
        COMPATIBILITY: int = 7
        STRUCTURAL: int = 8
        LIFECYCLE: int = 9
    }

    class MuxGroup {
        selector_value: int
        pdu: PDUInstance
    }

    class ContainerPDUHeader {
        id_length_bits: int
        length_field_bits: int
    }

    class SignalInstance {
        bit_position: int | None = None
        update_indication_bit_position: int | None = None
        endianness: Literal['BE', 'LE'] = 'LE'
        signal: Signal
    }

    class PDU {
        name: str
        length: int
        pdu_usage: Literal['application', 'bap', 'diag_request', 'diag_response', 'diag_state', 'network_management', 'other', 'service', 'tpl', 'xcp_pre_configured', 'xcp_runtime_configured'] | None = None
        description: str | None = None
    }

    class FLYNCBaseModel {
    }

    class ContainedPDURef {
        header_id: int
        pdu_ref: str
        offset: int | None = 0
    }

    class MultiplexedPDU {
        name: str
        length: int
        pdu_usage: Literal['application', 'bap', 'diag_request', 'diag_response', 'diag_state', 'network_management', 'other', 'service', 'tpl', 'xcp_pre_configured', 'xcp_runtime_configured'] | None = None
        description: str | None = None
        type: Literal['multiplexed'] = 'multiplexed'
        selector_signal: SignalInstance
        static_group: list[PDUInstance] | None = None
        mux_groups: list[MuxGroup] = list
    }

    class ContainerPDU {
        name: str
        length: int
        pdu_usage: Literal['application', 'bap', 'diag_request', 'diag_response', 'diag_state', 'network_management', 'other', 'service', 'tpl', 'xcp_pre_configured', 'xcp_runtime_configured'] | None = None
        description: str | None = None
        type: Literal['container'] = 'container'
        pdu_id: int
        header: ContainerPDUHeader
        contained_pdus: list[ContainedPDURef] = list
    }

    class StandardPDU {
        name: str
        length: int
        pdu_usage: Literal['application', 'bap', 'diag_request', 'diag_response', 'diag_state', 'network_management', 'other', 'service', 'tpl', 'xcp_pre_configured', 'xcp_runtime_configured'] | None = None
        description: str | None = None
        type: Literal['standard'] = 'standard'
        signals: list[SignalInstance] = list
        signal_groups: list[SignalGroupInstance] = list
    }

    class PDUInstance {
        pdu_ref: str
        bit_position: int | None = None
        update_bit_position: int | None = None
    }

    class SignalGroupInstance {
        bit_position: int | None = None
        update_indication_bit_position: int | None = None
        endianness: Literal['BE', 'LE'] = 'LE'
        signal_group: SignalGroup
    }

    SignalGroupInstance ..> SignalGroup
    SignalInstance ..> Signal
    StandardPDU ..> SignalInstance
    StandardPDU ..> SignalGroupInstance
    MuxGroup ..> PDUInstance
    MultiplexedPDU ..> MuxGroup
    MultiplexedPDU ..> SignalInstance
    MultiplexedPDU ..> PDUInstance
    ContainerPDU ..> ContainerPDUHeader
    ContainerPDU ..> ContainedPDURef


    

There are three PDU types, distinguished by the type discriminator field:

type	Description
standard	Non-multiplexed PDU containing a flat list of signal (group) instances.
multiplexed	PDU with a selector signal; the active signal group depends on its value.
container	Ethernet Container PDU that packs several other PDUs into one payload.

class PDU

Bases: FLYNCBaseModel

Protocol Data Unit base class.

Parameters

namestr

Unique name of the PDU.

lengthint

Length of the PDU payload in bytes. Must be greater than 0.

pdu_usageLiteral[str], optional

Tag identifying special usage of the PDU. One of: “application”, “bap”, “diag_request”, “diag_response”, “diag_state”, “network_management”, “other”, “service”, “tpl”, “xcp_pre_configured”, “xcp_runtime_configured”.

descriptionstr, optional

Optional human-readable description.

Standard PDU

Expand for a YAML example - 📄 communication/channels/pdus/PDU_EngineStatus.flync.yaml

Note

Each PDU is stored in its own .flync.yaml file under communication/channels/pdus/. This directory is optional and may be omitted when no PDUs are defined.

name: PDU_EngineStatus
type: standard
length: 8
description: >-
  Engine speed, torque, coolant temperature and operating state.
  Transmitted cyclically at 10 ms by EngineECU on PowertrainCAN.

signals:
  - bit_position: 0
    endianness: LE

    signal:
      name: EngineSpeed
      description: Crankshaft rotational speed.
      bit_length: 16
      data_type: uint16
      factor: 0.25
      offset: 0.0
      lower_limit: 0.0
      upper_limit: 16383.75
      unit: rpm
      value_encoding:
        type: text_table
        entries:
          - value: 65535
            label: Signal_Not_Available
  - bit_position: 16
    endianness: LE

    signal:
      name: EngineTorque
      description: Indicated engine torque at crankshaft.
      bit_length: 16
      data_type: int16
      factor: 0.1
      offset: -3276.8
      lower_limit: -3276.8
      upper_limit: 3276.7
      unit: Nm
  - bit_position: 32
    endianness: LE

    signal:
      name: EngineCoolantTemp
      description: Engine coolant temperature.
      bit_length: 8
      data_type: uint8
      factor: 1.0
      offset: -40.0
      lower_limit: -40.0
      upper_limit: 215.0
      unit: degC
      value_encoding:
        type: text_table
        entries:
          - value: 254
            label: Sensor_Error
          - value: 255
            label: Signal_Not_Available
  - bit_position: 40
    endianness: LE

    signal:
      name: EngineStatus
      description: Engine operating state.
      bit_length: 4
      data_type: uint8
      value_encoding:
        type: text_table
        entries:
          - value: 0
            label: Stopped
          - value: 1
            label: Cranking
          - value: 2
            label: Running
          - value: 3
            label: Stall
          - value: 15
            label: Error

class StandardPDU

Bases: PDU

Non-multiplexed PDU containing a flat list of signal instances.

Parameters

signalslist of SignalInstance

Signal instances placed within this PDU.

signal_groupslist of SignalGroupInstance

Signal group instances placed within this PDU.

Multiplexed PDU

Expand for a YAML example - 📄 communication/channels/pdus/PDU_TransmissionStatus.flync.yaml

Note

A multiplexed PDU uses a selector_signal (the MUX switch) to select which mux_groups block of signals is active on each transmission cycle. This corresponds to the DBC M/mN multiplexer notation.

name: PDU_TransmissionStatus
type: multiplexed
length: 8
description: Transmission status, multiplexed on GearInfoMux selector.

selector_signal:
  bit_position: 0
  endianness: LE
  signal:
    name: GearInfoMux
    description: Multiplexer selector for TransmissionStatus PDU.
    bit_length: 4
    data_type: uint8

mux_groups:
  - selector_value: 0
    pdu:
      pdu_ref: PDU_TransmissionStatus_Gear
  - selector_value: 1
    pdu:
      pdu_ref: PDU_TransmissionStatus_Torque

class MultiplexedPDU

Bases: PDU

PDU with a selector signal that determines which signal group is active.

Parameters

selector_signalSignalInstance

The selector signal whose value determines the active mux group.

static_grouplist of PDUInstance, optional

Optional PDU Instances with signals that are always present regardless of the active mux group. A single PDU Instance (unwrapped mapping) is accepted as well and coerced into a one-element list.

mux_groupslist of MuxGroup

One entry per distinct selector value. Must contain at least one mux group.

class MuxGroup

Bases: FLYNCBaseModel

Set of signals active for a specific multiplexer selector value.

Parameters

selector_valueint

The value of the selector signal that activates this group. Must be greater than or equal to 0.

pduPDUInstance

The PDU Instance that is active for this selector_value.

Container PDU

Expand for a YAML example - 📄 communication/channels/ethernet_pdu_containers/eth_powertrain_container.flync.yaml

Note

An Ethernet Container PDU is stored in its own .flync.yaml file under communication/channels/pdus/, alongside all other PDU types. It bundles several application PDUs into one Ethernet payload. The per-slot header format is configured via the header block, which specifies id_length_bits and length_field_bits.

name: EthPowertrainContainer
type: container
pdu_id: 1
length: 31
header:
  id_length_bits: 16
  length_field_bits: 8
description: >-
  Container PDU bundling powertrain PDUs (engine status, vehicle dynamics,
  transmission state) into a single Ethernet payload.

contained_pdus:
  - header_id: 257
    pdu_ref: PDU_EngineStatus
    offset: 0
  - header_id: 513
    pdu_ref: PDU_VehicleDynamics
    offset: 11
  - header_id: 769
    pdu_ref: PDU_TransmissionStatus
    offset: 20

class ContainerPDUHeader

Bases: FLYNCBaseModel

Per-slot header configuration for a ContainerPDU.

Parameters

id_length_bitsint

Bit length of the PDU ID field. Must be a multiple of 8 and at most 32.

length_field_bitsint

Bit length of the payload-length field. Must be a multiple of 8 and at most 32.

class ContainerPDU

Bases: PDU

Ethernet Container PDU that packs multiple PDUs into one frame payload.

Each contained PDU is prefixed with a header carrying its ID and length, allowing the receiver to demultiplex the slots at runtime.

Parameters

pdu_idint

Numeric identifier for this container PDU on the network. Must be greater than or equal to 0.

headerContainerPDUHeader

Per-slot header format specifying the bit widths of the ID and length fields.

contained_pduslist of ContainedPDURef

PDUs packed inside this container, each referenced by name.

class ContainedPDURef

Bases: FLYNCBaseModel

Reference to a PDU packed inside a ContainerPDU.

Parameters

header_idint

Numeric identifier greater than 0 placed in the slot header for this contained PDU.

pdu_refstr

Name of the referenced PDU.

offsetint, optional

Bit offset of this slot (header + payload) within the container payload. When multiple PDUs are packed sequentially this encodes the start position of each slot so receivers can locate it without parsing preceding slots. Must be greater than or equal to 0.

class PDUInstance

Bases: FLYNCBaseModel

Placement of a PDU at a specific bit offset within a CAN or LIN frame.

Parameters

pdu_refstr

Name of the referenced PDU.

bit_positionint, optional

Bit offset where this PDU begins within the frame. Must be greater than or equal to 0.

update_bit_positionint, optional

Bit position of the update indication bit, when applicable. Must be greater than or equal to 0.

Frame

A Frame is the protocol-specific transport unit that carries one or more PDUs on a physical bus. CAN and CAN FD frames are defined inside communication/channels/can/; LIN frames inside communication/channels/lin/; J1939 frames alongside CAN frames in communication/channels/can/. All frame types reference PDUs by name via PDUInstance.

For Ethernet, there is no frame layer — sockets reference a ContainerPDU directly via a pdu_sender or pdu_receiver deployment.

Expand for Schematic

        classDiagram

    class Category {
        <<Enumeration>>
        VALUE_RANGE: int = 1
        REQUIRED: int = 2
        CONSISTENCY: int = 3
        UNIQUENESS: int = 4
        REFERENCE: int = 5
        FORMAT: int = 6
        COMPATIBILITY: int = 7
        STRUCTURAL: int = 8
        LIFECYCLE: int = 9
    }

    class Frame {
        name: str
        length: int
        frame_usage: Literal['application', 'bap', 'diag_request', 'diag_response', 'diag_state', 'network_management', 'other', 'service', 'tpl', 'xcp_pre_configured', 'xcp_runtime_configured'] | None = None
        description: str | None = None
        packed_pdus: list[PDUInstance] = list
    }

    class CANFDFrame {
        name: str
        length: int
        frame_usage: Literal['application', 'bap', 'diag_request', 'diag_response', 'diag_state', 'network_management', 'other', 'service', 'tpl', 'xcp_pre_configured', 'xcp_runtime_configured'] | None = None
        description: str | None = None
        packed_pdus: list[PDUInstance] = list
        can_id: int
        id_format: Literal['standard_11bit', 'extended_29bit']
        timing: FrameTransmissionTiming | None = None
        type: Literal['can_fd'] = 'can_fd'
        bit_rate_switch: bool = True
        error_state_indicator: bool = False
    }

    class CANFrame {
        name: str
        length: int
        frame_usage: Literal['application', 'bap', 'diag_request', 'diag_response', 'diag_state', 'network_management', 'other', 'service', 'tpl', 'xcp_pre_configured', 'xcp_runtime_configured'] | None = None
        description: str | None = None
        packed_pdus: list[PDUInstance] = list
        can_id: int
        id_format: Literal['standard_11bit', 'extended_29bit']
        timing: FrameTransmissionTiming | None = None
        type: Literal['can'] = 'can'
        is_remote_frame: bool = False
    }

    class FrameTransmissionTiming {
        debounce_time: float | None = None
        cyclic_timings: list[FrameCyclicTiming] = list
        event_timings: list[FrameEventTiming] = list
    }

    class FLYNCBaseModel {
    }

    class J1939Frame {
        name: str
        length: Literal[8] = 8
        frame_usage: Literal['application', 'bap', 'diag_request', 'diag_response', 'diag_state', 'network_management', 'other', 'service', 'tpl', 'xcp_pre_configured', 'xcp_runtime_configured'] | None = None
        description: str | None = None
        packed_pdus: list[PDUInstance] = list
        priority: int
        pdu_format: int
        pdu_specific: int
        data_page: int
        extended_data_page: int
        destination_type: Literal['global', 'specific']
        type: Literal['j1939'] = 'j1939'
        timing: FrameTransmissionTiming | None = None
    }

    class LINFrame {
        name: str
        length: int
        frame_usage: Literal['application', 'bap', 'diag_request', 'diag_response', 'diag_state', 'network_management', 'other', 'service', 'tpl', 'xcp_pre_configured', 'xcp_runtime_configured'] | None = None
        description: str | None = None
        packed_pdus: list[PDUInstance] = list
        type: Literal['lin'] = 'lin'
        lin_id: int
        checksum_type: Literal['classic', 'enhanced'] = 'enhanced'
        timing: FrameTransmissionTiming | None = None
    }

    class FrameCyclicTiming {
        cycle: float
    }

    class FrameEventTiming {
        final_repetitions: int = 0
        repeating_time_range: float = 0.0
    }

    class CANFrameBase {
        name: str
        length: int
        frame_usage: Literal['application', 'bap', 'diag_request', 'diag_response', 'diag_state', 'network_management', 'other', 'service', 'tpl', 'xcp_pre_configured', 'xcp_runtime_configured'] | None = None
        description: str | None = None
        packed_pdus: list[PDUInstance] = list
        can_id: int
        id_format: Literal['standard_11bit', 'extended_29bit']
        timing: FrameTransmissionTiming | None = None
    }

    class PDUInstance {
        pdu_ref: str
        bit_position: int | None = None
        update_bit_position: int | None = None
    }

    FrameTransmissionTiming ..> FrameEventTiming
    FrameTransmissionTiming ..> FrameCyclicTiming
    Frame ..> PDUInstance
    CANFrameBase ..> FrameTransmissionTiming
    CANFrameBase ..> PDUInstance
    CANFrame ..> FrameTransmissionTiming
    CANFrame ..> PDUInstance
    CANFDFrame ..> FrameTransmissionTiming
    CANFDFrame ..> PDUInstance
    LINFrame ..> FrameTransmissionTiming
    LINFrame ..> PDUInstance
    J1939Frame ..> FrameTransmissionTiming
    J1939Frame ..> PDUInstance


    

class Frame

Bases: FLYNCBaseModel

Protocol-agnostic frame base class.

Parameters

namestr

Unique name of the frame.

lengthint

Length of the frame payload in bytes.

frame_usageLiteral[str], optional

Tag identifying special usage of the frame. One of:

• "application" marks the frame as carrying regular application traffic.

• "bap" marks the frame as carrying BAP (FIBEX compatibility).

• "diag_request" marks the frame as diagnostics request.

• "diag_response" marks the frame as diagnostics response.

• "diag_state" marks the frame as diagnostics state.

• "network_management" marks the frame as carrying Network Management traffic.

• "other" marks the frame as other usage.

• "service" marks the frame as service.

• "tpl" marks the frame as carrying a transport protocol.

• "xcp_pre_configured" marks the frame as static XCP.

• "xcp_runtime_configured" marks the frame as dynamic XCP.

descriptionstr, optional

Optional human-readable description.

packed_pduslist of PDUInstance

PDU instances placed at fixed bit offsets within this frame.

class CANFrameBase

Bases: Frame

Shared fields for CAN 2.0 and CAN FD frames.

Parameters

can_idint

CAN message identifier.

id_formatLiteral[“standard_11bit”, “extended_29bit”]

Identifier format.

timingFrameTransmissionTiming, optional

Transmission timing for this frame.

class CANFrame

Bases: CANFrameBase

Classical CAN frame (CAN 2.0A/B).

Parameters

can_idint

CAN message identifier. Range: [0, 0x7FF] for "standard_11bit", [0, 0x1FFFFFFF] for "extended_29bit".

id_formatLiteral[“standard_11bit”, “extended_29bit”]

Identifier format.

is_remote_framebool

Whether this is a Remote Transmission Request (RTR) frame. Defaults to False.

class CANFDFrame

Bases: CANFrameBase

CAN FD frame.

Supports payloads up to 64 bytes and an optional bit-rate switch for the data phase.

Parameters

can_idint

CAN message identifier. Same range rules as CANFrame.

id_formatLiteral[“standard_11bit”, “extended_29bit”]

Identifier format.

bit_rate_switchbool

Enables a higher bit rate during the data phase. Defaults to True.

error_state_indicatorbool

Error State Indicator flag. Defaults to False.

class J1939Frame

Bases: Frame

Basic J1939 Frame.

Parameters

typeLiteral[“j1939”]

Discriminator tag selecting this frame kind when parsed from a CAN bus frame list.

priorityint

J1939 message priority.

pdu_formatint

PDU Format (PF) field. Values below 240 select the PDU1 format, where pdu_specific is a Destination Address; values 240-255 select the PDU2 format, where pdu_specific is a Group Extension.

pdu_specific: int

Message PDU Specific (PS) field. For PDU1 (pdu_format < 240) it is a Destination Address; for PDU2 (pdu_format >= 240) it is a Group Extension that groups related messages.

data_page: int

Message data page.

extended_data_page: int

Message extended data page.

destination_type: Literal[“global”, “specific”]

Destination type. For PDU1 (pdu_format < 240) the pdu_specific field is a destination address: "specific" targets a single node (DA 0-254) and "global" broadcasts to every node (DA = 255). For PDU2 (pdu_format >= 240) the message is always a group broadcast, so this must be "global".

timingFrameTransmissionTiming, optional

Transmission timing for this frame.

Notes

A J1939 message carries exactly one Parameter Group (one PGN) in its 8-byte data field, so packed_pdus may contain at most one entry. This is unlike classical CAN, where a single frame may pack several PDUs.

class LINFrame

Bases: Frame

LIN unconditional frame.

Parameters

lin_idint

6-bit LIN frame identifier in the range [0, 0x3F].

checksum_typeLiteral[“classic”, “enhanced”]

LIN checksum model. Defaults to "enhanced".

timingFrameTransmissionTiming, optional

Transmission timing for this frame.

PDU Sender / Receiver Deployments

Expand for a YAML example - 📄 ecus/high_performance_compute/controllers/hpc_controller1/ethernet_interfaces/hpc_c1_iface1/sockets/socket_pdu.flync.yaml

Note

A pdu_sender deployment binds a ContainerPDU to a socket on the publishing ECU. A pdu_receiver deployment does the same for the subscribing ECU. Both are added to the deployments list of a SocketTCP or SocketUDP.

vlan_id: 20
sockets:

  - name: pdu_powertrain_tx
    endpoint_address: 10.0.20.5
    endpoint_type: unicast
    port_no: 30800
    protocol: udp
    deployments:
      - deployment_type: pdu_sender
        pdu_ref: EthPowertrainContainer

  - name: pdu_engine_status_tx
    endpoint_address: 10.0.20.5
    endpoint_type: unicast
    port_no: 30802
    protocol: udp
    deployments:
      - deployment_type: pdu_sender
        pdu_ref: PDU_EngineStatus

  - name: pdu_powertrain_rx
    endpoint_address: 10.0.20.5
    endpoint_type: unicast
    port_no: 30804
    protocol: udp
    deployments:
      - deployment_type: pdu_forwarder
        pdu_ref: EthPowertrainContainer
        egresses:
          - egress_type: can_frame
            bus_ref: DiagCAN
            frame_ref: 2024  # Frame_EngineDiagResponse (0x7E8)
            extract_pdu_ref: PDU_EngineStatus

          - egress_type: eth_socket
            socket_ref: pdu_powertrain_rebridge_tx

  - name: pdu_powertrain_rebridge_tx
    endpoint_address: 10.0.20.5
    endpoint_type: unicast
    port_no: 30806
    protocol: udp
    deployments:
      - deployment_type: pdu_sender
        pdu_ref: EthPowertrainContainer

class PDUSender

Bases: FLYNCBaseModel

Deployment that publishes a PDU onto a socket.

Transport (TCP/UDP, IP address, port) is owned by the enclosing socket; this model only binds a PDU to that socket. The publishing ECU is the owner of the socket carrying this deployment.

Parameters

deployment_typeLiteral[“pdu_sender”]

Discriminator value for DeploymentUnion.

pdu_refstr

Name of a PDU declared under communication.channels — any of StandardPDU, MultiplexedPDU, or ContainerPDU. Validated at workspace level once the full model is assembled.

class PDUReceiver

Bases: FLYNCBaseModel

Deployment that subscribes to a PDU on a socket.

Transport (TCP/UDP, IP address, port) is owned by the enclosing socket; this model only binds a PDU to that socket. The receiving ECU is the owner of the socket carrying this deployment.

Parameters

deployment_typeLiteral[“pdu_receiver”]

Discriminator value for DeploymentUnion.

pdu_refstr

Name of a PDU declared under communication.channels — any of StandardPDU, MultiplexedPDU, or ContainerPDU. Validated at workspace level once the full model is assembled.

PDU Forwarder Deployments

A PDU Forwarder is a third per-PDU role (alongside pdu_sender and pdu_receiver) that consumes a PDU on its parent carrier and re-emits it on one or more egresses. The same primitive exists on both sides of the modeled network:

• PDUForwarder is an Ethernet-side deployment that lives inside a socket’s deployments block.

• CANFrameForwarder is a CAN-interface list entry under forwarder_frames on CANInterface.

Each forwarder lists one or more ForwarderEgress items — a discriminated union of CANFrameEgress (re-emit on a CAN frame) and EthSocketEgress (re-emit on an Ethernet socket). Optional extract_pdu_ref on an egress selects a single inner PDU when the ingress is a ContainerPDU.

Expand for a YAML example - 📄 ecus/high_performance_compute/controllers/hpc_controller1/can_interfaces/powertrain_can_interface.flync.yaml

Note

A forwarder_frames entry consumes frame_ref from the parent interface’s bus and re-emits it on one or more egresses. The example below fans Frame_EngineStatus to a CAN frame on DiagCAN (CAN → CAN) and to an Ethernet socket (CAN → Ethernet).

bus_ref: PowertrainCAN
sender_frames: []
receiver_frames:
  - bus_ref: PowertrainCAN
    frame_ref: 257   # Frame_EngineStatus (0x101)
  - bus_ref: PowertrainCAN
    frame_ref: 513   # Frame_VehicleDynamics (0x201)
  - bus_ref: PowertrainCAN
    frame_ref: 769   # Frame_TransmissionStatus (0x301)

forwarder_frames:
  - frame_ref: Frame_EngineStatus
    egresses:
      - egress_type: can_frame
        bus_ref: DiagCAN
        frame_ref: 2024  # Frame_EngineDiagResponse (0x7E8)
      - egress_type: eth_socket
        socket_ref: pdu_engine_status_tx

Expand for a YAML example - 📄 ecus/high_performance_compute/controllers/hpc_controller1/ethernet_interfaces/hpc_c1_iface1/sockets/socket_pdu.flync.yaml

Note

A pdu_forwarder deployment consumes pdu_ref on the parent socket. The forwarder on pdu_powertrain_rx extracts PDU_EngineStatus from the inbound container and emits it on the DiagCAN diagnostic frame (Ethernet → CAN), and also re-bridges the whole container to a peer Ethernet socket (Ethernet → Ethernet).

vlan_id: 20
sockets:

  - name: pdu_powertrain_tx
    endpoint_address: 10.0.20.5
    endpoint_type: unicast
    port_no: 30800
    protocol: udp
    deployments:
      - deployment_type: pdu_sender
        pdu_ref: EthPowertrainContainer

  - name: pdu_engine_status_tx
    endpoint_address: 10.0.20.5
    endpoint_type: unicast
    port_no: 30802
    protocol: udp
    deployments:
      - deployment_type: pdu_sender
        pdu_ref: PDU_EngineStatus

  - name: pdu_powertrain_rx
    endpoint_address: 10.0.20.5
    endpoint_type: unicast
    port_no: 30804
    protocol: udp
    deployments:
      - deployment_type: pdu_forwarder
        pdu_ref: EthPowertrainContainer
        egresses:
          - egress_type: can_frame
            bus_ref: DiagCAN
            frame_ref: 2024  # Frame_EngineDiagResponse (0x7E8)
            extract_pdu_ref: PDU_EngineStatus

          - egress_type: eth_socket
            socket_ref: pdu_powertrain_rebridge_tx

  - name: pdu_powertrain_rebridge_tx
    endpoint_address: 10.0.20.5
    endpoint_type: unicast
    port_no: 30806
    protocol: udp
    deployments:
      - deployment_type: pdu_sender
        pdu_ref: EthPowertrainContainer

class PDUForwarder

Bases: FLYNCBaseModel

Socket deployment that consumes a PDU on its parent socket and re-emits it on one or more egresses.

Parameters

deployment_typeLiteral[“pdu_forwarder”]

Type discriminator for this forwarder.

pdu_refstr

Reference to the PDU being forwarded.

egressesList[ForwarderEgress]

List of egress targets where the forwarded PDU is re-emitted. Must contain at least one egress.

class CANFrameForwarder

Bases: FLYNCBaseModel

CAN-interface forwarder that consumes an ingress frame and re-emits it on one or more egresses.

Parameters

frame_refstr

Reference to the CAN frame being forwarded.

egressesList[ForwarderEgress]

List of egress targets where the forwarded frame is re-emitted. Must contain at least one egress.

class ForwarderEgress

Bases: RootModel

Discriminated-union wrapper over a single forwarder egress (CANFrameEgress or EthSocketEgress).

class CANFrameEgress

Bases: FLYNCBaseModel

Forwarder egress that re-emits the forwarded PDU on a CAN frame.

Parameters

egress_typeLiteral[“can_frame”]

Type discriminator for this egress.

bus_refstr

Reference to the target CAN bus.

frame_refint

Reference to the target CAN frame.

extract_pdu_refstr, optional

Optional reference to a PDU to extract from the forwarded data.

class EthSocketEgress

Bases: FLYNCBaseModel

Forwarder egress that re-emits the forwarded PDU on an Ethernet socket (unicast/multicast follows the target’s endpoint_address).

Parameters

egress_typeLiteral[“eth_socket”]

Type discriminator for this egress.

socket_refstr

Reference to the target Ethernet socket.

extract_pdu_refstr, optional

Optional reference to a PDU to extract from the forwarded data.

Frame Timing

Transmission timing is configured at the frame layer for every protocol. Each CAN, CAN FD, or LIN frame may carry an optional timing field that drives cyclic, event-driven, and debounce scheduling of the frame as a whole on the wire.

class FrameTransmissionTiming

Bases: FLYNCBaseModel

Frame transmission timing configuration.

Parameters

debounce_timefloat, optional

Debounce delay in seconds before transmission occurs.

cyclic_timingslist of FrameCyclicTiming

Cyclic timing configurations.

event_timingslist of FrameEventTiming

Event-driven timing configurations.

class FrameCyclicTiming

Bases: FLYNCBaseModel

Cyclic transmission timing.

Parameters

cyclefloat

Cycle time in seconds. Must be greater than 0.

class FrameEventTiming

Bases: FLYNCBaseModel

Event-based transmission timing.

Parameters

final_repetitionsint

Number of repetitions after an event is triggered. Defaults to 0.

repeating_time_rangefloat

Time interval in seconds between repetitions. Defaults to 0.0.