FreeEMS  0.2.0-SNAPSHOT-285-g028e24c
FixedConfigs.h
Go to the documentation of this file.
1 /* FreeEMS - the open source engine management system
2  *
3  * Copyright 2008-2014 Fred Cooke
4  *
5  * This file is part of the FreeEMS project.
6  *
7  * FreeEMS software is free software: you can redistribute it and/or modify
8  * it under the terms of the GNU General Public License as published by
9  * the Free Software Foundation, either version 3 of the License, or
10  * (at your option) any later version.
11  *
12  * FreeEMS software is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15  * GNU General Public License for more details.
16  *
17  * You should have received a copy of the GNU General Public License
18  * along with any FreeEMS software. If not, see http://www.gnu.org/licenses/
19  *
20  * We ask that if you make any changes to this file you email them upstream to
21  * us at admin(at)diyefi(dot)org or, even better, fork the code on github.com!
22  *
23  * Thank you for choosing FreeEMS to run your engine!
24  */
25 
26 
27 /** @file
28  *
29  * @ingroup allHeaders
30  * @ingroup globalHeaders
31  * @ingroup dataStructures
32  *
33  * @brief Struct typedefs for fixed configuration
34  *
35  * This file contains the struct data type definitions for fixed configuration items.
36  *
37  * Fixed, in this context means that it typically is not tuned in a live way
38  * and therefore should not be cached in RAM while running. Usually these are
39  * values that do not change such as cylinder volume, injector size, cylinder
40  * count and other constants related to physical aspects of the engine setup.
41  * When adding configuration values, please consider adding them here first.
42  * If a value doesn't need to be live tunable definitely put it here instead.
43  */
44 
45 
46 /* Header file multiple inclusion protection courtesy eclipse Header Template */
47 /* and http://gcc.gnu.org/onlinedocs/gcc-3.1.1/cpp/ C pre processor manual */
48 #ifndef FILE_FIXED_CONFIGS_H_SEEN
49 #define FILE_FIXED_CONFIGS_H_SEEN
50 
51 
52 /// Decoder and scheduling settings
53 typedef struct {
54  unsigned char syncConfirmationsRunning; ///< Upon losing sync while already running, how many sync points are required to consider resync achieved. This should be a relatively high number.
55  unsigned char syncConfirmationsStarting; ///< Upon losing sync while starting, before having gained sync for the first time, how many sync points are required to consider initial sync achieved. This should be a near-zero for fast starts.
56  unsigned short accelerationInputEventTimeTolerance; ///< This will be replaced: http://issues.freeems.org/view.php?id=118
57  unsigned short decelerationInputEventTimeTolerance; ///< This will be replaced: http://issues.freeems.org/view.php?id=118
58  unsigned short missingToothTolerance; ///< The future of this variable is uncertain!
60 
61 
62 #define SOURCE_NORMAL 0
63 #define SOURCE_PRESET 1
64 #define SOURCE_LINEAR 2 ///< Read from the normal ADC pin, but process linearly. For bench use, mainly.
65 
66 /**
67  * Configuration that controls how the values of variables are determined.
68  */
69 typedef struct {
70  unsigned char BRV;
71  unsigned char CHT;
72  unsigned char IAT;
73 } sensorSource;
74 
75 
76 /** @brief Preset values for inputs and other variables
77  *
78  * In some cases you may want to ignore input readings and just use some
79  * configured value for a particular sensor. These are the values used when you
80  * choose to use a fixed reading instead of the real thing.
81  */
82 typedef struct {
83  unsigned short presetIAT; ///< Preset variable value to override calculated values.
84  unsigned short presetCHT; ///< @copydoc presetIAT
85  unsigned short presetBRV; ///< @copydoc presetIAT
86 
87  unsigned short failsafeIATIgnition; ///< Value to fall back on if a sensor fault is detected
88  unsigned short failsafeIATInjection; ///< @copydoc failsafeIATIgnition
89  unsigned short failsafeCHT; ///< @copydoc failsafeIATIgnition
90  unsigned short failsafeBRV; ///< @copydoc failsafeIATIgnition
91  unsigned short failsafeMAP; ///< @copydoc failsafeIATIgnition
92  unsigned short failsafeAAP; ///< @copydoc failsafeIATIgnition
93  unsigned short failsafeTPS; ///< @copydoc failsafeIATIgnition
94 } sensorPreset;
95 
96 
97 /// Ranges for sensors with linear config
98 typedef struct {
99  signed short MAPMinimum; ///< Vacuum required to make the sensor reach 0 Volt output. Theoretical only, most do not rail.
100  unsigned short MAPRange; ///< Number of kPa between 0 Volts and 5 Volts.
101  unsigned short AAPMinimum; ///< @copydoc MAPMinimum
102  unsigned short AAPRange; ///< @copydoc MAPRange
103  unsigned short EGOMinimum; ///< Lambda that 0 Volt input corresponds to.
104  unsigned short EGORange; ///< Lambda difference between what 0V and 5V inputs correspond to.
105  unsigned short BRVMinimum; ///< Battery Voltage that 0 Volt input means. 0 Volts usually. TODO YAGNI usually? always? what/why?
106  unsigned short BRVRange; ///< TODO reword when above is fixed. Real world voltage difference between lowest and highest ADC reading (0 to 5V). FreeEMS standard is 24.5 Volts for 1k and 3k9 resistors on a 12v vehicle.
107  unsigned short TPSMinimumADC; ///< This should be zero, but often isn't, this value is what the TPS input reads with the throttle fully closed.
108  unsigned short TPSMaximumADC; ///< This should be the maximum ADC value, but often isn't. This value is what the TPS input reads with the throttle fully open.
109 } sensorRange;
110 
111 
112 /// Fuel injection settings
113 typedef struct {
114  unsigned short perCylinderVolume; ///< 500cc = 0.5l 0.5 * 32768 = pcv, so divide by 32768 go get litres.
115  unsigned short injectorFlow; ///< Injector flow of 240cc/min / 60 is 4ml/second is multiplied by 1024, so divide by 1024 for ml/second, divide by 1000 for litres/second.
116  unsigned short stoichiometricAFR; ///< 34 for hydrogen, all others less, figure is 14.7 * 1024, divide by 1024 to get AFR.
117  unsigned short densityOfFuelAtSTP; ///< 703gm/litre for Octane. 32 * fuel density = number, divide by 32 for the real figure.
118 } engineSetting;
119 
120 
121 /// Settings related to serial communications
122 typedef struct {
123  unsigned short baudDivisor; ///< The number used to set the data rate. 22 = (40MHz / (16*115.2kHz)) = 21.7013889
124 } serialSetting;
125 
126 
127 /// Settings for coarse bit bang outputs
128 typedef struct {
129  unsigned char outputActions[256]; ///< Nothing, On, Off, Toggle for each input event.
130  unsigned char* ports[4]; ///< The addresses of the port control registers.
131  unsigned char masks[4]; ///< The masks to apply to the ports above.
132  unsigned char numberConfigured; ///< How many to loop through, max of 4
134 
135 
136 /// Settings for ignition and injection output scheduling
137 typedef struct {
138  unsigned short anglesOfTDC[MAX_NUMBER_OF_OUTPUT_EVENTS]; ///< The effective TDC angle of the event in question.
139  unsigned char outputEventPinNumbers[MAX_NUMBER_OF_OUTPUT_EVENTS]; ///< Which of the 6 pins should be associated with this event
140  unsigned char schedulingConfigurationBits[MAX_NUMBER_OF_OUTPUT_EVENTS]; ///< 0 = ignition, 1 = injection
141  unsigned short decoderEngineOffset;
142  /**<
143  * Add decoderEngineOffset to code degrees to find 0/TDC for cyl/output 1
144  * or subtract from real degrees to get code degrees. Make this number
145  * larger to advance the base timing, make it smaller to retard it. IE, if
146  * you have 10btdc in your table, flat, and a timing light shows 5btdc on
147  * the engine, then increase this number by 5 degrees. More here:
148  *
149  * http://forum.diyefi.org/viewtopic.php?f=54&t=1523
150  */
151  unsigned char numberOfConfiguredOutputEvents; ///< Should match the used section of the three arrays above
152  unsigned char numberOfInjectionsPerEngineCycle; ///< How much to divide the fuel pulse width by to get the per injection fuel pulse width
154 
155 
156 /// Enable flags for each cut
157 typedef struct {
158  unsigned InjectionRPM :1; ///< @todo document this
159  unsigned IgnitionRPM :1; ///< @todo document this
160  unsigned InjOverBoost :1; ///< @todo document this
161  unsigned IgnOverBoost :1; ///< @todo document this
162  unsigned Spare0 :1;
163  unsigned Spare1 :1;
164  unsigned Spare2 :1;
165  unsigned Spare3 :1;
166  unsigned Spare4 :1;
167  unsigned Spare5 :1;
168  unsigned Spare6 :1;
169  unsigned Spare7 :1;
170  unsigned Spare8 :1;
171  unsigned Spare9 :1;
172  unsigned SpareA :1;
173  unsigned SpareB :1;
174 } cutEnabled;
175 
176 
177 /// Single cut/limiter
178 typedef struct {
179  unsigned short disableThreshold; ///< Level at which to disable outputs
180  unsigned short reenableThreshold; ///< Level at which to re-enable outputs
181 } singleCut;
182 
183 
184 /// Cuts and limiters
185 typedef struct { // Comment represents normal and recommended cut type
186  singleCut InjectionRPM; ///< Injection, enabled by default at 5k with both and 200 RPM hysteresis
187  singleCut IgnitionRPM; ///< Ignition, enabled by default at 5k with both and 220 RPM hysteresis to ensure not lean when power comes back on
188  singleCut OverBoost; ///< Ignition, enabled by default, set to rail value for sensor, with large hysteresis, requires time out to operate safely
189 
190  // Disabled by default until duties are available, then enabled and fuel duty hard coded, elec duty optional, re enabled by time out not just hysteresis
191 // singleCut InjectionFuelDuty; ///< Both, disabled by default, until duties are available
192 // singleCut InjectionElecDuty; ///< Both, disabled by default, until duties are available
193 
194  // These require other logic in addition to the generic logic:
195 // singleCut TwoStep; ///< Ignition only or both, disabled by default
196 // singleCut OverHeat; ///< Ignition only or both, disabled by default
197 // singleCut Overrun; ///< Injection, disabled by default
198 // singleCut FloodClear; ///< Injection, disabled by default
199  cutEnabled cutsEnabled; ///< Override hard code on for desired fuel duty not to exceed 102.4% or similar
201 
202 
203 typedef struct {
204  unsigned short* variable;
205  unsigned short upperValue;
206  unsigned short lowerValue;
207  unsigned char* port;
208  unsigned char mask;
209  unsigned char flags; // for go high or low on success.
211 
212 
213 #define NUMBER_OF_OUTPUT_CONFIGS 8
214 typedef struct {
216  unsigned char numberConfigured;
217  unsigned char spare;
219 
220 
221 /// Settings related to sensor reading
222 typedef struct {
223  unsigned short readingTimeout; ///< How often an ADC reading MUST occur.
224  unsigned char numberOfADCsToRead;
225  unsigned char fuelPumpPrimePeriod;
226 } sensorSetting;
227 
228 
229 #define LOAD_MAP 0
230 #define LOAD_TPS 1
231 #define LOAD_MAF 2
232 #define LOAD_AAP 3
233 
234 #define ALGO_SPEED_DENSITY 0
235 #define ALGO_ALPHA_N 1
236 #define ALGO_MAF 2
237 #define ALGO_SD_AN_BLEND 3
238 
239 #define DWELL_BRV 0
240 #define DWELL_RPM 1
241 #define DWELL_FIXED 2
242 
243 /// Settings for fueling algorithms
244 typedef struct {
245  unsigned char loadType;
246  unsigned char algorithmType;
247  unsigned char dwellType;
248  unsigned char padding;
249  unsigned short dwellFixedPeriod;
251 
252 
253 /// Input output pin usage configuration @todo TODO document this better
254 typedef struct {
255 // unsigned char PullUpEnable; ///< Enables per-port weak (~100k) internal pullups. See section 22.3.2.11 on page 834 of MC9S12XDP512RMV2.pdf
256 // unsigned char ReducedDrive; ///< Do NOT change this! This reduces drive strength and could harm your engine. See section 22.3.2.12 on page 835 of MC9S12XDP512RMV2.pdf
257  unsigned char PWMEnable; ///< Enables the PWM functionality for each pin. Note for 16 bit you the low order bit enabled. See section 8.3.2.1 on page 368 of MC9S12XDP512RMV2.pdf
258  unsigned char PWMPolarity; ///< Inverts the duty of the output. 1 means "duty is high portion", 0 means "duty is low portion". See section 8.3.2.2 on page 370 of MC9S12XDP512RMV2.pdf
259  unsigned char PWMClock; ///< TODO abstract this away
260  unsigned char PWMClockPrescaler; ///< TODO abstract this away
261  unsigned char PWMCenterAlign; ///< See section 8.3.2.5 on page 372 of MC9S12XDP512RMV2.pdf
262  unsigned char PWMControl; ///< The high four bits concatenate the 8 bit PWM channels into 4 16 bit channels on a pair by pair basis. 4 joins (0,1), 5 joins (2,3), 6 joins (4,5), 7 joins (6,7).
263  unsigned char PWMScalerA; ///< TODO abstract this away
264  unsigned char PWMScalerB; ///< TODO abstract this away
265 
266  unsigned char PWMPeriod0; ///< TODO abstract this away
267  unsigned char PWMPeriod1; ///< TODO abstract this away
268  unsigned char PWMPeriod2; ///< TODO abstract this away
269  unsigned char PWMPeriod3; ///< TODO abstract this away
270  unsigned char PWMPeriod4; ///< TODO abstract this away
271  unsigned char PWMPeriod5; ///< TODO abstract this away
272  unsigned char PWMPeriod6; ///< TODO abstract this away
273  unsigned char PWMPeriod7; ///< TODO abstract this away
274 
275  unsigned char PWMInitialDuty0; ///< The duty cycle at power up. Usually unimportant due to being overwritten by the algorithm involved milliseconds later.
276  unsigned char PWMInitialDuty1; ///< The duty cycle at power up. Usually unimportant due to being overwritten by the algorithm involved milliseconds later.
277  unsigned char PWMInitialDuty2; ///< The duty cycle at power up. Usually unimportant due to being overwritten by the algorithm involved milliseconds later.
278  unsigned char PWMInitialDuty3; ///< The duty cycle at power up. Usually unimportant due to being overwritten by the algorithm involved milliseconds later.
279  unsigned char PWMInitialDuty4; ///< The duty cycle at power up. Usually unimportant due to being overwritten by the algorithm involved milliseconds later.
280  unsigned char PWMInitialDuty5; ///< The duty cycle at power up. Usually unimportant due to being overwritten by the algorithm involved milliseconds later.
281  unsigned char PWMInitialDuty6; ///< The duty cycle at power up. Usually unimportant due to being overwritten by the algorithm involved milliseconds later.
282  unsigned char PWMInitialDuty7; ///< The duty cycle at power up. Usually unimportant due to being overwritten by the algorithm involved milliseconds later.
283 
284  unsigned char PortInitialValueA; ///< The state of the port at power up. @see PortDirectionA
285  unsigned char PortInitialValueB; ///< The state of the port at power up. @see PortDirectionB
286  unsigned char PortInitialValueC; ///< The state of the port at power up. @see PortDirectionC
287  unsigned char PortInitialValueD; ///< The state of the port at power up. @see PortDirectionD
288  unsigned char PortInitialValueE; ///< The state of the port at power up. @see PortDirectionE
289  unsigned char PortInitialValueH; ///< The state of the port at power up. @see PortDirectionH
290  unsigned char PortInitialValueJ; ///< The state of the port at power up. @see PortDirectionJ
291  unsigned char PortInitialValueK; ///< The state of the port at power up. @see PortDirectionK
292  unsigned char PortInitialValueM; ///< The state of the port at power up. @see PortDirectionM
293  unsigned char PortInitialValueP; ///< The state of the port at power up. @see PortDirectionP
294  unsigned char PortInitialValueS; ///< The state of the port at power up. @see PortDirectionS
295  unsigned char PortInitialValueT; ///< The state of the port at power up. @see PortDirectionT Currently this setting is ignored. TODO Make it take effect on unused port T pins.
296 
297  unsigned char PortDirectionA; ///< @see PortDirectionB Pin 6 is the Firmware Load switch input AND the Check Engine Light output. Pin 7 is the standard fuel pump relay drive pin. These bits are therefore overridden and have no effect.
298  unsigned char PortDirectionB; ///< Whether pins act as inputs or outputs, 1 means output, 0 means input. 0 is the default for most pins. Note, peripheral modules which use these pins override this control.
299  unsigned char PortDirectionC; ///< @see PortDirectionB
300  unsigned char PortDirectionD; ///< @see PortDirectionB
301  unsigned char PortDirectionE; ///< @see PortDirectionB This port is associated with various control bits. Extreme care should be taken when using them, regardless of what for. Pins 0 and 1 are always inputs regardless of this setting.
302  unsigned char PortDirectionH; ///< @see PortDirectionB This port is associated with the SPI1 (0-3), SPI2 (4-7), SCI4 (4,5), and SCI5 (6,7) modules.
303  unsigned char PortDirectionJ; ///< @see PortDirectionB This port is associated with the SCI2 (0,1), I2C0 (6,7), I2C1 (4,5), and CAN4 (6,7) modules.
304  unsigned char PortDirectionK; ///< @see PortDirectionB
305  unsigned char PortDirectionM; ///< @see PortDirectionB This port is associated with the CAN0 (0,1), CAN1 (2,3), CAN2 (4,5), CAN3 (6,7), and SCI3 (6,7) modules.
306  unsigned char PortDirectionP; ///< @see PortDirectionB This port is associated with the PWM (0-7) module.
307  unsigned char PortDirectionS; ///< @see PortDirectionB This port is associated with the SCI0 (0,1), SCI1 (2,3), and SPI0 (4-7) modules. Primary communication is over SCI0, therefore the control bits for those pins are overridden to ensure correct operation, and have no effect.
308  unsigned char PortDirectionT; ///< @see PortDirectionB This port is associated with the ECT (0-7) module. Currently this setting is ignored. TODO Make it take effect on unused port T pins.
310 
311 
312 #define userTextFieldArrayLength1 (flashSectorSize - (sizeof(engineSetting) + sizeof(serialSetting) + sizeof(coarseBitBangSetting) + sizeof(schedulingSetting) + sizeof(cutAndLimiterSetting) + sizeof(simpleGPIOSetting)))
313 /**
314  * One of two structs of fixed configuration data such as physical parameters etc.
315  *
316  * If you add something here, please ensure you update all of the following :
317  * - Default values in the initial definitions in FixedConfig1.c and FixedConfig2.c
318  * - The lookupBlockDetails() function in blockDetailsLookup.c
319  * - The JSON data map and other related firmware interface definition files
320  */
321 typedef struct {
322  engineSetting engineSettings; ///< @see engineSetting
323  serialSetting serialSettings; ///< @see serialSetting
324  coarseBitBangSetting coarseBitBangSettings; ///< @see coarseBitBangSetting
325  schedulingSetting schedulingSettings; ///< @see schedulingSetting
326  cutAndLimiterSetting cutAndLimiterSettings; ///< @see cutAndLimiterSetting
327  simpleGPIOSetting simpleGPIOSettings; ///< @see simpleGPIOSetting
328  unsigned char userTextField[userTextFieldArrayLength1]; ///< For on-board meta-data such as which vehicle the unit is from, put your personal tuning notes here!
329 } fixedConfig1;
330 
331 
332 #define userTextFieldArrayLength2 (flashSectorSize - (sizeof(sensorSource) + sizeof(sensorPreset) + sizeof(sensorRange) + sizeof(sensorSetting) + sizeof(algorithmSetting) + sizeof(inputOutputSetting) + sizeof(decoderSetting)))
333 /** @copydoc fixedConfig1 */
334 typedef struct {
335  sensorSource sensorSources; ///< @see sensorSource
336  sensorPreset sensorPresets; ///< @see sensorPreset
337  sensorRange sensorRanges; ///< @see sensorRange
338  sensorSetting sensorSettings; ///< @see sensorSetting
339  algorithmSetting algorithmSettings; ///< @see algorithmSetting
340  inputOutputSetting inputOutputSettings; ///< @see inputOutputSetting
341  decoderSetting decoderSettings; ///< @see decoderSetting
342  unsigned char userTextField2[userTextFieldArrayLength2]; ///< For on-board meta-data such as which vehicle the unit is from, put your personal tuning notes here!
343 } fixedConfig2;
344 
345 
346 #else
347  /* let us know if we are being untidy with headers */
348  #warning "Header file FIXED_CONFIGS_H seen before, sort it out!"
349 /* end of the wrapper ifdef from the very top */
350 #endif