https://sourceforge.net/p/honobdapt/wiki/add/Recent changes to addenFri, 21 Jun 2013 14:20:17 -0000https://sourceforge.net/p/honobdapt/wiki/add/<div class="markdown_content"><pre>--- v49 +++ v50 @@ -1,6 +1,5 @@ - -HonOBDapt 1.0 +###HonOBDapt 1.0 a. Intro, Summary </pre> </div>Andrew smithFri, 21 Jun 2013 14:20:17 -0000https://sourceforge.nete49c5209f4f6934aa405feb67628b754482ef449https://sourceforge.net/p/honobdapt/wiki/add/<pre>&lt;pre&gt;--- v48 +++ v49 @@ -1,75 +1,75 @@ -###HonOBDapt 10 - - -a Intro Summary -b Prototype - -HonOBDapt translates requests for onboard automotive computer sensor data from an ISO standard OBD II format to a Honda proprietary format used in 9295 Honda Civics - -HonOBDapt uses a general purpose microcontroller module equipped with external digital IO ports the Arduino Uno Rev 3 HonOBDapt uses a Freescale MC33660 ISOLink logic level converter integrated circuit to electrically connect the OBD II signal line to the Arduino HonOBDapt software is written in C++ and uses the SoftwareSerialWithHalfDuplex library - -HonOBDapt supports core interactive diagnostic functionality of the OBD II standard comprised of essential sensor data including air and coolant temperature spark advance fuel injector pulse width exhaust gas oxygen content engine speed RPM short and long term fuel trim fuel system status open or closed loop manifold barometric pressure atmospheric barometric pressure throttle position vehicle speed etc There is also a basic capability of translating check engine diagnostic trouble codes DTCs There is no support for obtaining OBD II freeze frame data nor any analog to the concept of continuous fuel status EVAP system or misfire monitoring - -These limitations notwithstanding this adapter serves a crucial purpose in allowing 9295 Honda Civics to be diagnosed with modern readily available OBD II diagnostic scanners - - -A prototype was constructed with the following several trips to the junkyard to buy a Honda on board computer ECU and OBD II standard connectors lots of hot glue and some mild eyestrain from trying to solder the MC33660 which is manufactured only in a package intended for automated assembly The prototype was tested with an ELM compatible Bluetooth OBD II scanner The prototype was tested with the OBD II PC software packages Scantool and OBDAutoDoctor - - -Sections I II III C++ Software Specification -Sections IV V VI VII Electrical and Hardware specification -Section VIII TODO - -I Control Flow - a Asynchronous Processing Unit Design - b Main Event Loop - c State controller design considerations -II Class Reference - a BusCoordinator - b BusInit - c TryReady - d GenericBusInitAttempt - e GenericBusInitComplete - f CommCoordinator - g GenericCommMessageCollector - h GenericCommMessageProcessor - i HondaCommCoordinator - j HondaCommMessageCollector - k HondaCommMessageProcessor - l IHandler - m IGenericHandler - o IISOReply - p GenericISOReply - n GenericHandler - q HondaHandler - r HondaPort ISOPort - s HondaMap ISOPID +HonOBDapt 1.0 + + +a. Intro, Summary +b. Prototype + +HonOBDapt translates requests for on-board automotive computer sensor data from an ISO standard OBD II format to a Honda proprietary format used in 92-95 Honda Civics. + +HonOBDapt uses a general purpose microcontroller module equipped with external digital I/O ports, the Arduino Uno Rev. 3. HonOBDapt uses a Freescale MC33660 ISOLink logic level converter integrated circuit to electrically connect the OBD II signal line to the Arduino. HonOBDapt software is written in C++ and uses the SoftwareSerialWithHalfDuplex library. + +HonOBDapt supports core interactive diagnostic functionality of the OBD II standard, comprised of essential sensor data including: air and coolant temperature, spark advance, fuel injector pulse width, exhaust gas oxygen content, engine speed (RPM), short and long term fuel trim, fuel system status (open or closed loop), manifold barometric pressure, atmospheric barometric pressure, throttle position, vehicle speed, etc. There is also a basic capability of translating check engine diagnostic trouble codes (DTCs). There is no support for obtaining OBD II freeze frame data, nor any analog to the concept of continuous fuel status, EVAP system or misfire monitoring. + +These limitations notwithstanding this adapter serves a crucial purpose in allowing 92-95 Honda Civics to be diagnosed with modern, readily available OBD II diagnostic scanners. + + +A prototype was constructed with the following: several trips to the junkyard to buy a Honda on board computer (ECU) and OBD II standard connectors, lots of hot glue and some mild eyestrain from trying to solder the MC33660, which is manufactured only in a package intended for automated assembly. The prototype was tested with an ELM compatible Bluetooth OBD II scanner. The prototype was tested with the OBD II PC software packages Scantool and OBDAutoDoctor. + + +Sections I, II, III: C++ Software Specification +Sections IV, V, VI, VII: Electrical and Hardware specification +Section VIII: TODO + +I. Control Flow + a. Asynchronous Processing Unit Design + b. Main Event Loop + c. State controller design, considerations +II. Class Reference + a. BusCoordinator + b. BusInit + c. TryReady + d. GenericBusInitAttempt + e. GenericBusInitComplete + f. CommCoordinator + g. GenericCommMessageCollector + h. GenericCommMessageProcessor + i. HondaCommCoordinator + j. HondaCommMessageCollector + k. HondaCommMessageProcessor + l. IHandler + m. IGenericHandler + o. IISOReply + p. GenericISOReply + n. GenericHandler + q. HondaHandler + r. HondaPort, ISOPort + s. HondaMap, ISOPID -III Patterns and Principles - SubSections a b c d e f Object Oriented Characteristics - SubSections g h i j k l m Gang of Four Patterns - - a Polymorphism - b Loose Coupling - c Separation of Concerns - d Information Hiding and Encapsulation - e Reuse and Inheritance - f Generalization - g Template - h Command Pattern - i Chain of Responsibility Responsibility Driven Design - j State Automaton finite state machine - k Strategy - l Mediator - m Adapter - -IV Serial Ports -V MC33660 -VI Arduino -VII OBD II -VIII TODO +III. Patterns and Principles + SubSections a, b, c, d, e, f: Object Oriented Characteristics + SubSections g, h, i, j, k, l, m: Gang of Four Patterns + + a. Polymorphism + b. Loose Coupling, + c. Separation of Concerns + d. Information Hiding and Encapsulation + e. Reuse and Inheritance + f. Generalization + g. Template + h. Command Pattern + i. Chain of Responsibility, Responsibility Driven Design + j. State, Automaton, finite state machine + k. Strategy + l. Mediator + m. Adapter + +IV. Serial Ports +V. MC33660 +VI. Arduino +VII. OBD II +VIII. TODO @@ -78,200 +78,200 @@ Asynchronous processing unit design -Generally classes involved in handshaking and serial communications support Work DoneWorking and Reset -These functions serve as a basic cooperative multitasking system Work is called when a higher level controller has a time slice to give to the unit The Work function of each controller is expected to do its work and exit quickly If the conditions are met that allow the handshaking or communications to proceed to the next higher level DoneWorking should return true Reset is used to reset the internal state of the unit typically at the end of a logical session controlled by a higher level controller - -Generally the units are oneshot triggers If for example a unit is falsely triggered to initiate a particular process by noise or an invalid packet it will continue to attempt completion of the process and cannot properly proceed with a valid sequence until it is Reset by a higher level controller +Generally, classes involved in handshaking and serial communications support Work(), DoneWorking() and Reset(). +These functions serve as a basic cooperative multitasking system. Work() is called when a higher level controller has a time slice to give to the unit. The Work() function of each controller is expected to do its' work, and exit quickly. If the conditions are met that allow the handshaking or communications to proceed to the next higher level, DoneWorking() should return true. Reset() is used to reset the internal state of the unit, typically at the end of a logical session controlled by a higher level controller. + +Generally, the units are one-shot triggers. If, for example, a unit is falsely triggered to initiate a particular process ( by noise or an invalid packet ), it will continue to attempt completion of the process and cannot properly proceed with a valid sequence until it is Reset() by a higher level controller. Main Event Loop -The main event loop cycles through the upper lever coordinators BusCoordinator CommCoordinator and HondaCommCoordinator in a round robin fashion calling Work and checking DoneWorking on each one - -The OBD II port requires a bus initialization handshaking sequences No bus initialization is necessary on the HondaPort - -The main event loop strives to move the system into higher and higher levels of functioning The macro levels of functioning are -Level 1 OBD II bus not initialized -Level 2 OBD II bus initialized waiting for incoming request from the OBD II port -Level 3 Message received from the OBD II port and forwarded to the HondaPort waiting for message from HondaPort -Level 4 Message received from the HondaPort and forwarded to the OBD II port - -Once the functioning level reaches 4 the process restarts generally at level 2 but possibly level 1 - -Level 1 - -The main event loop maintains a state variable that is either NOCOMM or COMMESTAB Each time through the main event loop if the state is NOCOMM bus not initialized then BusCoordinatorWork is called -The BusCoordinator will work to initialize the OBD II bus and achieve a higher state COMMESTAB by using TryReady BusInit GenericBusInitAttempt and GenericBusInitComplete After the call to BusCoordinatorWork BusCoordinatorDoneWorking is checked If this function returns true then the bus is ready for communications and the state is set to COMMESTAB if DoneWorking is not true the main event loop restarts again attempting to raise the functioning level by successfully initializating the OBD II bus - -Level 2 -Once the bus is initialized CommCoordinatorWork will be called to try to continue to raise the processing level -CommCoordinator will use GenericCommMessageCollector to get any incoming data on the OBD II port - -If there is no data available immediately on the serial port the GenericCommMessageCollectorWork will exit immediately; this allows the CommCoordinator to exit and yield control to the main event loop - -If there is waiting data the data will be retrieved and a state of COLLECT will be marked internally to GenericCommMessageCollector - -During the next iteration through the main event loop CommCoordinatorWork will be called and the Work function will call GenericCommMessageCollectorWork If there is more data available on the OBD II port that data will be collected by the GenericCommMessageCollector Since the internal state of GenericCommMessageCollector is COLLECT the new data will be appended to the existing message buffer +The main event loop cycles through the upper lever coordinators, BusCoordinator, CommCoordinator and HondaCommCoordinator in a round robin fashion, calling .Work() and checking .DoneWorking() on each one. + +The OBD II port requires a bus initialization handshaking sequences. No bus initialization is necessary on the HondaPort. + +The main event loop strives to move the system into higher and higher levels of functioning. The macro levels of functioning are: +Level 1. OBD II bus not initialized +Level 2. OBD II bus initialized, waiting for incoming request from the OBD II port. +Level 3. Message received from the OBD II port and forwarded to the HondaPort, waiting for message from HondaPort +Level 4. Message received from the HondaPort and forwarded to the OBD II port. + +Once the functioning level reaches 4, the process restarts generally at level 2, but possibly level 1. + +Level 1. + +The main event loop maintains a state variable that is either NO_COMM or COMM_ESTAB. Each time through the main event loop, if the state is NO_COMM (bus not initialized), then BusCoordinator.Work() is called. +The BusCoordinator will work to initialize the OBD II bus and achieve a higher state, COMM_ESTAB, by using TryReady, BusInit, GenericBusInitAttempt and GenericBusInitComplete. After the call to BusCoordinator.Work(), BusCoordinator.DoneWorking() is checked. If this function returns true, then the bus is ready for communications and the state is set to COMM_ESTAB. if DoneWorking() is not true, the main event loop restarts, again attempting to raise the functioning level by successfully initializating the OBD II bus. + +Level 2. +Once the bus is initialized, CommCoordinator.Work() will be called to try to continue to raise the processing level. +CommCoordinator will use GenericCommMessageCollector to get any incoming data on the OBD II port. + +If there is no data available immediately on the serial port, the GenericCommMessageCollector.Work() will exit immediately; this allows the CommCoordinator to exit and yield control to the main event loop. + +If there is waiting data, the data will be retrieved and a state of COLLECT will be marked internally to GenericCommMessageCollector. + +During the next iteration through the main event loop, CommCoordinator.Work() will be called and the Work() function will call GenericCommMessageCollector.Work(). If there is more data available on the OBD II port, that data will be collected by the GenericCommMessageCollector. Since the internal state of GenericCommMessageCollector is COLLECT, the new data will be appended to the existing message buffer. Level 3 -A true return value from GenericCommMessageCollectorDoneWorking signifies that a complete and valid OBD II message has been received and the internal state of the coordinator CommCoordinator will be marked as MESSAGERECEIVED Then the GenericCommMessageProcessor will become active processing the request by calling HondaHandlerIncomingPID The HondaHandler will translate the OBD II PID to an appropriate request for Honda data and will call SendHondaRequest to send a command sequence to the HondaPort HondaHandler will then assign the request to the HondaCommCoordinator which queues the request using a function pointer to establish a nonblocking asynchronous callback to be executed when the HondaPort data is ready -CommMessageProcessor and CommCoordinator then yield control to the main event loop - -During the next iteration of the main event loop HondaCommCoordinatorWork will be called and the HondaCommCoordinator will pick up the queued request and set an internal state of WORKING The HondaCommCoordinator will use the HondaCommMessageCollector to get any incoming data on the HondaPort If there is waiting data the character data will be retrieved and a state of COLLECT will be marked internally in the HondaCommMessageCollector - -DUring the next iteration through the main event loop HondaCommCoordinatorWork will be called If there is more data that data will be collected by the HondaCommMessageCollector Since the internal state of HondaCommMessageCollector is COLLECT the new data will be appended to the existing message buffer +A true return value from GenericCommMessageCollector.DoneWorking() signifies that a complete and valid OBD II message has been received and the internal state of the coordinator, CommCoordinator, will be marked as MESSAGE_RECEIVED. Then the GenericCommMessageProcessor will become active, processing the request by calling HondaHandler.IncomingPID(). The HondaHandler will translate the OBD II PID to an appropriate request for Honda data and will call SendHondaRequest() to send a command sequence to the HondaPort. HondaHandler will then assign the request to the HondaCommCoordinator, which queues the request, using a function pointer to establish a non-blocking asynchronous callback to be executed when the HondaPort data is ready. +CommMessageProcessor and CommCoordinator then yield control to the main event loop. + +During the next iteration of the main event loop, HondaCommCoordinator.Work() will be called and the HondaCommCoordinator will pick up the queued request and set an internal state of WORKING. The HondaCommCoordinator will use the HondaCommMessageCollector to get any incoming data on the HondaPort. If there is waiting data, the character data will be retrieved and a state of COLLECT will be marked internally in the HondaCommMessageCollector + +DUring the next iteration through the main event loop, HondaCommCoordinator.Work() will be called. If there is more data, that data will be collected by the HondaCommMessageCollector. Since the internal state of HondaCommMessageCollector is COLLECT the new data will be appended to the existing message buffer. Level 4 -When the message from the HondaPort is complete and valid signaled by the HondaCommMessageCollector returning true to DoneWorking the HondaCommMessageProcessor will become active and process the message by executing HondaHandlerCallback HondaHandlerCallback will execute the appropriate return function matching the original asynchronous request and effect the translation of the Honda sensor data into ISO measurements using a member of the group ISOMeasurementsTOISOReply and the reply to the OBD II port using a GenericHandlerIISOReply family member - -At this point the overall state has reached its highest point of productivity The various MessageCollectors and MessageProcessors are reset and the main event loop restarts at level 2 waiting for more serial messages from the OBD II port - - Advantages of state controller design - -Extensibility - -This structure provides a clean clear implementation that lends itself to further modifications and extension such as hooks to process other data or timeout watchdogs because there are clear places to hook into the overall flow of handshaking or messaging without the risk of undesirable interaction or needing to understand the lower level operation of each controller - -This structure also provides a clean way to implement potentially deep nested logic in a clear easy to debug and trace fashion - -Each asynchronous unit is coded with the overall structure in mind For example TryReadyWork will not block but will do a small amount of work polling the OBD II KLine bus status and checking the timeofday millis to maintain a running total of idle time and then Work will exit TryReady can maintain internal state such as the running total but encapsulates that state and signifies that internal conditions have been satisfied by returning true to DoneWorking Also when logical conditions require Reset can be used to reset the running total - -In this way serial communications or handshaking can be carefully controlled from the upper level -For instance this structure makes it easy and clear to implement an *OVERALL* handshake attempt timeout without modifying functionally distinct units such as TryReady - -Error Handling - -When dealing with serial port messaging subject to noise message fragments being received etc -it is quite possible for individual functional units to become stuck or hung due to waiting for message termination or validation that will never succeed because of midmessage corruption invalid or nonstandard messages etc - -In this type of messaging environment it is important to maintain supervisory control with clear topdown control logic The asynchronous nonblocking Work DoneWorking pattern lends itself to implementing supervisory controls - -Of paramount importance is that the supervisory code and its interface to lower level code be clear distinct and concise so that unforseen situations; ie dealing with slightly altered or new packets or protocol details and their concomitant issues; can be dealt with effectively - -Complexity and correctness - -The factoring of complicated nested communications logic into a body of state machines is an effective way of managing complexity and makes logical defects more apparent This factoring methodology allows the program to be treated as the steps of an algorithm facilitating the application of mathematically rigorous techniques to prove or disprove the correctness of the program logic - - Possible ramifications of state controller design - -Although the event loop design of the serial communications code has additional overhead compared to a more direct lowlevel approach and can cause an entire event loop to be executed between individual serial character data retrievals the overhead is mostly syntactic exposition and is not expected to be computationally intensive - -As well 9600 baud is not particularly fast relative to Arduinos microprocessor speed and the SoftwareSerial library is interrupt driven interrupts take priority over all other execution context and SoftwareSerial maintains its own input buffers Also the direct serial controllers CommMessageCollector and HondaCommMessageCollector are enhanced with a burst mode that increases their priority under certain circumstances Due to these factors it is considered extremely unlikely for the overhead of the state machine control system to cause a loss of serial data on any port +When the message from the HondaPort is complete and valid, signaled by the HondaCommMessageCollector returning true to DoneWorking(), the HondaCommMessageProcessor will become active and process the message by executing HondaHandler.Callback(). HondaHandler.Callback() will execute the appropriate return function matching the original asynchronous request and effect the translation of the Honda sensor data into ISO measurements, using a member of the group ISOMeasurementsTOISOReply, and the reply to the OBD II port, using a GenericHandler.IISOReply family member. + +At this point the overall state has reached its highest point of productivity. The various MessageCollector(s) and MessageProcessor(s) are reset, and the main event loop restarts at level 2, waiting for more serial messages from the OBD II port. + +-- Advantages of state controller design + +---Extensibility + +This structure provides a clean, clear implementation that lends itself to further modifications and extension, such as hooks to process other data or timeout watchdogs, because there are clear places to hook into the overall flow of handshaking or messaging without the risk of undesirable interaction or needing to understand the lower level operation of each controller. + +This structure also provides a clean way to implement potentially deep nested logic in a clear, easy to debug and trace fashion. + +Each asynchronous unit is coded with the overall structure in mind. For example, TryReady.Work() will not block but will do a small amount of work, polling the OBD II K-Line bus status and checking the time-of-day ( millis() ) to maintain a running total of idle time and then Work() will exit. TryReady can maintain internal state such as the running total but encapsulates that state and signifies that internal conditions have been satisfied by returning true to DoneWorking(). Also, when logical conditions require, Reset() can be used to reset the running total. + +In this way serial communications or handshaking can be carefully controlled from the upper level. +For instance, this structure makes it easy and clear to implement an *OVERALL* handshake attempt timeout, without modifying functionally distinct units such as TryReady. + +---Error Handling + +When dealing with serial port messaging, subject to noise, message fragments being received, etc, +it is quite possible for individual functional units to become stuck or hung due to: waiting for message termination or validation that will never succeed because of mid-message corruption, invalid or nonstandard messages, etc. + +In this type of messaging environment it is important to maintain supervisory control with clear top-down control logic. The asynchronous, non-blocking Work(), DoneWorking() pattern lends itself to implementing supervisory controls. + +Of paramount importance is that the supervisory code and its' interface to lower level code be clear, distinct and concise, so that unforseen situations; i.e. dealing with slightly altered or new packets or protocol details and their concomitant issues; can be dealt with effectively. + +---Complexity and correctness + +The factoring of complicated nested communications logic into a body of state machines is an effective way of managing complexity and makes logical defects more apparent. This factoring methodology allows the program to be treated as the steps of an algorithm, facilitating the application of mathematically rigorous techniques to prove or disprove the correctness of the program logic. + +-- Possible ramifications of state controller design + +Although the event loop design of the serial communications code has additional overhead compared to a more direct low-level approach, and can cause an entire event loop to be executed between individual serial character data retrievals, the overhead is mostly syntactic exposition, and is not expected to be computationally intensive. + +As well, 9600 baud is not particularly fast relative to Arduino's microprocessor speed and the SoftwareSerial library is interrupt driven ( interrupts take priority over all other execution context ) and SoftwareSerial maintains its' own input buffers. Also, the direct serial controllers, CommMessageCollector and HondaCommMessageCollector are enhanced with a burst mode that increases their priority under certain circumstances. Due to these factors it is considered extremely unlikely for the overhead of the state machine control system to cause a loss of serial data on any port. CLASS REFERENCE BusCoordinator -The BusCoordinator is responsible for coordinating the bus initialization process including bus idle time prerequisite wakeuppacket handshaking and confirmation handshaking -The Buscoordinator uses TryReady BusInit GenericBusInitAttempt and GenericBusInitComplete +The BusCoordinator is responsible for coordinating the bus initialization process including: bus idle time prerequisite, wakeup-packet handshaking and confirmation handshaking. +The Buscoordinator uses TryReady, BusInit, GenericBusInitAttempt, and GenericBusInitComplete. TryReady -TryReady polls the OBD II KLine bus pin and establishes that the necessary bus idle condition has been met before handshaking begins +TryReady polls the OBD II K-Line bus pin and establishes that the necessary bus idle condition has been met before handshaking begins. BusInit -Tasked with the job of attempting and completing an OBD II bus initialization handshake sequence Uses GenericBusInitAttempt and GenericBusInitComplete - -GenericBusInitAttempt establishes generic requirements for a bus initialization attempt which begins the handshaking sequence of an OBD II session Uses WAKEPACK array a storage area for KLine bus pin logic level transition times 10ms 100ms etc This routine uses Arduinos digitalRead to check the logic level of the OBD II KLine bus pin When the pin alters state High to Low or Low to High the timeofday millis is recorded This recorded value is compared to the timeofday when the next level transition occurs and in this way the length of the handshaking pulse or pulses is established - -If the transition pattern is a valid OBD II KLine bus wakeup pattern DoneWorking will return true +Tasked with the job of attempting and completing an OBD II bus initialization handshake sequence. Uses GenericBusInitAttempt and GenericBusInitComplete. + +GenericBusInitAttempt - establishes generic requirements for a bus initialization attempt, which begins the handshaking sequence of an OBD II session. Uses WAKE_PACK array, a storage area for K-Line bus pin logic level transition times ( 10ms, 100ms, etc ). This routine uses Arduino's digitalRead to check the logic level of the OBD II K-Line bus pin. When the pin alters state ( High to Low or Low to High ) the time-of-day ( millis() ) is recorded. This recorded value is compared to the time-of-day when the next level transition occurs, and in this way the length of the handshaking pulse or pulses is established. + +If the transition pattern is a valid OBD II K-Line bus wake-up pattern, DoneWorking() will return true. The protocol specific details of the GenericBusInitAttempt are left to the more derived classes -BusInitAttemptISO14230slow BusInitAttemptISO14230fast BusInitAttemptISO9141 +BusInitAttempt_ISO14230_slow, BusInitAttempt_ISO14230_fast, BusInitAttempt_ISO9141 GenericBusInitComplete -establishes basic requirements of bus initialization completion which finishes the handshaking sequences for an OBD II session The completion of the handshaking is accomplished by sending a confirmation message mathematically derived from the messages received during a bus initialization attempt to the OBD II port - -The protocol specific details of the BusInitComplete are left to the more derived classes -BusInitCompleteISO9141 BusInitComplete14230slow BusInitCompleteISO14230fast +establishes basic requirements of bus initialization completion which finishes the handshaking sequences for an OBD II session. The completion of the handshaking is accomplished by sending a confirmation message, mathematically derived from the messages received during a bus initialization attempt, to the OBD II port. + +The protocol specific details of the BusInitComplete are left to the more derived classes: +BusInitComplete_ISO9141, BusInitComplete_14230_slow, BusInitComplete_ISO14230_fast CommCoordinator -The CommCoordinator is responsible for collecting verifying and processing messages on the OBD II Kline serial port Processing generally concludes with a call to HondaHandlerIncomingPID which accepts responsibility for replying to the OBD II Kline serial port with the requested Honda on board computer ECU data Uses GenericCommMessageCollector and GenericCommMessageProcessor +The CommCoordinator is responsible for collecting, verifying and processing messages on the OBD II K-line serial port. Processing generally concludes with a call to HondaHandler.IncomingPID(), which accepts responsibility for replying to the OBD II K-line serial port with the requested Honda on board computer (ECU) data. Uses GenericCommMessageCollector and GenericCommMessageProcessor. GenericCommMessageCollector -Collects the serial data from the OBD II port and establishes completeness appropriate headers and basic errorchecking checksum of incoming serial data - -This message collector supports a serial burst mode assuming that an incoming serial character is usually followed by the remaining characters without delay This routine is authorized to busywait block waiting for serial data for a maximum time interval defined by SERIALBURSTMAXTIMESLICE before relinquishing control to its coordinator - -Protocol specific details are left to the more derived classes ISOCommMessageCollectorISO9141 ISOCommMessageCollectorISO14230 - - -GenericCommMessageProcessor -Processes a valid message containing an OBD II PID by calling HondaHandlerIncomingPID to transfer responsibility for retrieving the requested data and sending a reply to the OBD II port IncomingPID function does not block and GenericCommMessageProcessor and its coordinator CommCoordinator can exit immediately after the call to IncomingPID - - -Protocol specific details are left to the more derived classes CommMessageProcessorISO9141 CommMessageProcessorISO14230 - - -HondaCommCoordinator manages Honda communications Uses HondaCommMessageCollector and HondaCommMessageProcessor - -Works in conjunction with the HondaHandler Provides AssignWork function which when called by HondaHandler queues a request for Honda data +Collects the serial data from the OBD II port and establishes completeness (appropriate headers) and basic error-checking (checksum) of incoming serial data. + +This message collector supports a serial burst mode, assuming that an incoming serial character is usually followed by the remaining characters without delay. This routine is authorized to busy-wait (block) waiting for serial data for a maximum time interval defined by SERIAL_BURST_MAX_TIME_SLICE, before relinquishing control to its' coordinator. + +Protocol specific details are left to the more derived classes: ISOCommMessageCollector_ISO9141, ISOCommMessageCollector_ISO14230 + + +GenericCommMessageProcessor - +Processes a valid message containing an OBD II PID by calling HondaHandler.IncomingPID() to transfer responsibility for retrieving the requested data and sending a reply to the OBD II port. IncomingPID function does not block and GenericCommMessageProcessor and its' coordinator CommCoordinator can exit immediately after the call to IncomingPID. + + +Protocol specific details are left to the more derived classes: CommMessageProcessor_ISO9141, CommMessageProcessor_ISO14230 + + +HondaCommCoordinator manages Honda communications. Uses HondaCommMessageCollector and HondaCommMessageProcessor. + +Works in conjunction with the HondaHandler. Provides AssignWork function which, when called by HondaHandler, queues a request for Honda data. HondaCommMessageCollector -Collects the serial data from the HondaPort Establishes completeness appropriate headers errorchecking checksum of incoming serial data - -This message collector supports a serial burst mode assuming that an incoming serial character is usually followed by the remaining characters without delay This routine is authorized to busywait block waiting for serial data for a maximum time interval defined by SERIALBURSTMAXTIMESLICE before relinquishing control to its coordinator +Collects the serial data from the HondaPort. Establishes completeness, appropriate headers, error-checking (checksum) of incoming serial data. + +This message collector supports a serial burst mode, assuming that an incoming serial character is usually followed by the remaining characters without delay. This routine is authorized to busy-wait (block) waiting for serial data for a maximum time interval defined by SERIAL_BURST_MAX_TIME_SLICE, before relinquishing control to its' coordinator. HondaCommMessageProcessor -Processes valid messages from the HondaPort Processing concludes with a call to HondaHandlerCallback which effects translation of the Honda data and the reply to the OBD II port using a member of the GenericHandler ISOMeasurementsToISOReply group and an IISOReply family member - - -IHandler establishes what a handler used by the CommCoordinatorCommMessageProcessor must do -A class implementing IHandler must support IncomingPID At a fundamental level to implement the IHandler interface the class must be able to do something with IncomingPID perhaps ignoring unsupported operations This class would be a good jumping off point for diverse purposes for example a class that only logs the incoming messages - -IGenericHandler supports VIN and Capabilities -A slightly richer implementation would be required to at a minimum reply with the Vehicle Identification Number and the Capabilities which is a list of supported sensors or other data that can be retrieved - -IISOReply is an interface defining the generic requirements of a reply to the OBD II port - -GenericISOReply is class containing generic OBD II port reply code -The protocol specific details are left to the more derived classes ProtocolReplyISO9141 and ProtocolReplyISO14230 +Processes valid messages from the HondaPort. Processing concludes with a call to HondaHandler.Callback(), which effects translation of the Honda data and the reply to the OBD II port using a member of the GenericHandler ISOMeasurementsToISOReply group and an IISOReply family member. + + +IHandler establishes what a handler, used by the CommCoordinator.CommMessageProcessor, must do +A class implementing IHandler must support IncomingPID. At a fundamental level, to implement the IHandler interface the class must be able to do something with IncomingPID, perhaps ignoring unsupported operations. This class would be a good jumping off point for diverse purposes, for example, a class that only logs the incoming messages. + +IGenericHandler supports VIN and Capabilities. +A slightly richer implementation would be required to, at a minimum, reply with the Vehicle Identification Number and the Capabilities, which is a list of supported sensors or other data that can be retrieved. + +IISOReply is an interface defining the generic requirements of a reply to the OBD II port. + +GenericISOReply is class containing generic OBD II port reply code. +The protocol specific details are left to the more derived classes: ProtocolReply_ISO9141 and ProtocolReply_ISO14230. GenericHandler -Adds an interface of virtual function prototypes that describe the expected input and output for a sensor data retrieval implementation and a baseline map function ISOPIDTOGENERICHANDLERMAP that links OBD II PIDs to functions in the sensor interface GenericHandler builds directly upon its direct ancestor abstractions IGenericHandler and IHandler but becomes richer and more concrete by extending outside of that family to become a composition with an IISOReply family member - - -GenericHandler also defines functions that convert data to an OBD II format These functions follow the naming convention ISOMeasurementsToISOReplyXXXXX These functions accept input data in the scale dictated by the OBD II standard; ie temperature is measured in Celcius degress with the input data to the function represented by the formula Actual Temp 40 EG if the temperature of the coolant is determined to be 55 deg C you would call ISOMeasureToISOReplyScalarbyte 15 ; - -The inclusion of an IISOReply family member which includes functions that reply to the OBD II port and the definitions of the ISOMeasurementsToISOReply functions establishes that at this level of class abstraction that the concept of handling will be to send a reply message to the OBD II port The IISOReply member also provides functions toward this end At this level the implementation of the sensor data virtual functions is left abstract - - -HondaHandler becomes the most derived richest member of this family tree It is a complete fully functional handler It adds concrete implementations of the remaining abstractions in the GenericHandler family hierarchy the abstract sensor data retrieval interface and IncomingPID - -The HondaHandler implements IncomingPID by using the generic mapping of OBD II PIDS onto the abstract sensor data retrieval interface ISOPIDTOGENERICHANDLERMAP The HondaHandler implementation of the sensor data retrieval functions is asynchronous and delegated relying on the placement of its functional colleague HondaCommCoordinator in the main event loop to retrieve the data from the HondaPort - -HondaCommCoordinatorAssignWork is used to communicate with the HondaCommCoordinator requesting that during the next main event loop cycle the retrieval of a particular sensor value from the Honda on board computer ECU -AssignWork establishes a callback function pointer for the HondaCommCoordinator to call when the requested data has been retrieved - -When the HondaCommCoordinator responds with the data HondaHandler converts maps or otherwise translates the data values from the Honda scaling or other representations into values compatible with the OBD II measurement scale or representation Then a member of the GenericHandlerISOMeasurementsTOISOReplyXXXX group is called to generically convert the data into an OBD II format and then use an IISOReply family member to effect the reply to the OBD II port using the proper protocol - - -HondaHandler implements the IGeneralAsyncHandler interface marking it as an asynchronous class - -HondaHandler defines GeneralAsyncRequest a function that factors out the common code for setting up the function pointer +Adds an interface of virtual function prototypes that describe the expected input and output for a sensor data retrieval implementation and a baseline map function, ISOPID_TO_GENERIC_HANDLER_MAP, that links OBD II PIDs to functions in the sensor interface. GenericHandler builds directly upon its direct ancestor abstractions IGenericHandler and IHandler, but becomes richer and more concrete by extending outside of that family to become a composition with an IISOReply family member. + + +GenericHandler also defines functions that convert data to an OBD II format. These functions follow the naming convention ISOMeasurementsToISOReply..XXXXX. These functions accept input data in the scale dictated by the OBD II standard; i.e. temperature is measured in Celcius degress, with the input data to the function represented by the formula "Actual Temp - 40". E.G., if the temperature of the coolant is determined to be 55 deg. C., you would call ISOMeasureToISOReply_Scalar_byte( 15 ); + +The inclusion of an IISOReply family member which includes functions that reply to the OBD II port and the definitions of the ISOMeasurementsToISOReply functions establishes that at this level of class abstraction that the concept of handling will be to send a reply message to the OBD II port. The IISOReply member also provides functions toward this end. At this level, the implementation of the sensor data virtual functions is left abstract. + + +HondaHandler becomes the most derived, richest member of this family tree. It is a complete, fully functional handler. It adds concrete implementations of the remaining abstractions in the GenericHandler family hierarchy, the abstract sensor data retrieval interface and IncomingPID(). + +The HondaHandler implements IncomingPID by using the generic mapping of OBD II PIDS onto the abstract sensor data retrieval interface, ISOPID_TO_GENERIC_HANDLER_MAP. The HondaHandler implementation of the sensor data retrieval functions is asynchronous, and delegated, relying on the placement of its' functional colleague, HondaCommCoordinator, in the main event loop, to retrieve the data from the HondaPort. + +HondaCommCoordinator.AssignWork() is used to communicate with the HondaCommCoordinator, requesting that during the next main event loop cycle, the retrieval of a particular sensor value from the Honda on board computer (ECU). +AssignWork establishes a callback function pointer for the HondaCommCoordinator to call when the requested data has been retrieved. + +When the HondaCommCoordinator responds with the data, HondaHandler converts, maps or otherwise translates the data values from the Honda scaling or other representations, into values compatible with the OBD II measurement scale or representation. Then a member of the GenericHandler.ISOMeasurementsTOISOReply...XXXX group is called to generically convert the data into an OBD II format and then use an IISOReply family member to effect the reply to the OBD II port using the proper protocol. + + +HondaHandler implements the IGeneralAsyncHandler interface, marking it as an asynchronous class. + +HondaHandler defines GeneralAsyncRequest, a function that factors out the common code for setting up the function pointer. IGenericAsyncHandler -IGenericAsyncHandler is a marker interface Implementing it marks a class as asynchronous in nature - - -ISOPort HondaPort -ISOPort and HondaPort provide character based access to the serial ports defined using a SoftwareSerial instance configured to communicate on the digital IO pins connected to the OBD II connector and the Honda Diagnostic Link Connector - -ISOPort and HondaPort provide safety features by providing a consistent interface to the serial ports which can often become unmanageable within nested serial communications logic - -All reads and writes are done through these interfaces so the checksums are calculated through these routines reducing the risk of multiple conflicting direct access +IGenericAsyncHandler is a marker interface. Implementing it marks a class as asynchronous in nature. + + +ISOPort, HondaPort +ISOPort and HondaPort provide character based access to the serial ports, defined using a SoftwareSerial instance configured to communicate on the digital I/O pins connected to the OBD II connector and the Honda Diagnostic Link Connector. + +ISOPort and HondaPort provide safety features by providing a consistent interface to the serial ports, which can often become unmanageable within nested serial communications logic. + +All reads and writes are done through these interfaces, so the checksums are calculated through these routines, reducing the risk of multiple conflicting direct access. HondaMap -HondaMap objects are used to refer to specific sensors in the Honda onboard computer ECU The definition includes an address and length Some sensors return two bytes for example RPM If the twobyte return data is a scalar value the data is bigendian that is the most significant byte the one that counts for 256 for each 1 of its value is the first of the twobytes transmitted by the ECU +HondaMap objects are used to refer to specific sensors in the Honda on-board computer (ECU). The definition includes an address and length. Some sensors return two bytes, for example, RPM. If the two-byte return data is a scalar value, the data is big-endian, that is, the most significant byte, the one that counts for 256 for each 1 of its' value, is the first of the two-bytes transmitted by the ECU. ISOPID -ISOPID objects are used to represent OBD II requests Each request contains a mode and an identifier Mode 1 is sensors Mode 3 is Diagnostic Trouble Codes EG Mode 1 identifier 0x0C is engine speed RPM +ISOPID objects are used to represent OBD II requests. Each request contains a mode and an identifier. Mode 1 is sensors. Mode 3 is Diagnostic Trouble Codes. E.G. Mode 1, identifier 0x0C is engine speed (RPM). @@ -280,162 +280,162 @@ PATTERNS -Object Oriented characteristics +Object Oriented characteristics: Polymorphism -GenericBusInitAttempt ISO14230BusInitAttempt ISO9141BusInitAttempt - -When the variable oBusInitAttempt takes the form of a ISO14230BusInitAttempt the BusCoordinator doesnt know or care about this All the BusCoordinator needs to know is that a GenericBusInitAttempt is being utilized Thus the principle of polymorphism or many forms is being leveraged to achieve more generalized code From one perspective the form of the instance variable oBusInitAttempt is GenericBusInitAttempt and from another perspective the form is ISO14230BusInitAttempt thus polymorphic - -IHandler GenericHandler HondaHandler -The IHandler abstract interface is used in the CommMessageProcessor The form of the instance variable in CommMessageProcessor is an abstract IHandler at compile time At run time however the IHandler object takes the form of a concrete HondaHandler From the perspective of the CommMessageProcessor the instance variable is an IHandler but from a macro system level view the instance variable is a HondaHandler Thus this variable takes many forms and is polymorphic GenericHandler is another form of an IHandler albeit a kind of abstract unexpressed form as instantiating it would result in an incomplete handler implementation +GenericBusInitAttempt, ISO14230_BusInitAttempt, ISO9141_BusInitAttempt + +When the variable oBusInitAttempt takes the form of a ISO14230_BusInitAttempt, the BusCoordinator doesn't know or care about this. All the BusCoordinator needs to know is that a GenericBusInitAttempt is being utilized. Thus the principle of polymorphism, or many forms, is being leveraged to achieve more generalized code. From one perspective the form of the instance variable oBusInitAttempt is GenericBusInitAttempt and from another perspective the form is ISO14230_BusInitAttempt, thus polymorphic. + +IHandler, GenericHandler, HondaHandler +The IHandler abstract interface is used in the CommMessageProcessor. The form of the instance variable in CommMessageProcessor is an abstract IHandler at compile time. At run time, however the IHandler object takes the form of a concrete HondaHandler. From the perspective of the CommMessageProcessor the instance variable is an IHandler, but from a macro, system level view, the instance variable is a HondaHandler. Thus this variable takes many forms and is polymorphic. GenericHandler is another form of an IHandler, albeit a kind of abstract 'unexpressed' form, as instantiating it would result in an incomplete handler implementation. Loose Coupling -Even though they work closely together to accomplish the overall goal in this adapter implementation -there is a loosecoupling between the CommMessageProcessor receiving a PID from the OBDII port and the HondaHandler effecting a reply to the OBD II port This coupling is loose because the Handler could be implemented in different ways and this loose coupling leaves the door open for more diverse interpretations of the term handling - -In this adapter implementation the loose coupling make it easier to inject an asynchronous handler into the design The CommMessageProcessor is coupled only to an IHandler an interface definition aka contract specification not tied directly to the asynchronous implementation of HondaHandler reducing the chance of cascading changes rippling through multiple functional units - -One of the advantages of the loose coupling in this adapter implementation is its ability to mitigate the situation where one subsystem is blocked by another It would be undesirable to make the CommMessageProcessor blockwait for the Honda data to be retrieved The data may never come but we still want the CommMessageProcessor to be able to degrade gracefully and respond to its immediate supervisor The loose coupling supports this because the HondaHandler doesnt take control when it is tasked with getting Honda sensor data It is delegated to do so and this is a pattern of Chain of Responsibility but the CommMessageProcessor maintains control and can exit cleanly This clean exit facilitates the placement of supervisory control logic where it belongs; at a high logical level in the code not buried deep in the implementation details of a particular low level unit - -Loose coupling has its benefits and downfalls Loose coupling allows flexibility in implementing the Handler without changing the CommMessageProcessor and ultimately aids in the implementation of an asynchronous handler but this does not come without issues For example there is no way to easily enforce transactional integrity across this coupling or pass error or control messages such as retry across this coupling because by the time a failure is detected on one side of the coupling the execution context that initiated the request has exited A similar problem occurs with nonasynchronous loose coupling where for example it is impossible to pass an error message because the loose coupling only supports a limited interface +Even though they work closely together to accomplish the overall goal in this adapter implementation, +there is a loose-coupling between the CommMessageProcessor, receiving a PID from the OBDII port and the HondaHandler, effecting a reply to the OBD II port. This coupling is loose because the Handler could be implemented in different ways and this loose coupling leaves the door open for more diverse interpretations of the term 'handling'. + +In this adapter implementation the loose coupling make it easier to inject an asynchronous handler into the design. The CommMessageProcessor is coupled only to an IHandler, an interface definition ( aka, contract specification ), not tied directly to the asynchronous implementation of HondaHandler, reducing the chance of cascading changes rippling through multiple functional units. + +One of the advantages of the loose coupling in this adapter implementation is its' ability to mitigate the situation where one subsystem is blocked by another. It would be undesirable to make the CommMessageProcessor block(wait) for the Honda data to be retrieved. The data may never come but we still want the CommMessageProcessor to be able to degrade gracefully and respond to its' immediate supervisor. The loose coupling supports this because the HondaHandler doesn't take control when it is tasked with getting Honda sensor data. It is delegated to do so and this is a pattern of Chain of Responsibility, but the CommMessageProcessor maintains control and can exit cleanly. This clean exit facilitates the placement of supervisory control logic where it belongs; at a high logical level in the code, not buried deep in the implementation details of a particular low level unit. + +Loose coupling has its benefits and downfalls. Loose coupling allows flexibility in implementing the Handler without changing the CommMessageProcessor, and ultimately aids in the implementation of an asynchronous handler, but this does not come without issues. For example, there is no way to easily enforce transactional integrity across this coupling, or pass error or control messages such as 'retry' across this coupling because by the time a failure is detected on one side of the coupling, the execution context that initiated the request has exited. A similar problem occurs with non-asynchronous loose coupling, where, for example, it is impossible to pass an error message because the loose coupling only supports a limited interface. Separation of Concerns -See Patterns and Principles Loose Coupling Information Hiding and Encapsulation and Chain of Responsibility +See _Patterns and Principles_ "Loose Coupling", "Information Hiding and Encapsulation", and "Chain of Responsibility" Generalization - Reuse Inheritance and Templates - Benefits -The sharing of common functionality reduces the overall code load that must be inspected It also increase the chances that changes made to the system will propagate in the proper way - Ramifications -The factoring out of common functionality must be done thoughtfully and carefully as the benefits of reuse are quickly outweighed by the complexity of managing entanglement between sharing classes - -See Also Generalization composition flexibility of modularity -see Also Generalization composition ramifications -See Also Generalization overgeneralization -See Also Template for examples; Generally whereever there is a Template there is reuse - - -Generalization composition - Reuse factoring flexibility of modularity - Benefits -Factoring out distinct conceptual groups of functionality like sensor data virtual function interface ISOMeasurementsTOISOReply grouping IISOReply and GenericISOReply provides the flexibility of modularity Individual pieces can be swapped in and out eg substituting a newer Controller Area Network diagnostic subsystem implementation for the OBD II system as long as the new piece adheres to the established convention defined by interfaces - -Flexibilty means less risk Generalizing may take more frontend design time but reduces the amplitude of wildschedule swings on the back end - Ramifications -Compositional reuse can lead a design down a dead end If a class inherits everything from a composed class and implements a new subsystem without a solid set of abstract interfaces or contracts to define exactly where in the tree the new functionality branches off from or differs from the previous incarnation it is likely that new functionality will simply rewrite existing functionality - -So there is a place on the spectrum between strict inheritance hierarchytogod class compositional multipurposing that must be chosen carefully Too tight interface adherence limits the diversity that future implementations can create Too little interface adherance and excessive use of adhoc compositional reuse encourages rewrites and bigballofmud designs +-- Reuse, Inheritance and Templates +--- Benefits +The sharing of common functionality reduces the overall code load that must be inspected. It also increase the chances that changes made to the system will propagate in the proper way. +--- Ramifications +The factoring out of common functionality must be done thoughtfully and carefully, as the benefits of reuse are quickly outweighed by the complexity of managing entanglement between sharing classes. + +See Also, Generalization, composition, flexibility of modularity +see Also, Generalization, composition, ramifications +See Also, Generalization, overgeneralization +See Also, Template for examples; Generally whereever there is a Template there is reuse. + + +Generalization, composition +-- Reuse, factoring, flexibility of modularity +--- Benefits +Factoring out distinct conceptual groups of functionality like sensor data virtual function interface, ISOMeasurementsTOISOReply grouping, IISOReply and GenericISOReply provides the flexibility of modularity. Individual pieces can be swapped in and out, e.g. substituting a newer Controller Area Network diagnostic subsystem implementation for the OBD II system, as long as the new piece adheres to the established convention, defined by interfaces. + +Flexibilty means less risk. Generalizing may take more front-end design time, but reduces the amplitude of wild-schedule swings on the back end. +--- Ramifications +Compositional reuse can lead a design down a dead end. If a class inherits everything from a composed class and implements a new subsystem, without a solid set of abstract interfaces ( or contracts ) to define exactly where in the tree the new functionality branches off from ( or differs from the previous incarnation ), it is likely that new functionality will simply rewrite existing functionality. + +So there is a place on the spectrum between strict inheritance hierarchy-to-god class compositional multipurposing that must be chosen carefully. Too tight interface adherence limits the diversity that future implementations can create. Too little interface adherance and excessive use of ad-hoc compositional reuse encourages rewrites and big-ball-of-mud designs. Overgeneralization -The attempt to use generic structures is a noble goal but there is a limit to how far to take it The architect of class families must focus on the real purpose of the design effort Is it to solve a particular problem with a flexible building block pattern that reduces the risk that changing requirements will render the code unusable? -Or is the design effort moving dangerously toward overgeneralization For example a good home builder might carry a variety of tools saws hammer etc some of which may even be used to build other tools eg scaffolding for painting But the home builder doesnt carry a smelting forge in the truck He doesnt need that much generality and to attempt such would actually be counterproductive for building a house so the principle is to keep some perspective about the goal you are trying to achieve - -Too much factoring and generalizing can cause unnecessary complexity As the class family becomes more fragmented and modular it becomes harder for the consumer to understand how to use it - -So the place on the spectrum of generalismtospecialization is important There is always a design tradeoff As Spolsky says the trash can must be open on top so people can put trash in But it needs to be closed on top so trash doesnt blow away - - -Generalization practical implications and best practices - -The structure of the IHandler family beginning with the IHandler interface and ending with the HondaHandler -is constructed with inheritance and composition - -The HondaHandler inherits functionality from the trunk GenericHandler But GenericHandler is actually formed of inheritance from IGenericHandler and IHandler but also of composition with another family tree IISOReply So the trunk HondaHandler inherits is already a compositional mixture and not a strict inheritance hierarchy of is a relationships The mixing of the ISOMeasurementsTOISOReply functions and an IISOReply family member into the IHandler family hierarchy effectively constrains handlers derived from GenericHandler to being OBD IIbased handlers - -HondaHandler is also formed with a mix of inheritance and composition; inheriting from GenericHandler but also formed by being composed with IGenericAsyncHandler - -In principle if the classes form a definite tight hierarchy and really could not be split into separate pieces that are independently functional use inheritance Another rule of thumb is if the relationship is a direct building *upon* use inheritance If the relationship is a kind of association with or equal level partnership use composition If the classes could be split use a composition approach to achieve the right mix of lateral building blocks - -The GenericHandler is made concrete on the OBD II side and left abstract on the Honda side because this is the most likely usage pattern The next logical step for the IHandler family tree would be to branch off at the GenericHandler level to create a concrete implementation of another proprietary standard that needed to adapt to the now ubiquitious OBD II standard This is a likely reuse pattern but not the only one afforded by the generalization topology described here It is hard to conceptualize exactly what could be constructed with the existing modules and interfaces or contracts but that is the beauty of infrastructure in the designers opinion - - -Generalization principles serve as design heuristics when building reusable infrastructure or tooling to build Mediators like GenericHandler where one or more sides may be unknown at the time of construction of the tooling +The attempt to use generic structures is a noble goal, but there is a limit to how far to take it. The architect of class families must focus on the real purpose of the design effort. Is it to solve a particular problem, with a flexible building block pattern, that reduces the risk that changing requirements will render the code unusable? +Or is the design effort moving dangerously toward overgeneralization. For example, a good home builder might carry a variety of tools, saws, hammer, etc, some of which may even be used to build other tools. e.g. scaffolding for painting. But the home builder doesn't carry a smelting forge in the truck. He doesn't need that much generality and to attempt such would actually be counterproductive - for building a house - so the principle is to keep some perspective about the goal you are trying to achieve. + +Too much factoring and generalizing can cause unnecessary complexity. As the class family becomes more fragmented and modular it becomes harder for the consumer to understand how to use it. + +So the place on the spectrum of generalism-to-specialization is important. There is always a design trade-off. As Spolsky says, the trash can must be open on top so people can put trash in. But it needs to be closed on top so trash doesn't blow away. + + +Generalization, practical implications and best practices + +The structure of the IHandler family, beginning with the IHandler interface and ending with the HondaHandler. +is constructed with inheritance and composition. + +The HondaHandler inherits functionality from the trunk, GenericHandler. But GenericHandler is actually formed of inheritance from IGenericHandler and IHandler, but also of composition with another family tree, IISOReply. So the trunk HondaHandler inherits is already a compositional mixture and not a strict inheritance hierarchy of 'is a' relationships. The mixing of the ISOMeasurementsTOISOReply functions and an IISOReply family member into the IHandler family hierarchy effectively constrains handlers derived from GenericHandler to being OBD II-based handlers. + +HondaHandler is also formed with a mix of inheritance and composition; inheriting from GenericHandler but also formed by being composed with IGenericAsyncHandler. + +In principle, if the classes form a definite tight hierarchy and really could not be split into separate pieces that are independently functional, use inheritance. Another rule of thumb is if the relationship is a direct building *upon* , use inheritance. If the relationship is a kind of association with, or equal level partnership, use composition. If the classes could be split, use a composition approach to achieve the right mix of 'lateral' building blocks. + +The GenericHandler is made concrete on the OBD II side and left abstract on the Honda side because this is the most likely usage pattern. The next logical step for the IHandler family tree would be to branch off at the GenericHandler level to create a concrete implementation of another proprietary standard that needed to adapt to the now ubiquitious OBD II standard. This is a likely re-use pattern, but not the only one afforded by the generalization topology described here. It is hard to conceptualize exactly what could be constructed with the existing modules and interfaces ( or contracts ) but that is the beauty of infrastructure in the designer's opinion. + + +Generalization principles serve as design heuristics when building re-usable infrastructure ( or tooling ) to build Mediators like GenericHandler where one or more sides may be unknown at the time of construction of the tooling. Mixins -The IHandler family may benefit from a more formal analysis and redesign using mixins which are a combination of methods from separate classes +The IHandler family may benefit from a more formal analysis and re-design using mixins, which are a combination of methods from separate classes. Traits -The IHandler family may benefit from a more formal analysis and redesign using traits a set of methods that implement a behaviour and a set of methods that parameterize that behaviour - - -See Also Class References GenericHandler HondaHandler - -Template - -IHandler provides a template for any class that may be used as a handler by CommMessageProcessor -HondaHandler is the most derived class from this template - -IISOReply provides a template for any class that replies to the ISOPort ISOReply9141 and ISOReply14320 build on this template - -GenericBusInitAttempt provides a template for classes that attempt OBD II protocol bus initialization Since there are three similar but nontheless unique possible methods of initialization ISO9141 ISO14230slow and ISO14230fast the shared code between these three is factored into the template and only the unique characteristics remain in the most derived classes BusInitAttemptISO9141 BusInitAttemptISO14230slow BusInitAttemptISO14230fast +The IHandler family may benefit from a more formal analysis and re-design using traits, a set of methods that implement a behaviour and a set of methods that parameterize that behaviour. + + +See Also, _Class References_ "GenericHandler", "HondaHandler" + +Template: + +IHandler provides a template for any class that may be used as a handler, by CommMessageProcessor. +HondaHandler is the most derived class from this template. + +IISOReply provides a template for any class that replies to the ISOPort. ISOReply_9141 and ISOReply14320 build on this template. + +GenericBusInitAttempt provides a template for classes that attempt OBD II protocol bus initialization. Since there are three similar but nontheless unique possible methods of initialization (ISO9141, ISO14230_slow, and ISO14230_fast) the shared code between these three is factored into the template and only the unique characteristics remain in the most derived classes (BusInitAttempt_ISO9141, BusInitAttempt_ISO14230_slow, BusInitAttempt_ISO14230_fast). Information Hiding and Encapsulation -ISOPort and HondaPort encapsulate the checksum running total variable improving code safety +ISOPort and HondaPort encapsulate the checksum running total variable, improving code safety. -Each coordinator BusCoordinator CommCoordinator HondaCommCoordinator or controller TryReady BusInitAttempt CommMessageCollector etc hides its internal state providing a standard interface This improves safety and reduces the need to understand the internal details to make changes to the logic using these functional units - -HondaMap and ISOPID classes hide the lowlevel details of these data structures providing a safer eg a Honda address can never be inadvertently associated with wrong length because they are stored together more convenient way of manipulating these logical units +Each coordinator (BusCoordinator, CommCoordinator, HondaCommCoordinator) or controller (TryReady, BusInitAttempt, CommMessageCollector, etc) hides its internal state, providing a standard interface. This improves safety and reduces the need to understand the internal details to make changes to the logic using these functional units. + +HondaMap and ISOPID classes hide the low-level details of these data structures, providing a safer ( e.g. a Honda address can never be inadvertently associated with wrong length because they are stored together ), more convenient way of manipulating these logical units. Command Pattern -GenericHandler contains a function ISOPIDTOGENERICHANDLERMAP that is built in a command pattern that lends itself to further adhoc modification by adding executable code within the respective command hooks -Each ISOPID is treated as a command object directing execution into the appropriate sensor data retrieval function This pattern is extensible for example easily allowing for two or more separate retrieval steps or other adhoc functionality in the commanded subroutine - - -Chain of Responsibility -The functional colleagues CommMessageProcessor and HondaHandler exhibit characteristics of a Chain of Responsibility pattern The CommMessageProcessor does not directly handle the gathering of the data that is required for the successful conversions of the PID it receives into Honda data Rather it relies on an indirect Chain of Responsibility When a PID is received by CommMessageProcessor a delegating call to IncomingPID is made This shifts responsibility of actually completing this task onto another subsystem - - -HondaHandler AssignWork GeneralAsyncRequest -The HondaHandler sends a message to HondaCommCoordinator using AssignWork to retrieve the appropriate data from the HondaPort The AssignWork function shifts the responsibility to the HondaCommCoordinator to retrieve the data The HondaCommCoordinator is given the responsibility for retrieving the data and is also given the tools in the form of a Callback function pointer to *ASYNCHRONOUSLY* satisfy its obligation of returning the data - -The BusCoordinator BusInit and GenericBusInitAttempt or GenericBusInitComplete form a Chain of Responsibility pattern The BusCoordinator is responsible for the overall bus initialization sequences but it delegates responsibilty for this task to two associated classes TryReady and BusInit BusInit then transfers responsibility to its delegates GenericBusInitAttempt and GenericBusInitComplete Thus the responsibility for certain actions is transferred in a chain - -The main event loop and select parts of the class design could be considered an example of Responsibility Driven Design using a ClusteredDelegated control Structure - - - -State - -Many examples -The main event loop stores state about the overall OBD II connection state with two macro level states NOCOMM and COMMESTAB -BusCoordinator stores state about the state of bus handshaking -BusInitAttempt stores state about the state of the bus initialization attempt -Each of these units is called repeatedly to accomplish a single logical task and they keep track of where they are by a State pattern; they are guided and alter their behaviour based on their transient state - -DoneWorking and Reset provide consistent safe encapsulated access to the state - -The main event loop and all the subsidiary loops contained within could all be considered an example of one complex Automaton These structures could also be described as finite state machines - -Strategy - -The implementation of IHandlerIncomingPID by HondaHandler could be considered one Strategy for dealing with the incoming OBD II request This larger unit of work seems to qualify as a strategy and diverges from the Template definition of mere alteration of subtle details by a class deriving from a Template -Compare Template - - - - - -Mediator - -GenericHandler is a mediator because it is the only class that knows the internal details of two systems the OBD II system and the Honda system - -From the perspective of the CommMessageProcessor the IHandler base interface presents a simplified interface to the Honda side that consists of only one function call IncomingPID - -From the perspective of the Honda side GenericHandler presents a simplified interface to the OBD II side that consists of a group of ISOMeasurementsToISOReplyXXXX reply functions The input and operation of these functions is well defined and simple - -Thus the GenericHandler serves as a mediator providing a simplified interface to a complex task of obtaining Honda sensor data as well a providing a simplified interface to a complex task of sending data to the OBD II port using the proper protocol mediating these two sides of the system - -Adapter -At a macro level the entire hardware software system is an Adapter converting and translating the requests and data from one system into a format compatible with another system +GenericHandler contains a function ISOPID_TO_GENERIC_HANDLER_MAP(), that is built in a command pattern that lends itself to further ad-hoc modification by adding executable code within the respective command hooks. +Each ISOPID is treated as a command object, directing execution into the appropriate sensor data retrieval function. This pattern is extensible, for example, easily allowing for two or more separate retrieval steps or other ad-hoc functionality in the commanded subroutine. + + +Chain of Responsibility: +The functional colleagues CommMessageProcessor and HondaHandler exhibit characteristics of a Chain of Responsibility pattern. The CommMessageProcessor does not directly handle the gathering of the data that is required for the successful conversions of the PID it receives into Honda data. Rather, it relies on an indirect Chain of Responsibility. When a PID is received by CommMessageProcessor, a delegating call to IncomingPID is made. This shifts responsibility of actually completing this task onto another subsystem. + + +HondaHandler, AssignWork, GeneralAsyncRequest +The HondaHandler sends a message to HondaCommCoordinator using AssignWork to retrieve the appropriate data from the HondaPort. The AssignWork function shifts the responsibility to the HondaCommCoordinator to retrieve the data. The HondaCommCoordinator is given the responsibility for retrieving the data, and is also given the tools, in the form of a Callback function pointer, to *ASYNCHRONOUSLY* satisfy it's obligation of returning the data. + +The BusCoordinator, BusInit and GenericBusInitAttempt (or GenericBusInitComplete) form a Chain of Responsibility pattern. The BusCoordinator is responsible for the overall bus initialization sequences, but it delegates responsibilty for this task to two associated classes, TryReady and BusInit. BusInit then transfers responsibility to its' delegates GenericBusInitAttempt and GenericBusInitComplete. Thus the responsibility for certain actions is transferred in a chain. + +The main event loop and select parts of the class design could be considered an example of Responsibility Driven Design, using a Clustered/Delegated control Structure. + + + +State: + +Many examples: +The main event loop stores state about the overall OBD II connection state with two macro level states, NO_COMM and COMM_ESTAB. +BusCoordinator stores state about the state of bus handshaking. +BusInitAttempt stores state about the state of the bus initialization attempt. +Each of these units is called repeatedly to accomplish a single logical task and they keep track of where they are by a State pattern; they are guided and alter their behaviour based on their transient state. + +DoneWorking() and Reset() provide consistent, safe, encapsulated access to the state. + +The main event loop and all the subsidiary loops contained within could all be considered an example of one complex Automaton. These structures could also be described as finite state machines. + +Strategy: + +The implementation of IHandler.IncomingPID() by HondaHandler could be considered one Strategy for dealing with the incoming OBD II request. This larger unit of work seems to qualify as a strategy and diverges from the Template definition of mere alteration of subtle details by a class deriving from a Template. +Compare Template. + + + + + +Mediator: + +GenericHandler is a mediator because it is the only class that knows the internal details of two systems: the OBD II system and the Honda system. + +From the perspective of the CommMessageProcessor, the IHandler base interface presents a simplified interface to the Honda side that consists of only one function call, IncomingPID. + +From the perspective of the Honda side GenericHandler presents a simplified interface to the OBD II side that consists of a group of ISOMeasurementsToISOReply...XXXX reply functions. The input and operation of these functions is well defined and simple. + +Thus the GenericHandler serves as a mediator, providing a simplified interface to a complex task of obtaining Honda sensor data as well a providing a simplified interface to a complex task of sending data to the OBD II port using the proper protocol, mediating these two sides of the system. + +Adapter: +At a macro level, the entire hardware / software system is an Adapter, converting and translating the requests and data from one system into a format compatible with another system. @@ -444,55 +444,55 @@ Software Serial -The SoftwareSerial library was chosen for two reasons The Arduino only has one hardware serial port and the best use for this port is as a debugging aid to see the trace messages from the monitor - -The other reason is that there is a need to operate the serial port at a nonstandard Honda baud rate The serial timing in SoftwareSerialh was adjusted though minimally for 9470 baud The original timing for 9600 baud worked before these adjustments were made This baud rate is relatively low and the difference between the Honda rate and the standard rate is small so it is possible these timing adjustments are superfluous - -Due to the nature of the SoftwareSerial interrupt driven design only one serial port can be active at any time Therefore at precise junctions in the control structure each port is activated with a listen statement - -Half Duplex This section is unconfirmed and based on the best knowledge of the designer - -SoftwareSerialWithHalfDuplex is used because the communication line on the Honda Diagnostic Link Connector is half duplex that is only one member the client HonOBDapt or the server on board computer ECU can transmit data at one time SoftwareSerialWithHalfDuplex supports this configuration by specifying the same pin for Transmit and Receive It is the responibillty of the HondaCommCoordinator to enforce this constraint as the behaviour of SoftwareSerialWithHalfDuplex if an attempt is made to transmit and receive at the same time is unknown - -The OBD II ISOPort is also half duplex but is connected to the MC33660 which has a full duplex style of connection with both Receive and Transmit pin connections This provides a physical electrical way of enforcing half duplex on the OBD II KLine as a communications participant attempting to bring the line low or high while the other participant is still transmitting will simply be ignored by the circuitry in the MC33660 +The SoftwareSerial library was chosen for two reasons. The Arduino only has one hardware serial port, and the best use for this port is as a debugging aid to see the trace messages from the monitor. + +The other reason is that there is a need to operate the serial port at a non-standard Honda baud rate. The serial timing in SoftwareSerial.h was adjusted, though minimally, for 9470 baud. The original timing for 9600 baud worked before these adjustments were made. This baud rate is relatively low and the difference between the Honda rate and the standard rate is small, so it is possible these timing adjustments are superfluous. + +Due to the nature of the SoftwareSerial interrupt driven design, only one serial port can be active at any time. Therefore, at precise junctions in the control structure, each port is activated with a .listen() statement. + +Half Duplex. This section is unconfirmed and based on the best knowledge of the designer. + +SoftwareSerialWithHalfDuplex is used because the communication line on the Honda Diagnostic Link Connector is half duplex, that is, only one member, the client (HonOBDapt) or the server (on board computer, ECU) can transmit data at one time. SoftwareSerialWithHalfDuplex supports this configuration by specifying the same pin for Transmit and Receive. It is the responibillty of the HondaCommCoordinator to enforce this constraint, as the behaviour of SoftwareSerialWithHalfDuplex if an attempt is made to transmit and receive at the same time is unknown. + +The OBD II ISOPort is also half duplex, but is connected to the MC33660 which has a full duplex style of connection with both Receive and Transmit pin connections. This provides a physical, electrical way of enforcing half duplex on the OBD II K-Line, as a communications participant attempting to bring the line low or high while the other participant is still transmitting will simply be ignored by the circuitry in the MC33660. MC33660 -MC33660 is a level conversion integrated circuit that converts 5 volt logic signals to 12 volt logic signals This is necessary because the main hardware component the Arduino uses 5 volt signals on its digital IO pins and OBD II specifies 12 volt signals MC33660 is an integrated circuit specifically designed for logic level conversion in an OBD II automotive application and should therefore be particularly suited to this application in terms of susceptibility to noise overload protection etc MC33660 is designed to be connected to the KLine bus and therefore provides an appropriate electrical interface for serial communications and busstyle level transitions +MC33660 is a level conversion integrated circuit that converts 5 volt logic signals to 12 volt logic signals. This is necessary because the main hardware component, the Arduino, uses 5 volt signals on its' digital I/O pins and OBD II specifies 12 volt signals. MC33660 is an integrated circuit specifically designed for logic level conversion in an OBD II automotive application and should therefore be particularly suited to this application in terms of susceptibility to noise, overload protection, etc. MC33660 is designed to be connected to the K-Line bus and therefore provides an appropriate electrical interface for serial communications and bus-style level transitions. Arduino -Arduino provides 5 volt logic level digital IO pins that are suited to this application The application of a software library that allows serial communications on any pin provides significant flexibility Arduino has flexible power supply requirements and can be operated on a 12 volt system Nominal current draw through the onboard voltage regulator in this application is 200mA Heat created by the voltage regulator dropping 12 volts to 5 volts to power the on board processor is dissipated by a small onboard heatsink so the current limits and supply voltage combination must be carefully selected The current configuration is within limits to the best knowledge of the designer and has been anecdotally confirmed by feeling for excess heat from the voltage regulator +Arduino provides 5 volt logic level digital I/O pins that are suited to this application. The application of a software library that allows serial communications on any pin provides significant flexibility. Arduino has flexible power supply requirements and can be operated on a 12 volt system. Nominal current draw through the onboard voltage regulator in this application is 200mA. Heat created by the voltage regulator dropping 12 volts to 5 volts to power the on board processor is dissipated by a small on-board heatsink, so the current limits and supply voltage combination must be carefully selected. The current configuration is within limits to the best knowledge of the designer and has been anecdotally confirmed by feeling for excess heat from the voltage regulator. OBD II -The OBD II electrical and logical communications standard is actually a conglomeration of many existing standards at the time of creation of the OBD II standard by ISO This adapter supports the KLine standards of ISO9141 ISO14230slow and ISO14230fast Only one is technically required as any OBD II compliant scanner must be able to work with all three but the implementations vary only minimally and provide a good exercise and example of certain software design techniques +The OBD II electrical and logical communications standard is actually a conglomeration of many existing standards at the time of creation of the OBD II 'standard' by ISO. This adapter supports the K-Line standard(s) of ISO-9141, ISO-14230_slow, and ISO-14230_fast. Only one is technically required as any OBD II compliant scanner must be able to work with all three, but the implementations vary only minimally and provide a good exercise and example of certain software design techniques. TODO -Asynchronous Multitasking - -There should be an ITask interface to constrain and define the exact nature of the controllers that have the Work DoneWorking and Reset functions - -Handler class family construction - -The sensor data virtual function prototypes in GenericHandler should be split into a separate interface definition then implemented virtually by GenericHandler and concretely by more derived classes like HondaHandler - -The ISOMeasurementToISOReplyXXXX family of functions should be extracted out of GenericHandler and put in a separate mixin - -The IGeneralAsyncHander should be expanded and more clearly defined to include the GeneralAsyncRequest function defined in an adhoc manner in HondaHandler - -Other - -The HondaCommCoordinator should implement an IWorkQueue interface clarifying the role of the Assignwork function - -The magic numbers of the digital IO pins used for serial communications in SoftwareSerial should be extracted out into a define +----Asynchronous Multitasking: + +There should be an ITask interface to constrain and define the exact nature of the controller(s) that have the Work(), DoneWorking(), and Reset() functions. + +-----Handler class family construction: + +The sensor data virtual function prototypes in GenericHandler should be split into a separate interface definition, then implemented virtually by GenericHandler and concretely by more derived classes like HondaHandler. + +The ISOMeasurementToISOReply...XXXX family of functions should be extracted out of GenericHandler and put in a separate mix-in. + +The IGeneralAsyncHander should be expanded and more clearly defined to include the GeneralAsyncRequest function defined in an ad-hoc manner in HondaHandler. + +----Other + +The HondaCommCoordinator should implement an IWorkQueue interface, clarifying the role of the Assignwork function. + +The magic number(s) of the digital I/O pins used for serial communications in SoftwareSerial should be extracted out into a #define. &lt;/pre&gt;</pre>Andrew smithFri, 21 Jun 2013 14:20:04 -0000https://sourceforge.netaf68b3ba674f2c630afd8313dffade78c1a25740https://sourceforge.net/p/honobdapt/wiki/add/<div class="markdown_content"><pre>--- v47 +++ v48 @@ -1,7 +1,6 @@ - -HonOBDapt 10 +###HonOBDapt 10 a Intro Summary </pre> </div>Andrew smithFri, 21 Jun 2013 14:18:40 -0000https://sourceforge.net1b0e2d9cbae4248427003d43b89bb7f5463de936https://sourceforge.net/p/honobdapt/wiki/add/<pre>&lt;pre&gt;--- v46 +++ v47 @@ -1,74 +1,76 @@ -###HonOBDapt 1.0 - - -a. Intro, Summary -b. Prototype - -HonOBDapt translates requests for on-board automotive computer sensor data from an ISO standard OBD II format to a Honda proprietary format used in 92-95 Honda Civics. - -HonOBDapt uses a general purpose microcontroller module equipped with external digital I/O ports, the Arduino Uno Rev. 3. HonOBDapt uses a Freescale MC33660 ISOLink logic level converter integrated circuit to electrically connect the OBD II signal line to the Arduino. HonOBDapt software is written in C++ and uses the SoftwareSerialWithHalfDuplex library. - -HonOBDapt supports core interactive diagnostic functionality of the OBD II standard, comprised of essential sensor data including: air and coolant temperature, spark advance, fuel injector pulse width, exhaust gas oxygen content, engine speed (RPM), short and long term fuel trim, fuel system status (open or closed loop), manifold barometric pressure, atmospheric barometric pressure, throttle position, vehicle speed, etc. There is also a basic capability of translating check engine diagnostic trouble codes (DTCs). There is no support for obtaining OBD II freeze frame data, nor any analog to the concept of continuous fuel status, EVAP system or misfire monitoring. - -These limitations notwithstanding this adapter serves a crucial purpose in allowing 92-95 Honda Civics to be diagnosed with modern, readily available OBD II diagnostic scanners. - - -A prototype was constructed with the following: several trips to the junkyard to buy a Honda on board computer (ECU) and OBD II standard connectors, lots of hot glue and some mild eyestrain from trying to solder the MC33660, which is manufactured only in a package intended for automated assembly. The prototype was tested with an ELM compatible Bluetooth OBD II scanner. The prototype was tested with the OBD II PC software packages Scantool and OBDAutoDoctor. - - -Sections I, II, III: C++ Software Specification -Sections IV, V, VI, VII: Electrical and Hardware specification -Section VIII: TODO - -I. Control Flow - a. Asynchronous Processing Unit Design - b. Main Event Loop - c. State controller design, considerations -II. Class Reference - a. BusCoordinator - b. BusInit - c. TryReady - d. GenericBusInitAttempt - e. GenericBusInitComplete - f. CommCoordinator - g. GenericCommMessageCollector - h. GenericCommMessageProcessor - i. HondaCommCoordinator - j. HondaCommMessageCollector - k. HondaCommMessageProcessor - l. IHandler - m. IGenericHandler - o. IISOReply - p. GenericISOReply - n. GenericHandler - q. HondaHandler - r. HondaPort, ISOPort - s. HondaMap, ISOPID + + +HonOBDapt 10 + + +a Intro Summary +b Prototype + +HonOBDapt translates requests for onboard automotive computer sensor data from an ISO standard OBD II format to a Honda proprietary format used in 9295 Honda Civics + +HonOBDapt uses a general purpose microcontroller module equipped with external digital IO ports the Arduino Uno Rev 3 HonOBDapt uses a Freescale MC33660 ISOLink logic level converter integrated circuit to electrically connect the OBD II signal line to the Arduino HonOBDapt software is written in C++ and uses the SoftwareSerialWithHalfDuplex library + +HonOBDapt supports core interactive diagnostic functionality of the OBD II standard comprised of essential sensor data including air and coolant temperature spark advance fuel injector pulse width exhaust gas oxygen content engine speed RPM short and long term fuel trim fuel system status open or closed loop manifold barometric pressure atmospheric barometric pressure throttle position vehicle speed etc There is also a basic capability of translating check engine diagnostic trouble codes DTCs There is no support for obtaining OBD II freeze frame data nor any analog to the concept of continuous fuel status EVAP system or misfire monitoring + +These limitations notwithstanding this adapter serves a crucial purpose in allowing 9295 Honda Civics to be diagnosed with modern readily available OBD II diagnostic scanners + + +A prototype was constructed with the following several trips to the junkyard to buy a Honda on board computer ECU and OBD II standard connectors lots of hot glue and some mild eyestrain from trying to solder the MC33660 which is manufactured only in a package intended for automated assembly The prototype was tested with an ELM compatible Bluetooth OBD II scanner The prototype was tested with the OBD II PC software packages Scantool and OBDAutoDoctor + + +Sections I II III C++ Software Specification +Sections IV V VI VII Electrical and Hardware specification +Section VIII TODO + +I Control Flow + a Asynchronous Processing Unit Design + b Main Event Loop + c State controller design considerations +II Class Reference + a BusCoordinator + b BusInit + c TryReady + d GenericBusInitAttempt + e GenericBusInitComplete + f CommCoordinator + g GenericCommMessageCollector + h GenericCommMessageProcessor + i HondaCommCoordinator + j HondaCommMessageCollector + k HondaCommMessageProcessor + l IHandler + m IGenericHandler + o IISOReply + p GenericISOReply + n GenericHandler + q HondaHandler + r HondaPort ISOPort + s HondaMap ISOPID -III. Patterns and Principles - SubSections a, b, c, d, e, f: Object Oriented Characteristics - SubSections g, h, i, j, k, l, m: Gang of Four Patterns - - a. Polymorphism - b. Loose Coupling, - c. Separation of Concerns - d. Information Hiding and Encapsulation - e. Reuse and Inheritance - f. Generalization - g. Template - h. Command Pattern - i. Chain of Responsibility, Responsibility Driven Design - j. State, Automaton, finite state machine - k. Strategy - l. Mediator - m. Adapter - -IV. Serial Ports -V. MC33660 -VI. Arduino -VII. OBD II -VIII. TODO +III Patterns and Principles + SubSections a b c d e f Object Oriented Characteristics + SubSections g h i j k l m Gang of Four Patterns + + a Polymorphism + b Loose Coupling + c Separation of Concerns + d Information Hiding and Encapsulation + e Reuse and Inheritance + f Generalization + g Template + h Command Pattern + i Chain of Responsibility Responsibility Driven Design + j State Automaton finite state machine + k Strategy + l Mediator + m Adapter + +IV Serial Ports +V MC33660 +VI Arduino +VII OBD II +VIII TODO @@ -77,200 +79,200 @@ Asynchronous processing unit design -Generally, classes involved in handshaking and serial communications support Work(), DoneWorking() and Reset(). -These functions serve as a basic cooperative multitasking system. Work() is called when a higher level controller has a time slice to give to the unit. The Work() function of each controller is expected to do its' work, and exit quickly. If the conditions are met that allow the handshaking or communications to proceed to the next higher level, DoneWorking() should return true. Reset() is used to reset the internal state of the unit, typically at the end of a logical session controlled by a higher level controller. - -Generally, the units are one-shot triggers. If, for example, a unit is falsely triggered to initiate a particular process ( by noise or an invalid packet ), it will continue to attempt completion of the process and cannot properly proceed with a valid sequence until it is Reset() by a higher level controller. +Generally classes involved in handshaking and serial communications support Work DoneWorking and Reset +These functions serve as a basic cooperative multitasking system Work is called when a higher level controller has a time slice to give to the unit The Work function of each controller is expected to do its work and exit quickly If the conditions are met that allow the handshaking or communications to proceed to the next higher level DoneWorking should return true Reset is used to reset the internal state of the unit typically at the end of a logical session controlled by a higher level controller + +Generally the units are oneshot triggers If for example a unit is falsely triggered to initiate a particular process by noise or an invalid packet it will continue to attempt completion of the process and cannot properly proceed with a valid sequence until it is Reset by a higher level controller Main Event Loop -The main event loop cycles through the upper lever coordinators, BusCoordinator, CommCoordinator and HondaCommCoordinator in a round robin fashion, calling .Work() and checking .DoneWorking() on each one. - -The OBD II port requires a bus initialization handshaking sequences. No bus initialization is necessary on the HondaPort. - -The main event loop strives to move the system into higher and higher levels of functioning. The macro levels of functioning are: -Level 1. OBD II bus not initialized -Level 2. OBD II bus initialized, waiting for incoming request from the OBD II port. -Level 3. Message received from the OBD II port and forwarded to the HondaPort, waiting for message from HondaPort -Level 4. Message received from the HondaPort and forwarded to the OBD II port. - -Once the functioning level reaches 4, the process restarts generally at level 2, but possibly level 1. - -Level 1. - -The main event loop maintains a state variable that is either NO_COMM or COMM_ESTAB. Each time through the main event loop, if the state is NO_COMM (bus not initialized), then BusCoordinator.Work() is called. -The BusCoordinator will work to initialize the OBD II bus and achieve a higher state, COMM_ESTAB, by using TryReady, BusInit, GenericBusInitAttempt and GenericBusInitComplete. After the call to BusCoordinator.Work(), BusCoordinator.DoneWorking() is checked. If this function returns true, then the bus is ready for communications and the state is set to COMM_ESTAB. if DoneWorking() is not true, the main event loop restarts, again attempting to raise the functioning level by successfully initializating the OBD II bus. - -Level 2. -Once the bus is initialized, CommCoordinator.Work() will be called to try to continue to raise the processing level. -CommCoordinator will use GenericCommMessageCollector to get any incoming data on the OBD II port. - -If there is no data available immediately on the serial port, the GenericCommMessageCollector.Work() will exit immediately; this allows the CommCoordinator to exit and yield control to the main event loop. - -If there is waiting data, the data will be retrieved and a state of COLLECT will be marked internally to GenericCommMessageCollector. - -During the next iteration through the main event loop, CommCoordinator.Work() will be called and the Work() function will call GenericCommMessageCollector.Work(). If there is more data available on the OBD II port, that data will be collected by the GenericCommMessageCollector. Since the internal state of GenericCommMessageCollector is COLLECT, the new data will be appended to the existing message buffer. +The main event loop cycles through the upper lever coordinators BusCoordinator CommCoordinator and HondaCommCoordinator in a round robin fashion calling Work and checking DoneWorking on each one + +The OBD II port requires a bus initialization handshaking sequences No bus initialization is necessary on the HondaPort + +The main event loop strives to move the system into higher and higher levels of functioning The macro levels of functioning are +Level 1 OBD II bus not initialized +Level 2 OBD II bus initialized waiting for incoming request from the OBD II port +Level 3 Message received from the OBD II port and forwarded to the HondaPort waiting for message from HondaPort +Level 4 Message received from the HondaPort and forwarded to the OBD II port + +Once the functioning level reaches 4 the process restarts generally at level 2 but possibly level 1 + +Level 1 + +The main event loop maintains a state variable that is either NOCOMM or COMMESTAB Each time through the main event loop if the state is NOCOMM bus not initialized then BusCoordinatorWork is called +The BusCoordinator will work to initialize the OBD II bus and achieve a higher state COMMESTAB by using TryReady BusInit GenericBusInitAttempt and GenericBusInitComplete After the call to BusCoordinatorWork BusCoordinatorDoneWorking is checked If this function returns true then the bus is ready for communications and the state is set to COMMESTAB if DoneWorking is not true the main event loop restarts again attempting to raise the functioning level by successfully initializating the OBD II bus + +Level 2 +Once the bus is initialized CommCoordinatorWork will be called to try to continue to raise the processing level +CommCoordinator will use GenericCommMessageCollector to get any incoming data on the OBD II port + +If there is no data available immediately on the serial port the GenericCommMessageCollectorWork will exit immediately; this allows the CommCoordinator to exit and yield control to the main event loop + +If there is waiting data the data will be retrieved and a state of COLLECT will be marked internally to GenericCommMessageCollector + +During the next iteration through the main event loop CommCoordinatorWork will be called and the Work function will call GenericCommMessageCollectorWork If there is more data available on the OBD II port that data will be collected by the GenericCommMessageCollector Since the internal state of GenericCommMessageCollector is COLLECT the new data will be appended to the existing message buffer Level 3 -A true return value from GenericCommMessageCollector.DoneWorking() signifies that a complete and valid OBD II message has been received and the internal state of the coordinator, CommCoordinator, will be marked as MESSAGE_RECEIVED. Then the GenericCommMessageProcessor will become active, processing the request by calling HondaHandler.IncomingPID(). The HondaHandler will translate the OBD II PID to an appropriate request for Honda data and will call SendHondaRequest() to send a command sequence to the HondaPort. HondaHandler will then assign the request to the HondaCommCoordinator, which queues the request, using a function pointer to establish a non-blocking asynchronous callback to be executed when the HondaPort data is ready. -CommMessageProcessor and CommCoordinator then yield control to the main event loop. - -During the next iteration of the main event loop, HondaCommCoordinator.Work() will be called and the HondaCommCoordinator will pick up the queued request and set an internal state of WORKING. The HondaCommCoordinator will use the HondaCommMessageCollector to get any incoming data on the HondaPort. If there is waiting data, the character data will be retrieved and a state of COLLECT will be marked internally in the HondaCommMessageCollector - -DUring the next iteration through the main event loop, HondaCommCoordinator.Work() will be called. If there is more data, that data will be collected by the HondaCommMessageCollector. Since the internal state of HondaCommMessageCollector is COLLECT the new data will be appended to the existing message buffer. +A true return value from GenericCommMessageCollectorDoneWorking signifies that a complete and valid OBD II message has been received and the internal state of the coordinator CommCoordinator will be marked as MESSAGERECEIVED Then the GenericCommMessageProcessor will become active processing the request by calling HondaHandlerIncomingPID The HondaHandler will translate the OBD II PID to an appropriate request for Honda data and will call SendHondaRequest to send a command sequence to the HondaPort HondaHandler will then assign the request to the HondaCommCoordinator which queues the request using a function pointer to establish a nonblocking asynchronous callback to be executed when the HondaPort data is ready +CommMessageProcessor and CommCoordinator then yield control to the main event loop + +During the next iteration of the main event loop HondaCommCoordinatorWork will be called and the HondaCommCoordinator will pick up the queued request and set an internal state of WORKING The HondaCommCoordinator will use the HondaCommMessageCollector to get any incoming data on the HondaPort If there is waiting data the character data will be retrieved and a state of COLLECT will be marked internally in the HondaCommMessageCollector + +DUring the next iteration through the main event loop HondaCommCoordinatorWork will be called If there is more data that data will be collected by the HondaCommMessageCollector Since the internal state of HondaCommMessageCollector is COLLECT the new data will be appended to the existing message buffer Level 4 -When the message from the HondaPort is complete and valid, signaled by the HondaCommMessageCollector returning true to DoneWorking(), the HondaCommMessageProcessor will become active and process the message by executing HondaHandler.Callback(). HondaHandler.Callback() will execute the appropriate return function matching the original asynchronous request and effect the translation of the Honda sensor data into ISO measurements, using a member of the group ISOMeasurementsTOISOReply, and the reply to the OBD II port, using a GenericHandler.IISOReply family member. - -At this point the overall state has reached its highest point of productivity. The various MessageCollector(s) and MessageProcessor(s) are reset, and the main event loop restarts at level 2, waiting for more serial messages from the OBD II port. - --- Advantages of state controller design - ----Extensibility - -This structure provides a clean, clear implementation that lends itself to further modifications and extension, such as hooks to process other data or timeout watchdogs, because there are clear places to hook into the overall flow of handshaking or messaging without the risk of undesirable interaction or needing to understand the lower level operation of each controller. - -This structure also provides a clean way to implement potentially deep nested logic in a clear, easy to debug and trace fashion. - -Each asynchronous unit is coded with the overall structure in mind. For example, TryReady.Work() will not block but will do a small amount of work, polling the OBD II K-Line bus status and checking the time-of-day ( millis() ) to maintain a running total of idle time and then Work() will exit. TryReady can maintain internal state such as the running total but encapsulates that state and signifies that internal conditions have been satisfied by returning true to DoneWorking(). Also, when logical conditions require, Reset() can be used to reset the running total. - -In this way serial communications or handshaking can be carefully controlled from the upper level. -For instance, this structure makes it easy and clear to implement an *OVERALL* handshake attempt timeout, without modifying functionally distinct units such as TryReady. - ----Error Handling - -When dealing with serial port messaging, subject to noise, message fragments being received, etc, -it is quite possible for individual functional units to become stuck or hung due to: waiting for message termination or validation that will never succeed because of mid-message corruption, invalid or nonstandard messages, etc. - -In this type of messaging environment it is important to maintain supervisory control with clear top-down control logic. The asynchronous, non-blocking Work(), DoneWorking() pattern lends itself to implementing supervisory controls. - -Of paramount importance is that the supervisory code and its' interface to lower level code be clear, distinct and concise, so that unforseen situations; i.e. dealing with slightly altered or new packets or protocol details and their concomitant issues; can be dealt with effectively. - ----Complexity and correctness - -The factoring of complicated nested communications logic into a body of state machines is an effective way of managing complexity and makes logical defects more apparent. This factoring methodology allows the program to be treated as the steps of an algorithm, facilitating the application of mathematically rigorous techniques to prove or disprove the correctness of the program logic. - --- Possible ramifications of state controller design - -Although the event loop design of the serial communications code has additional overhead compared to a more direct low-level approach, and can cause an entire event loop to be executed between individual serial character data retrievals, the overhead is mostly syntactic exposition, and is not expected to be computationally intensive. - -As well, 9600 baud is not particularly fast relative to Arduino's microprocessor speed and the SoftwareSerial library is interrupt driven ( interrupts take priority over all other execution context ) and SoftwareSerial maintains its' own input buffers. Also, the direct serial controllers, CommMessageCollector and HondaCommMessageCollector are enhanced with a burst mode that increases their priority under certain circumstances. Due to these factors it is considered extremely unlikely for the overhead of the state machine control system to cause a loss of serial data on any port. +When the message from the HondaPort is complete and valid signaled by the HondaCommMessageCollector returning true to DoneWorking the HondaCommMessageProcessor will become active and process the message by executing HondaHandlerCallback HondaHandlerCallback will execute the appropriate return function matching the original asynchronous request and effect the translation of the Honda sensor data into ISO measurements using a member of the group ISOMeasurementsTOISOReply and the reply to the OBD II port using a GenericHandlerIISOReply family member + +At this point the overall state has reached its highest point of productivity The various MessageCollectors and MessageProcessors are reset and the main event loop restarts at level 2 waiting for more serial messages from the OBD II port + + Advantages of state controller design + +Extensibility + +This structure provides a clean clear implementation that lends itself to further modifications and extension such as hooks to process other data or timeout watchdogs because there are clear places to hook into the overall flow of handshaking or messaging without the risk of undesirable interaction or needing to understand the lower level operation of each controller + +This structure also provides a clean way to implement potentially deep nested logic in a clear easy to debug and trace fashion + +Each asynchronous unit is coded with the overall structure in mind For example TryReadyWork will not block but will do a small amount of work polling the OBD II KLine bus status and checking the timeofday millis to maintain a running total of idle time and then Work will exit TryReady can maintain internal state such as the running total but encapsulates that state and signifies that internal conditions have been satisfied by returning true to DoneWorking Also when logical conditions require Reset can be used to reset the running total + +In this way serial communications or handshaking can be carefully controlled from the upper level +For instance this structure makes it easy and clear to implement an *OVERALL* handshake attempt timeout without modifying functionally distinct units such as TryReady + +Error Handling + +When dealing with serial port messaging subject to noise message fragments being received etc +it is quite possible for individual functional units to become stuck or hung due to waiting for message termination or validation that will never succeed because of midmessage corruption invalid or nonstandard messages etc + +In this type of messaging environment it is important to maintain supervisory control with clear topdown control logic The asynchronous nonblocking Work DoneWorking pattern lends itself to implementing supervisory controls + +Of paramount importance is that the supervisory code and its interface to lower level code be clear distinct and concise so that unforseen situations; ie dealing with slightly altered or new packets or protocol details and their concomitant issues; can be dealt with effectively + +Complexity and correctness + +The factoring of complicated nested communications logic into a body of state machines is an effective way of managing complexity and makes logical defects more apparent This factoring methodology allows the program to be treated as the steps of an algorithm facilitating the application of mathematically rigorous techniques to prove or disprove the correctness of the program logic + + Possible ramifications of state controller design + +Although the event loop design of the serial communications code has additional overhead compared to a more direct lowlevel approach and can cause an entire event loop to be executed between individual serial character data retrievals the overhead is mostly syntactic exposition and is not expected to be computationally intensive + +As well 9600 baud is not particularly fast relative to Arduinos microprocessor speed and the SoftwareSerial library is interrupt driven interrupts take priority over all other execution context and SoftwareSerial maintains its own input buffers Also the direct serial controllers CommMessageCollector and HondaCommMessageCollector are enhanced with a burst mode that increases their priority under certain circumstances Due to these factors it is considered extremely unlikely for the overhead of the state machine control system to cause a loss of serial data on any port CLASS REFERENCE BusCoordinator -The BusCoordinator is responsible for coordinating the bus initialization process including: bus idle time prerequisite, wakeup-packet handshaking and confirmation handshaking. -The Buscoordinator uses TryReady, BusInit, GenericBusInitAttempt, and GenericBusInitComplete. +The BusCoordinator is responsible for coordinating the bus initialization process including bus idle time prerequisite wakeuppacket handshaking and confirmation handshaking +The Buscoordinator uses TryReady BusInit GenericBusInitAttempt and GenericBusInitComplete TryReady -TryReady polls the OBD II K-Line bus pin and establishes that the necessary bus idle condition has been met before handshaking begins. +TryReady polls the OBD II KLine bus pin and establishes that the necessary bus idle condition has been met before handshaking begins BusInit -Tasked with the job of attempting and completing an OBD II bus initialization handshake sequence. Uses GenericBusInitAttempt and GenericBusInitComplete. - -GenericBusInitAttempt - establishes generic requirements for a bus initialization attempt, which begins the handshaking sequence of an OBD II session. Uses WAKE_PACK array, a storage area for K-Line bus pin logic level transition times ( 10ms, 100ms, etc ). This routine uses Arduino's digitalRead to check the logic level of the OBD II K-Line bus pin. When the pin alters state ( High to Low or Low to High ) the time-of-day ( millis() ) is recorded. This recorded value is compared to the time-of-day when the next level transition occurs, and in this way the length of the handshaking pulse or pulses is established. - -If the transition pattern is a valid OBD II K-Line bus wake-up pattern, DoneWorking() will return true. +Tasked with the job of attempting and completing an OBD II bus initialization handshake sequence Uses GenericBusInitAttempt and GenericBusInitComplete + +GenericBusInitAttempt establishes generic requirements for a bus initialization attempt which begins the handshaking sequence of an OBD II session Uses WAKEPACK array a storage area for KLine bus pin logic level transition times 10ms 100ms etc This routine uses Arduinos digitalRead to check the logic level of the OBD II KLine bus pin When the pin alters state High to Low or Low to High the timeofday millis is recorded This recorded value is compared to the timeofday when the next level transition occurs and in this way the length of the handshaking pulse or pulses is established + +If the transition pattern is a valid OBD II KLine bus wakeup pattern DoneWorking will return true The protocol specific details of the GenericBusInitAttempt are left to the more derived classes -BusInitAttempt_ISO14230_slow, BusInitAttempt_ISO14230_fast, BusInitAttempt_ISO9141 +BusInitAttemptISO14230slow BusInitAttemptISO14230fast BusInitAttemptISO9141 GenericBusInitComplete -establishes basic requirements of bus initialization completion which finishes the handshaking sequences for an OBD II session. The completion of the handshaking is accomplished by sending a confirmation message, mathematically derived from the messages received during a bus initialization attempt, to the OBD II port. - -The protocol specific details of the BusInitComplete are left to the more derived classes: -BusInitComplete_ISO9141, BusInitComplete_14230_slow, BusInitComplete_ISO14230_fast +establishes basic requirements of bus initialization completion which finishes the handshaking sequences for an OBD II session The completion of the handshaking is accomplished by sending a confirmation message mathematically derived from the messages received during a bus initialization attempt to the OBD II port + +The protocol specific details of the BusInitComplete are left to the more derived classes +BusInitCompleteISO9141 BusInitComplete14230slow BusInitCompleteISO14230fast CommCoordinator -The CommCoordinator is responsible for collecting, verifying and processing messages on the OBD II K-line serial port. Processing generally concludes with a call to HondaHandler.IncomingPID(), which accepts responsibility for replying to the OBD II K-line serial port with the requested Honda on board computer (ECU) data. Uses GenericCommMessageCollector and GenericCommMessageProcessor. +The CommCoordinator is responsible for collecting verifying and processing messages on the OBD II Kline serial port Processing generally concludes with a call to HondaHandlerIncomingPID which accepts responsibility for replying to the OBD II Kline serial port with the requested Honda on board computer ECU data Uses GenericCommMessageCollector and GenericCommMessageProcessor GenericCommMessageCollector -Collects the serial data from the OBD II port and establishes completeness (appropriate headers) and basic error-checking (checksum) of incoming serial data. - -This message collector supports a serial burst mode, assuming that an incoming serial character is usually followed by the remaining characters without delay. This routine is authorized to busy-wait (block) waiting for serial data for a maximum time interval defined by SERIAL_BURST_MAX_TIME_SLICE, before relinquishing control to its' coordinator. - -Protocol specific details are left to the more derived classes: ISOCommMessageCollector_ISO9141, ISOCommMessageCollector_ISO14230 - - -GenericCommMessageProcessor - -Processes a valid message containing an OBD II PID by calling HondaHandler.IncomingPID() to transfer responsibility for retrieving the requested data and sending a reply to the OBD II port. IncomingPID function does not block and GenericCommMessageProcessor and its' coordinator CommCoordinator can exit immediately after the call to IncomingPID. - - -Protocol specific details are left to the more derived classes: CommMessageProcessor_ISO9141, CommMessageProcessor_ISO14230 - - -HondaCommCoordinator manages Honda communications. Uses HondaCommMessageCollector and HondaCommMessageProcessor. - -Works in conjunction with the HondaHandler. Provides AssignWork function which, when called by HondaHandler, queues a request for Honda data. +Collects the serial data from the OBD II port and establishes completeness appropriate headers and basic errorchecking checksum of incoming serial data + +This message collector supports a serial burst mode assuming that an incoming serial character is usually followed by the remaining characters without delay This routine is authorized to busywait block waiting for serial data for a maximum time interval defined by SERIALBURSTMAXTIMESLICE before relinquishing control to its coordinator + +Protocol specific details are left to the more derived classes ISOCommMessageCollectorISO9141 ISOCommMessageCollectorISO14230 + + +GenericCommMessageProcessor +Processes a valid message containing an OBD II PID by calling HondaHandlerIncomingPID to transfer responsibility for retrieving the requested data and sending a reply to the OBD II port IncomingPID function does not block and GenericCommMessageProcessor and its coordinator CommCoordinator can exit immediately after the call to IncomingPID + + +Protocol specific details are left to the more derived classes CommMessageProcessorISO9141 CommMessageProcessorISO14230 + + +HondaCommCoordinator manages Honda communications Uses HondaCommMessageCollector and HondaCommMessageProcessor + +Works in conjunction with the HondaHandler Provides AssignWork function which when called by HondaHandler queues a request for Honda data HondaCommMessageCollector -Collects the serial data from the HondaPort. Establishes completeness, appropriate headers, error-checking (checksum) of incoming serial data. - -This message collector supports a serial burst mode, assuming that an incoming serial character is usually followed by the remaining characters without delay. This routine is authorized to busy-wait (block) waiting for serial data for a maximum time interval defined by SERIAL_BURST_MAX_TIME_SLICE, before relinquishing control to its' coordinator. +Collects the serial data from the HondaPort Establishes completeness appropriate headers errorchecking checksum of incoming serial data + +This message collector supports a serial burst mode assuming that an incoming serial character is usually followed by the remaining characters without delay This routine is authorized to busywait block waiting for serial data for a maximum time interval defined by SERIALBURSTMAXTIMESLICE before relinquishing control to its coordinator HondaCommMessageProcessor -Processes valid messages from the HondaPort. Processing concludes with a call to HondaHandler.Callback(), which effects translation of the Honda data and the reply to the OBD II port using a member of the GenericHandler ISOMeasurementsToISOReply group and an IISOReply family member. - - -IHandler establishes what a handler, used by the CommCoordinator.CommMessageProcessor, must do -A class implementing IHandler must support IncomingPID. At a fundamental level, to implement the IHandler interface the class must be able to do something with IncomingPID, perhaps ignoring unsupported operations. This class would be a good jumping off point for diverse purposes, for example, a class that only logs the incoming messages. - -IGenericHandler supports VIN and Capabilities. -A slightly richer implementation would be required to, at a minimum, reply with the Vehicle Identification Number and the Capabilities, which is a list of supported sensors or other data that can be retrieved. - -IISOReply is an interface defining the generic requirements of a reply to the OBD II port. - -GenericISOReply is class containing generic OBD II port reply code. -The protocol specific details are left to the more derived classes: ProtocolReply_ISO9141 and ProtocolReply_ISO14230. +Processes valid messages from the HondaPort Processing concludes with a call to HondaHandlerCallback which effects translation of the Honda data and the reply to the OBD II port using a member of the GenericHandler ISOMeasurementsToISOReply group and an IISOReply family member + + +IHandler establishes what a handler used by the CommCoordinatorCommMessageProcessor must do +A class implementing IHandler must support IncomingPID At a fundamental level to implement the IHandler interface the class must be able to do something with IncomingPID perhaps ignoring unsupported operations This class would be a good jumping off point for diverse purposes for example a class that only logs the incoming messages + +IGenericHandler supports VIN and Capabilities +A slightly richer implementation would be required to at a minimum reply with the Vehicle Identification Number and the Capabilities which is a list of supported sensors or other data that can be retrieved + +IISOReply is an interface defining the generic requirements of a reply to the OBD II port + +GenericISOReply is class containing generic OBD II port reply code +The protocol specific details are left to the more derived classes ProtocolReplyISO9141 and ProtocolReplyISO14230 GenericHandler -Adds an interface of virtual function prototypes that describe the expected input and output for a sensor data retrieval implementation and a baseline map function, ISOPID_TO_GENERIC_HANDLER_MAP, that links OBD II PIDs to functions in the sensor interface. GenericHandler builds directly upon its direct ancestor abstractions IGenericHandler and IHandler, but becomes richer and more concrete by extending outside of that family to become a composition with an IISOReply family member. - - -GenericHandler also defines functions that convert data to an OBD II format. These functions follow the naming convention ISOMeasurementsToISOReply..XXXXX. These functions accept input data in the scale dictated by the OBD II standard; i.e. temperature is measured in Celcius degress, with the input data to the function represented by the formula "Actual Temp - 40". E.G., if the temperature of the coolant is determined to be 55 deg. C., you would call ISOMeasureToISOReply_Scalar_byte( 15 ); - -The inclusion of an IISOReply family member which includes functions that reply to the OBD II port and the definitions of the ISOMeasurementsToISOReply functions establishes that at this level of class abstraction that the concept of handling will be to send a reply message to the OBD II port. The IISOReply member also provides functions toward this end. At this level, the implementation of the sensor data virtual functions is left abstract. - - -HondaHandler becomes the most derived, richest member of this family tree. It is a complete, fully functional handler. It adds concrete implementations of the remaining abstractions in the GenericHandler family hierarchy, the abstract sensor data retrieval interface and IncomingPID(). - -The HondaHandler implements IncomingPID by using the generic mapping of OBD II PIDS onto the abstract sensor data retrieval interface, ISOPID_TO_GENERIC_HANDLER_MAP. The HondaHandler implementation of the sensor data retrieval functions is asynchronous, and delegated, relying on the placement of its' functional colleague, HondaCommCoordinator, in the main event loop, to retrieve the data from the HondaPort. - -HondaCommCoordinator.AssignWork() is used to communicate with the HondaCommCoordinator, requesting that during the next main event loop cycle, the retrieval of a particular sensor value from the Honda on board computer (ECU). -AssignWork establishes a callback function pointer for the HondaCommCoordinator to call when the requested data has been retrieved. - -When the HondaCommCoordinator responds with the data, HondaHandler converts, maps or otherwise translates the data values from the Honda scaling or other representations, into values compatible with the OBD II measurement scale or representation. Then a member of the GenericHandler.ISOMeasurementsTOISOReply...XXXX group is called to generically convert the data into an OBD II format and then use an IISOReply family member to effect the reply to the OBD II port using the proper protocol. - - -HondaHandler implements the IGeneralAsyncHandler interface, marking it as an asynchronous class. - -HondaHandler defines GeneralAsyncRequest, a function that factors out the common code for setting up the function pointer. +Adds an interface of virtual function prototypes that describe the expected input and output for a sensor data retrieval implementation and a baseline map function ISOPIDTOGENERICHANDLERMAP that links OBD II PIDs to functions in the sensor interface GenericHandler builds directly upon its direct ancestor abstractions IGenericHandler and IHandler but becomes richer and more concrete by extending outside of that family to become a composition with an IISOReply family member + + +GenericHandler also defines functions that convert data to an OBD II format These functions follow the naming convention ISOMeasurementsToISOReplyXXXXX These functions accept input data in the scale dictated by the OBD II standard; ie temperature is measured in Celcius degress with the input data to the function represented by the formula Actual Temp 40 EG if the temperature of the coolant is determined to be 55 deg C you would call ISOMeasureToISOReplyScalarbyte 15 ; + +The inclusion of an IISOReply family member which includes functions that reply to the OBD II port and the definitions of the ISOMeasurementsToISOReply functions establishes that at this level of class abstraction that the concept of handling will be to send a reply message to the OBD II port The IISOReply member also provides functions toward this end At this level the implementation of the sensor data virtual functions is left abstract + + +HondaHandler becomes the most derived richest member of this family tree It is a complete fully functional handler It adds concrete implementations of the remaining abstractions in the GenericHandler family hierarchy the abstract sensor data retrieval interface and IncomingPID + +The HondaHandler implements IncomingPID by using the generic mapping of OBD II PIDS onto the abstract sensor data retrieval interface ISOPIDTOGENERICHANDLERMAP The HondaHandler implementation of the sensor data retrieval functions is asynchronous and delegated relying on the placement of its functional colleague HondaCommCoordinator in the main event loop to retrieve the data from the HondaPort + +HondaCommCoordinatorAssignWork is used to communicate with the HondaCommCoordinator requesting that during the next main event loop cycle the retrieval of a particular sensor value from the Honda on board computer ECU +AssignWork establishes a callback function pointer for the HondaCommCoordinator to call when the requested data has been retrieved + +When the HondaCommCoordinator responds with the data HondaHandler converts maps or otherwise translates the data values from the Honda scaling or other representations into values compatible with the OBD II measurement scale or representation Then a member of the GenericHandlerISOMeasurementsTOISOReplyXXXX group is called to generically convert the data into an OBD II format and then use an IISOReply family member to effect the reply to the OBD II port using the proper protocol + + +HondaHandler implements the IGeneralAsyncHandler interface marking it as an asynchronous class + +HondaHandler defines GeneralAsyncRequest a function that factors out the common code for setting up the function pointer IGenericAsyncHandler -IGenericAsyncHandler is a marker interface. Implementing it marks a class as asynchronous in nature. - - -ISOPort, HondaPort -ISOPort and HondaPort provide character based access to the serial ports, defined using a SoftwareSerial instance configured to communicate on the digital I/O pins connected to the OBD II connector and the Honda Diagnostic Link Connector. - -ISOPort and HondaPort provide safety features by providing a consistent interface to the serial ports, which can often become unmanageable within nested serial communications logic. - -All reads and writes are done through these interfaces, so the checksums are calculated through these routines, reducing the risk of multiple conflicting direct access. +IGenericAsyncHandler is a marker interface Implementing it marks a class as asynchronous in nature + + +ISOPort HondaPort +ISOPort and HondaPort provide character based access to the serial ports defined using a SoftwareSerial instance configured to communicate on the digital IO pins connected to the OBD II connector and the Honda Diagnostic Link Connector + +ISOPort and HondaPort provide safety features by providing a consistent interface to the serial ports which can often become unmanageable within nested serial communications logic + +All reads and writes are done through these interfaces so the checksums are calculated through these routines reducing the risk of multiple conflicting direct access HondaMap -HondaMap objects are used to refer to specific sensors in the Honda on-board computer (ECU). The definition includes an address and length. Some sensors return two bytes, for example, RPM. If the two-byte return data is a scalar value, the data is big-endian, that is, the most significant byte, the one that counts for 256 for each 1 of its' value, is the first of the two-bytes transmitted by the ECU. +HondaMap objects are used to refer to specific sensors in the Honda onboard computer ECU The definition includes an address and length Some sensors return two bytes for example RPM If the twobyte return data is a scalar value the data is bigendian that is the most significant byte the one that counts for 256 for each 1 of its value is the first of the twobytes transmitted by the ECU ISOPID -ISOPID objects are used to represent OBD II requests. Each request contains a mode and an identifier. Mode 1 is sensors. Mode 3 is Diagnostic Trouble Codes. E.G. Mode 1, identifier 0x0C is engine speed (RPM). +ISOPID objects are used to represent OBD II requests Each request contains a mode and an identifier Mode 1 is sensors Mode 3 is Diagnostic Trouble Codes EG Mode 1 identifier 0x0C is engine speed RPM @@ -279,162 +281,162 @@ PATTERNS -Object Oriented characteristics: +Object Oriented characteristics Polymorphism -GenericBusInitAttempt, ISO14230_BusInitAttempt, ISO9141_BusInitAttempt - -When the variable oBusInitAttempt takes the form of a ISO14230_BusInitAttempt, the BusCoordinator doesn't know or care about this. All the BusCoordinator needs to know is that a GenericBusInitAttempt is being utilized. Thus the principle of polymorphism, or many forms, is being leveraged to achieve more generalized code. From one perspective the form of the instance variable oBusInitAttempt is GenericBusInitAttempt and from another perspective the form is ISO14230_BusInitAttempt, thus polymorphic. - -IHandler, GenericHandler, HondaHandler -The IHandler abstract interface is used in the CommMessageProcessor. The form of the instance variable in CommMessageProcessor is an abstract IHandler at compile time. At run time, however the IHandler object takes the form of a concrete HondaHandler. From the perspective of the CommMessageProcessor the instance variable is an IHandler, but from a macro, system level view, the instance variable is a HondaHandler. Thus this variable takes many forms and is polymorphic. GenericHandler is another form of an IHandler, albeit a kind of abstract 'unexpressed' form, as instantiating it would result in an incomplete handler implementation. +GenericBusInitAttempt ISO14230BusInitAttempt ISO9141BusInitAttempt + +When the variable oBusInitAttempt takes the form of a ISO14230BusInitAttempt the BusCoordinator doesnt know or care about this All the BusCoordinator needs to know is that a GenericBusInitAttempt is being utilized Thus the principle of polymorphism or many forms is being leveraged to achieve more generalized code From one perspective the form of the instance variable oBusInitAttempt is GenericBusInitAttempt and from another perspective the form is ISO14230BusInitAttempt thus polymorphic + +IHandler GenericHandler HondaHandler +The IHandler abstract interface is used in the CommMessageProcessor The form of the instance variable in CommMessageProcessor is an abstract IHandler at compile time At run time however the IHandler object takes the form of a concrete HondaHandler From the perspective of the CommMessageProcessor the instance variable is an IHandler but from a macro system level view the instance variable is a HondaHandler Thus this variable takes many forms and is polymorphic GenericHandler is another form of an IHandler albeit a kind of abstract unexpressed form as instantiating it would result in an incomplete handler implementation Loose Coupling -Even though they work closely together to accomplish the overall goal in this adapter implementation, -there is a loose-coupling between the CommMessageProcessor, receiving a PID from the OBDII port and the HondaHandler, effecting a reply to the OBD II port. This coupling is loose because the Handler could be implemented in different ways and this loose coupling leaves the door open for more diverse interpretations of the term 'handling'. - -In this adapter implementation the loose coupling make it easier to inject an asynchronous handler into the design. The CommMessageProcessor is coupled only to an IHandler, an interface definition ( aka, contract specification ), not tied directly to the asynchronous implementation of HondaHandler, reducing the chance of cascading changes rippling through multiple functional units. - -One of the advantages of the loose coupling in this adapter implementation is its' ability to mitigate the situation where one subsystem is blocked by another. It would be undesirable to make the CommMessageProcessor block(wait) for the Honda data to be retrieved. The data may never come but we still want the CommMessageProcessor to be able to degrade gracefully and respond to its' immediate supervisor. The loose coupling supports this because the HondaHandler doesn't take control when it is tasked with getting Honda sensor data. It is delegated to do so and this is a pattern of Chain of Responsibility, but the CommMessageProcessor maintains control and can exit cleanly. This clean exit facilitates the placement of supervisory control logic where it belongs; at a high logical level in the code, not buried deep in the implementation details of a particular low level unit. - -Loose coupling has its benefits and downfalls. Loose coupling allows flexibility in implementing the Handler without changing the CommMessageProcessor, and ultimately aids in the implementation of an asynchronous handler, but this does not come without issues. For example, there is no way to easily enforce transactional integrity across this coupling, or pass error or control messages such as 'retry' across this coupling because by the time a failure is detected on one side of the coupling, the execution context that initiated the request has exited. A similar problem occurs with non-asynchronous loose coupling, where, for example, it is impossible to pass an error message because the loose coupling only supports a limited interface. +Even though they work closely together to accomplish the overall goal in this adapter implementation +there is a loosecoupling between the CommMessageProcessor receiving a PID from the OBDII port and the HondaHandler effecting a reply to the OBD II port This coupling is loose because the Handler could be implemented in different ways and this loose coupling leaves the door open for more diverse interpretations of the term handling + +In this adapter implementation the loose coupling make it easier to inject an asynchronous handler into the design The CommMessageProcessor is coupled only to an IHandler an interface definition aka contract specification not tied directly to the asynchronous implementation of HondaHandler reducing the chance of cascading changes rippling through multiple functional units + +One of the advantages of the loose coupling in this adapter implementation is its ability to mitigate the situation where one subsystem is blocked by another It would be undesirable to make the CommMessageProcessor blockwait for the Honda data to be retrieved The data may never come but we still want the CommMessageProcessor to be able to degrade gracefully and respond to its immediate supervisor The loose coupling supports this because the HondaHandler doesnt take control when it is tasked with getting Honda sensor data It is delegated to do so and this is a pattern of Chain of Responsibility but the CommMessageProcessor maintains control and can exit cleanly This clean exit facilitates the placement of supervisory control logic where it belongs; at a high logical level in the code not buried deep in the implementation details of a particular low level unit + +Loose coupling has its benefits and downfalls Loose coupling allows flexibility in implementing the Handler without changing the CommMessageProcessor and ultimately aids in the implementation of an asynchronous handler but this does not come without issues For example there is no way to easily enforce transactional integrity across this coupling or pass error or control messages such as retry across this coupling because by the time a failure is detected on one side of the coupling the execution context that initiated the request has exited A similar problem occurs with nonasynchronous loose coupling where for example it is impossible to pass an error message because the loose coupling only supports a limited interface Separation of Concerns -See _Patterns and Principles_ "Loose Coupling", "Information Hiding and Encapsulation", and "Chain of Responsibility" +See Patterns and Principles Loose Coupling Information Hiding and Encapsulation and Chain of Responsibility Generalization --- Reuse, Inheritance and Templates ---- Benefits -The sharing of common functionality reduces the overall code load that must be inspected. It also increase the chances that changes made to the system will propagate in the proper way. ---- Ramifications -The factoring out of common functionality must be done thoughtfully and carefully, as the benefits of reuse are quickly outweighed by the complexity of managing entanglement between sharing classes. - -See Also, Generalization, composition, flexibility of modularity -see Also, Generalization, composition, ramifications -See Also, Generalization, overgeneralization -See Also, Template for examples; Generally whereever there is a Template there is reuse. - - -Generalization, composition --- Reuse, factoring, flexibility of modularity ---- Benefits -Factoring out distinct conceptual groups of functionality like sensor data virtual function interface, ISOMeasurementsTOISOReply grouping, IISOReply and GenericISOReply provides the flexibility of modularity. Individual pieces can be swapped in and out, e.g. substituting a newer Controller Area Network diagnostic subsystem implementation for the OBD II system, as long as the new piece adheres to the established convention, defined by interfaces. - -Flexibilty means less risk. Generalizing may take more front-end design time, but reduces the amplitude of wild-schedule swings on the back end. ---- Ramifications -Compositional reuse can lead a design down a dead end. If a class inherits everything from a composed class and implements a new subsystem, without a solid set of abstract interfaces ( or contracts ) to define exactly where in the tree the new functionality branches off from ( or differs from the previous incarnation ), it is likely that new functionality will simply rewrite existing functionality. - -So there is a place on the spectrum between strict inheritance hierarchy-to-god class compositional multipurposing that must be chosen carefully. Too tight interface adherence limits the diversity that future implementations can create. Too little interface adherance and excessive use of ad-hoc compositional reuse encourages rewrites and big-ball-of-mud designs. + Reuse Inheritance and Templates + Benefits +The sharing of common functionality reduces the overall code load that must be inspected It also increase the chances that changes made to the system will propagate in the proper way + Ramifications +The factoring out of common functionality must be done thoughtfully and carefully as the benefits of reuse are quickly outweighed by the complexity of managing entanglement between sharing classes + +See Also Generalization composition flexibility of modularity +see Also Generalization composition ramifications +See Also Generalization overgeneralization +See Also Template for examples; Generally whereever there is a Template there is reuse + + +Generalization composition + Reuse factoring flexibility of modularity + Benefits +Factoring out distinct conceptual groups of functionality like sensor data virtual function interface ISOMeasurementsTOISOReply grouping IISOReply and GenericISOReply provides the flexibility of modularity Individual pieces can be swapped in and out eg substituting a newer Controller Area Network diagnostic subsystem implementation for the OBD II system as long as the new piece adheres to the established convention defined by interfaces + +Flexibilty means less risk Generalizing may take more frontend design time but reduces the amplitude of wildschedule swings on the back end + Ramifications +Compositional reuse can lead a design down a dead end If a class inherits everything from a composed class and implements a new subsystem without a solid set of abstract interfaces or contracts to define exactly where in the tree the new functionality branches off from or differs from the previous incarnation it is likely that new functionality will simply rewrite existing functionality + +So there is a place on the spectrum between strict inheritance hierarchytogod class compositional multipurposing that must be chosen carefully Too tight interface adherence limits the diversity that future implementations can create Too little interface adherance and excessive use of adhoc compositional reuse encourages rewrites and bigballofmud designs Overgeneralization -The attempt to use generic structures is a noble goal, but there is a limit to how far to take it. The architect of class families must focus on the real purpose of the design effort. Is it to solve a particular problem, with a flexible building block pattern, that reduces the risk that changing requirements will render the code unusable? -Or is the design effort moving dangerously toward overgeneralization. For example, a good home builder might carry a variety of tools, saws, hammer, etc, some of which may even be used to build other tools. e.g. scaffolding for painting. But the home builder doesn't carry a smelting forge in the truck. He doesn't need that much generality and to attempt such would actually be counterproductive - for building a house - so the principle is to keep some perspective about the goal you are trying to achieve. - -Too much factoring and generalizing can cause unnecessary complexity. As the class family becomes more fragmented and modular it becomes harder for the consumer to understand how to use it. - -So the place on the spectrum of generalism-to-specialization is important. There is always a design trade-off. As Spolsky says, the trash can must be open on top so people can put trash in. But it needs to be closed on top so trash doesn't blow away. - - -Generalization, practical implications and best practices - -The structure of the IHandler family, beginning with the IHandler interface and ending with the HondaHandler. -is constructed with inheritance and composition. - -The HondaHandler inherits functionality from the trunk, GenericHandler. But GenericHandler is actually formed of inheritance from IGenericHandler and IHandler, but also of composition with another family tree, IISOReply. So the trunk HondaHandler inherits is already a compositional mixture and not a strict inheritance hierarchy of 'is a' relationships. The mixing of the ISOMeasurementsTOISOReply functions and an IISOReply family member into the IHandler family hierarchy effectively constrains handlers derived from GenericHandler to being OBD II-based handlers. - -HondaHandler is also formed with a mix of inheritance and composition; inheriting from GenericHandler but also formed by being composed with IGenericAsyncHandler. - -In principle, if the classes form a definite tight hierarchy and really could not be split into separate pieces that are independently functional, use inheritance. Another rule of thumb is if the relationship is a direct building *upon* , use inheritance. If the relationship is a kind of association with, or equal level partnership, use composition. If the classes could be split, use a composition approach to achieve the right mix of 'lateral' building blocks. - -The GenericHandler is made concrete on the OBD II side and left abstract on the Honda side because this is the most likely usage pattern. The next logical step for the IHandler family tree would be to branch off at the GenericHandler level to create a concrete implementation of another proprietary standard that needed to adapt to the now ubiquitious OBD II standard. This is a likely re-use pattern, but not the only one afforded by the generalization topology described here. It is hard to conceptualize exactly what could be constructed with the existing modules and interfaces ( or contracts ) but that is the beauty of infrastructure in the designer's opinion. - - -Generalization principles serve as design heuristics when building re-usable infrastructure ( or tooling ) to build Mediators like GenericHandler where one or more sides may be unknown at the time of construction of the tooling. +The attempt to use generic structures is a noble goal but there is a limit to how far to take it The architect of class families must focus on the real purpose of the design effort Is it to solve a particular problem with a flexible building block pattern that reduces the risk that changing requirements will render the code unusable? +Or is the design effort moving dangerously toward overgeneralization For example a good home builder might carry a variety of tools saws hammer etc some of which may even be used to build other tools eg scaffolding for painting But the home builder doesnt carry a smelting forge in the truck He doesnt need that much generality and to attempt such would actually be counterproductive for building a house so the principle is to keep some perspective about the goal you are trying to achieve + +Too much factoring and generalizing can cause unnecessary complexity As the class family becomes more fragmented and modular it becomes harder for the consumer to understand how to use it + +So the place on the spectrum of generalismtospecialization is important There is always a design tradeoff As Spolsky says the trash can must be open on top so people can put trash in But it needs to be closed on top so trash doesnt blow away + + +Generalization practical implications and best practices + +The structure of the IHandler family beginning with the IHandler interface and ending with the HondaHandler +is constructed with inheritance and composition + +The HondaHandler inherits functionality from the trunk GenericHandler But GenericHandler is actually formed of inheritance from IGenericHandler and IHandler but also of composition with another family tree IISOReply So the trunk HondaHandler inherits is already a compositional mixture and not a strict inheritance hierarchy of is a relationships The mixing of the ISOMeasurementsTOISOReply functions and an IISOReply family member into the IHandler family hierarchy effectively constrains handlers derived from GenericHandler to being OBD IIbased handlers + +HondaHandler is also formed with a mix of inheritance and composition; inheriting from GenericHandler but also formed by being composed with IGenericAsyncHandler + +In principle if the classes form a definite tight hierarchy and really could not be split into separate pieces that are independently functional use inheritance Another rule of thumb is if the relationship is a direct building *upon* use inheritance If the relationship is a kind of association with or equal level partnership use composition If the classes could be split use a composition approach to achieve the right mix of lateral building blocks + +The GenericHandler is made concrete on the OBD II side and left abstract on the Honda side because this is the most likely usage pattern The next logical step for the IHandler family tree would be to branch off at the GenericHandler level to create a concrete implementation of another proprietary standard that needed to adapt to the now ubiquitious OBD II standard This is a likely reuse pattern but not the only one afforded by the generalization topology described here It is hard to conceptualize exactly what could be constructed with the existing modules and interfaces or contracts but that is the beauty of infrastructure in the designers opinion + + +Generalization principles serve as design heuristics when building reusable infrastructure or tooling to build Mediators like GenericHandler where one or more sides may be unknown at the time of construction of the tooling Mixins -The IHandler family may benefit from a more formal analysis and re-design using mixins, which are a combination of methods from separate classes. +The IHandler family may benefit from a more formal analysis and redesign using mixins which are a combination of methods from separate classes Traits -The IHandler family may benefit from a more formal analysis and re-design using traits, a set of methods that implement a behaviour and a set of methods that parameterize that behaviour. - - -See Also, _Class References_ "GenericHandler", "HondaHandler" - -Template: - -IHandler provides a template for any class that may be used as a handler, by CommMessageProcessor. -HondaHandler is the most derived class from this template. - -IISOReply provides a template for any class that replies to the ISOPort. ISOReply_9141 and ISOReply14320 build on this template. - -GenericBusInitAttempt provides a template for classes that attempt OBD II protocol bus initialization. Since there are three similar but nontheless unique possible methods of initialization (ISO9141, ISO14230_slow, and ISO14230_fast) the shared code between these three is factored into the template and only the unique characteristics remain in the most derived classes (BusInitAttempt_ISO9141, BusInitAttempt_ISO14230_slow, BusInitAttempt_ISO14230_fast). +The IHandler family may benefit from a more formal analysis and redesign using traits a set of methods that implement a behaviour and a set of methods that parameterize that behaviour + + +See Also Class References GenericHandler HondaHandler + +Template + +IHandler provides a template for any class that may be used as a handler by CommMessageProcessor +HondaHandler is the most derived class from this template + +IISOReply provides a template for any class that replies to the ISOPort ISOReply9141 and ISOReply14320 build on this template + +GenericBusInitAttempt provides a template for classes that attempt OBD II protocol bus initialization Since there are three similar but nontheless unique possible methods of initialization ISO9141 ISO14230slow and ISO14230fast the shared code between these three is factored into the template and only the unique characteristics remain in the most derived classes BusInitAttemptISO9141 BusInitAttemptISO14230slow BusInitAttemptISO14230fast Information Hiding and Encapsulation -ISOPort and HondaPort encapsulate the checksum running total variable, improving code safety. +ISOPort and HondaPort encapsulate the checksum running total variable improving code safety -Each coordinator (BusCoordinator, CommCoordinator, HondaCommCoordinator) or controller (TryReady, BusInitAttempt, CommMessageCollector, etc) hides its internal state, providing a standard interface. This improves safety and reduces the need to understand the internal details to make changes to the logic using these functional units. - -HondaMap and ISOPID classes hide the low-level details of these data structures, providing a safer ( e.g. a Honda address can never be inadvertently associated with wrong length because they are stored together ), more convenient way of manipulating these logical units. +Each coordinator BusCoordinator CommCoordinator HondaCommCoordinator or controller TryReady BusInitAttempt CommMessageCollector etc hides its internal state providing a standard interface This improves safety and reduces the need to understand the internal details to make changes to the logic using these functional units + +HondaMap and ISOPID classes hide the lowlevel details of these data structures providing a safer eg a Honda address can never be inadvertently associated with wrong length because they are stored together more convenient way of manipulating these logical units Command Pattern -GenericHandler contains a function ISOPID_TO_GENERIC_HANDLER_MAP(), that is built in a command pattern that lends itself to further ad-hoc modification by adding executable code within the respective command hooks. -Each ISOPID is treated as a command object, directing execution into the appropriate sensor data retrieval function. This pattern is extensible, for example, easily allowing for two or more separate retrieval steps or other ad-hoc functionality in the commanded subroutine. - - -Chain of Responsibility: -The functional colleagues CommMessageProcessor and HondaHandler exhibit characteristics of a Chain of Responsibility pattern. The CommMessageProcessor does not directly handle the gathering of the data that is required for the successful conversions of the PID it receives into Honda data. Rather, it relies on an indirect Chain of Responsibility. When a PID is received by CommMessageProcessor, a delegating call to IncomingPID is made. This shifts responsibility of actually completing this task onto another subsystem. - - -HondaHandler, AssignWork, GeneralAsyncRequest -The HondaHandler sends a message to HondaCommCoordinator using AssignWork to retrieve the appropriate data from the HondaPort. The AssignWork function shifts the responsibility to the HondaCommCoordinator to retrieve the data. The HondaCommCoordinator is given the responsibility for retrieving the data, and is also given the tools, in the form of a Callback function pointer, to *ASYNCHRONOUSLY* satisfy it's obligation of returning the data. - -The BusCoordinator, BusInit and GenericBusInitAttempt (or GenericBusInitComplete) form a Chain of Responsibility pattern. The BusCoordinator is responsible for the overall bus initialization sequences, but it delegates responsibilty for this task to two associated classes, TryReady and BusInit. BusInit then transfers responsibility to its' delegates GenericBusInitAttempt and GenericBusInitComplete. Thus the responsibility for certain actions is transferred in a chain. - -The main event loop and select parts of the class design could be considered an example of Responsibility Driven Design, using a Clustered/Delegated control Structure. - - - -State: - -Many examples: -The main event loop stores state about the overall OBD II connection state with two macro level states, NO_COMM and COMM_ESTAB. -BusCoordinator stores state about the state of bus handshaking. -BusInitAttempt stores state about the state of the bus initialization attempt. -Each of these units is called repeatedly to accomplish a single logical task and they keep track of where they are by a State pattern; they are guided and alter their behaviour based on their transient state. - -DoneWorking() and Reset() provide consistent, safe, encapsulated access to the state. - -The main event loop and all the subsidiary loops contained within could all be considered an example of one complex Automaton. These structures could also be described as finite state machines. - -Strategy: - -The implementation of IHandler.IncomingPID() by HondaHandler could be considered one Strategy for dealing with the incoming OBD II request. This larger unit of work seems to qualify as a strategy and diverges from the Template definition of mere alteration of subtle details by a class deriving from a Template. -Compare Template. - - - - - -Mediator: - -GenericHandler is a mediator because it is the only class that knows the internal details of two systems: the OBD II system and the Honda system. - -From the perspective of the CommMessageProcessor, the IHandler base interface presents a simplified interface to the Honda side that consists of only one function call, IncomingPID. - -From the perspective of the Honda side GenericHandler presents a simplified interface to the OBD II side that consists of a group of ISOMeasurementsToISOReply...XXXX reply functions. The input and operation of these functions is well defined and simple. - -Thus the GenericHandler serves as a mediator, providing a simplified interface to a complex task of obtaining Honda sensor data as well a providing a simplified interface to a complex task of sending data to the OBD II port using the proper protocol, mediating these two sides of the system. - -Adapter: -At a macro level, the entire hardware / software system is an Adapter, converting and translating the requests and data from one system into a format compatible with another system. +GenericHandler contains a function ISOPIDTOGENERICHANDLERMAP that is built in a command pattern that lends itself to further adhoc modification by adding executable code within the respective command hooks +Each ISOPID is treated as a command object directing execution into the appropriate sensor data retrieval function This pattern is extensible for example easily allowing for two or more separate retrieval steps or other adhoc functionality in the commanded subroutine + + +Chain of Responsibility +The functional colleagues CommMessageProcessor and HondaHandler exhibit characteristics of a Chain of Responsibility pattern The CommMessageProcessor does not directly handle the gathering of the data that is required for the successful conversions of the PID it receives into Honda data Rather it relies on an indirect Chain of Responsibility When a PID is received by CommMessageProcessor a delegating call to IncomingPID is made This shifts responsibility of actually completing this task onto another subsystem + + +HondaHandler AssignWork GeneralAsyncRequest +The HondaHandler sends a message to HondaCommCoordinator using AssignWork to retrieve the appropriate data from the HondaPort The AssignWork function shifts the responsibility to the HondaCommCoordinator to retrieve the data The HondaCommCoordinator is given the responsibility for retrieving the data and is also given the tools in the form of a Callback function pointer to *ASYNCHRONOUSLY* satisfy its obligation of returning the data + +The BusCoordinator BusInit and GenericBusInitAttempt or GenericBusInitComplete form a Chain of Responsibility pattern The BusCoordinator is responsible for the overall bus initialization sequences but it delegates responsibilty for this task to two associated classes TryReady and BusInit BusInit then transfers responsibility to its delegates GenericBusInitAttempt and GenericBusInitComplete Thus the responsibility for certain actions is transferred in a chain + +The main event loop and select parts of the class design could be considered an example of Responsibility Driven Design using a ClusteredDelegated control Structure + + + +State + +Many examples +The main event loop stores state about the overall OBD II connection state with two macro level states NOCOMM and COMMESTAB +BusCoordinator stores state about the state of bus handshaking +BusInitAttempt stores state about the state of the bus initialization attempt +Each of these units is called repeatedly to accomplish a single logical task and they keep track of where they are by a State pattern; they are guided and alter their behaviour based on their transient state + +DoneWorking and Reset provide consistent safe encapsulated access to the state + +The main event loop and all the subsidiary loops contained within could all be considered an example of one complex Automaton These structures could also be described as finite state machines + +Strategy + +The implementation of IHandlerIncomingPID by HondaHandler could be considered one Strategy for dealing with the incoming OBD II request This larger unit of work seems to qualify as a strategy and diverges from the Template definition of mere alteration of subtle details by a class deriving from a Template +Compare Template + + + + + +Mediator + +GenericHandler is a mediator because it is the only class that knows the internal details of two systems the OBD II system and the Honda system + +From the perspective of the CommMessageProcessor the IHandler base interface presents a simplified interface to the Honda side that consists of only one function call IncomingPID + +From the perspective of the Honda side GenericHandler presents a simplified interface to the OBD II side that consists of a group of ISOMeasurementsToISOReplyXXXX reply functions The input and operation of these functions is well defined and simple + +Thus the GenericHandler serves as a mediator providing a simplified interface to a complex task of obtaining Honda sensor data as well a providing a simplified interface to a complex task of sending data to the OBD II port using the proper protocol mediating these two sides of the system + +Adapter +At a macro level the entire hardware software system is an Adapter converting and translating the requests and data from one system into a format compatible with another system @@ -443,36 +445,55 @@ Software Serial -The SoftwareSerial library was chosen for two reasons. The Arduino only has one hardware serial port, and the best use for this port is as a debugging aid to see the trace messages from the monitor. - -The other reason is that there is a need to operate the serial port at a non-standard Honda baud rate. The serial timing in SoftwareSerial.h was adjusted, though minimally, for 9470 baud. The original timing for 9600 baud worked before these adjustments were made. This baud rate is relatively low and the difference between the Honda rate and the standard rate is small, so it is possible these timing adjustments are superfluous. - -Due to the nature of the SoftwareSerial interrupt driven design, only one serial port can be active at any time. Therefore, at precise junctions in the control structure, each port is activated with a .listen() statement. - -Half Duplex. This section is unconfirmed and based on the best knowledge of the designer. - -SoftwareSerialWithHalfDuplex is used because the communication line on the Honda Diagnostic Link Connector is half duplex, that is, only one member, the client (HonOBDapt) or the server (on board computer, ECU) can transmit data at one time. SoftwareSerialWithHalfDuplex supports this configuration by specifying the same pin for Transmit and Receive. It is the responibillty of the HondaCommCoordinator to enforce this constraint, as the behaviour of SoftwareSerialWithHalfDuplex if an attempt is made to transmit and receive at the same time is unknown. - -The OBD II ISOPort is also half duplex, but is connected to the MC33660 which has a full duplex style of connection with both Receive and Transmit pin connections. This provides a physical, electrical way of enforcing half duplex on the OBD II K-Line, as a communications participant attempting to bring the line low or high while the other participant is still transmitting will simply be ignored by the circuitry in the MC33660. +The SoftwareSerial library was chosen for two reasons The Arduino only has one hardware serial port and the best use for this port is as a debugging aid to see the trace messages from the monitor + +The other reason is that there is a need to operate the serial port at a nonstandard Honda baud rate The serial timing in SoftwareSerialh was adjusted though minimally for 9470 baud The original timing for 9600 baud worked before these adjustments were made This baud rate is relatively low and the difference between the Honda rate and the standard rate is small so it is possible these timing adjustments are superfluous + +Due to the nature of the SoftwareSerial interrupt driven design only one serial port can be active at any time Therefore at precise junctions in the control structure each port is activated with a listen statement + +Half Duplex This section is unconfirmed and based on the best knowledge of the designer + +SoftwareSerialWithHalfDuplex is used because the communication line on the Honda Diagnostic Link Connector is half duplex that is only one member the client HonOBDapt or the server on board computer ECU can transmit data at one time SoftwareSerialWithHalfDuplex supports this configuration by specifying the same pin for Transmit and Receive It is the responibillty of the HondaCommCoordinator to enforce this constraint as the behaviour of SoftwareSerialWithHalfDuplex if an attempt is made to transmit and receive at the same time is unknown + +The OBD II ISOPort is also half duplex but is connected to the MC33660 which has a full duplex style of connection with both Receive and Transmit pin connections This provides a physical electrical way of enforcing half duplex on the OBD II KLine as a communications participant attempting to bring the line low or high while the other participant is still transmitting will simply be ignored by the circuitry in the MC33660 MC33660 -MC33660 is a level conversion integrated circuit that converts 5 volt logic signals to 12 volt logic signals. This is necessary because the main hardware component, the Arduino, uses 5 volt signals on its' digital I/O pins and OBD II specifies 12 volt signals. MC33660 is an integrated circuit specifically designed for logic level conversion in an OBD II automotive application and should therefore be particularly suited to this application in terms of susceptibility to noise, overload protection, etc. MC33660 is designed to be connected to the K-Line bus and therefore provides an appropriate electrical interface for serial communications and bus-style level transitions. +MC33660 is a level conversion integrated circuit that converts 5 volt logic signals to 12 volt logic signals This is necessary because the main hardware component the Arduino uses 5 volt signals on its digital IO pins and OBD II specifies 12 volt signals MC33660 is an integrated circuit specifically designed for logic level conversion in an OBD II automotive application and should therefore be particularly suited to this application in terms of susceptibility to noise overload protection etc MC33660 is designed to be connected to the KLine bus and therefore provides an appropriate electrical interface for serial communications and busstyle level transitions Arduino -Arduino provides 5 volt logic level digital I/O pins that are suited to this application. The application of a software library that allows serial communications on any pin provides significant flexibility. Arduino has flexible power supply requirements and can be operated on a 12 volt system. Nominal current draw through the onboard voltage regulator in this application is 200mA. Heat created by the voltage regulator dropping 12 volts to 5 volts to power the on board processor is dissipated by a small on-board heatsink, so the current limits and supply voltage combination must be carefully selected. The current configuration is within limits to the best knowledge of the designer and has been anecdotally confirmed by feeling for excess heat from the voltage regulator. +Arduino provides 5 volt logic level digital IO pins that are suited to this application The application of a software library that allows serial communications on any pin provides significant flexibility Arduino has flexible power supply requirements and can be operated on a 12 volt system Nominal current draw through the onboard voltage regulator in this application is 200mA Heat created by the voltage regulator dropping 12 volts to 5 volts to power the on board processor is dissipated by a small onboard heatsink so the current limits and supply voltage combination must be carefully selected The current configuration is within limits to the best knowledge of the designer and has been anecdotally confirmed by feeling for excess heat from the voltage regulator OBD II -The OBD II electrical and logical communications standard is actually a conglomeration of many existing standards at the time of creation of the OBD II 'standard' by ISO. This adapter supports the K-Line standard(s) of ISO-9141, ISO-14230_slow, and ISO-14230_fast. Only one is technically required as any OBD II compliant scanner must be able to work with all three, but the implementations vary only minimally and provide a good exercise and example of certain software design techniques. - - +The OBD II electrical and logical communications standard is actually a conglomeration of many existing standards at the time of creation of the OBD II standard by ISO This adapter supports the KLine standards of ISO9141 ISO14230slow and ISO14230fast Only one is technically required as any OBD II compliant scanner must be able to work with all three but the implementations vary only minimally and provide a good exercise and example of certain software design techniques + + +TODO + +Asynchronous Multitasking + +There should be an ITask interface to constrain and define the exact nature of the controllers that have the Work DoneWorking and Reset functions + +Handler class family construction + +The sensor data virtual function prototypes in GenericHandler should be split into a separate interface definition then implemented virtually by GenericHandler and concretely by more derived classes like HondaHandler + +The ISOMeasurementToISOReplyXXXX family of functions should be extracted out of GenericHandler and put in a separate mixin + +The IGeneralAsyncHander should be expanded and more clearly defined to include the GeneralAsyncRequest function defined in an adhoc manner in HondaHandler + +Other + +The HondaCommCoordinator should implement an IWorkQueue interface clarifying the role of the Assignwork function + +The magic numbers of the digital IO pins used for serial communications in SoftwareSerial should be extracted out into a define &lt;/pre&gt;</pre>Andrew smithFri, 21 Jun 2013 14:18:28 -0000https://sourceforge.net6e6b51d639991ea5d274fccbcbc67cba2c3bac86https://sourceforge.net/p/honobdapt/wiki/add/<div class="markdown_content"><pre>--- v45 +++ v46 @@ -1,6 +1,5 @@ - -HonOBDapt 1.0 +###HonOBDapt 1.0 a. Intro, Summary </pre> </div>Andrew smithFri, 21 Jun 2013 14:17:44 -0000https://sourceforge.net6a5e1d2a7d4ecf4e05d4a12efa0ff5286d29b9dahttps://sourceforge.net/p/honobdapt/wiki/add/<div class="markdown_content"><pre>--- v44 +++ v45 @@ -1,8 +1,10 @@ -###HonOBDapt 1.0 - - -####a. Intro, Summary -####b. Prototype + + +HonOBDapt 1.0 + + +a. Intro, Summary +b. Prototype HonOBDapt translates requests for on-board automotive computer sensor data from an ISO standard OBD II format to a Honda proprietary format used in 92-95 Honda Civics. @@ -16,9 +18,9 @@ A prototype was constructed with the following: several trips to the junkyard to buy a Honda on board computer (ECU) and OBD II standard connectors, lots of hot glue and some mild eyestrain from trying to solder the MC33660, which is manufactured only in a package intended for automated assembly. The prototype was tested with an ELM compatible Bluetooth OBD II scanner. The prototype was tested with the OBD II PC software packages Scantool and OBDAutoDoctor. -###Sections I, II, III: C++ Software Specification -###Sections IV, V, VI, VII: Electrical and Hardware specification -###Section VIII: TODO +Sections I, II, III: C++ Software Specification +Sections IV, V, VI, VII: Electrical and Hardware specification +Section VIII: TODO I. Control Flow a. Asynchronous Processing Unit Design @@ -72,9 +74,9 @@ -####CONTROL FLOW - -#####Asynchronous processing unit design +CONTROL FLOW + +Asynchronous processing unit design Generally, classes involved in handshaking and serial communications support Work(), DoneWorking() and Reset(). These functions serve as a basic cooperative multitasking system. Work() is called when a higher level controller has a time slice to give to the unit. The Work() function of each controller is expected to do its' work, and exit quickly. If the conditions are met that allow the handshaking or communications to proceed to the next higher level, DoneWorking() should return true. Reset() is used to reset the internal state of the unit, typically at the end of a logical session controlled by a higher level controller. @@ -82,7 +84,7 @@ Generally, the units are one-shot triggers. If, for example, a unit is falsely triggered to initiate a particular process ( by noise or an invalid packet ), it will continue to attempt completion of the process and cannot properly proceed with a valid sequence until it is Reset() by a higher level controller. -#####Main Event Loop +Main Event Loop The main event loop cycles through the upper lever coordinators, BusCoordinator, CommCoordinator and HondaCommCoordinator in a round robin fashion, calling .Work() and checking .DoneWorking() on each one. @@ -476,5 +478,6 @@ + </pre> </div>Andrew smithFri, 21 Jun 2013 14:17:29 -0000https://sourceforge.net600f9eca71613ff127afa506e31e6a1eed68de06https://sourceforge.net/p/honobdapt/wiki/add/<div class="markdown_content"><pre>--- v43 +++ v44 @@ -1,4 +1,3 @@ - ###HonOBDapt 1.0 @@ -473,26 +472,6 @@ The OBD II electrical and logical communications standard is actually a conglomeration of many existing standards at the time of creation of the OBD II 'standard' by ISO. This adapter supports the K-Line standard(s) of ISO-9141, ISO-14230_slow, and ISO-14230_fast. Only one is technically required as any OBD II compliant scanner must be able to work with all three, but the implementations vary only minimally and provide a good exercise and example of certain software design techniques. -TODO - -----Asynchronous Multitasking: - -There should be an ITask interface to constrain and define the exact nature of the controller(s) that have the Work(), DoneWorking(), and Reset() functions. - ------Handler class family construction: - -The sensor data virtual function prototypes in GenericHandler should be split into a separate interface definition, then implemented virtually by GenericHandler and concretely by more derived classes like HondaHandler. - -The ISOMeasurementToISOReply...XXXX family of functions should be extracted out of GenericHandler and put in a separate mix-in. - -The IGeneralAsyncHander should be expanded and more clearly defined to include the GeneralAsyncRequest function defined in an ad-hoc manner in HondaHandler. - -----Other - -The HondaCommCoordinator should implement an IWorkQueue interface, clarifying the role of the Assignwork function. - -The magic number(s) of the digital I/O pins used for serial communications in SoftwareSerial should be extracted out into a define. - </pre> </div>Andrew smithFri, 21 Jun 2013 14:16:32 -0000https://sourceforge.net5ffff3c072e54506339ec73c463ae268b960862dhttps://sourceforge.net/p/honobdapt/wiki/add/<div class="markdown_content"><pre>--- v42 +++ v43 @@ -1,10 +1,9 @@ - -HonOBDapt 1.0 - - -a. Intro, Summary -b. Prototype +###HonOBDapt 1.0 + + +####a. Intro, Summary +####b. Prototype HonOBDapt translates requests for on-board automotive computer sensor data from an ISO standard OBD II format to a Honda proprietary format used in 92-95 Honda Civics. @@ -18,9 +17,9 @@ A prototype was constructed with the following: several trips to the junkyard to buy a Honda on board computer (ECU) and OBD II standard connectors, lots of hot glue and some mild eyestrain from trying to solder the MC33660, which is manufactured only in a package intended for automated assembly. The prototype was tested with an ELM compatible Bluetooth OBD II scanner. The prototype was tested with the OBD II PC software packages Scantool and OBDAutoDoctor. -Sections I, II, III: C++ Software Specification -Sections IV, V, VI, VII: Electrical and Hardware specification -Section VIII: TODO +###Sections I, II, III: C++ Software Specification +###Sections IV, V, VI, VII: Electrical and Hardware specification +###Section VIII: TODO I. Control Flow a. Asynchronous Processing Unit Design @@ -74,9 +73,9 @@ -CONTROL FLOW - -Asynchronous processing unit design +####CONTROL FLOW + +#####Asynchronous processing unit design Generally, classes involved in handshaking and serial communications support Work(), DoneWorking() and Reset(). These functions serve as a basic cooperative multitasking system. Work() is called when a higher level controller has a time slice to give to the unit. The Work() function of each controller is expected to do its' work, and exit quickly. If the conditions are met that allow the handshaking or communications to proceed to the next higher level, DoneWorking() should return true. Reset() is used to reset the internal state of the unit, typically at the end of a logical session controlled by a higher level controller. @@ -84,7 +83,7 @@ Generally, the units are one-shot triggers. If, for example, a unit is falsely triggered to initiate a particular process ( by noise or an invalid packet ), it will continue to attempt completion of the process and cannot properly proceed with a valid sequence until it is Reset() by a higher level controller. -Main Event Loop +#####Main Event Loop The main event loop cycles through the upper lever coordinators, BusCoordinator, CommCoordinator and HondaCommCoordinator in a round robin fashion, calling .Work() and checking .DoneWorking() on each one. </pre> </div>Andrew smithFri, 21 Jun 2013 14:15:41 -0000https://sourceforge.net37ab5497873a4c641bbdfee0db2dd02d7062f81fhttps://sourceforge.net/p/honobdapt/wiki/add/<pre>&lt;pre&gt;--- v41 +++ v42 @@ -1,203 +1,277 @@ -####HonOBDapt 10 + + +HonOBDapt 1.0 + + +a. Intro, Summary +b. Prototype + +HonOBDapt translates requests for on-board automotive computer sensor data from an ISO standard OBD II format to a Honda proprietary format used in 92-95 Honda Civics. + +HonOBDapt uses a general purpose microcontroller module equipped with external digital I/O ports, the Arduino Uno Rev. 3. HonOBDapt uses a Freescale MC33660 ISOLink logic level converter integrated circuit to electrically connect the OBD II signal line to the Arduino. HonOBDapt software is written in C++ and uses the SoftwareSerialWithHalfDuplex library. + +HonOBDapt supports core interactive diagnostic functionality of the OBD II standard, comprised of essential sensor data including: air and coolant temperature, spark advance, fuel injector pulse width, exhaust gas oxygen content, engine speed (RPM), short and long term fuel trim, fuel system status (open or closed loop), manifold barometric pressure, atmospheric barometric pressure, throttle position, vehicle speed, etc. There is also a basic capability of translating check engine diagnostic trouble codes (DTCs). There is no support for obtaining OBD II freeze frame data, nor any analog to the concept of continuous fuel status, EVAP system or misfire monitoring. + +These limitations notwithstanding this adapter serves a crucial purpose in allowing 92-95 Honda Civics to be diagnosed with modern, readily available OBD II diagnostic scanners. + + +A prototype was constructed with the following: several trips to the junkyard to buy a Honda on board computer (ECU) and OBD II standard connectors, lots of hot glue and some mild eyestrain from trying to solder the MC33660, which is manufactured only in a package intended for automated assembly. The prototype was tested with an ELM compatible Bluetooth OBD II scanner. The prototype was tested with the OBD II PC software packages Scantool and OBDAutoDoctor. + + +Sections I, II, III: C++ Software Specification +Sections IV, V, VI, VII: Electrical and Hardware specification +Section VIII: TODO + +I. Control Flow + a. Asynchronous Processing Unit Design + b. Main Event Loop + c. State controller design, considerations +II. Class Reference + a. BusCoordinator + b. BusInit + c. TryReady + d. GenericBusInitAttempt + e. GenericBusInitComplete + f. CommCoordinator + g. GenericCommMessageCollector + h. GenericCommMessageProcessor + i. HondaCommCoordinator + j. HondaCommMessageCollector + k. HondaCommMessageProcessor + l. IHandler + m. IGenericHandler + o. IISOReply + p. GenericISOReply + n. GenericHandler + q. HondaHandler + r. HondaPort, ISOPort + s. HondaMap, ISOPID + +III. Patterns and Principles + SubSections a, b, c, d, e, f: Object Oriented Characteristics + SubSections g, h, i, j, k, l, m: Gang of Four Patterns + + a. Polymorphism + b. Loose Coupling, + c. Separation of Concerns + d. Information Hiding and Encapsulation + e. Reuse and Inheritance + f. Generalization + g. Template + h. Command Pattern + i. Chain of Responsibility, Responsibility Driven Design + j. State, Automaton, finite state machine + k. Strategy + l. Mediator + m. Adapter + +IV. Serial Ports +V. MC33660 +VI. Arduino +VII. OBD II +VIII. TODO + + CONTROL FLOW Asynchronous processing unit design -Generally classes involved in handshaking and serial communications support Work DoneWorking and Reset -These functions serve as a basic cooperative multitasking system Work is called when a higher level controller has a time slice to give to the unit The Work function of each controller is expected to do its work and exit quickly If the conditions are met that allow the handshaking or communications to proceed to the next higher level DoneWorking should return true Reset is used to reset the internal state of the unit typically at the end of a logical session controlled by a higher level controller - -Generally the units are oneshot triggers If for example a unit is falsely triggered to initiate a particular process by noise or an invalid packet it will continue to attempt completion of the process and cannot properly proceed with a valid sequence until it is Reset by a higher level controller +Generally, classes involved in handshaking and serial communications support Work(), DoneWorking() and Reset(). +These functions serve as a basic cooperative multitasking system. Work() is called when a higher level controller has a time slice to give to the unit. The Work() function of each controller is expected to do its' work, and exit quickly. If the conditions are met that allow the handshaking or communications to proceed to the next higher level, DoneWorking() should return true. Reset() is used to reset the internal state of the unit, typically at the end of a logical session controlled by a higher level controller. + +Generally, the units are one-shot triggers. If, for example, a unit is falsely triggered to initiate a particular process ( by noise or an invalid packet ), it will continue to attempt completion of the process and cannot properly proceed with a valid sequence until it is Reset() by a higher level controller. Main Event Loop -The main event loop cycles through the upper lever coordinators BusCoordinator CommCoordinator and HondaCommCoordinator in a round robin fashion calling Work and checking DoneWorking on each one - -The OBD II port requires a bus initialization handshaking sequences No bus initialization is necessary on the HondaPort - -The main event loop strives to move the system into higher and higher levels of functioning The macro levels of functioning are -Level 1 OBD II bus not initialized -Level 2 OBD II bus initialized waiting for incoming request from the OBD II port -Level 3 Message received from the OBD II port and forwarded to the HondaPort waiting for message from HondaPort -Level 4 Message received from the HondaPort and forwarded to the OBD II port - -Once the functioning level reaches 4 the process restarts generally at level 2 but possibly level 1 - -Level 1 - -The main event loop maintains a state variable that is either NOCOMM or COMMESTAB Each time through the main event loop if the state is NOCOMM bus not initialized then BusCoordinatorWork is called -The BusCoordinator will work to initialize the OBD II bus and achieve a higher state COMMESTAB by using TryReady BusInit GenericBusInitAttempt and GenericBusInitComplete After the call to BusCoordinatorWork BusCoordinatorDoneWorking is checked If this function returns true then the bus is ready for communications and the state is set to COMMESTAB if DoneWorking is not true the main event loop restarts again attempting to raise the functioning level by successfully initializating the OBD II bus - -Level 2 -Once the bus is initialized CommCoordinatorWork will be called to try to continue to raise the processing level -CommCoordinator will use GenericCommMessageCollector to get any incoming data on the OBD II port - -If there is no data available immediately on the serial port the GenericCommMessageCollectorWork will exit immediately; this allows the CommCoordinator to exit and yield control to the main event loop - -If there is waiting data the data will be retrieved and a state of COLLECT will be marked internally to GenericCommMessageCollector - -During the next iteration through the main event loop CommCoordinatorWork will be called and the Work function will call GenericCommMessageCollectorWork If there is more data available on the OBD II port that data will be collected by the GenericCommMessageCollector Since the internal state of GenericCommMessageCollector is COLLECT the new data will be appended to the existing message buffer +The main event loop cycles through the upper lever coordinators, BusCoordinator, CommCoordinator and HondaCommCoordinator in a round robin fashion, calling .Work() and checking .DoneWorking() on each one. + +The OBD II port requires a bus initialization handshaking sequences. No bus initialization is necessary on the HondaPort. + +The main event loop strives to move the system into higher and higher levels of functioning. The macro levels of functioning are: +Level 1. OBD II bus not initialized +Level 2. OBD II bus initialized, waiting for incoming request from the OBD II port. +Level 3. Message received from the OBD II port and forwarded to the HondaPort, waiting for message from HondaPort +Level 4. Message received from the HondaPort and forwarded to the OBD II port. + +Once the functioning level reaches 4, the process restarts generally at level 2, but possibly level 1. + +Level 1. + +The main event loop maintains a state variable that is either NO_COMM or COMM_ESTAB. Each time through the main event loop, if the state is NO_COMM (bus not initialized), then BusCoordinator.Work() is called. +The BusCoordinator will work to initialize the OBD II bus and achieve a higher state, COMM_ESTAB, by using TryReady, BusInit, GenericBusInitAttempt and GenericBusInitComplete. After the call to BusCoordinator.Work(), BusCoordinator.DoneWorking() is checked. If this function returns true, then the bus is ready for communications and the state is set to COMM_ESTAB. if DoneWorking() is not true, the main event loop restarts, again attempting to raise the functioning level by successfully initializating the OBD II bus. + +Level 2. +Once the bus is initialized, CommCoordinator.Work() will be called to try to continue to raise the processing level. +CommCoordinator will use GenericCommMessageCollector to get any incoming data on the OBD II port. + +If there is no data available immediately on the serial port, the GenericCommMessageCollector.Work() will exit immediately; this allows the CommCoordinator to exit and yield control to the main event loop. + +If there is waiting data, the data will be retrieved and a state of COLLECT will be marked internally to GenericCommMessageCollector. + +During the next iteration through the main event loop, CommCoordinator.Work() will be called and the Work() function will call GenericCommMessageCollector.Work(). If there is more data available on the OBD II port, that data will be collected by the GenericCommMessageCollector. Since the internal state of GenericCommMessageCollector is COLLECT, the new data will be appended to the existing message buffer. Level 3 -A true return value from GenericCommMessageCollectorDoneWorking signifies that a complete and valid OBD II message has been received and the internal state of the coordinator CommCoordinator will be marked as MESSAGERECEIVED Then the GenericCommMessageProcessor will become active processing the request by calling HondaHandlerIncomingPID The HondaHandler will translate the OBD II PID to an appropriate request for Honda data and will call SendHondaRequest to send a command sequence to the HondaPort HondaHandler will then assign the request to the HondaCommCoordinator which queues the request using a function pointer to establish a nonblocking asynchronous callback to be executed when the HondaPort data is ready -CommMessageProcessor and CommCoordinator then yield control to the main event loop - -During the next iteration of the main event loop HondaCommCoordinatorWork will be called and the HondaCommCoordinator will pick up the queued request and set an internal state of WORKING The HondaCommCoordinator will use the HondaCommMessageCollector to get any incoming data on the HondaPort If there is waiting data the character data will be retrieved and a state of COLLECT will be marked internally in the HondaCommMessageCollector - -DUring the next iteration through the main event loop HondaCommCoordinatorWork will be called If there is more data that data will be collected by the HondaCommMessageCollector Since the internal state of HondaCommMessageCollector is COLLECT the new data will be appended to the existing message buffer +A true return value from GenericCommMessageCollector.DoneWorking() signifies that a complete and valid OBD II message has been received and the internal state of the coordinator, CommCoordinator, will be marked as MESSAGE_RECEIVED. Then the GenericCommMessageProcessor will become active, processing the request by calling HondaHandler.IncomingPID(). The HondaHandler will translate the OBD II PID to an appropriate request for Honda data and will call SendHondaRequest() to send a command sequence to the HondaPort. HondaHandler will then assign the request to the HondaCommCoordinator, which queues the request, using a function pointer to establish a non-blocking asynchronous callback to be executed when the HondaPort data is ready. +CommMessageProcessor and CommCoordinator then yield control to the main event loop. + +During the next iteration of the main event loop, HondaCommCoordinator.Work() will be called and the HondaCommCoordinator will pick up the queued request and set an internal state of WORKING. The HondaCommCoordinator will use the HondaCommMessageCollector to get any incoming data on the HondaPort. If there is waiting data, the character data will be retrieved and a state of COLLECT will be marked internally in the HondaCommMessageCollector + +DUring the next iteration through the main event loop, HondaCommCoordinator.Work() will be called. If there is more data, that data will be collected by the HondaCommMessageCollector. Since the internal state of HondaCommMessageCollector is COLLECT the new data will be appended to the existing message buffer. Level 4 -When the message from the HondaPort is complete and valid signaled by the HondaCommMessageCollector returning true to DoneWorking the HondaCommMessageProcessor will become active and process the message by executing HondaHandlerCallback HondaHandlerCallback will execute the appropriate return function matching the original asynchronous request and effect the translation of the Honda sensor data into ISO measurements using a member of the group ISOMeasurementsTOISOReply and the reply to the OBD II port using a GenericHandlerIISOReply family member - -At this point the overall state has reached its highest point of productivity The various MessageCollectors and MessageProcessors are reset and the main event loop restarts at level 2 waiting for more serial messages from the OBD II port - - Advantages of state controller design - -Extensibility - -This structure provides a clean clear implementation that lends itself to further modifications and extension such as hooks to process other data or timeout watchdogs because there are clear places to hook into the overall flow of handshaking or messaging without the risk of undesirable interaction or needing to understand the lower level operation of each controller - -This structure also provides a clean way to implement potentially deep nested logic in a clear easy to debug and trace fashion - -Each asynchronous unit is coded with the overall structure in mind For example TryReadyWork will not block but will do a small amount of work polling the OBD II KLine bus status and checking the timeofday millis to maintain a running total of idle time and then Work will exit TryReady can maintain internal state such as the running total but encapsulates that state and signifies that internal conditions have been satisfied by returning true to DoneWorking Also when logical conditions require Reset can be used to reset the running total - -In this way serial communications or handshaking can be carefully controlled from the upper level -For instance this structure makes it easy and clear to implement an *OVERALL* handshake attempt timeout without modifying functionally distinct units such as TryReady - -Error Handling - -When dealing with serial port messaging subject to noise message fragments being received etc -it is quite possible for individual functional units to become stuck or hung due to waiting for message termination or validation that will never succeed because of midmessage corruption invalid or nonstandard messages etc - -In this type of messaging environment it is important to maintain supervisory control with clear topdown control logic The asynchronous nonblocking Work DoneWorking pattern lends itself to implementing supervisory controls - -Of paramount importance is that the supervisory code and its interface to lower level code be clear distinct and concise so that unforseen situations; ie dealing with slightly altered or new packets or protocol details and their concomitant issues; can be dealt with effectively - -Complexity and correctness - -The factoring of complicated nested communications logic into a body of state machines is an effective way of managing complexity and makes logical defects more apparent This factoring methodology allows the program to be treated as the steps of an algorithm facilitating the application of mathematically rigorous techniques to prove or disprove the correctness of the program logic - - Possible ramifications of state controller design - -Although the event loop design of the serial communications code has additional overhead compared to a more direct lowlevel approach and can cause an entire event loop to be executed between individual serial character data retrievals the overhead is mostly syntactic exposition and is not expected to be computationally intensive - -As well 9600 baud is not particularly fast relative to Arduinos microprocessor speed and the SoftwareSerial library is interrupt driven interrupts take priority over all other execution context and SoftwareSerial maintains its own input buffers Also the direct serial controllers CommMessageCollector and HondaCommMessageCollector are enhanced with a burst mode that increases their priority under certain circumstances Due to these factors it is considered extremely unlikely for the overhead of the state machine control system to cause a loss of serial data on any port +When the message from the HondaPort is complete and valid, signaled by the HondaCommMessageCollector returning true to DoneWorking(), the HondaCommMessageProcessor will become active and process the message by executing HondaHandler.Callback(). HondaHandler.Callback() will execute the appropriate return function matching the original asynchronous request and effect the translation of the Honda sensor data into ISO measurements, using a member of the group ISOMeasurementsTOISOReply, and the reply to the OBD II port, using a GenericHandler.IISOReply family member. + +At this point the overall state has reached its highest point of productivity. The various MessageCollector(s) and MessageProcessor(s) are reset, and the main event loop restarts at level 2, waiting for more serial messages from the OBD II port. + +-- Advantages of state controller design + +---Extensibility + +This structure provides a clean, clear implementation that lends itself to further modifications and extension, such as hooks to process other data or timeout watchdogs, because there are clear places to hook into the overall flow of handshaking or messaging without the risk of undesirable interaction or needing to understand the lower level operation of each controller. + +This structure also provides a clean way to implement potentially deep nested logic in a clear, easy to debug and trace fashion. + +Each asynchronous unit is coded with the overall structure in mind. For example, TryReady.Work() will not block but will do a small amount of work, polling the OBD II K-Line bus status and checking the time-of-day ( millis() ) to maintain a running total of idle time and then Work() will exit. TryReady can maintain internal state such as the running total but encapsulates that state and signifies that internal conditions have been satisfied by returning true to DoneWorking(). Also, when logical conditions require, Reset() can be used to reset the running total. + +In this way serial communications or handshaking can be carefully controlled from the upper level. +For instance, this structure makes it easy and clear to implement an *OVERALL* handshake attempt timeout, without modifying functionally distinct units such as TryReady. + +---Error Handling + +When dealing with serial port messaging, subject to noise, message fragments being received, etc, +it is quite possible for individual functional units to become stuck or hung due to: waiting for message termination or validation that will never succeed because of mid-message corruption, invalid or nonstandard messages, etc. + +In this type of messaging environment it is important to maintain supervisory control with clear top-down control logic. The asynchronous, non-blocking Work(), DoneWorking() pattern lends itself to implementing supervisory controls. + +Of paramount importance is that the supervisory code and its' interface to lower level code be clear, distinct and concise, so that unforseen situations; i.e. dealing with slightly altered or new packets or protocol details and their concomitant issues; can be dealt with effectively. + +---Complexity and correctness + +The factoring of complicated nested communications logic into a body of state machines is an effective way of managing complexity and makes logical defects more apparent. This factoring methodology allows the program to be treated as the steps of an algorithm, facilitating the application of mathematically rigorous techniques to prove or disprove the correctness of the program logic. + +-- Possible ramifications of state controller design + +Although the event loop design of the serial communications code has additional overhead compared to a more direct low-level approach, and can cause an entire event loop to be executed between individual serial character data retrievals, the overhead is mostly syntactic exposition, and is not expected to be computationally intensive. + +As well, 9600 baud is not particularly fast relative to Arduino's microprocessor speed and the SoftwareSerial library is interrupt driven ( interrupts take priority over all other execution context ) and SoftwareSerial maintains its' own input buffers. Also, the direct serial controllers, CommMessageCollector and HondaCommMessageCollector are enhanced with a burst mode that increases their priority under certain circumstances. Due to these factors it is considered extremely unlikely for the overhead of the state machine control system to cause a loss of serial data on any port. CLASS REFERENCE BusCoordinator -The BusCoordinator is responsible for coordinating the bus initialization process including bus idle time prerequisite wakeuppacket handshaking and confirmation handshaking -The Buscoordinator uses TryReady BusInit GenericBusInitAttempt and GenericBusInitComplete +The BusCoordinator is responsible for coordinating the bus initialization process including: bus idle time prerequisite, wakeup-packet handshaking and confirmation handshaking. +The Buscoordinator uses TryReady, BusInit, GenericBusInitAttempt, and GenericBusInitComplete. TryReady -TryReady polls the OBD II KLine bus pin and establishes that the necessary bus idle condition has been met before handshaking begins +TryReady polls the OBD II K-Line bus pin and establishes that the necessary bus idle condition has been met before handshaking begins. BusInit -Tasked with the job of attempting and completing an OBD II bus initialization handshake sequence Uses GenericBusInitAttempt and GenericBusInitComplete - -GenericBusInitAttempt establishes generic requirements for a bus initialization attempt which begins the handshaking sequence of an OBD II session Uses WAKEPACK array a storage area for KLine bus pin logic level transition times 10ms 100ms etc This routine uses Arduinos digitalRead to check the logic level of the OBD II KLine bus pin When the pin alters state High to Low or Low to High the timeofday millis is recorded This recorded value is compared to the timeofday when the next level transition occurs and in this way the length of the handshaking pulse or pulses is established - -If the transition pattern is a valid OBD II KLine bus wakeup pattern DoneWorking will return true +Tasked with the job of attempting and completing an OBD II bus initialization handshake sequence. Uses GenericBusInitAttempt and GenericBusInitComplete. + +GenericBusInitAttempt - establishes generic requirements for a bus initialization attempt, which begins the handshaking sequence of an OBD II session. Uses WAKE_PACK array, a storage area for K-Line bus pin logic level transition times ( 10ms, 100ms, etc ). This routine uses Arduino's digitalRead to check the logic level of the OBD II K-Line bus pin. When the pin alters state ( High to Low or Low to High ) the time-of-day ( millis() ) is recorded. This recorded value is compared to the time-of-day when the next level transition occurs, and in this way the length of the handshaking pulse or pulses is established. + +If the transition pattern is a valid OBD II K-Line bus wake-up pattern, DoneWorking() will return true. The protocol specific details of the GenericBusInitAttempt are left to the more derived classes -BusInitAttemptISO14230slow BusInitAttemptISO14230fast BusInitAttemptISO9141 +BusInitAttempt_ISO14230_slow, BusInitAttempt_ISO14230_fast, BusInitAttempt_ISO9141 GenericBusInitComplete -establishes basic requirements of bus initialization completion which finishes the handshaking sequences for an OBD II session The completion of the handshaking is accomplished by sending a confirmation message mathematically derived from the messages received during a bus initialization attempt to the OBD II port - -The protocol specific details of the BusInitComplete are left to the more derived classes -BusInitCompleteISO9141 BusInitComplete14230slow BusInitCompleteISO14230fast +establishes basic requirements of bus initialization completion which finishes the handshaking sequences for an OBD II session. The completion of the handshaking is accomplished by sending a confirmation message, mathematically derived from the messages received during a bus initialization attempt, to the OBD II port. + +The protocol specific details of the BusInitComplete are left to the more derived classes: +BusInitComplete_ISO9141, BusInitComplete_14230_slow, BusInitComplete_ISO14230_fast CommCoordinator -The CommCoordinator is responsible for collecting verifying and processing messages on the OBD II Kline serial port Processing generally concludes with a call to HondaHandlerIncomingPID which accepts responsibility for replying to the OBD II Kline serial port with the requested Honda on board computer ECU data Uses GenericCommMessageCollector and GenericCommMessageProcessor +The CommCoordinator is responsible for collecting, verifying and processing messages on the OBD II K-line serial port. Processing generally concludes with a call to HondaHandler.IncomingPID(), which accepts responsibility for replying to the OBD II K-line serial port with the requested Honda on board computer (ECU) data. Uses GenericCommMessageCollector and GenericCommMessageProcessor. GenericCommMessageCollector -Collects the serial data from the OBD II port and establishes completeness appropriate headers and basic errorchecking checksum of incoming serial data - -This message collector supports a serial burst mode assuming that an incoming serial character is usually followed by the remaining characters without delay This routine is authorized to busywait block waiting for serial data for a maximum time interval defined by SERIALBURSTMAXTIMESLICE before relinquishing control to its coordinator - -Protocol specific details are left to the more derived classes ISOCommMessageCollectorISO9141 ISOCommMessageCollectorISO14230 - - -GenericCommMessageProcessor -Processes a valid message containing an OBD II PID by calling HondaHandlerIncomingPID to transfer responsibility for retrieving the requested data and sending a reply to the OBD II port IncomingPID function does not block and GenericCommMessageProcessor and its coordinator CommCoordinator can exit immediately after the call to IncomingPID - - -Protocol specific details are left to the more derived classes CommMessageProcessorISO9141 CommMessageProcessorISO14230 - - -HondaCommCoordinator manages Honda communications Uses HondaCommMessageCollector and HondaCommMessageProcessor - -Works in conjunction with the HondaHandler Provides AssignWork function which when called by HondaHandler queues a request for Honda data +Collects the serial data from the OBD II port and establishes completeness (appropriate headers) and basic error-checking (checksum) of incoming serial data. + +This message collector supports a serial burst mode, assuming that an incoming serial character is usually followed by the remaining characters without delay. This routine is authorized to busy-wait (block) waiting for serial data for a maximum time interval defined by SERIAL_BURST_MAX_TIME_SLICE, before relinquishing control to its' coordinator. + +Protocol specific details are left to the more derived classes: ISOCommMessageCollector_ISO9141, ISOCommMessageCollector_ISO14230 + + +GenericCommMessageProcessor - +Processes a valid message containing an OBD II PID by calling HondaHandler.IncomingPID() to transfer responsibility for retrieving the requested data and sending a reply to the OBD II port. IncomingPID function does not block and GenericCommMessageProcessor and its' coordinator CommCoordinator can exit immediately after the call to IncomingPID. + + +Protocol specific details are left to the more derived classes: CommMessageProcessor_ISO9141, CommMessageProcessor_ISO14230 + + +HondaCommCoordinator manages Honda communications. Uses HondaCommMessageCollector and HondaCommMessageProcessor. + +Works in conjunction with the HondaHandler. Provides AssignWork function which, when called by HondaHandler, queues a request for Honda data. HondaCommMessageCollector -Collects the serial data from the HondaPort Establishes completeness appropriate headers errorchecking checksum of incoming serial data - -This message collector supports a serial burst mode assuming that an incoming serial character is usually followed by the remaining characters without delay This routine is authorized to busywait block waiting for serial data for a maximum time interval defined by SERIALBURSTMAXTIMESLICE before relinquishing control to its coordinator +Collects the serial data from the HondaPort. Establishes completeness, appropriate headers, error-checking (checksum) of incoming serial data. + +This message collector supports a serial burst mode, assuming that an incoming serial character is usually followed by the remaining characters without delay. This routine is authorized to busy-wait (block) waiting for serial data for a maximum time interval defined by SERIAL_BURST_MAX_TIME_SLICE, before relinquishing control to its' coordinator. HondaCommMessageProcessor -Processes valid messages from the HondaPort Processing concludes with a call to HondaHandlerCallback which effects translation of the Honda data and the reply to the OBD II port using a member of the GenericHandler ISOMeasurementsToISOReply group and an IISOReply family member - -IHandler establishes what a handler used by the CommCoordinatorCommMessageProcessor must do -A class implementing IHandler must support IncomingPID At a fundamental level to implement the IHandler interface the class must be able to do something with IncomingPID perhaps ignoring unsupported operations This class would be a good jumping off point for diverse purposes for example a class that only logs the incoming messages - -IGenericHandler supports VIN and Capabilities -A slightly richer implementation would be required to at a minimum reply with the Vehicle Identification Number and the Capabilities which is a list of supported sensors or other data that can be retrieved - -IISOReply is an interface defining the generic requirements of a reply to the OBD II port - -GenericISOReply is class containing generic OBD II port reply code -The protocol specific details are left to the more derived classes ProtocolReplyISO9141 and ProtocolReplyISO14230 +Processes valid messages from the HondaPort. Processing concludes with a call to HondaHandler.Callback(), which effects translation of the Honda data and the reply to the OBD II port using a member of the GenericHandler ISOMeasurementsToISOReply group and an IISOReply family member. + + +IHandler establishes what a handler, used by the CommCoordinator.CommMessageProcessor, must do +A class implementing IHandler must support IncomingPID. At a fundamental level, to implement the IHandler interface the class must be able to do something with IncomingPID, perhaps ignoring unsupported operations. This class would be a good jumping off point for diverse purposes, for example, a class that only logs the incoming messages. + +IGenericHandler supports VIN and Capabilities. +A slightly richer implementation would be required to, at a minimum, reply with the Vehicle Identification Number and the Capabilities, which is a list of supported sensors or other data that can be retrieved. + +IISOReply is an interface defining the generic requirements of a reply to the OBD II port. + +GenericISOReply is class containing generic OBD II port reply code. +The protocol specific details are left to the more derived classes: ProtocolReply_ISO9141 and ProtocolReply_ISO14230. GenericHandler -Adds an interface of virtual function prototypes that describe the expected input and output for a sensor data retrieval implementation and a baseline map function ISOPIDTOGENERICHANDLERMAP that links OBD II PIDs to functions in the sensor interface GenericHandler builds directly upon its direct ancestor abstractions IGenericHandler and IHandler but becomes richer and more concrete by extending outside of that family to become a composition with an IISOReply family member - - -GenericHandler also defines functions that convert data to an OBD II format These functions follow the naming convention ISOMeasurementsToISOReplyXXXXX These functions accept input data in the scale dictated by the OBD II standard; ie temperature is measured in Celcius degress with the input data to the function represented by the formula Actual Temp 40 EG if the temperature of the coolant is determined to be 55 deg C you would call ISOMeasureToISOReplyScalarbyte 15 ; - -The inclusion of an IISOReply family member which includes functions that reply to the OBD II port and the definitions of the ISOMeasurementsToISOReply functions establishes that at this level of class abstraction that the concept of handling will be to send a reply message to the OBD II port The IISOReply member also provides functions toward this end At this level the implementation of the sensor data virtual functions is left abstract - - -HondaHandler becomes the most derived richest member of this family tree It is a complete fully functional handler It adds concrete implementations of the remaining abstractions in the GenericHandler family hierarchy the abstract sensor data retrieval interface and IncomingPID - -The HondaHandler implements IncomingPID by using the generic mapping of OBD II PIDS onto the abstract sensor data retrieval interface ISOPIDTOGENERICHANDLERMAP The HondaHandler implementation of the sensor data retrieval functions is asynchronous and delegated relying on the placement of its functional colleague HondaCommCoordinator in the main event loop to retrieve the data from the HondaPort - -HondaCommCoordinatorAssignWork is used to communicate with the HondaCommCoordinator requesting that during the next main event loop cycle the retrieval of a particular sensor value from the Honda on board computer ECU -AssignWork establishes a callback function pointer for the HondaCommCoordinator to call when the requested data has been retrieved - -When the HondaCommCoordinator responds with the data HondaHandler converts maps or otherwise translates the data values from the Honda scaling or other representations into values compatible with the OBD II measurement scale or representation Then a member of the GenericHandlerISOMeasurementsTOISOReplyXXXX group is called to generically convert the data into an OBD II format and then use an IISOReply family member to effect the reply to the OBD II port using the proper protocol - - -HondaHandler implements the IGeneralAsyncHandler interface marking it as an asynchronous class - -HondaHandler defines GeneralAsyncRequest a function that factors out the common code for setting up the function pointer +Adds an interface of virtual function prototypes that describe the expected input and output for a sensor data retrieval implementation and a baseline map function, ISOPID_TO_GENERIC_HANDLER_MAP, that links OBD II PIDs to functions in the sensor interface. GenericHandler builds directly upon its direct ancestor abstractions IGenericHandler and IHandler, but becomes richer and more concrete by extending outside of that family to become a composition with an IISOReply family member. + + +GenericHandler also defines functions that convert data to an OBD II format. These functions follow the naming convention ISOMeasurementsToISOReply..XXXXX. These functions accept input data in the scale dictated by the OBD II standard; i.e. temperature is measured in Celcius degress, with the input data to the function represented by the formula "Actual Temp - 40". E.G., if the temperature of the coolant is determined to be 55 deg. C., you would call ISOMeasureToISOReply_Scalar_byte( 15 ); + +The inclusion of an IISOReply family member which includes functions that reply to the OBD II port and the definitions of the ISOMeasurementsToISOReply functions establishes that at this level of class abstraction that the concept of handling will be to send a reply message to the OBD II port. The IISOReply member also provides functions toward this end. At this level, the implementation of the sensor data virtual functions is left abstract. + + +HondaHandler becomes the most derived, richest member of this family tree. It is a complete, fully functional handler. It adds concrete implementations of the remaining abstractions in the GenericHandler family hierarchy, the abstract sensor data retrieval interface and IncomingPID(). + +The HondaHandler implements IncomingPID by using the generic mapping of OBD II PIDS onto the abstract sensor data retrieval interface, ISOPID_TO_GENERIC_HANDLER_MAP. The HondaHandler implementation of the sensor data retrieval functions is asynchronous, and delegated, relying on the placement of its' functional colleague, HondaCommCoordinator, in the main event loop, to retrieve the data from the HondaPort. + +HondaCommCoordinator.AssignWork() is used to communicate with the HondaCommCoordinator, requesting that during the next main event loop cycle, the retrieval of a particular sensor value from the Honda on board computer (ECU). +AssignWork establishes a callback function pointer for the HondaCommCoordinator to call when the requested data has been retrieved. + +When the HondaCommCoordinator responds with the data, HondaHandler converts, maps or otherwise translates the data values from the Honda scaling or other representations, into values compatible with the OBD II measurement scale or representation. Then a member of the GenericHandler.ISOMeasurementsTOISOReply...XXXX group is called to generically convert the data into an OBD II format and then use an IISOReply family member to effect the reply to the OBD II port using the proper protocol. + + +HondaHandler implements the IGeneralAsyncHandler interface, marking it as an asynchronous class. + +HondaHandler defines GeneralAsyncRequest, a function that factors out the common code for setting up the function pointer. IGenericAsyncHandler -IGenericAsyncHandler is a marker interface Implementing it marks a class as asynchronous in nature - - -ISOPort HondaPort -ISOPort and HondaPort provide character based access to the serial ports defined using a SoftwareSerial instance configured to communicate on the digital IO pins connected to the OBD II connector and the Honda Diagnostic Link Connector - -ISOPort and HondaPort provide safety features by providing a consistent interface to the serial ports which can often become unmanageable within nested serial communications logic - -All reads and writes are done through these interfaces so the checksums are calculated through these routines reducing the risk of multiple conflicting direct access +IGenericAsyncHandler is a marker interface. Implementing it marks a class as asynchronous in nature. + + +ISOPort, HondaPort +ISOPort and HondaPort provide character based access to the serial ports, defined using a SoftwareSerial instance configured to communicate on the digital I/O pins connected to the OBD II connector and the Honda Diagnostic Link Connector. + +ISOPort and HondaPort provide safety features by providing a consistent interface to the serial ports, which can often become unmanageable within nested serial communications logic. + +All reads and writes are done through these interfaces, so the checksums are calculated through these routines, reducing the risk of multiple conflicting direct access. HondaMap -HondaMap objects are used to refer to specific sensors in the Honda onboard computer ECU The definition includes an address and length Some sensors return two bytes for example RPM If the twobyte return data is a scalar value the data is bigendian that is the most significant byte the one that counts for 256 for each 1 of its value is the first of the twobytes transmitted by the ECU +HondaMap objects are used to refer to specific sensors in the Honda on-board computer (ECU). The definition includes an address and length. Some sensors return two bytes, for example, RPM. If the two-byte return data is a scalar value, the data is big-endian, that is, the most significant byte, the one that counts for 256 for each 1 of its' value, is the first of the two-bytes transmitted by the ECU. ISOPID -ISOPID objects are used to represent OBD II requests Each request contains a mode and an identifier Mode 1 is sensors Mode 3 is Diagnostic Trouble Codes EG Mode 1 identifier 0x0C is engine speed RPM +ISOPID objects are used to represent OBD II requests. Each request contains a mode and an identifier. Mode 1 is sensors. Mode 3 is Diagnostic Trouble Codes. E.G. Mode 1, identifier 0x0C is engine speed (RPM). @@ -206,216 +280,223 @@ PATTERNS -Object Oriented characteristics +Object Oriented characteristics: Polymorphism -GenericBusInitAttempt ISO14230BusInitAttempt ISO9141BusInitAttempt - -When the variable oBusInitAttempt takes the form of a ISO14230BusInitAttempt the BusCoordinator doesnt know or care about this All the BusCoordinator needs to know is that a GenericBusInitAttempt is being utilized Thus the principle of polymorphism or many forms is being leveraged to achieve more generalized code From one perspective the form of the instance variable oBusInitAttempt is GenericBusInitAttempt and from another perspective the form is ISO14230BusInitAttempt thus polymorphic - -IHandler GenericHandler HondaHandler -The IHandler abstract interface is used in the CommMessageProcessor The form of the instance variable in CommMessageProcessor is an abstract IHandler at compile time At run time however the IHandler object takes the form of a concrete HondaHandler From the perspective of the CommMessageProcessor the instance variable is an IHandler but from a macro system level view the instance variable is a HondaHandler Thus this variable takes many forms and is polymorphic GenericHandler is another form of an IHandler albeit a kind of abstract unexpressed form as instantiating it would result in an incomplete handler implementation +GenericBusInitAttempt, ISO14230_BusInitAttempt, ISO9141_BusInitAttempt + +When the variable oBusInitAttempt takes the form of a ISO14230_BusInitAttempt, the BusCoordinator doesn't know or care about this. All the BusCoordinator needs to know is that a GenericBusInitAttempt is being utilized. Thus the principle of polymorphism, or many forms, is being leveraged to achieve more generalized code. From one perspective the form of the instance variable oBusInitAttempt is GenericBusInitAttempt and from another perspective the form is ISO14230_BusInitAttempt, thus polymorphic. + +IHandler, GenericHandler, HondaHandler +The IHandler abstract interface is used in the CommMessageProcessor. The form of the instance variable in CommMessageProcessor is an abstract IHandler at compile time. At run time, however the IHandler object takes the form of a concrete HondaHandler. From the perspective of the CommMessageProcessor the instance variable is an IHandler, but from a macro, system level view, the instance variable is a HondaHandler. Thus this variable takes many forms and is polymorphic. GenericHandler is another form of an IHandler, albeit a kind of abstract 'unexpressed' form, as instantiating it would result in an incomplete handler implementation. Loose Coupling -Even though they work closely together to accomplish the overall goal in this adapter implementation -there is a loosecoupling between the CommMessageProcessor receiving a PID from the OBDII port and the HondaHandler effecting a reply to the OBD II port This coupling is loose because the Handler could be implemented in different ways and this loose coupling leaves the door open for more diverse interpretations of the term handling - -In this adapter implementation the loose coupling make it easier to inject an asynchronous handler into the design The CommMessageProcessor is coupled only to an IHandler an interface definition aka contract specification not tied directly to the asynchronous implementation of HondaHandler reducing the chance of cascading changes rippling through multiple functional units - -One of the advantages of the loose coupling in this adapter implementation is its ability to mitigate the situation where one subsystem is blocked by another It would be undesirable to make the CommMessageProcessor blockwait for the Honda data to be retrieved The data may never come but we still want the CommMessageProcessor to be able to degrade gracefully and respond to its immediate supervisor The loose coupling supports this because the HondaHandler doesnt take control when it is tasked with getting Honda sensor data It is delegated to do so and this is a pattern of Chain of Responsibility but the CommMessageProcessor maintains control and can exit cleanly This clean exit facilitates the placement of supervisory control logic where it belongs; at a high logical level in the code not buried deep in the implementation details of a particular low level unit - -Loose coupling has its benefits and downfalls Loose coupling allows flexibility in implementing the Handler without changing the CommMessageProcessor and ultimately aids in the implementation of an asynchronous handler but this does not come without issues For example there is no way to easily enforce transactional integrity across this coupling or pass error or control messages such as retry across this coupling because by the time a failure is detected on one side of the coupling the execution context that initiated the request has exited A similar problem occurs with nonasynchronous loose coupling where for example it is impossible to pass an error message because the loose coupling only supports a limited interface +Even though they work closely together to accomplish the overall goal in this adapter implementation, +there is a loose-coupling between the CommMessageProcessor, receiving a PID from the OBDII port and the HondaHandler, effecting a reply to the OBD II port. This coupling is loose because the Handler could be implemented in different ways and this loose coupling leaves the door open for more diverse interpretations of the term 'handling'. + +In this adapter implementation the loose coupling make it easier to inject an asynchronous handler into the design. The CommMessageProcessor is coupled only to an IHandler, an interface definition ( aka, contract specification ), not tied directly to the asynchronous implementation of HondaHandler, reducing the chance of cascading changes rippling through multiple functional units. + +One of the advantages of the loose coupling in this adapter implementation is its' ability to mitigate the situation where one subsystem is blocked by another. It would be undesirable to make the CommMessageProcessor block(wait) for the Honda data to be retrieved. The data may never come but we still want the CommMessageProcessor to be able to degrade gracefully and respond to its' immediate supervisor. The loose coupling supports this because the HondaHandler doesn't take control when it is tasked with getting Honda sensor data. It is delegated to do so and this is a pattern of Chain of Responsibility, but the CommMessageProcessor maintains control and can exit cleanly. This clean exit facilitates the placement of supervisory control logic where it belongs; at a high logical level in the code, not buried deep in the implementation details of a particular low level unit. + +Loose coupling has its benefits and downfalls. Loose coupling allows flexibility in implementing the Handler without changing the CommMessageProcessor, and ultimately aids in the implementation of an asynchronous handler, but this does not come without issues. For example, there is no way to easily enforce transactional integrity across this coupling, or pass error or control messages such as 'retry' across this coupling because by the time a failure is detected on one side of the coupling, the execution context that initiated the request has exited. A similar problem occurs with non-asynchronous loose coupling, where, for example, it is impossible to pass an error message because the loose coupling only supports a limited interface. Separation of Concerns -See Patterns and Principles Loose Coupling Information Hiding and Encapsulation and Chain of Responsibility +See _Patterns and Principles_ "Loose Coupling", "Information Hiding and Encapsulation", and "Chain of Responsibility" Generalization - Reuse Inheritance and Templates - Benefits -The sharing of common functionality reduces the overall code load that must be inspected It also increase the chances that changes made to the system will propagate in the proper way - Ramifications -The factoring out of common functionality must be done thoughtfully and carefully as the benefits of reuse are quickly outweighed by the complexity of managing entanglement between sharing classes - -See Also Generalization composition flexibility of modularity -see Also Generalization composition ramifications -See Also Generalization overgeneralization -See Also Template for examples; Generally whereever there is a Template there is reuse - - -Generalization composition - Reuse factoring flexibility of modularity - Benefits -Factoring out distinct conceptual groups of functionality like sensor data virtual function interface ISOMeasurementsTOISOReply grouping IISOReply and GenericISOReply provides the flexibility of modularity Individual pieces can be swapped in and out eg substituting a newer Controller Area Network diagnostic subsystem implementation for the OBD II system as long as the new piece adheres to the established convention defined by interfaces - -Flexibilty means less risk Generalizing may take more frontend design time but reduces the amplitude of wildschedule swings on the back end - Ramifications -Compositional reuse can lead a design down a dead end If a class inherits everything from a composed class and implements a new subsystem without a solid set of abstract interfaces or contracts to define exactly where in the tree the new functionality branches off from or differs from the previous incarnation it is likely that new functionality will simply rewrite existing functionality - -So there is a place on the spectrum between strict inheritance hierarchytogod class compositional multipurposing that must be chosen carefully Too tight interface adherence limits the diversity that future implementations can create Too little interface adherance and excessive use of adhoc compositional reuse encourages rewrites and bigballofmud designs +-- Reuse, Inheritance and Templates +--- Benefits +The sharing of common functionality reduces the overall code load that must be inspected. It also increase the chances that changes made to the system will propagate in the proper way. +--- Ramifications +The factoring out of common functionality must be done thoughtfully and carefully, as the benefits of reuse are quickly outweighed by the complexity of managing entanglement between sharing classes. + +See Also, Generalization, composition, flexibility of modularity +see Also, Generalization, composition, ramifications +See Also, Generalization, overgeneralization +See Also, Template for examples; Generally whereever there is a Template there is reuse. + + +Generalization, composition +-- Reuse, factoring, flexibility of modularity +--- Benefits +Factoring out distinct conceptual groups of functionality like sensor data virtual function interface, ISOMeasurementsTOISOReply grouping, IISOReply and GenericISOReply provides the flexibility of modularity. Individual pieces can be swapped in and out, e.g. substituting a newer Controller Area Network diagnostic subsystem implementation for the OBD II system, as long as the new piece adheres to the established convention, defined by interfaces. + +Flexibilty means less risk. Generalizing may take more front-end design time, but reduces the amplitude of wild-schedule swings on the back end. +--- Ramifications +Compositional reuse can lead a design down a dead end. If a class inherits everything from a composed class and implements a new subsystem, without a solid set of abstract interfaces ( or contracts ) to define exactly where in the tree the new functionality branches off from ( or differs from the previous incarnation ), it is likely that new functionality will simply rewrite existing functionality. + +So there is a place on the spectrum between strict inheritance hierarchy-to-god class compositional multipurposing that must be chosen carefully. Too tight interface adherence limits the diversity that future implementations can create. Too little interface adherance and excessive use of ad-hoc compositional reuse encourages rewrites and big-ball-of-mud designs. Overgeneralization -The attempt to use generic structures is a noble goal but there is a limit to how far to take it The architect of class families must focus on the real purpose of the design effort Is it to solve a particular problem with a flexible building block pattern that reduces the risk that changing requirements will render the code unusable? -Or is the design effort moving dangerously toward overgeneralization For example a good home builder might carry a variety of tools saws hammer etc some of which may even be used to build other tools eg scaffolding for painting But the home builder doesnt carry a smelting forge in the truck He doesnt need that much generality and to attempt such would actually be counterproductive for building a house so the principle is to keep some perspective about the goal you are trying to achieve - -Too much factoring and generalizing can cause unnecessary complexity As the class family becomes more fragmented and modular it becomes harder for the consumer to understand how to use it - -So the place on the spectrum of generalismtospecialization is important There is always a design tradeoff As Spolsky says the trash can must be open on top so people can put trash in But it needs to be closed on top so trash doesnt blow away - - -Generalization practical implications and best practices - -The structure of the IHandler family beginning with the IHandler interface and ending with the HondaHandler -is constructed with inheritance and composition - -The HondaHandler inherits functionality from the trunk GenericHandler But GenericHandler is actually formed of inheritance from IGenericHandler and IHandler but also of composition with another family tree IISOReply So the trunk HondaHandler inherits is already a compositional mixture and not a strict inheritance hierarchy of is a relationships The mixing of the ISOMeasurementsTOISOReply functions and an IISOReply family member into the IHandler family hierarchy effectively constrains handlers derived from GenericHandler to being OBD IIbased handlers - -HondaHandler is also formed with a mix of inheritance and composition; inheriting from GenericHandler but also formed by being composed with IGenericAsyncHandler - -In principle if the classes form a definite tight hierarchy and really could not be split into separate pieces that are independently functional use inheritance Another rule of thumb is if the relationship is a direct building *upon* use inheritance If the relationship is a kind of association with or equal level partnership use composition If the classes could be split use a composition approach to achieve the right mix of lateral building blocks - -The GenericHandler is made concrete on the OBD II side and left abstract on the Honda side because this is the most likely usage pattern The next logical step for the IHandler family tree would be to branch off at the GenericHandler level to create a concrete implementation of another proprietary standard that needed to adapt to the now ubiquitious OBD II standard This is a likely reuse pattern but not the only one afforded by the generalization topology described here It is hard to conceptualize exactly what could be constructed with the existing modules and interfaces or contracts but that is the beauty of infrastructure in the designers opinion - - -Generalization principles serve as design heuristics when building reusable infrastructure or tooling to build Mediators like GenericHandler where one or more sides may be unknown at the time of construction of the tooling +The attempt to use generic structures is a noble goal, but there is a limit to how far to take it. The architect of class families must focus on the real purpose of the design effort. Is it to solve a particular problem, with a flexible building block pattern, that reduces the risk that changing requirements will render the code unusable? +Or is the design effort moving dangerously toward overgeneralization. For example, a good home builder might carry a variety of tools, saws, hammer, etc, some of which may even be used to build other tools. e.g. scaffolding for painting. But the home builder doesn't carry a smelting forge in the truck. He doesn't need that much generality and to attempt such would actually be counterproductive - for building a house - so the principle is to keep some perspective about the goal you are trying to achieve. + +Too much factoring and generalizing can cause unnecessary complexity. As the class family becomes more fragmented and modular it becomes harder for the consumer to understand how to use it. + +So the place on the spectrum of generalism-to-specialization is important. There is always a design trade-off. As Spolsky says, the trash can must be open on top so people can put trash in. But it needs to be closed on top so trash doesn't blow away. + + +Generalization, practical implications and best practices + +The structure of the IHandler family, beginning with the IHandler interface and ending with the HondaHandler. +is constructed with inheritance and composition. + +The HondaHandler inherits functionality from the trunk, GenericHandler. But GenericHandler is actually formed of inheritance from IGenericHandler and IHandler, but also of composition with another family tree, IISOReply. So the trunk HondaHandler inherits is already a compositional mixture and not a strict inheritance hierarchy of 'is a' relationships. The mixing of the ISOMeasurementsTOISOReply functions and an IISOReply family member into the IHandler family hierarchy effectively constrains handlers derived from GenericHandler to being OBD II-based handlers. + +HondaHandler is also formed with a mix of inheritance and composition; inheriting from GenericHandler but also formed by being composed with IGenericAsyncHandler. + +In principle, if the classes form a definite tight hierarchy and really could not be split into separate pieces that are independently functional, use inheritance. Another rule of thumb is if the relationship is a direct building *upon* , use inheritance. If the relationship is a kind of association with, or equal level partnership, use composition. If the classes could be split, use a composition approach to achieve the right mix of 'lateral' building blocks. + +The GenericHandler is made concrete on the OBD II side and left abstract on the Honda side because this is the most likely usage pattern. The next logical step for the IHandler family tree would be to branch off at the GenericHandler level to create a concrete implementation of another proprietary standard that needed to adapt to the now ubiquitious OBD II standard. This is a likely re-use pattern, but not the only one afforded by the generalization topology described here. It is hard to conceptualize exactly what could be constructed with the existing modules and interfaces ( or contracts ) but that is the beauty of infrastructure in the designer's opinion. + + +Generalization principles serve as design heuristics when building re-usable infrastructure ( or tooling ) to build Mediators like GenericHandler where one or more sides may be unknown at the time of construction of the tooling. Mixins -The IHandler family may benefit from a more formal analysis and redesign using mixins which are a combination of methods from separate classes +The IHandler family may benefit from a more formal analysis and re-design using mixins, which are a combination of methods from separate classes. Traits -The IHandler family may benefit from a more formal analysis and redesign using traits a set of methods that implement a behaviour and a set of methods that parameterize that behaviour - - -See Also Class References GenericHandler HondaHandler - -Template - -IHandler provides a template for any class that may be used as a handler by CommMessageProcessor -HondaHandler is the most derived class from this template - -IISOReply provides a template for any class that replies to the ISOPort ISOReply9141 and ISOReply14320 build on this template - -GenericBusInitAttempt provides a template for classes that attempt OBD II protocol bus initialization Since there are three similar but nontheless unique possible methods of initialization ISO9141 ISO14230slow and ISO14230fast the shared code between these three is factored into the template and only the unique characteristics remain in the most derived classes BusInitAttemptISO9141 BusInitAttemptISO14230slow BusInitAttemptISO14230fast +The IHandler family may benefit from a more formal analysis and re-design using traits, a set of methods that implement a behaviour and a set of methods that parameterize that behaviour. + + +See Also, _Class References_ "GenericHandler", "HondaHandler" + +Template: + +IHandler provides a template for any class that may be used as a handler, by CommMessageProcessor. +HondaHandler is the most derived class from this template. + +IISOReply provides a template for any class that replies to the ISOPort. ISOReply_9141 and ISOReply14320 build on this template. + +GenericBusInitAttempt provides a template for classes that attempt OBD II protocol bus initialization. Since there are three similar but nontheless unique possible methods of initialization (ISO9141, ISO14230_slow, and ISO14230_fast) the shared code between these three is factored into the template and only the unique characteristics remain in the most derived classes (BusInitAttempt_ISO9141, BusInitAttempt_ISO14230_slow, BusInitAttempt_ISO14230_fast). Information Hiding and Encapsulation -ISOPort and HondaPort encapsulate the checksum running total variable improving code safety +ISOPort and HondaPort encapsulate the checksum running total variable, improving code safety. -Each coordinator BusCoordinator CommCoordinator HondaCommCoordinator or controller TryReady BusInitAttempt CommMessageCollector etc hides its internal state providing a standard interface This improves safety and reduces the need to understand the internal details to make changes to the logic using these functional units - -HondaMap and ISOPID classes hide the lowlevel details of these data structures providing a safer eg a Honda address can never be inadvertently associated with wrong length because they are stored together more convenient way of manipulating these logical units +Each coordinator (BusCoordinator, CommCoordinator, HondaCommCoordinator) or controller (TryReady, BusInitAttempt, CommMessageCollector, etc) hides its internal state, providing a standard interface. This improves safety and reduces the need to understand the internal details to make changes to the logic using these functional units. + +HondaMap and ISOPID classes hide the low-level details of these data structures, providing a safer ( e.g. a Honda address can never be inadvertently associated with wrong length because they are stored together ), more convenient way of manipulating these logical units. Command Pattern -GenericHandler contains a function ISOPIDTOGENERICHANDLERMAP that is built in a command pattern that lends itself to further adhoc modification by adding executable code within the respective command hooks -Each ISOPID is treated as a command object directing execution into the appropriate sensor data retrieval function This pattern is extensible for example easily allowing for two or more separate retrieval steps or other adhoc functionality in the commanded subroutine - - -Chain of Responsibility -The functional colleagues CommMessageProcessor and HondaHandler exhibit characteristics of a Chain of Responsibility pattern The CommMessageProcessor does not directly handle the gathering of the data that is required for the successful conversions of the PID it receives into Honda data Rather it relies on an indirect Chain of Responsibility When a PID is received by CommMessageProcessor a delegating call to IncomingPID is made This shifts responsibility of actually completing this task onto another subsystem - - -HondaHandler AssignWork GeneralAsyncRequest -The HondaHandler sends a message to HondaCommCoordinator using AssignWork to retrieve the appropriate data from the HondaPort The AssignWork function shifts the responsibility to the HondaCommCoordinator to retrieve the data The HondaCommCoordinator is given the responsibility for retrieving the data and is also given the tools in the form of a Callback function pointer to *ASYNCHRONOUSLY* satisfy its obligation of returning the data - -The BusCoordinator BusInit and GenericBusInitAttempt or GenericBusInitComplete form a Chain of Responsibility pattern The BusCoordinator is responsible for the overall bus initialization sequences but it delegates responsibilty for this task to two associated classes TryReady and BusInit BusInit then transfers responsibility to its delegates GenericBusInitAttempt and GenericBusInitComplete Thus the responsibility for certain actions is transferred in a chain - -The main event loop and select parts of the class design could be considered an example of Responsibility Driven Design using a ClusteredDelegated control Structure - - - -State - -Many examples -The main event loop stores state about the overall OBD II connection state with two macro level states NOCOMM and COMMESTAB -BusCoordinator stores state about the state of bus handshaking -BusInitAttempt stores state about the state of the bus initialization attempt -Each of these units is called repeatedly to accomplish a single logical task and they keep track of where they are by a State pattern; they are guided and alter their behaviour based on their transient state - -DoneWorking and Reset provide consistent safe encapsulated access to the state - -The main event loop and all the subsidiary loops contained within could all be considered an example of one complex Automaton These structures could also be described as finite state machines - -Strategy - -The implementation of IHandlerIncomingPID by HondaHandler could be considered one Strategy for dealing with the incoming OBD II request This larger unit of work seems to qualify as a strategy and diverges from the Template definition of mere alteration of subtle details by a class deriving from a Template -Compare Template - - - - - -Mediator - -GenericHandler is a mediator because it is the only class that knows the internal details of two systems the OBD II system and the Honda system - -From the perspective of the CommMessageProcessor the IHandler base interface presents a simplified interface to the Honda side that consists of only one function call IncomingPID - -From the perspective of the Honda side GenericHandler presents a simplified interface to the OBD II side that consists of a group of ISOMeasurementsToISOReplyXXXX reply functions The input and operation of these functions is well defined and simple - -Thus the GenericHandler serves as a mediator providing a simplified interface to a complex task of obtaining Honda sensor data as well a providing a simplified interface to a complex task of sending data to the OBD II port using the proper protocol mediating these two sides of the system +GenericHandler contains a function ISOPID_TO_GENERIC_HANDLER_MAP(), that is built in a command pattern that lends itself to further ad-hoc modification by adding executable code within the respective command hooks. +Each ISOPID is treated as a command object, directing execution into the appropriate sensor data retrieval function. This pattern is extensible, for example, easily allowing for two or more separate retrieval steps or other ad-hoc functionality in the commanded subroutine. + + +Chain of Responsibility: +The functional colleagues CommMessageProcessor and HondaHandler exhibit characteristics of a Chain of Responsibility pattern. The CommMessageProcessor does not directly handle the gathering of the data that is required for the successful conversions of the PID it receives into Honda data. Rather, it relies on an indirect Chain of Responsibility. When a PID is received by CommMessageProcessor, a delegating call to IncomingPID is made. This shifts responsibility of actually completing this task onto another subsystem. + + +HondaHandler, AssignWork, GeneralAsyncRequest +The HondaHandler sends a message to HondaCommCoordinator using AssignWork to retrieve the appropriate data from the HondaPort. The AssignWork function shifts the responsibility to the HondaCommCoordinator to retrieve the data. The HondaCommCoordinator is given the responsibility for retrieving the data, and is also given the tools, in the form of a Callback function pointer, to *ASYNCHRONOUSLY* satisfy it's obligation of returning the data. + +The BusCoordinator, BusInit and GenericBusInitAttempt (or GenericBusInitComplete) form a Chain of Responsibility pattern. The BusCoordinator is responsible for the overall bus initialization sequences, but it delegates responsibilty for this task to two associated classes, TryReady and BusInit. BusInit then transfers responsibility to its' delegates GenericBusInitAttempt and GenericBusInitComplete. Thus the responsibility for certain actions is transferred in a chain. + +The main event loop and select parts of the class design could be considered an example of Responsibility Driven Design, using a Clustered/Delegated control Structure. + + + +State: + +Many examples: +The main event loop stores state about the overall OBD II connection state with two macro level states, NO_COMM and COMM_ESTAB. +BusCoordinator stores state about the state of bus handshaking. +BusInitAttempt stores state about the state of the bus initialization attempt. +Each of these units is called repeatedly to accomplish a single logical task and they keep track of where they are by a State pattern; they are guided and alter their behaviour based on their transient state. + +DoneWorking() and Reset() provide consistent, safe, encapsulated access to the state. + +The main event loop and all the subsidiary loops contained within could all be considered an example of one complex Automaton. These structures could also be described as finite state machines. + +Strategy: + +The implementation of IHandler.IncomingPID() by HondaHandler could be considered one Strategy for dealing with the incoming OBD II request. This larger unit of work seems to qualify as a strategy and diverges from the Template definition of mere alteration of subtle details by a class deriving from a Template. +Compare Template. + + + + + +Mediator: + +GenericHandler is a mediator because it is the only class that knows the internal details of two systems: the OBD II system and the Honda system. + +From the perspective of the CommMessageProcessor, the IHandler base interface presents a simplified interface to the Honda side that consists of only one function call, IncomingPID. + +From the perspective of the Honda side GenericHandler presents a simplified interface to the OBD II side that consists of a group of ISOMeasurementsToISOReply...XXXX reply functions. The input and operation of these functions is well defined and simple. + +Thus the GenericHandler serves as a mediator, providing a simplified interface to a complex task of obtaining Honda sensor data as well a providing a simplified interface to a complex task of sending data to the OBD II port using the proper protocol, mediating these two sides of the system. + +Adapter: +At a macro level, the entire hardware / software system is an Adapter, converting and translating the requests and data from one system into a format compatible with another system. + + SERIAL PORTS Software Serial -The SoftwareSerial library was chosen for two reasons The Arduino only has one hardware serial port and the best use for this port is as a debugging aid to see the trace messages from the monitor - -The other reason is that there is a need to operate the serial port at a nonstandard Honda baud rate The serial timing in SoftwareSerialh was adjusted though minimally for 9470 baud The original timing for 9600 baud worked before these adjustments were made This baud rate is relatively low and the difference between the Honda rate and the standard rate is small so it is possible these timing adjustments are superfluous - -Due to the nature of the SoftwareSerial interrupt driven design only one serial port can be active at any time Therefore at precise junctions in the control structure each port is activated with a listen statement - -Half Duplex This section is unconfirmed and based on the best knowledge of the designer - -SoftwareSerialWithHalfDuplex is used because the communication line on the Honda Diagnostic Link Connector is half duplex that is only one member the client HonOBDapt or the server on board computer ECU can transmit data at one time SoftwareSerialWithHalfDuplex supports this configuration by specifying the same pin for Transmit and Receive It is the responibillty of the HondaCommCoordinator to enforce this constraint as the behaviour of SoftwareSerialWithHalfDuplex if an attempt is made to transmit and receive at the same time is unknown - -The OBD II ISOPort is also half duplex but is connected to the MC33660 which has a full duplex style of connection with both Receive and Transmit pin connections This provides a physical electrical way of enforcing half duplex on the OBD II KLine as a communications participant attempting to bring the line low or high while the other participant is still transmitting will simply be ignored by the circuitry in the MC33660 +The SoftwareSerial library was chosen for two reasons. The Arduino only has one hardware serial port, and the best use for this port is as a debugging aid to see the trace messages from the monitor. + +The other reason is that there is a need to operate the serial port at a non-standard Honda baud rate. The serial timing in SoftwareSerial.h was adjusted, though minimally, for 9470 baud. The original timing for 9600 baud worked before these adjustments were made. This baud rate is relatively low and the difference between the Honda rate and the standard rate is small, so it is possible these timing adjustments are superfluous. + +Due to the nature of the SoftwareSerial interrupt driven design, only one serial port can be active at any time. Therefore, at precise junctions in the control structure, each port is activated with a .listen() statement. + +Half Duplex. This section is unconfirmed and based on the best knowledge of the designer. + +SoftwareSerialWithHalfDuplex is used because the communication line on the Honda Diagnostic Link Connector is half duplex, that is, only one member, the client (HonOBDapt) or the server (on board computer, ECU) can transmit data at one time. SoftwareSerialWithHalfDuplex supports this configuration by specifying the same pin for Transmit and Receive. It is the responibillty of the HondaCommCoordinator to enforce this constraint, as the behaviour of SoftwareSerialWithHalfDuplex if an attempt is made to transmit and receive at the same time is unknown. + +The OBD II ISOPort is also half duplex, but is connected to the MC33660 which has a full duplex style of connection with both Receive and Transmit pin connections. This provides a physical, electrical way of enforcing half duplex on the OBD II K-Line, as a communications participant attempting to bring the line low or high while the other participant is still transmitting will simply be ignored by the circuitry in the MC33660. MC33660 -MC33660 is a level conversion integrated circuit that converts 5 volt logic signals to 12 volt logic signals This is necessary because the main hardware component the Arduino uses 5 volt signals on its digital IO pins and OBD II specifies 12 volt signals MC33660 is an integrated circuit specifically designed for logic level conversion in an OBD II automotive application and should therefore be particularly suited to this application in terms of susceptibility to noise overload protection etc MC33660 is designed to be connected to the KLine bus and therefore provides an appropriate electrical interface for serial communications and busstyle level transitions +MC33660 is a level conversion integrated circuit that converts 5 volt logic signals to 12 volt logic signals. This is necessary because the main hardware component, the Arduino, uses 5 volt signals on its' digital I/O pins and OBD II specifies 12 volt signals. MC33660 is an integrated circuit specifically designed for logic level conversion in an OBD II automotive application and should therefore be particularly suited to this application in terms of susceptibility to noise, overload protection, etc. MC33660 is designed to be connected to the K-Line bus and therefore provides an appropriate electrical interface for serial communications and bus-style level transitions. Arduino -Arduino provides 5 volt logic level digital IO pins that are suited to this application The application of a software library that allows serial communications on any pin provides significant flexibility Arduino has flexible power supply requirements and can be operated on a 12 volt system Nominal current draw through the onboard voltage regulator in this application is 200mA Heat created by the voltage regulator dropping 12 volts to 5 volts to power the on board processor is dissipated by a small onboard heatsink so the current limits and supply voltage combination must be carefully selected The current configuration is within limits to the best knowledge of the designer and has been anecdotally confirmed by feeling for excess heat from the voltage regulator +Arduino provides 5 volt logic level digital I/O pins that are suited to this application. The application of a software library that allows serial communications on any pin provides significant flexibility. Arduino has flexible power supply requirements and can be operated on a 12 volt system. Nominal current draw through the onboard voltage regulator in this application is 200mA. Heat created by the voltage regulator dropping 12 volts to 5 volts to power the on board processor is dissipated by a small on-board heatsink, so the current limits and supply voltage combination must be carefully selected. The current configuration is within limits to the best knowledge of the designer and has been anecdotally confirmed by feeling for excess heat from the voltage regulator. OBD II -The OBD II electrical and logical communications standard is actually a conglomeration of many existing standards at the time of creation of the OBD II standard by ISO This adapter supports the KLine standards of ISO9141 ISO14230slow and ISO14230fast Only one is technically required as any OBD II compliant scanner must be able to work with all three but the implementations vary only minimally and provide a good exercise and example of certain software design techniques +The OBD II electrical and logical communications standard is actually a conglomeration of many existing standards at the time of creation of the OBD II 'standard' by ISO. This adapter supports the K-Line standard(s) of ISO-9141, ISO-14230_slow, and ISO-14230_fast. Only one is technically required as any OBD II compliant scanner must be able to work with all three, but the implementations vary only minimally and provide a good exercise and example of certain software design techniques. TODO -Asynchronous Multitasking - -There should be an ITask interface to constrain and define the exact nature of the controllers that have the Work DoneWorking and Reset functions - -Handler class family construction - -The sensor data virtual function prototypes in GenericHandler should be split into a separate interface definition then implemented virtually by GenericHandler and concretely by more derived classes like HondaHandler - -The ISOMeasurementToISOReplyXXXX family of functions should be extracted out of GenericHandler and put in a separate mixin - -The IGeneralAsyncHander should be expanded and more clearly defined to include the GeneralAsyncRequest function defined in an adhoc manner in HondaHandler - -Other - -The HondaCommCoordinator should implement an IWorkQueue interface clarifying the role of the Assignwork function - -The magic numbers of the digital IO pins used for serial communications in SoftwareSerial should be extracted out into a #define - - -Adapter -At a macro level the entire hardware software system is an Adapter converting and translating the requests and data from one system into a format compatible with another system - +----Asynchronous Multitasking: + +There should be an ITask interface to constrain and define the exact nature of the controller(s) that have the Work(), DoneWorking(), and Reset() functions. + +-----Handler class family construction: + +The sensor data virtual function prototypes in GenericHandler should be split into a separate interface definition, then implemented virtually by GenericHandler and concretely by more derived classes like HondaHandler. + +The ISOMeasurementToISOReply...XXXX family of functions should be extracted out of GenericHandler and put in a separate mix-in. + +The IGeneralAsyncHander should be expanded and more clearly defined to include the GeneralAsyncRequest function defined in an ad-hoc manner in HondaHandler. + +----Other + +The HondaCommCoordinator should implement an IWorkQueue interface, clarifying the role of the Assignwork function. + +The magic number(s) of the digital I/O pins used for serial communications in SoftwareSerial should be extracted out into a define. + + + + + + + &lt;/pre&gt;</pre>Andrew smithFri, 21 Jun 2013 14:14:41 -0000https://sourceforge.net70545d7fd66e9d9bb8c374b8a3b608325614ac56https://sourceforge.net/p/honobdapt/wiki/add/<div class="markdown_content"><pre>--- v40 +++ v41 @@ -360,6 +360,62 @@ Thus the GenericHandler serves as a mediator providing a simplified interface to a complex task of obtaining Honda sensor data as well a providing a simplified interface to a complex task of sending data to the OBD II port using the proper protocol mediating these two sides of the system +SERIAL PORTS + + + +Software Serial +The SoftwareSerial library was chosen for two reasons The Arduino only has one hardware serial port and the best use for this port is as a debugging aid to see the trace messages from the monitor + +The other reason is that there is a need to operate the serial port at a nonstandard Honda baud rate The serial timing in SoftwareSerialh was adjusted though minimally for 9470 baud The original timing for 9600 baud worked before these adjustments were made This baud rate is relatively low and the difference between the Honda rate and the standard rate is small so it is possible these timing adjustments are superfluous + +Due to the nature of the SoftwareSerial interrupt driven design only one serial port can be active at any time Therefore at precise junctions in the control structure each port is activated with a listen statement + +Half Duplex This section is unconfirmed and based on the best knowledge of the designer + +SoftwareSerialWithHalfDuplex is used because the communication line on the Honda Diagnostic Link Connector is half duplex that is only one member the client HonOBDapt or the server on board computer ECU can transmit data at one time SoftwareSerialWithHalfDuplex supports this configuration by specifying the same pin for Transmit and Receive It is the responibillty of the HondaCommCoordinator to enforce this constraint as the behaviour of SoftwareSerialWithHalfDuplex if an attempt is made to transmit and receive at the same time is unknown + +The OBD II ISOPort is also half duplex but is connected to the MC33660 which has a full duplex style of connection with both Receive and Transmit pin connections This provides a physical electrical way of enforcing half duplex on the OBD II KLine as a communications participant attempting to bring the line low or high while the other participant is still transmitting will simply be ignored by the circuitry in the MC33660 + + +MC33660 + + +MC33660 is a level conversion integrated circuit that converts 5 volt logic signals to 12 volt logic signals This is necessary because the main hardware component the Arduino uses 5 volt signals on its digital IO pins and OBD II specifies 12 volt signals MC33660 is an integrated circuit specifically designed for logic level conversion in an OBD II automotive application and should therefore be particularly suited to this application in terms of susceptibility to noise overload protection etc MC33660 is designed to be connected to the KLine bus and therefore provides an appropriate electrical interface for serial communications and busstyle level transitions + + +Arduino + +Arduino provides 5 volt logic level digital IO pins that are suited to this application The application of a software library that allows serial communications on any pin provides significant flexibility Arduino has flexible power supply requirements and can be operated on a 12 volt system Nominal current draw through the onboard voltage regulator in this application is 200mA Heat created by the voltage regulator dropping 12 volts to 5 volts to power the on board processor is dissipated by a small onboard heatsink so the current limits and supply voltage combination must be carefully selected The current configuration is within limits to the best knowledge of the designer and has been anecdotally confirmed by feeling for excess heat from the voltage regulator + + + +OBD II + +The OBD II electrical and logical communications standard is actually a conglomeration of many existing standards at the time of creation of the OBD II standard by ISO This adapter supports the KLine standards of ISO9141 ISO14230slow and ISO14230fast Only one is technically required as any OBD II compliant scanner must be able to work with all three but the implementations vary only minimally and provide a good exercise and example of certain software design techniques + + +TODO + +Asynchronous Multitasking + +There should be an ITask interface to constrain and define the exact nature of the controllers that have the Work DoneWorking and Reset functions + +Handler class family construction + +The sensor data virtual function prototypes in GenericHandler should be split into a separate interface definition then implemented virtually by GenericHandler and concretely by more derived classes like HondaHandler + +The ISOMeasurementToISOReplyXXXX family of functions should be extracted out of GenericHandler and put in a separate mixin + +The IGeneralAsyncHander should be expanded and more clearly defined to include the GeneralAsyncRequest function defined in an adhoc manner in HondaHandler + +Other + +The HondaCommCoordinator should implement an IWorkQueue interface clarifying the role of the Assignwork function + +The magic numbers of the digital IO pins used for serial communications in SoftwareSerial should be extracted out into a #define + + Adapter At a macro level the entire hardware software system is an Adapter converting and translating the requests and data from one system into a format compatible with another system </pre> </div>Andrew smithFri, 21 Jun 2013 14:13:56 -0000https://sourceforge.netaa3396f1d81008d902f6c0cbdcd91bcebec85c22