AgIsoStack++
A control-function-focused implementation of the major ISOBUS and J1939 protocols
Loading...
Searching...
No Matches
Classes | Public Types | Public Member Functions | Public Attributes | Private Types | Private Member Functions | Static Private Member Functions | Private Attributes | Static Private Attributes | List of all members
isobus::DiagnosticProtocol Class Reference

Manages the DM1, DM2, and DM3 messages for ISO11783 or J1939. More...

#include <isobus_diagnostic_protocol.hpp>

Collaboration diagram for isobus::DiagnosticProtocol:
[legend]

Classes

class  DiagnosticTroubleCode
 A storage class for describing a complete DTC. More...
 
struct  DM22Data
 A structure to hold data about DM22 responses we need to send. More...
 

Public Types

enum class  ECUIdentificationFields : std::uint8_t {
  PartNumber = 0 , SerialNumber , Location , Type ,
  ManufacturerName , HardwareID , NumberOfFields
}
 Enumerates the different fields in the ECU identification message. More...
 
enum class  LampStatus {
  None , MalfunctionIndicatorLampSolid , MalfunctionIndicatorLampSlowFlash , MalfunctionIndicatorLampFastFlash ,
  RedStopLampSolid , RedStopLampSlowFlash , RedStopLampFastFlash , AmberWarningLampSolid ,
  AmberWarningLampSlowFlash , AmberWarningLampFastFlash , EngineProtectLampSolid , EngineProtectLampSlowFlash ,
  EngineProtectLampFastFlash
}
 The DTC lamp status as defined in J1939-73. Not used when in ISO11783 mode. More...
 
enum class  FailureModeIdentifier {
  DataValidAboveNormalMostSevere = 0 , DataValidBelowNormalMostSevere = 1 , DataErratic = 2 , VoltageAboveNormal = 3 ,
  VoltageBelowNormal = 4 , CurrentBelowNormal = 5 , CurrentAboveNormal = 6 , MechanicalSystemNotResponding = 7 ,
  AbnormalFrequency = 8 , AbnormalUpdateRate = 9 , AbnormalRateOfChange = 10 , RootCauseNotKnown = 11 ,
  BadIntelligentDevice = 12 , OutOfCalibration = 13 , SpecialInstructions = 14 , DataValidAboveNormalLeastSevere = 15 ,
  DataValidAboveNormalModeratelySevere = 16 , DataValidBelowNormalLeastSevere = 17 , DataValidBelowNormalModeratelySevere = 18 , ReceivedNetworkDataInError = 19 ,
  ConditionExists = 31
}
 FMI as defined in ISO11783-12 Annex E. More...
 
enum class  TransmitFlags {
  DM1 = 0 , DM2 , DiagnosticProtocolID , ProductIdentification ,
  DM22 , ECUIdentification , SoftwareIdentification , NumberOfFlags
}
 A set of transmit flags to manage sending DM1, DM2, and protocol ID. More...
 
enum class  NetworkType : std::uint8_t {
  SAEJ1939Network1PrimaryVehicleNetwork = 0 , SAEJ1922Network = 1 , SAEJ1587Network = 2 , CurrentDataLink = 3 ,
  OtherManufacturerSpecifiedPort = 4 , SAEJ1850Network = 5 , ISO9141Network = 6 , SAEJ1939Network2 = 7 ,
  SAEJ1939Network4 = 8 , ProprietaryNetwork2 = 9 , ProprietaryNetwork1 = 10 , SAEJ1939Network3 = 11 ,
  SAEJ1939Network5 = 25 , SAEJ1939Network6 = 26 , SAEJ1939Network7 = 27 , SAEJ1939Network8 = 28 ,
  SAEJ1939Network11 = 29 , SAEJ1939Network10 = 30 , SAEJ1939Network9 = 31 , Reserved = 32
}
 Enumerates the different networks in the DM13. More...
 
enum class  StopStartCommand : std::uint8_t { StopBroadcast = 0 , StartBroadcast = 1 , Reserved = 2 , DontCareNoAction = 3 }
 Enumerates the commands in the DM13. More...
 
enum class  SuspendSignalState : std::uint8_t {
  IndefiniteSuspension = 0 , PartialIndefiniteSuspension = 1 , TemporarySuspension = 2 , PartialTemporarySuspension = 3 ,
  Resuming = 4 , NotAvailable = 15
}
 Enumerates the different suspend signals for DM13. More...
 

Public Member Functions

 DiagnosticProtocol (std::shared_ptr< InternalControlFunction > internalControlFunction, NetworkType networkType=NetworkType::ProprietaryNetwork1)
 The constructor for this protocol.
 
 ~DiagnosticProtocol ()
 The destructor for this protocol.
 
bool initialize ()
 The protocol's initializer function.
 
bool get_initialized () const
 Returns if the protocol has been initialized.
 
void terminate ()
 The protocol's terminate function.
 
void update ()
 Updates the diagnostic protocol.
 
void set_j1939_mode (bool value)
 Enables the protocol to run in J1939 mode instead of ISO11783 mode.
 
bool get_j1939_mode () const
 Returns true if the protocol is in J1939 mode instead of ISO11783 mode, false if using ISO11783 mode.
 
void clear_active_diagnostic_trouble_codes ()
 Clears the list of active DTCs and makes them all inactive.
 
void clear_inactive_diagnostic_trouble_codes ()
 Clears the list of inactive DTCs and clears occurrence counts.
 
void clear_software_id_fields ()
 Clears all previously configured software ID fields set with set_software_id_field.
 
void set_ecu_id_field (ECUIdentificationFields field, const std::string &value)
 Sets one of the ECU identification strings for the ECU ID message.
 
bool set_diagnostic_trouble_code_active (const DiagnosticTroubleCode &dtc, bool active)
 Adds a DTC to the active list, or removes one from the active list.
 
bool get_diagnostic_trouble_code_active (const DiagnosticTroubleCode &dtc)
 Returns if a DTC is active.
 
bool set_product_identification_code (const std::string &value)
 Sets the product ID code used in the diagnostic protocol "Product Identification" message (PGN 0xFC8D)
 
bool set_product_identification_brand (const std::string &value)
 Sets the product identification brand used in the diagnostic protocol "Product Identification" message (PGN 0xFC8D)
 
bool set_product_identification_model (const std::string &value)
 Sets the product identification model used in the diagnostic protocol "Product Identification" message (PGN 0xFC8D)
 
void set_software_id_field (std::uint32_t index, const std::string &value)
 Adds an ascii string to this internal control function's software ID.
 
bool suspend_broadcasts (std::uint16_t suspendTime_seconds=0xFFFF)
 Informs the diagnostic protocol that you are going to suspend broadcasts.
 
bool get_broadcast_state () const
 Gets the current broadcast state for the connected network type.
 

Public Attributes

ControlFunctionFunctionalities ControlFunctionFunctionalitiesMessageInterface
 Use this interface to configure your CF's functionalities. This info will be reported to any ECU that requests it and you are required to support it on an ISOBUS.
 

Private Types

enum class  Lamps { MalfunctionIndicatorLamp , RedStopLamp , AmberWarningLamp , ProtectLamp }
 Lists the different lamps in J1939-73. More...
 
enum class  FlashState { Solid , Slow , Fast }
 Enumerates lamp flash states in J1939. More...
 
enum class  DM22ControlByte : std::uint8_t {
  RequestToClearPreviouslyActiveDTC = 0x01 , PositiveAcknowledgeOfPreviouslyActiveDTCClear = 0x02 , NegativeAcknowledgeOfPreviouslyActiveDTCClear = 0x03 , RequestToClearActiveDTC = 0x11 ,
  PositiveAcknowledgeOfActiveDTCClear = 0x12 , NegativeAcknowledgeOfActiveDTCClear = 0x13
}
 The DM22 multiplexer bytes. All bytes not given a value here are reserved by SAE. More...
 
enum class  DM22NegativeAcknowledgeIndicator : std::uint8_t {
  General = 0x00 , AccessDenied = 0x01 , UnknownOrDoesNotExist = 0x02 , DTCNoLongerPreviouslyActive = 0x03 ,
  DTCNoLongerActive = 0x04
}
 The negative acknowledge (NACK) reasons for a DM22 message. More...
 

Private Member Functions

std::uint8_t convert_flash_state_to_byte (FlashState flash) const
 A utility function to get the CAN representation of a FlashState.
 
void get_active_list_lamp_state_and_flash_state (Lamps targetLamp, FlashState &flash, bool &lampOn) const
 This is a way to find the overall lamp states to report.
 
void get_inactive_list_lamp_state_and_flash_state (Lamps targetLamp, FlashState &flash, bool &lampOn) const
 This is a way to find the overall lamp states to report.
 
void on_address_violation (std::shared_ptr< InternalControlFunction > affectedControlFunction)
 A callback function used to consume address violation events and activate a DTC as required in ISO11783-5.
 
bool send_diagnostic_message_1 () const
 Sends a DM1 encoded CAN message.
 
bool send_diagnostic_message_2 () const
 Sends a DM2 encoded CAN message.
 
bool send_diagnostic_protocol_identification () const
 Sends a message that identifies which diagnostic protocols are supported.
 
bool send_dm13_announce_suspension (std::uint16_t suspendTime_seconds) const
 Sends the DM13 to alert network devices of impending suspended broadcasts.
 
bool send_ecu_identification () const
 Sends the ECU ID message.
 
bool send_product_identification () const
 Sends the product identification message (PGN 0xFC8D)
 
bool send_software_identification () const
 Sends the software ID message.
 
bool process_all_dm22_responses ()
 Processes any DM22 responses from the queue.
 
void process_message (const CANMessage &message)
 A generic way for a protocol to process a received message.
 
bool parse_j1939_network_states (const CANMessage &message)
 Parses out the DM13 J1939 network states from a CAN message.
 
bool process_parameter_group_number_request (std::uint32_t parameterGroupNumber, std::shared_ptr< ControlFunction > requestingControlFunction, bool &acknowledge, AcknowledgementType &acknowledgementType)
 Handles PGN requests for the diagnostic protocol.
 

Static Private Member Functions

static void process_message (const CANMessage &message, void *parent)
 A generic way for a protocol to process a received message.
 
static bool process_parameter_group_number_request (std::uint32_t parameterGroupNumber, std::shared_ptr< ControlFunction > requestingControlFunction, bool &acknowledge, AcknowledgementType &acknowledgementType, void *parentPointer)
 
static void process_flags (std::uint32_t flag, void *parentPointer)
 A generic callback for a the class to process flags from the ProcessingFlags
 

Private Attributes

std::shared_ptr< InternalControlFunctionmyControlFunction
 The internal control function that this protocol will send from.
 
EventCallbackHandle addressViolationEventHandle
 Stores the handle from registering for address violation events.
 
NetworkType networkType
 The diagnostic network type that this protocol will use.
 
std::vector< DiagnosticTroubleCodeactiveDTCList
 Keeps track of all the active DTCs.
 
std::vector< DiagnosticTroubleCodeinactiveDTCList
 Keeps track of all the previously active DTCs.
 
std::vector< DM22Datadm22ResponseQueue
 Maintaining a list of DM22 responses we need to send to allow for retrying in case of Tx failures.
 
std::vector< std::string > ecuIdentificationFields
 Stores the ECU ID fields so we can transmit them when ECU ID's PGN is requested.
 
std::vector< std::string > softwareIdentificationFields
 Stores the Software ID fields so we can transmit them when the PGN is requested.
 
ProcessingFlags txFlags
 An instance of the processing flags to handle retries of some messages.
 
std::string productIdentificationCode
 The product identification code for sending the product identification message.
 
std::string productIdentificationBrand
 The product identification brand for sending the product identification message.
 
std::string productIdentificationModel
 The product identification model name for sending the product identification message.
 
std::uint32_t lastDM1SentTimestamp = 0
 A timestamp in milliseconds of the last time a DM1 was sent.
 
std::uint32_t lastDM13ReceivedTimestamp = 0
 A timestamp in milliseconds when we last got a DM13 message.
 
std::uint16_t customDM13SuspensionTime = 0
 If using a non-standard DM13 suspension time, this tracks that duration in milliseconds.
 
bool broadcastState = true
 Bitfield for tracking the network broadcast state for DM13.
 
bool j1939Mode = false
 Tells the protocol to operate according to J1939 instead of ISO11783.
 
bool initialized = false
 Stores if the interface has been initialized.
 

Static Private Attributes

static constexpr std::uint32_t DM_MAX_FREQUENCY_MS = 1000
 You are technically allowed to send more than this under limited circumstances, but a hard limit saves 4 RAM bytes per DTC and has BAM benefits.
 
static constexpr std::uint32_t DM13_HOLD_SIGNAL_TRANSMIT_INTERVAL_MS = 5000
 Defined in 5.7.13.13 SPN 1236.
 
static constexpr std::uint32_t DM13_TIMEOUT_MS = 6000
 The timeout in 5.7.13 after which nodes shall revert back to the normal broadcast state.
 
static constexpr std::uint16_t MAX_PAYLOAD_SIZE_BYTES = 1785
 DM 1 and 2 are limited to the BAM message max, because ETP does not allow global destinations.
 
static constexpr std::uint16_t MAX_DM13_CUSTOM_SUSPEND_TIME_MS = 64255
 The max valid value for a DM13 suspension time in milliseconds.
 
static constexpr std::uint8_t DM_PAYLOAD_BYTES_PER_DTC = 4
 The number of payload bytes per DTC that gets encoded into the messages.
 
static constexpr std::uint8_t PRODUCT_IDENTIFICATION_MAX_STRING_LENGTH = 50
 The max string length allowed in the fields of product ID, as defined in ISO 11783-12.
 
static constexpr std::uint8_t DM13_NUMBER_OF_J1939_NETWORKS = 11
 The number of networks in DM13 that are set aside for J1939.
 
static constexpr std::uint8_t DM13_NETWORK_BITMASK = 0x03
 Used to mask the network SPN values.
 
static constexpr std::uint8_t DM13_BITS_PER_NETWORK = 2
 Number of bits for the network SPNs.
 

Detailed Description

Manages the DM1, DM2, and DM3 messages for ISO11783 or J1939.

Definition at line 54 of file isobus_diagnostic_protocol.hpp.

Member Enumeration Documentation

◆ DM22ControlByte

enum class isobus::DiagnosticProtocol::DM22ControlByte : std::uint8_t
strongprivate

The DM22 multiplexer bytes. All bytes not given a value here are reserved by SAE.

Enumerator
RequestToClearPreviouslyActiveDTC 

Clear a previously active DTC.

PositiveAcknowledgeOfPreviouslyActiveDTCClear 

ACK for clearing a previously active DTC.

NegativeAcknowledgeOfPreviouslyActiveDTCClear 

NACK for clearing a previously active DTC.

RequestToClearActiveDTC 

Clear an active DTC.

PositiveAcknowledgeOfActiveDTCClear 

ACK clearing an active DTC.

NegativeAcknowledgeOfActiveDTCClear 

NACK clearing an active DTC.

Definition at line 347 of file isobus_diagnostic_protocol.hpp.

◆ DM22NegativeAcknowledgeIndicator

enum class isobus::DiagnosticProtocol::DM22NegativeAcknowledgeIndicator : std::uint8_t
strongprivate

The negative acknowledge (NACK) reasons for a DM22 message.

Enumerator
General 

General negative acknowledge.

AccessDenied 

Security denied access.

UnknownOrDoesNotExist 

The DTC is unknown or does not exist.

DTCNoLongerPreviouslyActive 

The DTC in in the active list but it was requested to clear from inactive list.

DTCNoLongerActive 

DTC is inactive, not active, but active was requested to be cleared.

Definition at line 358 of file isobus_diagnostic_protocol.hpp.

◆ ECUIdentificationFields

enum class isobus::DiagnosticProtocol::ECUIdentificationFields : std::uint8_t
strong

Enumerates the different fields in the ECU identification message.

Enumerator
PartNumber 

The part number of the physical ECU.

SerialNumber 

The serial number of the physical ECU.

Location 

The location of the ECU within a network.

Type 

The type of ECU. One example of a use of the ECU type could be for classifying ECU capabilities, such as I/O.

ManufacturerName 

Manufacturer name string.

HardwareID 

ISO 11783 only, This parameter is used to associate the hardware version of an ECU connected to the ISO 11783 network to a conformance test report of that hardware.

NumberOfFields 

The number of fields currently defined in the ISO standard.

Definition at line 58 of file isobus_diagnostic_protocol.hpp.

◆ FailureModeIdentifier

FMI as defined in ISO11783-12 Annex E.

Enumerator
DataValidAboveNormalMostSevere 

Condition is above normal as determined by the predefined most severe level limits for that particular measure of the condition.

DataValidBelowNormalMostSevere 

Condition is below normal as determined by the predefined most severe level limits for that particular measure of the condition.

DataErratic 

Erratic or intermittent data include all measurements that change at a rate not considered possible in real - world conditions.

VoltageAboveNormal 

A voltage signal, data or otherwise, is above the predefined limits that bound the range.

VoltageBelowNormal 

A voltage signal, data or otherwise, is below the predefined limits that bound the range.

CurrentBelowNormal 

A current signal, data or otherwise, is below the predefined limits that bound the range.

CurrentAboveNormal 

A current signal, data or otherwise, is above the predefined limits that bound the range.

MechanicalSystemNotResponding 

Any fault that is detected as the result of an improper mechanical adjustment, an improper response or action of a mechanical system.

AbnormalFrequency 

Any frequency or PWM signal that is outside the predefined limits which bound the signal range for frequency or duty cycle.

AbnormalUpdateRate 

Any failure that is detected when receipt of data through the data network is not at the update rate expected or required.

AbnormalRateOfChange 

Any data, exclusive of FMI 2, that are considered valid but which are changing at a rate that is outside the predefined limits that bound the rate of change for the system.

RootCauseNotKnown 

It has been detected that a failure has occurred in a particular subsystem but the exact nature of the fault is not known.

BadIntelligentDevice 

Internal diagnostic procedures have determined that the failure is one which requires the replacement of the ECU.

OutOfCalibration 

A failure that can be identified as the result of improper calibration.

SpecialInstructions 

Used when the on-board system can isolate the failure to a small number of choices but not to a single point of failure. See 11783-12 Annex E.

DataValidAboveNormalLeastSevere 

Condition is above what would be considered normal as determined by the predefined least severe level limits for that particular measure of the condition.

DataValidAboveNormalModeratelySevere 

Condition is above what would be considered normal as determined by the predefined moderately severe level limits for that particular measure of the condition.

DataValidBelowNormalLeastSevere 

Condition is below what would be considered normal as determined by the predefined least severe level limits for that particular measure of the condition.

DataValidBelowNormalModeratelySevere 

Condition is below what would be considered normal as determined by the predefined moderately severe level limits for that particular measure of the condition.

ReceivedNetworkDataInError 

Any failure that is detected when the data received through the network are found replaced by the �error indicator� value 0xFE.

ConditionExists 

The condition that is identified by the SPN exists when no applicable FMI exists (any other error)

Definition at line 88 of file isobus_diagnostic_protocol.hpp.

◆ FlashState

enum class isobus::DiagnosticProtocol::FlashState
strongprivate

Enumerates lamp flash states in J1939.

Enumerator
Solid 

Solid / no flash.

Slow 

Slow flash.

Fast 

Fast flash.

Definition at line 339 of file isobus_diagnostic_protocol.hpp.

◆ Lamps

enum class isobus::DiagnosticProtocol::Lamps
strongprivate

Lists the different lamps in J1939-73.

Enumerator
MalfunctionIndicatorLamp 

The "MIL".

RedStopLamp 

The "RSL".

AmberWarningLamp 

The "AWL".

ProtectLamp 

The engine protect lamp.

Definition at line 330 of file isobus_diagnostic_protocol.hpp.

◆ LampStatus

The DTC lamp status as defined in J1939-73. Not used when in ISO11783 mode.

Enumerator
MalfunctionIndicatorLampSolid 

A lamp used to relay only emissions-related trouble code information.

MalfunctionIndicatorLampSlowFlash 

A lamp used to relay only emissions-related trouble code information.

MalfunctionIndicatorLampFastFlash 

A lamp used to relay only emissions-related trouble code information.

RedStopLampSolid 

This lamp is used to relay trouble code information that is of a severe-enough condition that it warrants stopping the vehicle.

RedStopLampSlowFlash 

This lamp is used to relay trouble code information that is of a severe-enough condition that it warrants stopping the vehicle.

RedStopLampFastFlash 

This lamp is used to relay trouble code information that is of a severe-enough condition that it warrants stopping the vehicle.

AmberWarningLampSolid 

This lamp is used to relay trouble code information that is reporting a problem with the vehicle system but the vehicle need not be immediately stopped.

AmberWarningLampSlowFlash 

This lamp is used to relay trouble code information that is reporting a problem with the vehicle system but the vehicle need not be immediately stopped.

AmberWarningLampFastFlash 

This lamp is used to relay trouble code information that is reporting a problem with the vehicle system but the vehicle need not be immediately stopped.

EngineProtectLampSolid 

This lamp is used to relay trouble code information that is reporting a problem with a vehicle system that is most probably not electronic sub-system related.

EngineProtectLampSlowFlash 

This lamp is used to relay trouble code information that is reporting a problem with a vehicle system that is most probably not electronic sub-system related.

EngineProtectLampFastFlash 

This lamp is used to relay trouble code information that is reporting a problem with a vehicle system that is most probably not electronic sub-system related.

Definition at line 70 of file isobus_diagnostic_protocol.hpp.

◆ NetworkType

enum class isobus::DiagnosticProtocol::NetworkType : std::uint8_t
strong

Enumerates the different networks in the DM13.

Definition at line 128 of file isobus_diagnostic_protocol.hpp.

◆ StopStartCommand

enum class isobus::DiagnosticProtocol::StopStartCommand : std::uint8_t
strong

Enumerates the commands in the DM13.

Enumerator
StopBroadcast 

Stop broadcast.

StartBroadcast 

Start broadcast.

Reserved 

SAE Reserved.

DontCareNoAction 

Don’t Care/take no action (leave as is)

Definition at line 153 of file isobus_diagnostic_protocol.hpp.

◆ SuspendSignalState

enum class isobus::DiagnosticProtocol::SuspendSignalState : std::uint8_t
strong

Enumerates the different suspend signals for DM13.

Enumerator
IndefiniteSuspension 

Indefinite suspension of all broadcasts.

PartialIndefiniteSuspension 

Indefinite suspension of some messages.

TemporarySuspension 

Temporary suspension of all broadcasts.

PartialTemporarySuspension 

Temporary suspension of some messages.

Resuming 

Resuming normal broadcast pattern.

Definition at line 162 of file isobus_diagnostic_protocol.hpp.

◆ TransmitFlags

A set of transmit flags to manage sending DM1, DM2, and protocol ID.

Enumerator
DM1 

A flag to manage sending the DM1 message.

DM2 

A flag to manage sending the DM2 message.

DiagnosticProtocolID 

A flag to manage sending the Diagnostic protocol ID message.

ProductIdentification 

A flag to manage sending the product identification message.

DM22 

Process queued up DM22 responses.

ECUIdentification 

A flag to manage sending the ECU ID message.

SoftwareIdentification 

A flag to manage sending the software ID message.

NumberOfFlags 

The number of flags in the enum.

Definition at line 114 of file isobus_diagnostic_protocol.hpp.

Constructor & Destructor Documentation

◆ DiagnosticProtocol()

isobus::DiagnosticProtocol::DiagnosticProtocol ( std::shared_ptr< InternalControlFunction > internalControlFunction,
NetworkType networkType = NetworkType::ProprietaryNetwork1 )

The constructor for this protocol.

Parameters
[in]internalControlFunctionThe internal control function that owns this protocol and will be used to send messages
[in]networkTypeThe type of diagnostic network that this protocol will reflect

Definition at line 77 of file isobus_diagnostic_protocol.cpp.

◆ ~DiagnosticProtocol()

isobus::DiagnosticProtocol::~DiagnosticProtocol ( )

The destructor for this protocol.

Definition at line 91 of file isobus_diagnostic_protocol.cpp.

Here is the call graph for this function:

Member Function Documentation

◆ clear_active_diagnostic_trouble_codes()

void isobus::DiagnosticProtocol::clear_active_diagnostic_trouble_codes ( )

Clears the list of active DTCs and makes them all inactive.

Definition at line 205 of file isobus_diagnostic_protocol.cpp.

Here is the caller graph for this function:

◆ clear_inactive_diagnostic_trouble_codes()

void isobus::DiagnosticProtocol::clear_inactive_diagnostic_trouble_codes ( )

Clears the list of inactive DTCs and clears occurrence counts.

Definition at line 216 of file isobus_diagnostic_protocol.cpp.

Here is the caller graph for this function:

◆ clear_software_id_fields()

void isobus::DiagnosticProtocol::clear_software_id_fields ( )

Clears all previously configured software ID fields set with set_software_id_field.

Definition at line 221 of file isobus_diagnostic_protocol.cpp.

◆ convert_flash_state_to_byte()

std::uint8_t isobus::DiagnosticProtocol::convert_flash_state_to_byte ( FlashState flash) const
private

A utility function to get the CAN representation of a FlashState.

Parameters
flashThe flash state to convert
Returns
The two bit lamp state for CAN

Definition at line 377 of file isobus_diagnostic_protocol.cpp.

Here is the caller graph for this function:

◆ get_active_list_lamp_state_and_flash_state()

void isobus::DiagnosticProtocol::get_active_list_lamp_state_and_flash_state ( Lamps targetLamp,
FlashState & flash,
bool & lampOn ) const
private

This is a way to find the overall lamp states to report.

This searches the active DTC list to find if a lamp is on or off, and to find the overall flash state for that lamp. Basically, since the lamp states are global to the CAN message, we need a way to resolve the "total" lamp state from the list.

Parameters
[in]targetLampThe lamp to find the status of
[out]flashHow the lamp should be flashing
[out]lampOnIf the lamp state is on for any DTC

Definition at line 404 of file isobus_diagnostic_protocol.cpp.

Here is the caller graph for this function:

◆ get_broadcast_state()

bool isobus::DiagnosticProtocol::get_broadcast_state ( ) const

Gets the current broadcast state for the connected network type.

Returns
True if broadcasts are currently allowed, false if broadcasts are suspended for the connected network

Definition at line 372 of file isobus_diagnostic_protocol.cpp.

◆ get_diagnostic_trouble_code_active()

bool isobus::DiagnosticProtocol::get_diagnostic_trouble_code_active ( const DiagnosticTroubleCode & dtc)

Returns if a DTC is active.

Parameters
[in]dtcA diagnostic trouble code whose state should be altered
Returns
true if the DTC was in the active list

Definition at line 299 of file isobus_diagnostic_protocol.cpp.

◆ get_inactive_list_lamp_state_and_flash_state()

void isobus::DiagnosticProtocol::get_inactive_list_lamp_state_and_flash_state ( Lamps targetLamp,
FlashState & flash,
bool & lampOn ) const
private

This is a way to find the overall lamp states to report.

This searches the inactive DTC list to find if a lamp is on or off, and to find the overall flash state for that lamp. Basically, since the lamp states are global to the CAN message, we need a way to resolve the "total" lamp state from the list.

Parameters
[in]targetLampThe lamp to find the status of
[out]flashHow the lamp should be flashing
[out]lampOnIf the lamp state is on for any DTC

Definition at line 507 of file isobus_diagnostic_protocol.cpp.

Here is the caller graph for this function:

◆ get_initialized()

bool isobus::DiagnosticProtocol::get_initialized ( ) const

Returns if the protocol has been initialized.

Returns
true if the protocol has been initialized, otherwise false

Definition at line 127 of file isobus_diagnostic_protocol.cpp.

◆ get_j1939_mode()

bool isobus::DiagnosticProtocol::get_j1939_mode ( ) const

Returns true if the protocol is in J1939 mode instead of ISO11783 mode, false if using ISO11783 mode.

Returns
true if the protocol is in J1939 mode instead of ISO11783 mode, false if using ISO11783 mode

Definition at line 200 of file isobus_diagnostic_protocol.cpp.

Here is the caller graph for this function:

◆ initialize()

bool isobus::DiagnosticProtocol::initialize ( )

The protocol's initializer function.

Returns
true if the protocol was initialized, false if it was already initialized

Definition at line 96 of file isobus_diagnostic_protocol.cpp.

Here is the call graph for this function:

◆ on_address_violation()

void isobus::DiagnosticProtocol::on_address_violation ( std::shared_ptr< InternalControlFunction > affectedControlFunction)
private

A callback function used to consume address violation events and activate a DTC as required in ISO11783-5.

Parameters
[in]affectedControlFunctionThe control function affected by an address violation

Definition at line 610 of file isobus_diagnostic_protocol.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ parse_j1939_network_states()

bool isobus::DiagnosticProtocol::parse_j1939_network_states ( const CANMessage & message)
private

Parses out the DM13 J1939 network states from a CAN message.

Parameters
[in]messageThe message to parse from
Returns
true if the message was parsed, false if the message was invalid

Definition at line 1102 of file isobus_diagnostic_protocol.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ process_all_dm22_responses()

bool isobus::DiagnosticProtocol::process_all_dm22_responses ( )
private

Processes any DM22 responses from the queue.

We queue responses so that we can do Tx retries if needed

Returns
true if queue was completely processed, false if messages remain that could not be sent

Definition at line 892 of file isobus_diagnostic_protocol.cpp.

Here is the call graph for this function:

◆ process_flags()

void isobus::DiagnosticProtocol::process_flags ( std::uint32_t flag,
void * parentPointer )
staticprivate

A generic callback for a the class to process flags from the ProcessingFlags

Parameters
[in]flagThe flag to process
[in]parentPointerA generic context pointer to reference a specific instance of this protocol in the callback

Definition at line 1309 of file isobus_diagnostic_protocol.cpp.

◆ process_message() [1/2]

void isobus::DiagnosticProtocol::process_message ( const CANMessage & message)
private

A generic way for a protocol to process a received message.

Parameters
[in]messageA received CAN message

Definition at line 954 of file isobus_diagnostic_protocol.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ process_message() [2/2]

void isobus::DiagnosticProtocol::process_message ( const CANMessage & message,
void * parent )
staticprivate

A generic way for a protocol to process a received message.

Parameters
[in]messageA received CAN message
[in]parentProvides the context to the actual TP manager object

Definition at line 1094 of file isobus_diagnostic_protocol.cpp.

Here is the call graph for this function:

◆ process_parameter_group_number_request() [1/2]

bool isobus::DiagnosticProtocol::process_parameter_group_number_request ( std::uint32_t parameterGroupNumber,
std::shared_ptr< ControlFunction > requestingControlFunction,
bool & acknowledge,
AcknowledgementType & acknowledgementType )
private

Handles PGN requests for the diagnostic protocol.

Parameters
[in]parameterGroupNumberThe PGN being requested
[in]requestingControlFunctionThe control function that is requesting the PGN
[out]acknowledgeTells the PGN request protocol if it should respond to the request
[out]acknowledgementTypeThe type of acknowledgement to send to the requestor
Returns
true if any callback was able to handle the PGN request

Definition at line 1211 of file isobus_diagnostic_protocol.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ process_parameter_group_number_request() [2/2]

bool isobus::DiagnosticProtocol::process_parameter_group_number_request ( std::uint32_t parameterGroupNumber,
std::shared_ptr< ControlFunction > requestingControlFunction,
bool & acknowledge,
AcknowledgementType & acknowledgementType,
void * parentPointer )
staticprivate
Parameters
[in]parameterGroupNumberThe PGN being requested
[in]requestingControlFunctionThe control function that is requesting the PGN
[out]acknowledgeTells the PGN request protocol if it should respond to the request
[out]acknowledgementTypeThe type of acknowledgement to send to the requestor
[in]parentPointerGeneric context variable, usually a pointer to the class that the callback was registered for
Returns
true if any callback was able to handle the PGN request

Definition at line 1294 of file isobus_diagnostic_protocol.cpp.

Here is the call graph for this function:

◆ send_diagnostic_message_1()

bool isobus::DiagnosticProtocol::send_diagnostic_message_1 ( ) const
private

Sends a DM1 encoded CAN message.

Returns
true if the message was sent, otherwise false

Encode Protect state and flash

Encode amber warning lamp state and flash

Encode red stop lamp state and flash

Encode malfunction indicator lamp state and flash

Definition at line 626 of file isobus_diagnostic_protocol.cpp.

Here is the call graph for this function:

◆ send_diagnostic_message_2()

bool isobus::DiagnosticProtocol::send_diagnostic_message_2 ( ) const
private

Sends a DM2 encoded CAN message.

Returns
true if the message was sent, otherwise false

Encode Protect state and flash

Encode amber warning lamp state and flash

Encode red stop lamp state and flash

Encode malfunction indicator lamp state and flash

Definition at line 714 of file isobus_diagnostic_protocol.cpp.

Here is the call graph for this function:

◆ send_diagnostic_protocol_identification()

bool isobus::DiagnosticProtocol::send_diagnostic_protocol_identification ( ) const
private

Sends a message that identifies which diagnostic protocols are supported.

Returns
true if the message was sent, otherwise false

Bit 1 = J1939-73, Bit 2 = ISO 14230, Bit 3 = ISO 15765-3, else Reserved

Definition at line 802 of file isobus_diagnostic_protocol.cpp.

Here is the call graph for this function:

◆ send_dm13_announce_suspension()

bool isobus::DiagnosticProtocol::send_dm13_announce_suspension ( std::uint16_t suspendTime_seconds) const
private

Sends the DM13 to alert network devices of impending suspended broadcasts.

Parameters
suspendTime_secondsThe number of seconds that the broadcast will be suspended for
Returns
true if the message was sent, otherwise false

Definition at line 822 of file isobus_diagnostic_protocol.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ send_ecu_identification()

bool isobus::DiagnosticProtocol::send_ecu_identification ( ) const
private

Sends the ECU ID message.

Returns
true if the message was sent

Definition at line 840 of file isobus_diagnostic_protocol.cpp.

Here is the call graph for this function:

◆ send_product_identification()

bool isobus::DiagnosticProtocol::send_product_identification ( ) const
private

Sends the product identification message (PGN 0xFC8D)

Returns
true if the message was sent, otherwise false

Definition at line 857 of file isobus_diagnostic_protocol.cpp.

Here is the call graph for this function:

◆ send_software_identification()

bool isobus::DiagnosticProtocol::send_software_identification ( ) const
private

Sends the software ID message.

Returns
true if the message was sent, otherwise false

Definition at line 868 of file isobus_diagnostic_protocol.cpp.

Here is the call graph for this function:

◆ set_diagnostic_trouble_code_active()

bool isobus::DiagnosticProtocol::set_diagnostic_trouble_code_active ( const DiagnosticTroubleCode & dtc,
bool active )

Adds a DTC to the active list, or removes one from the active list.

When you call this function with a DTC and true, it will be added to the DM1 message. When you call it with a DTC and false it will be moved to the inactive list. If you get false as a return value, either the DTC was already in the target state or the data was not valid

Parameters
[in]dtcA diagnostic trouble code whose state should be altered
[in]activeSets if the DTC is currently active or not
Returns
True if the DTC was added/removed from the list, false if DTC was not valid or target state is invalid

First check to see if it's already in the inactive list

Definition at line 234 of file isobus_diagnostic_protocol.cpp.

Here is the caller graph for this function:

◆ set_ecu_id_field()

void isobus::DiagnosticProtocol::set_ecu_id_field ( ECUIdentificationFields field,
const std::string & value )

Sets one of the ECU identification strings for the ECU ID message.

See ECUIdentificationFields for a brief description of the fields

Note
The fields in this message are optional and separated by an ASCII "*". It is not necessary to include parametric data for all fields. Any additional ECU identification fields defined in the future will be appended at the end.
Attention
Do not include the "*" character in your field values and only use HardwareID when not in J1939 mode.
Parameters
[in]fieldThe field to set
[in]valueThe string value associated with the ECU ID field

Definition at line 226 of file isobus_diagnostic_protocol.cpp.

◆ set_j1939_mode()

void isobus::DiagnosticProtocol::set_j1939_mode ( bool value)

Enables the protocol to run in J1939 mode instead of ISO11783 mode.

See ISO11783-12 and J1939-73 for a complete explanation of the differences

Parameters
[in]valueThe desired mode. true for J1939 mode, false for ISO11783 mode

Definition at line 195 of file isobus_diagnostic_protocol.cpp.

◆ set_product_identification_brand()

bool isobus::DiagnosticProtocol::set_product_identification_brand ( const std::string & value)

Sets the product identification brand used in the diagnostic protocol "Product Identification" message (PGN 0xFC8D)

The product identification brand specifies the brand of a product. The combination of the product ID code and brand shall make the product unique in the world.

Parameters
valueThe ascii product brand, up to 50 characters long
Returns
true if the value was set, false if the string is too long

Definition at line 323 of file isobus_diagnostic_protocol.cpp.

◆ set_product_identification_code()

bool isobus::DiagnosticProtocol::set_product_identification_code ( const std::string & value)

Sets the product ID code used in the diagnostic protocol "Product Identification" message (PGN 0xFC8D)

The product identification code, as assigned by the manufacturer, corresponds with the number on the type plate of a product. For vehicles, this number can be the same as the VIN. For stand-alone systems, such as VTs, this number can be the same as the ECU ID number. The combination of the product identification code and brand shall make the product globally unique.

Parameters
valueThe ascii product identification code, up to 50 characters long
Returns
true if the value was set, false if the string is too long

Definition at line 311 of file isobus_diagnostic_protocol.cpp.

◆ set_product_identification_model()

bool isobus::DiagnosticProtocol::set_product_identification_model ( const std::string & value)

Sets the product identification model used in the diagnostic protocol "Product Identification" message (PGN 0xFC8D)

The product identification model specifies a unique product within a brand.

Parameters
valueThe ascii model string, up to 50 characters
Returns
true if the value was set, false if the string is too long

Definition at line 335 of file isobus_diagnostic_protocol.cpp.

◆ set_software_id_field()

void isobus::DiagnosticProtocol::set_software_id_field ( std::uint32_t index,
const std::string & value )

Adds an ascii string to this internal control function's software ID.

Use this to identify the software version of your application. Separate fields will be transmitted with a * delimeter. For example, if your main application's version is 1.00, and you have a bootloader that is version 2.00, you could set field 0 to be "App v1.00" and field 1 to be "Bootloader v2.00", and it will be transmitted on request as: "App v1.00*Bootloader v2.00*" in accordance with ISO 11783-12 You can remove a field by setting it to ""

Parameters
[in]indexThe field index to set
[in]valueThe software ID string to add

Definition at line 347 of file isobus_diagnostic_protocol.cpp.

◆ suspend_broadcasts()

bool isobus::DiagnosticProtocol::suspend_broadcasts ( std::uint16_t suspendTime_seconds = 0xFFFF)

Informs the diagnostic protocol that you are going to suspend broadcasts.

When you call this, DM1 and other broadcasts that come from this protocol will be stopped for the duration specified.

Parameters
[in]suspendTime_secondsIf you know the time for which broadcasts will be suspended, put it here, otherwise 0xFFFF
Returns
true if the message was sent, otherwise false

Definition at line 360 of file isobus_diagnostic_protocol.cpp.

Here is the call graph for this function:

◆ terminate()

void isobus::DiagnosticProtocol::terminate ( )

The protocol's terminate function.

Definition at line 132 of file isobus_diagnostic_protocol.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ update()

void isobus::DiagnosticProtocol::update ( )

Updates the diagnostic protocol.

Definition at line 156 of file isobus_diagnostic_protocol.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ activeDTCList

std::vector<DiagnosticTroubleCode> isobus::DiagnosticProtocol::activeDTCList
private

Keeps track of all the active DTCs.

Definition at line 495 of file isobus_diagnostic_protocol.hpp.

◆ addressViolationEventHandle

EventCallbackHandle isobus::DiagnosticProtocol::addressViolationEventHandle
private

Stores the handle from registering for address violation events.

Definition at line 493 of file isobus_diagnostic_protocol.hpp.

◆ broadcastState

bool isobus::DiagnosticProtocol::broadcastState = true
private

Bitfield for tracking the network broadcast state for DM13.

Definition at line 507 of file isobus_diagnostic_protocol.hpp.

◆ ControlFunctionFunctionalitiesMessageInterface

ControlFunctionFunctionalities isobus::DiagnosticProtocol::ControlFunctionFunctionalitiesMessageInterface

Use this interface to configure your CF's functionalities. This info will be reported to any ECU that requests it and you are required to support it on an ISOBUS.

Note
By default, this interface will only report that your ECU is a "Minimum Control Function".

Definition at line 250 of file isobus_diagnostic_protocol.hpp.

◆ customDM13SuspensionTime

std::uint16_t isobus::DiagnosticProtocol::customDM13SuspensionTime = 0
private

If using a non-standard DM13 suspension time, this tracks that duration in milliseconds.

Definition at line 506 of file isobus_diagnostic_protocol.hpp.

◆ DM13_BITS_PER_NETWORK

constexpr std::uint8_t isobus::DiagnosticProtocol::DM13_BITS_PER_NETWORK = 2
staticconstexprprivate

Number of bits for the network SPNs.

Definition at line 387 of file isobus_diagnostic_protocol.hpp.

◆ DM13_HOLD_SIGNAL_TRANSMIT_INTERVAL_MS

constexpr std::uint32_t isobus::DiagnosticProtocol::DM13_HOLD_SIGNAL_TRANSMIT_INTERVAL_MS = 5000
staticconstexprprivate

Defined in 5.7.13.13 SPN 1236.

Definition at line 379 of file isobus_diagnostic_protocol.hpp.

◆ DM13_NETWORK_BITMASK

constexpr std::uint8_t isobus::DiagnosticProtocol::DM13_NETWORK_BITMASK = 0x03
staticconstexprprivate

Used to mask the network SPN values.

Definition at line 386 of file isobus_diagnostic_protocol.hpp.

◆ DM13_NUMBER_OF_J1939_NETWORKS

constexpr std::uint8_t isobus::DiagnosticProtocol::DM13_NUMBER_OF_J1939_NETWORKS = 11
staticconstexprprivate

The number of networks in DM13 that are set aside for J1939.

Definition at line 385 of file isobus_diagnostic_protocol.hpp.

◆ DM13_TIMEOUT_MS

constexpr std::uint32_t isobus::DiagnosticProtocol::DM13_TIMEOUT_MS = 6000
staticconstexprprivate

The timeout in 5.7.13 after which nodes shall revert back to the normal broadcast state.

Definition at line 380 of file isobus_diagnostic_protocol.hpp.

◆ dm22ResponseQueue

std::vector<DM22Data> isobus::DiagnosticProtocol::dm22ResponseQueue
private

Maintaining a list of DM22 responses we need to send to allow for retrying in case of Tx failures.

Definition at line 497 of file isobus_diagnostic_protocol.hpp.

◆ DM_MAX_FREQUENCY_MS

constexpr std::uint32_t isobus::DiagnosticProtocol::DM_MAX_FREQUENCY_MS = 1000
staticconstexprprivate

You are technically allowed to send more than this under limited circumstances, but a hard limit saves 4 RAM bytes per DTC and has BAM benefits.

Definition at line 378 of file isobus_diagnostic_protocol.hpp.

◆ DM_PAYLOAD_BYTES_PER_DTC

constexpr std::uint8_t isobus::DiagnosticProtocol::DM_PAYLOAD_BYTES_PER_DTC = 4
staticconstexprprivate

The number of payload bytes per DTC that gets encoded into the messages.

Definition at line 383 of file isobus_diagnostic_protocol.hpp.

◆ ecuIdentificationFields

std::vector<std::string> isobus::DiagnosticProtocol::ecuIdentificationFields
private

Stores the ECU ID fields so we can transmit them when ECU ID's PGN is requested.

Definition at line 498 of file isobus_diagnostic_protocol.hpp.

◆ inactiveDTCList

std::vector<DiagnosticTroubleCode> isobus::DiagnosticProtocol::inactiveDTCList
private

Keeps track of all the previously active DTCs.

Definition at line 496 of file isobus_diagnostic_protocol.hpp.

◆ initialized

bool isobus::DiagnosticProtocol::initialized = false
private

Stores if the interface has been initialized.

Definition at line 509 of file isobus_diagnostic_protocol.hpp.

◆ j1939Mode

bool isobus::DiagnosticProtocol::j1939Mode = false
private

Tells the protocol to operate according to J1939 instead of ISO11783.

Definition at line 508 of file isobus_diagnostic_protocol.hpp.

◆ lastDM13ReceivedTimestamp

std::uint32_t isobus::DiagnosticProtocol::lastDM13ReceivedTimestamp = 0
private

A timestamp in milliseconds when we last got a DM13 message.

Definition at line 505 of file isobus_diagnostic_protocol.hpp.

◆ lastDM1SentTimestamp

std::uint32_t isobus::DiagnosticProtocol::lastDM1SentTimestamp = 0
private

A timestamp in milliseconds of the last time a DM1 was sent.

Definition at line 504 of file isobus_diagnostic_protocol.hpp.

◆ MAX_DM13_CUSTOM_SUSPEND_TIME_MS

constexpr std::uint16_t isobus::DiagnosticProtocol::MAX_DM13_CUSTOM_SUSPEND_TIME_MS = 64255
staticconstexprprivate

The max valid value for a DM13 suspension time in milliseconds.

Definition at line 382 of file isobus_diagnostic_protocol.hpp.

◆ MAX_PAYLOAD_SIZE_BYTES

constexpr std::uint16_t isobus::DiagnosticProtocol::MAX_PAYLOAD_SIZE_BYTES = 1785
staticconstexprprivate

DM 1 and 2 are limited to the BAM message max, because ETP does not allow global destinations.

Definition at line 381 of file isobus_diagnostic_protocol.hpp.

◆ myControlFunction

std::shared_ptr<InternalControlFunction> isobus::DiagnosticProtocol::myControlFunction
private

The internal control function that this protocol will send from.

Definition at line 492 of file isobus_diagnostic_protocol.hpp.

◆ networkType

NetworkType isobus::DiagnosticProtocol::networkType
private

The diagnostic network type that this protocol will use.

Definition at line 494 of file isobus_diagnostic_protocol.hpp.

◆ PRODUCT_IDENTIFICATION_MAX_STRING_LENGTH

constexpr std::uint8_t isobus::DiagnosticProtocol::PRODUCT_IDENTIFICATION_MAX_STRING_LENGTH = 50
staticconstexprprivate

The max string length allowed in the fields of product ID, as defined in ISO 11783-12.

Definition at line 384 of file isobus_diagnostic_protocol.hpp.

◆ productIdentificationBrand

std::string isobus::DiagnosticProtocol::productIdentificationBrand
private

The product identification brand for sending the product identification message.

Definition at line 502 of file isobus_diagnostic_protocol.hpp.

◆ productIdentificationCode

std::string isobus::DiagnosticProtocol::productIdentificationCode
private

The product identification code for sending the product identification message.

Definition at line 501 of file isobus_diagnostic_protocol.hpp.

◆ productIdentificationModel

std::string isobus::DiagnosticProtocol::productIdentificationModel
private

The product identification model name for sending the product identification message.

Definition at line 503 of file isobus_diagnostic_protocol.hpp.

◆ softwareIdentificationFields

std::vector<std::string> isobus::DiagnosticProtocol::softwareIdentificationFields
private

Stores the Software ID fields so we can transmit them when the PGN is requested.

Definition at line 499 of file isobus_diagnostic_protocol.hpp.

◆ txFlags

ProcessingFlags isobus::DiagnosticProtocol::txFlags
private

An instance of the processing flags to handle retries of some messages.

Definition at line 500 of file isobus_diagnostic_protocol.hpp.


The documentation for this class was generated from the following files: