flync_4_nm¶

Network Management — State Management Groups¶

Note

The central group registry is placed in the directory 📁 communication/state_management/ (file groups.flync.yaml). This is a non-mandatory directory for the FLYNC configuration. Memberships are declared entity-side — on ECUs, controllers, and buses.

FLYNC models network management vendor-neutrally: a state management group owns only its identity, a reference to an ordinary NM PDU (pdu_usage: network_management), and a reference to a shared, reusable timing profile. It has no member list — the effective member set is derived during validation from the memberships declared on the entities.

class StateManagementConfig¶

Bases: FLYNCBaseModel

System-wide state management configuration.

Serialized to the communication/state_management/ directory: the group registry lands in groups.flync.yaml and the reusable timing profiles in timing_profiles.flync.yaml. Designed to absorb future siblings (e.g. eFuse state dependencies) as additional files in the same directory without structural change.

Parameters¶

groupslist of StateManagementGroup: The central registry of state management groups.
timing_profileslist of GroupTiming: The reusable NM timing profiles referenced by the groups.

class StateManagementGroup¶

Bases: FLYNCBaseModel

A user-defined state management group.

The group is the single owner of identity and transport reference, and references a shared timing profile by name. It intentionally has NO member list: memberships are declared on the participating entities (StateMembershipRef) and resolved during system validation.

Parameters¶

namestr: Unique name of the group (e.g. COMFORT, VEHICLE).
nm_pdustr: Name reference to an existing StandardPDU with pdu_usage: network_management. The PDU carries the group’s relevance vector as an ordinary bitmask-encoded signal.
timing_profilestr: Name reference to a GroupTiming profile defined in the registry. Several groups may reference the same profile.
descriptionstr, optional: Optional human-readable description.
extensionsdict of str to str, optional: Optional map of extension keys and values for OEM- or tool-specific parameters. FLYNC carries them through untouched - they are never interpreted by the model or validation - so an OEM can attach its own per-group settings without a schema change.

class GroupTiming¶

Bases: FLYNCBaseModel

A reusable, bus-abstract NM timing profile.

A profile is defined once in the registry and referenced by name from any number of groups (StateManagementGroup.timing_profile), so groups that share the same timing reuse a single definition instead of repeating the values. Timing is never overridden per bus or per member; feasibility per bus segment is a validation concern. The parameters are grouped by phase: the normal-operation cycle time stays at the top level, while the announcement phase and the go-to-sleep progression each carry their own sub-model.

Parameters¶

namestr: Unique name of the profile (e.g. standard, fast).
descriptionstr, optional: Optional human-readable description.
cycle_time_msint: Cyclic transmission period of the NM PDU in milliseconds during normal operation.
announcementAnnouncementPhaseTiming, optional: Timing of the announcement phase that runs on state changes (e.g. joining the network or entering the sleep progression). Optional - omit it for a group that does not model an announcement phase.
sleepSleepTiming: Timing of the go-to-sleep progression (silence timeout and final wait).
extensionsdict of str to str, optional: Optional map of extension keys and values for OEM- or tool-specific timing parameters, carried through untouched (never interpreted).

class AnnouncementPhaseTiming¶

Bases: FLYNCBaseModel

Timing of a group’s announcement phase.

Whenever a bus participant changes the group’s state - for instance when it (re)joins the network AND when it begins the go-to-sleep progression, i.e. on state changes generally, not only after a wake-up - it re-announces itself for a bounded window so every member can resynchronize the derived member set before normal operation resumes. The phase is optional: a group that does not model it simply omits announcement.

Parameters¶

duration_msint: Total duration of the announcement phase in milliseconds, during which every member transmits so the member set can resynchronize.
burst_countint, optional: Number of NM PDUs sent back-to-back at the start of the phase (the initial burst) at burst_cycle_time_ms before the normal cadence resumes. Must be set together with burst_cycle_time_ms; the burst must fit within duration_ms.
burst_cycle_time_msint, optional: Faster transmission period used for those initial burst PDUs to propagate the state change quickly, before falling back to the group’s cycle_time_ms. Must be set together with burst_count and be shorter than cycle_time_ms.

class SleepTiming¶

Bases: FLYNCBaseModel

Timing of a group’s go-to-sleep progression.

Parameters¶

timeout_msint: Time in milliseconds without any NM PDU on the channel after which an already-released entity advances along the sleep progression toward the final wait phase. This silence timer does NOT decide release: while any bit is still requested the network stays awake regardless of it. The timer restarts on every NM PDU sent or received, so ongoing NM traffic keeps the group awake; actual sleep follows only once every registered bit is released and wait_before_sleep_ms has elapsed.
wait_before_sleep_msint: Time in milliseconds a node waits, after the network has gone quiet and all its registered bits are released, before it finally enters sleep - the last delay of the sleep progression.

Expand for a YAML example - 📄 timing_profiles.flync.yaml + groups.flync.yaml

# timing_profiles.flync.yaml — reusable, referenced by name from any group
timing_profiles:
- name: standard
  cycle_time_ms: 500              # message sending cycle in normal operation
  announcement:                   # optional: announcement phase
    duration_ms: 1000             # total duration of the announcement phase
    burst_count: 5                # number of initial burst PDUs
    burst_cycle_time_ms: 20       # cycle time for the initial burst PDUs
  sleep:                          # go-to-sleep progression
    timeout_ms: 2000              # timeout before preparing to go to sleep
    wait_before_sleep_ms: 1500    # time of preparing to go to sleep

# groups.flync.yaml
groups:
- name: VEHICLE
  description: Vehicle-wide group using PDU_NmMessage.
  nm_pdu: PDU_NmMessage
  timing_profile: standard
  extensions:            # optional OEM/tool-specific key/value hooks
    parameter_a: value_a
    parameter_b: value_b

Memberships¶

Entities declare membership themselves; the group never lists members.

class StateMembershipRef¶

Bases: FLYNCBaseModel

Entity-side assignment of an ECU, controller, or bus to a state management group.

Entities declare membership ONLY - never timing and never the NM PDU; everything the group owns stays in the central group registry. A bus membership enrols the bus as a single participant (default bit: the bus name) - it is never expanded into per-attached-ECU participants.

Parameters¶

groupstr: Name reference to a StateManagementGroup defined in communication/state_management/groups.flync.yaml.
roleLiteral[“participant”, “observer”], optional: participant (default) references a state bit and takes part in the wake/sleep decision. observer receives the group’s NM PDU and acts on it (e.g. a switch pulling a wake line) but references no bit and never influences the group’s sleep decision. The role is also the permission model: only participants may request the group state, because requesting means setting a relevance bit.
relevance_bitslist of str, optional: Names of the state bits in the group PDU’s relevance vector this participant references. A participant may reference several - one per vehicle function it takes part in - listed in a single membership instead of repeating the block per bit. Defaults to a single bit named after the declaring entity. Must be absent for observers.
extensionsdict of str to str, optional: Optional map of extension keys and values for OEM- or tool-specific per-membership parameters, carried through untouched (never interpreted).

Declaration sites:

Controller (recommended for multi-controller ECUs) — 📄 state_memberships.flync.yaml inside the controller folder.
ECU (whole-ECU granularity, also used by abstract ECUs) — 📄 state_memberships.flync.yaml inside the ECU folder.
Bus (bus-level membership) — inline state_memberships in the bus file: the whole bus is ONE participant, kept awake while requested and asleep as a unit when released, never expanded into per-attached-ECU participants. It may reference several relevance bits when the bus is needed for several functions (default: a single bit named after the bus), but wakes as a whole for any of them. This is the only option for LIN — LIN carries no NM message, so the bus can only move as a unit, driven by its master, which is either the source of the group state (e.g. a central gateway) or receives it on another bus.

Which variant applies depends on the transport:

LIN — bus-level only. LIN carries no NM message, so a LIN bus can only participate as a whole (via its master). The master itself may additionally hold its own membership in the same group (e.g. a central gateway that also participates with its own functions).
CAN — either variant, decided per CAN bus: node-level (its ECUs / controllers participate individually, per function) or bus-level (the whole CAN bus is one participant). Both are valid choices — neither is a default. Per CAN Bus choose one variant — node-level or bus-level — never both; mixing them for the same bus is rejected during validation.
Ethernet — node-level (its controllers / ECUs); Ethernet segments carry no bus-level object.

The two roles:

participant — references one or more relevance bits (the vehicle functions it takes part in, listed together in a single membership) and joins the wake/sleep decision.
observer — receives the group’s NM PDU and reacts to the group as a whole (e.g. a switch core pulling a wake line while the group is active); it watches the entire group, not individual bits, so it references no bit and never influences the decision.

Expand for a YAML example - 📄 state_memberships.flync.yaml

state_memberships:
- group: VEHICLE
  role: participant          # or: observer
  relevance_bits:            # vehicle functions this member references; list
    - AutonomousDriving      # several in ONE membership instead of
    - OnlineCommunication    # repeating the block; defaults to the
                             # entity name. Several members may share a
                             # bit. Absent for observers.

Each relevance bit has two states, requested and released; an entity that holds several bits or memberships sleeps only when all of them are released. The role is also the permission model: only participants may request the group state — setting a relevance bit — which is why declaring relevance_bits on an observer membership is rejected.

Transport independence and validation¶

The group’s NM PDU is bound to a transport with the ordinary PDU mechanisms:

Ethernet — a pdu_sender / pdu_receiver socket deployment, optionally through a Container PDU.
CAN / LIN — sender_frames / receiver_frames on the interface.

Validation cross-checks role against binding:

Check	Status
every referenced group exists in the registry	error
every group has at least one participant	error
the group’s references resolve — `nm_pdu` to a PDU flagged `pdu_usage: network_management`, `timing_profile` to a defined profile	error
role vs. transport binding: participants need a TX and an RX path, observers an RX path; a CAN bus member needs a frame binding plus an attached sender; a LIN bus member needs a master that knows the group state (as its source, or by receiving it on another bus)	error
a CAN bus uses a single membership variant (whole-bus or per-node), not both	error
redundant declarations	warning
every claimed relevance bit exists in the PDU’s vector	error
the group’s cycle time is plausible on every CAN bus carrying the NM PDU — physically feasible at the bus baud rate and consistent with the frame’s configured cyclic timing (LIN and Ethernet out of scope)	warning

Cross-bus forwarding¶

A group needs no coordinator object. When a group spans several buses, an ordinary gateway forwards its NM PDU from one bus onto the next using plain sender_frames / receiver_frames — the same mechanism any PDU uses to cross a bus. Each node reads the relevance vector it receives and applies the sleep decision locally, so the group’s behaviour emerges from ordinary forwarding plus each entity’s local sleep decision, not from a dedicated coordinating role.

In examples/flync_example the zonal_gateway does exactly this: it receives the VEHICLE NM PDU on Ethernet and forwards it onto BodyCAN through an ordinary Frame_Nm_Gateway sender frame.

Showcase¶

examples/flync_example exercises every use case: one vehicle-wide group (VEHICLE) across Ethernet, BodyCAN, DiagCAN, and BodyLIN, with relevance bits that are vehicle functions (AutonomousDriving / OnlineCommunication / Comfort), all three declaration sites, both roles, a gateway forwarding the NM PDU onto a CAN bus, an ECU referencing several function bits, and a LIN bus that participates without an NM frame. The walkthrough with the full use-case map lives in the NM section of the example documentation.