uCANca

h1. Specification Spreadsheets

{{>toc}}

warning. Nomenclature and scope of this text is not aligned with current status of specification spreadsheets, but the information is valuable for later adaptation

The Hardware/Software interfaces file is used to describe the interaction of the software algorithms with the rest of the system/environment.  The easiest way to understand all the features included in this document is approaching its description by the historical introduction of each of the features included in it.

h2. HwSw_Interfaces document evolution

Hystorically, the interaction between the software and the rest of the world is done through hardware (communication stack, sensors & actuators, electric lines...).  This is the main reason why the document's name is HwSw_Interfaces.

Another reason is that the main expert domain for this document is the hardware engineer.

h3. MCU pinout list

Initially, the HwSw_Interfaces file has been a list of microcontroller pins with associated function names and some remarks like the [[active logic]].

h3. Transfer functions

As some of the magnitudes associated to some pins have a transfer function (directly related with the sensor used for  this acquisition + the adaptation hardware), the hardware engineer used to include these transfer functions as annexes of the document, for software engineer reference.  Some of the simplest transfer functions (like linear ones) were not annexes, but spreadsheet formulas that acted like a calculator tool for the engineers.

As we will see later, these annexes looks like a readable version of the [[conversion|conversion rules]].

h3. Calibration

System specifications usually describe calibrable values to be used as thresholds to activate/deactivate a behaviour on the system.  These values are often related to a physical magnitude (see [[Flow]]).  And this physical magnitude is often read from the outside of the software world through one of the pins in the [[MCU]] pinout.

So, the way to obtain the [[raw value]] from the [[physical value]] of these calibrable values is to follow the same transfer function that the engineer used to describe the behaviour of this pin.  This will allow software magnitude to be calibrated directly in the same representation the magnitude is acquired [[raw value]], and avoid overheading calculations with floating points in order to be able to compare the value on the port with the calibration value.

As the HwSw_Interfaces already has a way to specify the [[conversion|conversion rules]], it is a good place to specify the [[calibration|calibrable values]].  Calibrations behave exactly as constants that use the same representation than [[flow|flows]] that are being acquired/synthesized through a microcontroller pin.  And we can not forget that for diagnosticating the system, the hardware engineer is the key domain expert of the team, so let's move the microphone to him in order to be able to understand and supervise the calibration specifications in an adequate language (stop debugging to know what is software supposed to do!!).

h3. On Board Diagnostics

With the arrival of the [[On Board Diagnostic| on-board diagnostics]] engineering requirements, electric magnitudes like battery lines or ignition lines were included in the list of diagnosticable things.  Safety redundancy support functions needed these information.  

Hardware engineers provide software with extra lines (normally ADC ports) to know the value of these magnitudes (let's think about diagnosticating the battery line on this example).  As ADC ports can not work with the values (0-24v in our example, where typical ADC is 0-5v or 0-3.3v), hardware engineer designed an adaptation circuit for this line, that is, created the battery diagnosis line. And provided a transfer function for this diagnosis line for the software engineer to correctly infer the [[physical value]] of the battery line from the battery diagnosis line.

So, apart from the previously present functional lines (or [[flows]] from the system's engineering point of view), the diagnosis lines and their transfer functions were added to the HwSw_Interfaces document.

h4. OBD Calibration

[[On Board Diagnostic]] is based in an algorithm that uses some conditions to generate some results.  These conditions are normally magnitude comparison on a calibrable value, and this calibrable value is created just for the OBD.  As the HwSw_Interfaces already has a way to specify calibrations and most OBD diagnostics are hardware based (and ... and ... ;) ), HwSw_Interfaces is a good place to specify the calibrations needed by OBDs.

Apart from the calibrations needed by the conditions, usually the OBD algorithm is tuned using specific calibrations that are needed for each OBD.  These are examples of them:

* A calibrable flag to activate/deactivate this OBD on engineering time, after-sales service, or EOL (product line strategies).

* The filtering time a fault condition is present in order to consider that the fault is actually present (known, qualification time of the OBD).

* The filtering time a fault condition is no more present in order to consider that an existing fault has actually dissapeared (recovery time).

Following the same motivation than before, the HwSw_Interfaces is including the definition of this calibration values pattern and its application to OBDs.

h2. Feature summary

HwSw_Interfaces allow the user to define:

* The input/output [[flow|flows]] of each hardware block at [[ECU]] level, including the [[MCU]]'s pinout.

** The [[flow type]]

** The [[conversion]] associated to it.

** The [[flow_direction|flow direction]] (input/output/bidir...).

* The [[conversion]] (transfer functions) available for being associated to the flows or the calibrable values.

* The calibrable values (associated or not to the flows) that the system need.

** Those for functional behaviour support.

** Those for [[On Board Diagnostic|OBD]] features support.

** Linked to applicable conversion rules.

* The [[On Board Diagnostic]]s of the system.

To support standarization/universalization, only when it is impossible or very hard to get it working, all categorized values must be selectable, in order to avoid typo errors.  This includes the ability to define dictionaries and automatic nomenclatures:

* Define prefixes, suffixes and particles for automatically naming calibration values or OBD mechanisms.

* Define flow types.

* Define [[OBD requirement]]s

* ...

{TODO} Continue describing this topic.

h2. A tour on the document

notice. A version of the document has been attached to this wiki page.  

warning. This file is only valid for educational purposes, please do not use it on a project!!!

notice. Convention

* A green area means user selectable/writable field.

* A grey area means "please don't touch!", as the value shown is automatically calculated using formulas.

h3. Tabs

Once the document is open, some tabs are found:

h4. Project tabs

** Cover: Information about the project and the document.

** Dictionary: Prefixes / Suffixes / Particles needed by the document in order to automatically generate nomenclature for flows/calibrations/etc.

h4. Pinout description tabs

** MMC: pinout description of the main microcontroller.

** Blocks: pinout description of the rest of the hardware blocks at the ECU level.

h4. OBD related tabs

** [[OBD recurrence time|Recurrence times]]: reference table for selecting [[OBD recurrence time]]s for an OBD.

** [[OBD failsafe command|Failsafe Commands]]: reference table for selecting the [[OBD failsafe command]]s that can be used to degrade the system's behaviour in case a [[OBD fault]] is present.

** [[OBD Failsafe Times]]: reference table for selecting how much time a failsafe command must be activated once the fault is present.

** [[OBD Detection moment]]s: reference table for selecting OBD's detection moment.

** [[OBD Precondition|Preconditions]]: reference table for selecting OBD's precondition.

** [[OBD Rehabilitation|Rehabilitations]]: reference table for selecting OBD's rehabilitation.

** [[OBD Requirement|Requirements]]: tab to specify the OBD's requirements (groups of faults).

** [[On Board Diagnostic|FaultsList]]: tab to specify the OBD's identification properties (name,abbrev,ID) and to check the automatically generated nomenclature (reference for software manual/automated codification).

** [[On Board Diagnostic|FaultsSpec]]: tab to specify the OBD's behaviour properties.  These properties can be selectable from the reference tables described before, or custom ones (free text).

** [[OBD failsafe command|FaultFailSafeCommands]]: In this tab you can associate each fault with the desired failsafe commands (and times) to be triggered when the fault occurs.

notice. Detection Moments, Preconditions, Failsafe Commands and Failsafe Times are  completely optional, they are present to support some OBD specification strategies.  If not applicable in acting project, software will ignore these values.

h4. Conversion related tabs

** [[Conversion]]: In this tab the conversion rules are specified.

** [[FT List]]: A table to describe the tabs that contain the transfer function for look-up table type conversion rules.  Here the user tells the document how to convert a value using a FT table present on a tab.  The name of the tabs listed here will be available as selectable for conversion rules.

** [[FT Table|XxxxFT]]: In tabs named this way, different function tables can be described, as reference for conversion rules that use look-up methods.

h4. Calibration related tabs

blabla