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.

The FeatureId structure 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 (str): The feature ID.
Returns:: FeatureId: The newly created instance.

property value

Get the feature ID value.

Returns:: int: The feature ID value.

property type

Get the feature ID type.

Returns:: int: The feature ID type.

property subtype

Get the feature ID subtype.

Returns:: int: The feature ID subtype.

property no

Get the feature ID app number.

Returns:: int: The feature ID application number.

class mtf.diag_port.sfa.sfa_manager.Feature

ECU feature implementation.

This class contains all the information related with a feature retrieved from an ECU via discovery.

__init__(feature_bytes: str)

Create a new instance using the given feature.

Args:: feature_bytes (str): The ECU feature data.
Returns:: Feature: The newly created instance.

property id

Get the feature ID.

Returns:: int: The feature ID value.

property status

Get the feature status.

Returns:: int: The feature status.

property validation

Get the feature validation status.

Returns:: int: The feature validation status.

property token_list

Get the tokens list.

Returns:: list: The list of tokens.

property token_available

Get whether there are tokens available.

Returns:: bool: True if tokens are available, False otherwise.

class mtf.diag_port.sfa.sfa_manager.TokenTimestamp

Timestamp of a token.

This class contains a customized timestamp object of a token. In order to be used easily, when retrieving the object as str, the output is the timestamp value in a readable format (Y-m-d H:M:S). The attribute “value” can be used to get the original hexadecimal value.

__init__(timestamp_bytes)

Create a new instance.

Args:: timestamp_bytes (int): The integral timestamp representation.
Returns:: TokenTimestamp: The newly created instance.

property value

Get the integral timestamp value.

Returns:: int: 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 using the given parameters.

Args:: token_bytes (str): The token values. offset (int): The offset to start interpreting the value from.
Returns:: FeatureSpecificFields: The newly created instance.

class mtf.diag_port.sfa.sfa_manager.ValidityCondition

Represent the validity condition of the token.

__init__(token_bytes: str, offset: int)

Create a new instance using the given parameters.

Args:: token_bytes (str): The token value(s). offset (int): The offset where to start parsing the data.
Returns:: ValidityCondition: The newly created instance.

class mtf.diag_port.sfa.sfa_manager.Token

Implementation of a secure token.

__init__(token_path)

Create a new instance from the data in the given path.

Args:: token_path (str): The path to the token data.
Returns:: Token: The newly created instance.

match_ecuid(ecuid)

check whether the token matches the provided ecu identifier.

Args:: ecuid (int): The ECU ID to match.
Returns:: bool: True on a match, False otherwise.

match_vinid(vinid)

check whether the token matches the provided VIN (Vehicle identification Number).

Args:: vinid (str): The VIN to check.
Returns:: bool: True on match, False otherwise.

match_ecuid_and_vinid(vinid, ecuid)

check wether the token matches both the given ECU ID and VIN.

Args:: ecuid (int): The ECU ID to check. vinid (str): The VIN to check.
Returns:: bool: True on success, False otherwise.

property name: Get the token name.

property length: Get the token length.

property link_type: Get the token link type.

property link_to_id: Get the token link to id.

property timestamp: Get the token timestamp.

property feature_id: Get the token feature id.

property enable_type: Get the token enable type.

property feature_specific_fields: Get the token’s feature specific fields.

property raw: Get the token as a byte array.

class mtf.diag_port.sfa.sfa_manager.SfaManager

(SFA) Manager implementation.

This class implements a manager to handle token parsing, use all functionality related to sfa coming from TDFNext.

Note:

Important

In order for the SFA Manager to work properly the diag manager must already have been started and all needed controllers must have been added as well.

__init__(): Create a new instance.

set_up(token_path: str)

Parse all tokens from the given path and set up the environment.

Args:: token_path (str): The path to parse tokens from.

Note:

Important

This method must be called before any other token-related method may be executed.

add_ecu(connection_name: str, ecu_id: str = None, vin_id: str = None)

Add an ECU defined by the given parameters.

Args:: connection_name (str): The name of the connection. ecu_id (str): The ID of the ECU to be added. vin_id (str): The Vehicle Identification Number of the ECU.
Returns:: bool: True if the operation was successful, False otherwise.

Note:

Note

This function adds an ECU to the list with all its tokens, checks if the tokens are available in the ECU by sending corresponding diagnosis jobs.

update_ecu(connection_name)

Update the ECU state defined by the given connection.

Args:: connection_name (str): The name of the connection / ECU to be updated.
Returns:: bool: True on success, False otherwise.

clean_ecu_list(): Clean the ECU list.

handle_engineering_token_status(engineering_token_status)

Check the given Engineering token status.

Args:: engineering_token_status (int): The engineering token status.

Note:

Note

If Engineering token is Disabled (status == 2) or Expired (status == 03) we need to generate new tokens.

handle_plant_token_status(result, plant_token_status, connection_name, switch_mode_retries)

Check the plant token status of the given connection.

Args:: result (int): The result code of the operation. plant_token_status (int): The plant token status value. connection_name (str): The name of the connection to chck on. switch_mode_retries (int): The number of retries before giving up.
Returns:: bool: True on success, False otherwise.

Note:

Note

On status codes 0x01 (Enabled), 0x02 (Disabled), and 0x03 (Expired) the token will be recovered, if possible.

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

Switch an ECU on the given connection to the given mode.

Args:: connection_name (str): The of the connection /ECU. target_mode (EcuModes): The ECU modeto switch to. switch_mode_retries (int): The number of retries before giving up (default: 5).
Returns:: bool: True on success, False otherwise.

handle_engineering_mode_switch(connection_name, current_mode, target_mode, switch_mode_retries)

Handle the switching process to Engineering Mode.

Args:: connection_name (str): The name of the connection / ECU. current_mode (EcuModes): The current ECU mode. target_mode (EcuModes): UNUSED. TODO: Remove this parameter. switch_mode_retries (int): The number of retries before giving up.
Returns:: bool: True on success, False otherwise.

handle_field_mode_switch(connection_name, current_mode, target_mode, switch_mode_retries)

Handle the switching process to FieldMode.

Args:: connection_name (str): The name of the connection / ECU. current_mode (EcuModes): The current ECU mode. target_mode (EcuModes): UNUSED. TODO: Remove this parameter. switch_mode_retries (int): The number of retries before giving up.
Returns:: bool: True on success, False otherwise.

handle_plant_mode_switch(connection_name, current_mode, target_mode, switch_mode_retries)

Handle the switching process to PlantMode.

Args:: connection_name (str): The name of the connection / ECU. current_mode (EcuModes): The current ECU mode. target_mode (EcuModes): UNUSED. TODO: Remove this parameter. switch_mode_retries (int): The number of retries before giving up.
Returns:: bool: True on success, False otherwise.

read_mode(connection_name: str)

Read the current ECU mode of the given connection.

Args:: connection_name (str): The name of the connection / ECU.
Returns:: EcuModes or None: The current ECU mode or None.

write_token(connection_name: str, feature_id: hex, retries=1)

Enable the given feature in ghe gven ECU.

Args:: connection_name (str): The name of the connetcion / ECU. feature_id (hex): The hexadecimal feature ID to enable. retries (int): The number of retries before giving up (default: 1).
Returns:: bool: True on success, False otherwise.

Note:

Note

The manager will start from the oldest token within that retry window until the newest token available in the list.

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

Enable the given feature in the given ECU using the given token.

Args:: connection_name (str): The name of the connection / ECU. feature_id (hex): The hexadecimal feature ID to enable. token_index (int): The index of the token to use.
Returns:: bool: True on sucess, False otherwise.

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

Enable or disable an ECU feature according to the given parameters.

Args:: connection_name (str): The name of the connection / ECU. feature_id (hex): The hexadecimal feature ID. status (int): Set to 1 to enable or 0 to disable the feature.
Returns:: bool: True on success, False otherwise.

read_status(connection_name: str, feature_id: hex)

Read the status of the given feature.

Args:: connection_name (str): The name of the connection / ECU. feature_id (hex): The hexadecimal feature ID.
Returns:: int or None: 1 if the feature is enabled, 0 if it is disabled, and None otherwise.

read_sensitive_feature_status(connection_name: str, feature_id: hex)

Read the status of the given feature.

Args:: connection_name (str): The name of the connection / ECU. feature_id (hex): The hexadecimal feature ID.
Returns:: int or None: 1 if the feature is enabled, 0 if it is disabled, and None otherwise.

write_sensitive_token(connection_name: str, feature_id: hex, retries=1)

Enable the given feature in ghe gven ECU.

Args:: connection_name (str): The name of the connetcion / ECU. feature_id (hex): The hexadecimal feature ID to enable. retries (int): The number of retries before giving up (default: 1).
Returns:: bool: True on success, False otherwise.

Note:

Note

The manager will start from the oldest token within that retry window until the newest token available in the list.

clear_feature(connection_name: str, feature_id: hex)

Clear the given featurein the given ECU.

Args:: connection_name (str): The name of te connection / ECU. feature_id (hex): The hexadecimal feature ID.
Returns:: bool: True on success, False otherwise.

Note:

Important

In order to clear a feature the ECU must be in Engineering Mode.

clear_all_features(connection_name: str)

Clear all features eabled previously in this session.

Args:: connection_name (str): The name of the connection / ECU.
Returns:: bool: True on success, False otherwise.

Note:

Important

In order to clear features the ECU must be in Engineering Mode, thus the Engineering Mode enabling token must not have been cleared in advance.

clear_all_features_mode(connection_name: str, original_mode)

Clear all session features.

Args:: connection_name (str): The name of the connection / ECU. original_mode (str): The current ECU mode.
Returns:: bool: True on success, False otherwise.

Note:

Important

In order to clear features the ECU must be in Engineering Mode, thus the Engineering Mode enabling token must not have been cleared in advance.

fallback_field_mode(connection_name: str, safe_mode=True)

Fall back to field mode.

Args:: connection_name (str): The name of the connection / ECU. safe_mode (bool): Whether or not to check for ENG tokens before falling back (default: True).
Returns:: bool: True on success, False otherwise

Note:

Note

This function sets the ecu back to FIELD mode from ENGINEERING or PLANT mode. If the safe_mode parameter is set to False, the function will skip checking whether there is at least, one ENG token available to go back to engineering mode if needed for token clearing.

property vin_id: Get the VIN (Vehicle Identification Number).

get_vin_id(connection_name: str)

Retrieve the VIN (Vehicle Identification Number).

Args:: connection_name (str): The name of the target ECU.
Returns:: str: The entire VIN or None if an error occurred.

property token_list: Get the tokens list.

get_ecu_id(connection_name)

Get the ECU ID.

Args:: connection_name (str): The name of the connection.
Returns:: string: The ECU ID.