Sfa Manager Module

This module contains the SFA python manager for token parsing, loading, erasing, etc.

class mtf.diag_port.sfa.sfa_manager.EcuModes

The values for the different modes the ECU can be in.

PLANT
ENGINEERING
FIELD
class mtf.diag_port.sfa.sfa_manager.FeatureId

Feature ID structure of a secure token.

Provides the value, type, subtype, and application number of a secure token feature.

__init__(feature_id_bytes: str)

Create a new instance with the given feature ID.

Args:

feature_id_bytes: The feature ID as a hex string.

property value: int

Get the feature ID value.

property type: int

Get the feature ID type.

property subtype: int

Get the feature ID subtype.

property no: int

Get the feature ID application number.

class mtf.diag_port.sfa.sfa_manager.Feature

ECU feature retrieved via discovery.

__init__(feature_bytes: str)

Create a new instance from the given feature bytes.

Args:

feature_bytes: The ECU feature data as a hex string.

property id: FeatureId

Get the feature ID.

property status: int

Get the feature status.

property validation: int

Get the feature validation status.

property token_list: list

Get the token list.

property token_reset_list: list

Get the list of reset tokens.

property token_available: bool

Return True when at least one token is available.

class mtf.diag_port.sfa.sfa_manager.TokenTimestamp

Customised timestamp for a token.

str(instance) returns a human-readable Y-m-d H:M:S string. Use the value property for the original integral representation.

__init__(timestamp_bytes: int)

Create a new instance.

Args:

timestamp_bytes: Integral UNIX timestamp.

property value: int

Get the integral timestamp value.

class mtf.diag_port.sfa.sfa_manager.FeatureSpecificFields

Feature-specific field of a token.

__init__(token_bytes: str, offset: int)

Create a new instance.

Args:

token_bytes: The token values as a hex string. offset: Start offset within token_bytes.

class mtf.diag_port.sfa.sfa_manager.ValidityCondition

Validity condition of a token.

__init__(token_bytes: str, offset: int)

Create a new instance.

Args:

token_bytes: The token values as a hex string. offset: Start offset within token_bytes.

class mtf.diag_port.sfa.sfa_manager.Token

Implementation of a secure token.

__init__(token_path: str)

Create a new instance from the token file at token_path.

Args:

token_path: Path to the token data file.

match_ecuid(ecuid: str) → bool

Return True when the token matches the given ECU identifier.

match_vinid(vinid: str) → bool

Return True when the token matches the given VIN.

match_ecuid_and_vinid(vinid: str, ecuid: str) → bool

Return True when the token matches both ECU ID and VIN.

property name: str

Get the token name.

property path: str

Get the token path.

property length: int

Get the token length.

Get the token link type.

Get the token link-to ID.

property timestamp: TokenTimestamp

Get the token timestamp.

property feature_id: FeatureId

Get the token feature ID.

property enable_type: int

Get the token enable type.

property feature_specific_fields: list

Get the token’s feature-specific fields.

property raw: bytearray

Get the token as a byte array.

class mtf.diag_port.sfa.sfa_manager.SfaManager

SFA Manager – handles token parsing and all SFA-related functionality.

Important

The DiagManager must have been started and all required controllers registered before using this manager.

__init__()

Create a new instance.

set_up(token_path: str) → None

Configure the tokens directory.

Tokens are loaded lazily when first needed.

Args:

token_path: Directory that contains the token files.

add_ecu(connection_name: str, ecu_id: str | None = None, vin_id: str | None = None) → bool

Add an ECU identified by connection_name.

Args:

connection_name: The ECU connection name. ecu_id: Optional explicit ECU ID (auto-read when omitted). vin_id: Optional explicit VIN (auto-read when omitted).

Returns:

True on success, False on failure.

update_ecu(connection_name: str) → bool

Refresh the feature list for an already-added ECU.

Args:

connection_name: The ECU connection name.

Returns:

True on success, False on failure.

clean_ecu_list() → None

Clear all ECUs from the internal list.

handle_engineering_token_status(engineering_token_status: int) → None

Log a warning when the Engineering token is disabled or expired.

handle_plant_token_status(result: bool, plant_token_status: int, connection_name: str, switch_mode_retries: int) → bool

React to a non-nominal Plant token status.

Args:

result: Accumulated result flag. plant_token_status: Status byte returned by the ECU. connection_name: ECU connection name. switch_mode_retries: Retry count for mode-switch operations.

Returns:

Updated accumulated result, or False on hard failure.

switch_mode(connection_name: str, target_mode: EcuModes, switch_mode_retries: int = 5) → bool

Switch the ECU on connection_name to target_mode.

Args:

connection_name: ECU connection name. target_mode: Desired ECU mode. switch_mode_retries: Token-write retry count.

Returns:

True on success, False on failure.

handle_engineering_mode_switch(connection_name: str, current_mode: EcuModes, target_mode: EcuModes, switch_mode_retries: int) → bool

Handle the transition to Engineering Mode.

handle_field_mode_switch(connection_name: str, current_mode: EcuModes, target_mode: EcuModes, switch_mode_retries: int) → bool

Handle the transition to Field Mode.

handle_plant_mode_switch(connection_name: str, current_mode: EcuModes, target_mode: EcuModes, switch_mode_retries: int) → bool

Handle the transition to Plant Mode.

read_mode(connection_name: str) → EcuModes | None

Read and return the current ECU mode, or None on failure.

write_token(connection_name: str, feature_id: int, retries: int = 1) → bool

Write (enable) the token for feature_id on connection_name.

Args:

connection_name: ECU connection name. feature_id: Feature ID (hex int). retries: Maximum number of tokens to try.

Returns:

True on success, False on failure.

write_specific_token(connection_name: str, feature_id: int, token_index: int) → bool

Write a specific token identified by token_index.

Args:

connection_name: ECU connection name. feature_id: Feature ID (hex int). token_index: Index within the token list.

Returns:

True on success, False on failure.

set_feature_status(connection_name: str, feature_id: int, status: int) → bool

Enable (1) or disable (0) an ECU feature.

Args:

connection_name: ECU connection name. feature_id: Feature ID (hex int). status: 1 to enable, 0 to disable.

Returns:

True on success, False on failure.

read_status(connection_name: str, feature_id: int) → int | None

Read and return the status byte of feature_id, or None on failure.

read_sensitive_feature_status(connection_name: str, feature_id: int) → int | bool

Read and return the sensitive-feature status byte, or False on failure.

get_reset_token_from_all_tokens(connection_name: str | None = None, feature_id: int | None = None)

Return the reset token for feature_id, or None when not found.

write_sensitive_token(connection_name: str, feature_id: int, retries: int = 1, deactivate: bool = False) → bool

Enable or disable the sensitive feature identified by feature_id.

Args:

connection_name: ECU connection name. feature_id: Feature ID (hex int). retries: Maximum number of tokens to try. deactivate: When True, deactivate the feature instead.

Returns:

True on success, False on failure.

clear_feature(connection_name: str, feature_id: int) → bool

Clear feature_id on connection_name.

Temporarily switches to Engineering mode if required.

Args:

connection_name: ECU connection name. feature_id: Feature ID (hex int).

Returns:

True on success, False on failure.

clear_all_features(connection_name: str) → bool

Clear all features written during this session.

Args:

connection_name: ECU connection name.

Returns:

True when every feature was cleared, False otherwise.

clear_all_features_mode(connection_name: str, original_mode: EcuModes) → bool

Clear all session features when already in Engineering mode.

Args:

connection_name: ECU connection name. original_mode: Current (and expected Engineering) mode.

Returns:

True on full success, False otherwise.

fallback_field_mode(connection_name: str, safe_mode: bool = True) → bool

Fall back to Field mode.

Args:

connection_name: ECU connection name. safe_mode: When True, refuses fallback if no further

Engineering tokens are available.

Returns:

True on success, False on failure.

property vin_id: str | None

Get the Vehicle Identification Number.

get_ecu_id(connection_name: str) → str | None

Return the ECU ID for connection_name.

get_vin_id(connection_name: str) → str | None

Return the Vehicle Identification Number for connection_name.

property token_list: list

Get the full token list.

property token_reset_list: list

Get the reset-token list.