| blob | f003fc75481b677e3250fc5d4119a78aef82ef64 |
1 /* A formal definition of how the data objects are structured and how to interpret them */
2 { "$schema":{"$ref":"http://www.diyefi.org/InterfaceStructureDescriptions.JSONSchema"},
3 /* The four part interface versioning scheme */
4 "InterfaceVersionUniqueIdentifier": "IFreeEMS Vanilla",
5 "InterfaceVersionUniqueMajor": 0,
6 "InterfaceVersionUniqueMinor": 0,
7 "InterfaceVersionUniqueRevision": 1,
8 /* For megasquirt use the numeric version is not relevant. */
9 "Primitives": [
10 {"Key": "Character", "Length": 1, "LabelCount": 1, "Name": "Character"},
11 {"Key": "BitFieldByte", "Length": 1, "LabelCount": 8, "Name": "Boolean Array[8]"},
12 {"Key": "BitFieldWord", "Length": 2, "LabelCount": 16, "Name": "Boolean Array[16]"},
13 {"Key": "BitFieldLong", "Length": 4, "LabelCount": 32, "Name": "Boolean Array[32]"},
14 {"Key": "SignedByte", "Length": 1, "LabelCount": 1, "Name": "Integer Signed Char"},
15 {"Key": "SignedWord", "Length": 2, "LabelCount": 1, "Name": "Integer Signed Short"},
16 {"Key": "SignedLong", "Length": 4, "LabelCount": 1, "Name": "Integer Signed Long"},
17 {"Key": "UnsignedByte", "Length": 1, "LabelCount": 1, "Name": "Integer Unsigned Char"},
18 {"Key": "UnsignedWord", "Length": 2, "LabelCount": 1, "Name": "Integer Unsigned Short"},
19 {"Key": "UnsignedLong", "Length": 4, "LabelCount": 1, "Name": "Integer Unsigned Long"}
20 ],
21 /* &&&&&&&&&&&&&& Transformation of the raw data stream. &&&&&&&&&&&&&& */
22 /* */
23 /* Character is just that, an unsigned byte interpreted as per the ISO */
24 /* standard character encoding for the latin character set, ISO-8859-1. */
25 /* */
26 /* Bitfields are normal unsigned integers interpreted as a series of */
27 /* bits representing one boolean flag each. As per the C standard zero */
28 /* is considered 'false' and 1 considered 'true'. */
29 /* */
30 /* Integer types are either signed or unsigned, where the signed */
31 /* representation is the standard two's complement format. */
32 /* */
33 /* The data transmitted by FreeEMS is sent in as a structured binary */
34 /* stream in the form of sequential raw values. While some of these can */
35 /* be read directly at face value simply by interpretting them as their */
36 /* basic data type, most require transformation before they can be used */
37 /* to understand the state of engine and other operating parameters. */
38 /* */
39 /* The first stage is to interpret a piece of the binary stream as a */
40 /* raw value. There are two examples are given below, one signed and */
41 /* the other unsigned. */
42 /* */
43 /* If the data type is SignedByte and a single byte is received, 0xAC */
44 /* it must be converted from two's complement : */
45 /* */
46 /* 0xAC - 1 = 0xAB */
47 /* 0xAB ^ 0xFF = 0x54 */
48 /* 0x54 * -1 = -84 */
49 /* */
50 /* If the data type is UnsignedWord and two bytes are received, 0x76 */
51 /* first and 0x3F second giving us 0x01CE then : */
52 /* */
53 /* 0x763F = 30271 */
54 /* */
55 /* Now suppose this is supposed to be a Lambda value, clearly it isn't */ */
56 /* correct as it stands. */
57 /* */
58 /* A human readable value can be calculated using the offset and ratio */
59 /* in the following way : */
60 /* */
61 /* ratio = between the raw value after offset is applied human value */
62 /* offset = between the value sent and one that is scalable */
63 /* raw value = numeric value of the data interpretted as its basic type */
64 /* human value = a meaningful figure representing the quantity involved */
65 /* */
66 /* [human value] = ( [raw value] + [offset] ) * [ratio] */
67 /* */
68 /* Using our previous example we can assume it was a temperature with */
69 /* the following attributes : */
70 /* */
71 /* unit = °C */
72 /* ratio = 0.01 */
73 /* offset = -27315 */
74 /* raw value = 30271 */
75 /* */
76 /* human value = (30271 - 27315) * 0.01 */
77 /* human value = 2956 * 0.01 */
78 /* human value = 29.56 */
79 /* */
80 /* temperature = 29.56 °C */
81 /* */
82 /* Twenty nine and a half degrees celcius is fairly typical for a turbo */
83 /* application assuming a reasonable ambient air temperature and fairly */
84 /* efficient intercooler setup. */
85 "Structures": [
86 {
87 "Key": "MainTable",
88 "Name": "Main Table",
89 "Description": "Large variable size, three dimensional table (typically RPM, Load, VE/Lambda/Timing/etc).",
90 "SizeInBytes": 1024,
91 "Components": [
92 {
93 "Name": "RPM Axis Length",
94 "Description": "How many RPM axis cells this table has.",
95 "Primitive": "UnsignedShort",
96 "Unit": "Cells",
97 "Count": 1
98 },
99 {
100 "Name": "Load Axis Length",
101 "Description": "How many Load axis cells this table has.",
102 "Primitive": "UnsignedShort",
103 "Unit": "Cells",
104 "Count": 1
105 },
106 {
107 "Name": "RPM Axis",
108 "Description": "The RPM axis values.",
109 "Primitive": "UnsignedShort",
110 "TransformDivisor": 2, /* 0 - 32767.5, 0.5 */
111 "Count": 27
112 "Unit": "RPM",
113 },
114 {
115 "Name": "Load Axis",
116 "Description": "The Load axis values.",
117 "Primitive": "UnsignedShort",
118 "TransformDivisor": 100, /* 0 - 655.35, 0.01 */
119 "Count": 21
120 "Unit": "%",
121 },
122 {
123 "Name": "VE Table",
124 "Description": "The Volumetric Efficiency table values.",
125 "Primitive": "UnsignedShort",
126 "TransformDivisor": 500, /* 0 - 131.07, 0.002 */
127 "Count": 462,
128 "Unit": "%",
129 }
130 ]
131 },
132 {
133 "Key": "LambdaTable",
134 "Name": "Lambda Table",
135 "Description": "Large variable size, three dimensional table (RPM, Load, Lambda).",
136 "SizeInBytes": 1024,
137 "Components": [
138 {
139 "Name": "RPM Axis Length",
140 "Description": "How many RPM axis cells this table has.",
141 "Primitive": "UnsignedShort",
142 "Unit": "Cells",
143 "Count": 1
144 },
145 {
146 "Name": "Load Axis Length",
147 "Description": "How many Load axis cells this table has.",
148 "Primitive": "UnsignedShort",
149 "Unit": "Cells",
150 "Count": 1
151 },
152 {
153 "Name": "RPM Axis",
154 "Description": "The RPM axis values.",
155 "Primitive": "UnsignedShort",
156 "TransformDivisor": 2, /* 0 - 32767.5, 0.5 */
157 "Count": 27
158 "Unit": "RPM",
159 },
160 {
161 "Name": "Load Axis",
162 "Description": "The Load axis values.",
163 "Primitive": "UnsignedShort",
164 "TransformDivisor": 100, /* 0 - 655.35, 0.01 */
165 "Count": 21
166 "Unit": "%",
167 },
168 {
169 "Name": "Lambda Table",
170 "Description": "The Lambda table values.",
171 "Primitive": "UnsignedShort",
172 "TransformDivisor": 32768, /* 0 - 2.0, 0.00003 */
173 "Count": 462,
174 "Unit": "%",
175 }
176 ]
177 }
178 ]
179 }