# Defining pages for _Deep OBD for BMW and VAG_
*This document is based on the original ediabaslib/DeepOBD documentation, with added comments and information I*
*found out when creating some extended Deep OBD pages with user defined code.*
*Original can be found here: https://github.com/uholeschak/ediabaslib/blob/master/docs/Page_specification.md*
Each page (tab) is defined in a single XML (`*.ccpage`) file. A general documentation of all XML tags could be found in the `BmwDeepObd.xsd` file. The documentation will be displayed in the XML editor when the `.xsd` is added as `xs:shema` in the XML file.
Table of contents:
* [Simple jobs](#simple-jobs)
* [Reading errors](#reading-errors)
* [User defined code](#user-defined-code)
* [Formatting results (FormatResult)](#formatting-results-formatresult)
* [Formatting error results (FormatErrorResult)](#formatting-error-results-formaterrorresult)
* [Processing results (ProcessResults)](#processing-results-processresults)
* [Control output of the page (UpdateResultList)](#control-output-of-the-page-updateresultlist)
* [Executing own jobs (ExecuteJob)](#executing-own-jobs-executejob)
* [Adding controls to the layout](#adding-controls-to-the-layout)
* [Grouping pages](#grouping-pages)
* [The configuration file](#the-configuration-file)
* [Broadcasts](#broadcasts)
* [Special jobs](#special-jobs)
## Simple jobs
If only some EDIABAS jobs with fixed arguments are required for one display page, the XML code is relative simple. Below is the example code to display climate data for a E61 vehicle:
``` xml
Climate
Indoor temperature [°C](°C):
Indoor temperature delayed [°C](°C):
Outdoor temperature [°C](°C):
Setpoint [°C](°C):
Heat exchanger temperature [°C](°C):
Heat exchanger setpoint [°C](°C):
Heat exchanger actuator [%](%):
Main actuator [%](%):
Evaporator temperature [°C](°C):
Pressure sensor [bar](bar):
Circulating air left [%](%):
Circulating air right [%](%):
Defrost [%](%):
Ventilation [%](%):
Cold air [%](%):
Leg room [%](%):
Refrigerating compressor [%](%):
Klima
Innentemperatur [°C](°C):
Innentemperatur verzögert [°C](°C):
Außentemperatur [°C](°C):
Sollwert [°C](°C):
Wärmetauschertemperatur [°C](°C):
Wärmetauschersollwert [°C](°C):
Wärmetauscherstellgröße [%](%):
Hauptstellgröße [%](%):
Verdampfertemperatur [°C](°C):
Drucksensor [bar](bar):
Umluft links [%](%):
Umluft rechts [%](%):
Abtauen [%](%):
Belüftung [%](%):
Kaltluft [%](%):
Fußraum [%](%):
Kältemittelverdichter [%](%):
```
The `page name` property specifies the title of the page and is a reference to the `strings` nodes.
With the attribute `display-mode` the type of the display could be specified (`list`: normal text list, `grid`: grid wiew for graphical gauge display).
The attribute `fontsize` allows to specify the font size of the display data in three steps (`small`, `medium` and `large`).
The attributes `gauges-portrait` and `gauges-landscape` specify the number of gauges per line in the corresponding display mode.
With `logfile` a log file name could be specified, that allows to log the display data. If the symbol `{D}` is used inside the log file name, it will be replaced by the current date and time.
Setting the `no_update` property prevents the configuration generator to update the file. This is helpful if changes have been made to an auto generated configuration.
The `strings` nodes contains the all the string used on this display page. If the current language is not matching the `lang` tag, the default language (without tag) is used. The `lang` property could be either the short form e.g. `'de'` or the long one `'de-DE'`.
The `jobs` node groups all EDIABAS jobs to execute. The property `sgbd` specifies the name of the group (`.grp`) or the sgbd (`.prg`) file to use. In VAG mode the property `mwtab` could be used to store the file name of the associated mwtab file.
Within the `jobs` node multiple `job` nodes specify the EDIABAS jobs to execute. They contain the following properties:
* `name`: Name of the job to execute
* `id`: Id for job result identification. If this element is specified the result name will be: `[id]#[data set index]#[result]`, otherwise it's: `[name]#[result]`.
* `sgbd`: Name of the SGBD file to load. This overrides the SGBD file from the `jobs` node. It's recommended to combine this with the id attribute.
* `fixed_func_struct_id`: Fixed function structure id from the BMW database. This entry is only used by the configuration generator.
* `args_first`: Allows to specify semicolon separated job arguments for the first job call.
* `args`: Allows to specify semicolon separated job arguments. If this is the first call and `args_first` is present `args_first` will be used instead.
* `result`: Allows to specify the required results. If omitted, all results will be generated, which may require more processing time.
* `display-order`: Allows to specify the index of the display order. If omitted the default value is 0. If two values are identical, the original order is retained.
* `grid-type`: If the `display-mode` ist switched to `grid`, the type of display element could be specified here:
* `hidden`: Nothing will be displayed.
* `text`: Text only, no gauge will be displayed.
* `simple-gauge-square`: A simple gauge with a square border will be displayed.
* `simple-gauge-round`: A simple gauge with a round border will be displayed.
* `simple-gauge-dot`: A simple gauge with a round border and a dot instead of a bar graph will be displayed.
* `min-value`: For gauge views the minimum value is specified with this attribute.
* `max-value`: For gauge views the maximim value is specified with this attribute.
* `log_tag=`: Adding this property allows to log the display data to a log file when activating the _Log data_ menu in the application. The `logfile` property in the `page` node has to be specified as well to activate logging.
* Each `display` node specifies one line of the display output. `Name` is again a reference to the text translation in the _strings_ nodes. With `result` the EDIABAS job result name is selected, that contains the data. The `format` property allows to format the result with the EDIABAS aspiResultText format specification [EDIABAS result types and formats](EDIABAS_result_types_and_formats.md).
The `page` node can optionally contain `display` nodes like the `job` node. They will be only used for [User defined code](#user-defined-code).
This is how the resulting page will look like:
![Climate page](Page_specification_AppClimateSmall.png)
## Reading errors
With the `read_errors` node it's possible to read an error summary of all ECUs. Simply list all ECU names and the corresponding sgbd file names in a separate `ecu` node, like in the example below.
The `errors` node supports a property `sgbd_functional`, this specifies the SGBD for functional (gobal) error reset. If this property is specified, a button _Global Error Reset_ button will appear.
Setting the `no_update` property prevents the configuration generator to update the file. This is helpful if changes have been made to an auto generated configuration.
The error message is generated by the sgbd file and is in the language of the sgbd.
The page also allows to selectively reset ECU errors.
``` xml
Errors
ACSM Crash security module
CAS Car access system
CCC-BO Front panel
CCC-GW Gateway
DDE Diesel elektronic
DSC Dynamic stability control
EKPS Fuel pump control
IHK Integrated heating climate automatic
KBM Chassis basic module
KGM Chassis gateway module
KOMBI Combination instrument
PDC Park distance control
RLS Rain main beam sensor
EPS Electric power steering
ULF Universal hands-free system
FZD Roof switch unit
Fehler
ACSM Crash-Sicherheits-Modul
CAS Car Access System
CCC-BO Bedienoberfläche
CCC-GW Gateway
DDE Diesel Elektronik
DSC Dynamische Stabilitätskontrolle
EKPS Kraftstoffpumpensteuerung
IHK Integrierte Heiz-Klima-Automatik
KBM Karosserie-Basismodul
KGM Karosserie-Gateway-Modul
KOMBI Instrumentenkombination
PDC Park-Distance-Control
RLS Regen-Fahrlicht-Sensor
EPS Elektromechanische Servolenkung
ULF Universale Ladefreisprechelektronik
FZD Funtionszentrum Dach
```
In the `ecu` node the property `name` is a link to a `string` node and `sgbd` is the name of the sgbd file. The output looks similar to this page:
![Erros E90](Page_specification_AppReadAllErrorsSmall.png)
# User defined code
If the jobs and display output is getting more complex, user defined code will be required.
In this case a C# class could be added to a `code` node, which defines a set of optional callback functions. If the `show_warnings` property is set to true, also warnings will be reported during compilation of the code.
``` xml
resultDict, bool firstCall)
{
}
public void ExecuteJob(EdiabasNet ediabas, ref MultiMap resultDict, bool firstCall)
{
}
public string FormatResult(JobReader.PageInfo pageInfo, Dictionary resultDict, string resultName)
{
}
public string FormatResult(JobReader.PageInfo pageInfo, Dictionary resultDict, string resultName, ref Android.Graphics.Color? textColor)
{
}
public string FormatResult(JobReader.PageInfo pageInfo, MultiMap resultDict, string resultName, ref Android.Graphics.Color? textColor)
{
}
public string FormatResult(JobReader.PageInfo pageInfo, MultiMap resultDict, string resultName, ref Android.Graphics.Color? textColor, ref double? dataValue)
{
}
public string FormatErrorResult(JobReader.PageInfo pageInfo, EdiabasThread.EdiabasErrorReport errorReport, string defaultMessage)
{
}
public void ProcessResults(Context context, JobReader.PageInfo pageInfo, MultiMap resultDict)
{
}
public void UpdateResultList(JobReader.PageInfo pageInfo, Dictionary resultDict, List resultList)
{
}
public void UpdateResultList(JobReader.PageInfo pageInfo, MultiMap resultDict, List resultList)
{
}
}
]]>
```
## Formatting results (FormatResult)
For special formatting of the result data, the callback `FormatResult` could be used. For each result of the EDIABAS results this function will be called with `resultName` set to the current result name. If the `display` node is a subnode of a `job` node the job name is prefixed with # as separator to the result name. If the `job` node contains an `id` attribute, the job name is `#`. The function will be only called if there is **no** `format` property in the `display` node.
[FK] if the data is acquired using ExecuteJob, ```resultName``` normally does not contain a prefix but just the result name itself.
The `textColor` output could be also used for the gauge color.
Especially for gauges there is the possibility to return custom values in `dataValue`, if scaling is required or the result has to be converted in a double value first.
[FK] I experienced that scaling/calculation does only change the value, but not the input for the gauge itself - it still uses the unmodified original value. See second example below for details.
Here is an example from the motor page:
``` cs
public string FormatResult(JobReader.PageInfo pageInfo, MultiMap resultDict, string resultName, ref Android.Graphics.Color? textColor, ref double? dataValue)
{
string result = string.Empty;
double value;
bool found;
switch (resultName)
{
case "STATUS_MESSWERTBLOCK_LESEN#STAT_UBATT_WERT":
value = ActivityMain.GetResultDouble(resultDict, resultName, 0, out found);
result = string.Format(ActivityMain.Culture, "{0,7:0.00}", value);
if (found && value < 11.0)
{
textColor = Android.Graphics.Color.Red;
}
if (!found) result = string.Empty;
break;
case "STATUS_MESSWERTBLOCK_LESEN#STAT_STRECKE_SEIT_ERFOLGREICHER_REGENERATION_WERT":
result = string.Format(ActivityMain.Culture, "{0,6:0.0}", ActivityMain.GetResultDouble(resultDict, resultName, 0, out found) / 1000.0);
if (!found) result = string.Empty;
break;
case "STATUS_MESSWERTBLOCK_LESEN#STAT_OELDRUCKSCHALTER_EIN_WERT":
result = ((ActivityMain.GetResultDouble (resultDict, resultName, 0, out found) > 0.5) && found) ? "1" : "0";
if (found && result == "1")
{
textColor = Android.Graphics.Color.Red;
}
if (!found) result = string.Empty;
break;
case "STATUS_MESSWERTBLOCK_LESEN#STAT_REGENERATIONSANFORDERUNG_WERT":
result = ((ActivityMain.GetResultDouble (resultDict, resultName, 0, out found) < 0.5) && found) ? "1" : "0";
if (!found) result = string.Empty;
break;
case "STATUS_MESSWERTBLOCK_LESEN#STAT_EGT_st_WERT":
result = ((ActivityMain.GetResultDouble (resultDict, resultName, 0, out found) > 1.5) && found) ? "1" : "0";
if (!found) result = string.Empty;
break;
case "STATUS_MESSWERTBLOCK_LESEN#STAT_REGENERATION_BLOCKIERUNG_UND_FREIGABE_WERT":
result = ((ActivityMain.GetResultDouble (resultDict, resultName, 0, out found) < 0.5) && found) ? "1" : "0";
if (!found) result = string.Empty;
break;
}
return result;
}
```
#### Colorized gauges/values depending on the value
```cs
public string FormatResult(JobReader.PageInfo pageInfo, MultiMap resultDict, string resultName, ref Android.Graphics.Color? textColor)
{
string result = string.Empty;
double value;
bool found;
switch (resultName)
{
// engine speed gauge
case "STATUS_MESSWERTBLOCK_LESEN#STAT_MOTORDREHZAHL_WERT":
value = ActivityMain.GetResultDouble(resultDict, resultName, 0, out found);
// result format: {0,[DIGITS TOTAL INCL COMMA],[0|0.0|0.00|0.000...]}
result = string.Format(ActivityMain.Culture, "{0,4:0}", value);
// list of possible color names can be found here:
// https://docs.microsoft.com/en-us/dotnet/api/android.graphics.color?view=xamarin-android-sdk-9
if (found && value <= 4000) textColor = Android.Graphics.Color.White;
else if (found && value <= 4250) textColor = Android.Graphics.Color.Yellow;
else if (found && value <= 4500) textColor = Android.Graphics.Color.Orange;
else if (found && value > 4500) textColor = Android.Graphics.Color.Red;
else textColor = Android.Graphics.Color.Gray;
break;
// battery voltage gauge
case "STATUS_MESSWERTBLOCK_LESEN#STAT_UBATT_WERT":
value = ActivityMain.GetResultDouble(resultDict, resultName, 0, out found);
// result format: {0,[DIGITS TOTAL INCL COMMA],[0|0.0|0.00|0.000...]}
result = string.Format(ActivityMain.Culture, "{0,4:0.0}", value);
if (found && value < 10.5) textColor = Android.Graphics.Color.Red;
else if (found && value < 11.5) textColor = Android.Graphics.Color.Orange;
else if (found && value <= 12.5) textColor = Android.Graphics.Color.Yellow;
else if (found && value <= 13.2) textColor = Android.Graphics.Color.Gray;
else if (found && value <= 14.5) textColor = Android.Graphics.Color.White;
else if (found && value > 14.5) textColor = Android.Graphics.Color.Red;
else textColor = Android.Graphics.Color.Gray;
break;
// coolant temperature gauge
case "STATUS_MESSWERTBLOCK_LESEN#STAT_KUEHLMITTELTEMPERATUR_WERT":
value = ActivityMain.GetResultDouble(resultDict, resultName, 0, out found);
result = string.Format(ActivityMain.Culture, "{0,3:0}", value);
if (found && value < 75) textColor = Android.Graphics.Color.Blue;
else if (found && value <= 105) textColor = Android.Graphics.Color.White;
else if (found && value <= 110) textColor = Android.Graphics.Color.Yellow;
else if (found && value <= 115) textColor = Android.Graphics.Color.Orange;
else if (found && value > 115) textColor = Android.Graphics.Color.Red;
else textColor = Android.Graphics.Color.Gray;
break;
}
return result;
}
```
#### Calculating result values
Another example. Here we are using the DME MS43 after-cat O2 sensors inputs as analog inputs for custom sensors, namely a MAP sensor of type MPX4250AP and the analog output of a Innovate LC-2 wideband lambda controller.
Note: this is a track car with supercharger, modified exhaust and headers (under floor cat instead of original headers mounted, monitor O2 sensors stripped), so read O2 inputs are not used any more and also disabled in the ECU tune for their original purpose.
Wideband and MAP sensor are only added for monitoring/logging and display.
Values are acquired using ExecuteJob function in this example, so the ```resultName``` is not prefixed. In this case the gauge´s min/max in the display tag is 0 to 3.55 for the MAP sensor and 0 to 5 for the Wideband in order to fit display value and gauge. This is needed as the gauge itself continues to display the original value from the ECU, not the calculated one.
```cs
public string FormatResult(JobReader.PageInfo pageInfo, MultiMap resultDict, string resultName, ref Android.Graphics.Color? textColor)
{
string result = string.Empty;
double value;
bool found;
switch (resultName)
{
// conversion for MAP Sensor type MPX4250AP
case "STAT_LS_NKAT_SIGNAL_1_WERT":
value = ActivityMain.GetResultDouble(resultDict, resultName, 0, out found);
value = ((( value / 4.9 ) + 0.04 ) / 0.004) * 10;
result = string.Format(ActivityMain.Culture, "{0,4:0}", value);
if (found && value < 200) textColor = Android.Graphics.Color.Black;
else if (found && value < 1000) textColor = Android.Graphics.Color.White;
else if (found && value < 1500) textColor = Android.Graphics.Color.Orange;
else textColor = Android.Graphics.Color.Red;
break;
// conversion for Innovate LC-2 Wideband controller
case "STAT_LS_NKAT_SIGNAL_2_WERT":
value = ActivityMain.GetResultDouble(resultDict, resultName, 0, out found);
value = (1.523-0.5) / 5.0 * value + 0.5;
result = string.Format(ActivityMain.Culture, "{0,5:0.00}", value);
if (found && value < 0.85) textColor = Android.Graphics.Color.Red;
else if (found && value < 0.90) textColor = Android.Graphics.Color.Orange;
else if (found && value < 0.95) textColor = Android.Graphics.Color.Yellow;
else if (found && value <= 1.05) textColor = Android.Graphics.Color.White;
else if (found && value <= 1.10) textColor = Android.Graphics.Color.Yellow;
else if (found && value <= 1.15) textColor = Android.Graphics.Color.Orange;
else if (found && value >1.15) textColor = Android.Graphics.Color.Red;
else textColor = Android.Graphics.Color.White;
break;
}
}
```
## Formatting error results (FormatErrorResult)
For special formatting of the error result data, the callback `FormatErrorResult` could be used. For each error entry this function will be called with `defaultMessage` set to the default error message output.
Here is an example from the errors page, that adds a RPM value to the error message. You have to add a `results` property to the `ecu` node specifying the results you want to be generated by the `FS_LESEN_DETAIL` job.
``` xml
errorDetail in errorReport.ErrorDetailSet)
{
string rpmText = ActivityMain.FormatResultDouble(errorDetail, "F_UW1_WERT", "{0,6:0.0}");
if (rpmText.Length > 0)
{
if (detailText.Length == 0)
{
detailText += rpmText + " 1/min";
}
}
}
if (detailText.Length > 0)
{
message += "\r\n" + detailText;
}
break;
}
}
return message;
}
}
]]>
```
## Processing results (ProcessResults)
For general processing of the result data, the callback `ProcessResults` could be used.
In this example a notification is displayed if the battery voltage is too low.
It uses the following functions to display the notifications:
``` cs
public static bool ShowNotification(Context context, int id, int priority, string title, string message, bool update = false);
public static bool HideNotification(Context context, int id);
```
The functions arguments are:
* `context`: The current application context.
* `id`: The notification id. It should be a value in the range of 0 and 9999. The same value must be used for `ShowNotification` and `HideNotification`.
* `priority`: The notification priority in the range of -2 to 2.
* `title`: The notification title.
* `title`: The notification message.
* `update`: If the notfication is already displayed, it will be not updated by default. When this value is `true` the current notification is updated.
``` xml
Battery
Voltage too low!
Batterie
Spannung zu niedrig!
resultDict)
{
double value;
bool found;
value = ActivityMain.GetResultDouble(resultDict, "STATUS_MESSWERTBLOCK_LESEN#STAT_UBATT_WERT", 0, out found);
if (found && value < 11.5)
{
ActivityMain.ShowNotification(context, 0, 2,
ActivityMain.GetPageString(pageInfo, "notification_title_battery"),
ActivityMain.GetPageString(pageInfo, "notification_voltage_low"));
}
else
{
ActivityMain.HideNotification(context, 0);
}
}
}
]]>
```
## Control output of the page (UpdateResultList)
Sometimes you want to dynamically control the number and the content of the output lines.
If the callback `UpdateResultList` is defined, you could directly fill the contents of the `resultListAdapter` which displays the results of the page. In this example from the (standard) _Adapter_ page the adapter configuration result will be displayed. Additionally only one column for output is used by setting the second argument of `resultListAdapter.Items.Add` to null. With `ActivityMain.GetPageString` it's possible to retrieve a string from the translation table.
``` cs
public void UpdateResultList(JobReader.PageInfo pageInfo, MultiMap resultDict, List resultList)
{
int result = configResult;
if (result > 0)
{
resultList.Add(new TableResultItem(ActivityMain.GetPageString(pageInfo, "adapter_config_ok"), null));
}
else if (result == 0)
{
resultList.Add(new TableResultItem(ActivityMain.GetPageString(pageInfo, "adapter_config_error"), null));
}
}
```
## Executing own jobs (ExecuteJob)
If more than one job has to be executed or the job requires special arguments, `ediabas.ExecuteJob` could be called in the `ExecuteJob` callback. Here is an example from the adapter page for calling a list of jobs. `EdiabasThread.MergeResultDictionarys` adds the results of the current job to the internal job list. The callback `ExecuteJob` will be executed in it's own thread. When using ExecuteJob it's recommended to add the `display` nodes to the `page` node because no `job` nodes will be present.
Note: using **ExecuteJob** the page should not contain nodes in the following format:
```xml
```
but instead only one tag defining the SGBD file that is used, just before the *code* tag:
```xml
```
and as described the *display* tags directly below the *page* tag.
#### Example
``` cs
class PageClass
{
private class EdiabasJob
{
private string jobName;
private string jobArgs;
private string resultRequests;
public EdiabasJob(string jobName, string jobArgs, string resultRequests)
{
this.jobName = jobName;
this.jobArgs = jobArgs;
this.resultRequests = resultRequests;
}
public string JobName
{
get
{
return jobName;
}
}
public string JobArgs
{
get
{
return jobArgs;
}
}
public string ResultRequests
{
get
{
return resultRequests;
}
}
}
static private readonly EdiabasJob[]() jobArray =
{
new EdiabasJob("ADAPTER_CMD",
"0xFE;0xFE",
string.Empty
),
new EdiabasJob("ADAPTER_CMD",
"0x80;0x00",
string.Empty
),
new EdiabasJob("ADAPTER_CMD",
"0x81;0x00",
string.Empty
),
new EdiabasJob("ADAPTER_CMD",
"0x82;0x00",
string.Empty
),
};
public void ExecuteJob(EdiabasNet ediabas, ref MultiMap resultDict, bool firstCall)
{
int index = 0;
foreach (EdiabasJob job in jobArray)
{
ediabas.ArgString = job.JobArgs;
ediabas.ArgBinaryStd = null;
ediabas.ResultsRequests = job.ResultRequests;
ediabas.ExecuteJob(job.JobName);
List> resultSets = ediabas.ResultSets;
if (resultSets != null && resultSets.Count >= 2)
{
EdiabasThread.MergeResultDictionarys(ref resultDict, resultSets[1](1), string.Format("{0}_", index));
}
index++;
}
}
}
```
#### Example using *firstCall*
Simple **ExecuteJob** example making use of *firstCall*.
On the first run an initial job is performed - in this case it switches the DDE to *cylinder system check mode*.
After that the actual values are read on every iteration (which would not output valid data without first switching the DDE to this mode using the firstCall job):
```cs
public void ExecuteJob(EdiabasNet ediabas, ref MultiMap resultDict, bool firstCall)
{
if (firstCall) {
ediabas.ArgString = string.Empty;
ediabas.ArgBinaryStd = null;
ediabas.ResultsRequests = "JOB_STATUS";
ediabas.ExecuteJob("START_SYSTEMCHECK_ZYL");
}
else {
ediabas.ArgString = string.Empty;
ediabas.ArgBinaryStd = null;
ediabas.ResultsRequests = "STAT_LAUFUNRUHE_LLR_MENGE_ZYL1_WERT;STAT_LAUFUNRUHE_LLR_MENGE_ZYL2_WERT;STAT_LAUFUNRUHE_LLR_MENGE_ZYL3_WERT;STAT_LAUFUNRUHE_LLR_MENGE_ZYL4_WERT;STAT_LAUFUNRUHE_LLR_MENGE_ZYL5_WERT;STAT_LAUFUNRUHE_LLR_MENGE_ZYL6_WERT";
ediabas.ExecuteJob("STATUS_LAUFUNRUHE_LLR_MENGE");
List> resultSets = ediabas.ResultSets;
if (resultSets != null && resultSets.Count >= 2)
{
EdiabasThread.MergeResultDictionarys(ref resultDict, resultSets[1]);
}
}
}
```
#### Multiple Jobs on the same ECU
Another example that performs 2 different Jobs of the same SGBD.
Job 2 is less important and is only performed at every 20th iteration, in order to speed up the update rate of Job 1.
Note Job 2´s result data is stored globally and the last values are always added to the output (otherwise it would only be visible for a short time):
```cs
> resultSets_Job2;
public void ExecuteJob(EdiabasNet ediabas, ref MultiMap resultDict, bool firstCall)
{
// resultSets for Job 1
List> resultSets;
// Job 1 - performed on every iteration
ediabas.ArgString = "JA;ILMMG;IPLAD;IPUMG;IUBAT;IMOAK;INMOT;SPLAD;ITKUM;ITLAL;IPRDR;IAFZG;IVKMH";
ediabas.ArgBinaryStd = null;
ediabas.ResultsRequests = string.Empty;
ediabas.ExecuteJob("STATUS_MESSWERTBLOCK_LESEN");
resultSets = ediabas.ResultSets;
if (resultSets != null && resultSets.Count >= 2)
{
EdiabasThread.MergeResultDictionarys(ref resultDict, resultSets[1]);
}
// Job 2 - only performed on every X iteration (defined by Job2_interval)
// results are stored in a global variable so that the last values can be displayed every time
if(counter_Job2 == 0) {
ediabas.ArgString = "lla";
ediabas.ArgBinaryStd = null;
ediabas.ResultsRequests = string.Empty;
ediabas.ExecuteJob("ABGLEICH_LESEN");
resultSets_Job2 = ediabas.ResultSets;
counter_Job2++;
}
else if(counter_Job2 >= Job2_interval) {
counter_Job2 = 0;
}
else {
counter_Job2++;
}
// Job 2 - merge last results to the output result list
if (resultSets_Job2 != null && resultSets_Job2.Count >= 2)
{
// prefix the output result names of Job 2 with "LLA_" as result name of that job is not descriptive
EdiabasThread.MergeResultDictionarys(ref resultDict, resultSets_Job2[1], "LLA_");
}
}
}
]]>
```
#### Multiple Jobs on different ECUs
Even more advanced example, adding another Job to the last example which is using a different SGBD.
Note the now empty *jobs* tag as the used SGBDs are loaded programmatically here.
The Job on the 2nd SGBD is much less important in this case and therefore only updated on every 98th iteration, so that it doesn´t slow down the update rate of the main job too much. Also there is some "error handling" if the Job on SGBD 2 fails.
```cs
> resultSets_Job2;
List> resultSets_JobSgbd2;
public void ExecuteJob(EdiabasNet ediabas, ref MultiMap resultDict, bool firstCall)
{
// resultSets for Job 1 (updated every time)
List> resultSets;
// switch to SGBD number 1 (index 0) on first run or if last used SGBD was a different one
if(firstCall || currSgbd != 0) {
currSgbd = 0;
ediabas.ResolveSgbdFile(conf_sgbds[0]);
// possibly needed initialisation
//ediabas.ArgString = string.Empty;
//ediabas.ArgBinaryStd = null;
//ediabas.ResultsRequests = string.Empty;
//ediabas.ExecuteJob("INITIALISIERUNG");
}
// Job 1 - performed on every iteration
ediabas.ArgString = "JA;ILMMG;IPLAD;IPUMG;IUBAT;IMOAK;INMOT;SPLAD;ITKUM;ITLAL;IPRDR;IAFZG;IVKMH";
ediabas.ArgBinaryStd = null;
ediabas.ResultsRequests = string.Empty;
ediabas.ExecuteJob("STATUS_MESSWERTBLOCK_LESEN");
resultSets = ediabas.ResultSets;
if (resultSets != null && resultSets.Count >= 2)
{
EdiabasThread.MergeResultDictionarys(ref resultDict, resultSets[1]);
}
// Job 2 - only performed on every X iteration (defined by Job2_interval)
// results are stored in a global variable so that the last values can be displayed every time
if(counter_Job2 == 0) {
ediabas.ArgString = "lla";
ediabas.ArgBinaryStd = null;
ediabas.ResultsRequests = string.Empty;
ediabas.ExecuteJob("ABGLEICH_LESEN");
resultSets_Job2 = ediabas.ResultSets;
counter_Job2++;
}
else if(counter_Job2 >= Job2_interval) {
counter_Job2 = 0;
}
else {
counter_Job2++;
}
// Job 2 - merge last results to the output result list
if (resultSets_Job2 != null && resultSets_Job2.Count >= 2)
{
// prefix the output result names of Job 2 with "LLA_" as result name of that job is not descriptive
EdiabasThread.MergeResultDictionarys(ref resultDict, resultSets_Job2[1], "LLA_");
}
// Job on SGBD 2 - only run on every Y iteration (defined by JobSgbd2_interval)
if(counter_JobSgbd2 == 0) {
counter_JobSgbd2++;
try {
// try/catch, to prevent an error here destroys the whole results of all jobs
// - otherwise NO data will be displayed if the SGBD 2 request fails
// switch to SGBD number 2 (index 1)
currSgbd = 1;
ediabas.ResolveSgbdFile(conf_sgbds[currSgbd]);
// if needed - initialisation
//ediabas.ArgString = string.Empty;
//ediabas.ArgBinaryStd = null;
//ediabas.ResultsRequests = string.Empty;
//ediabas.ExecuteJob("INITIALISIERUNG");
ediabas.ArgString = string.Empty;
ediabas.ArgBinaryStd = null;
ediabas.ResultsRequests = string.Empty;
ediabas.ExecuteJob("STATUS_TOENS_IO");
resultSets_JobSgbd2 = ediabas.ResultSets;
}
catch {
// ok then not
}
}
else if (counter_JobSgbd2 >= JobSgbd2_interval) {
counter_JobSgbd2 = 0;
}
else {
counter_JobSgbd2++;
}
// Job SGBD 2 - merge last results to the output result list
if (resultSets_JobSgbd2 != null && resultSets_JobSgbd2.Count >= 2)
{
// in this case with NO prefix as result names are descriptive
EdiabasThread.MergeResultDictionarys(ref resultDict, resultSets_JobSgbd2[1]);
}
}
}
]]>
```
## Adding controls to the layout
The standard layout only allows to display information, but there is no way to control outputs. With the callbacks `CreateLayout`, `DestroyLayout` and `UpdateLayout` there is a possibility to add own controls to the layout (in most cases buttons).
In this example from the AdapterCustom.ccpage buttons will be added to control the CAN block size, CAN separation time and the CAN mode. The `CreateLayout` adds the controls, `DestroyLayout` removes the controls and `UpdateLayout` is used to modify the state of the controls (depending form the connection state).
For every button there is a `Click` delegate that allows to set a global variable which is used for EDIABAS job control.
``` cs
private Button buttonBlockSize;
private Button buttonSepTime0;
private Button buttonSepTime1;
private Button buttonCan500;
private Button buttonCan100;
private Button buttonCanOff;
private int adapterCmd = -1;
private int adapterValue;
private int blockSize = 0;
public void CreateLayout(ActivityMain activity, JobReader.PageInfo pageInfo, LinearLayout pageLayout)
{
LinearLayout buttonLayout = new LinearLayout(activity);
buttonLayout.Orientation = Orientation.Vertical;
LinearLayout.LayoutParams buttonLayoutParams = new LinearLayout.LayoutParams(
ViewGroup.LayoutParams.MatchParent,
ViewGroup.LayoutParams.WrapContent);
buttonLayoutParams.Weight = 1;
buttonBlockSize = new Button(activity);
buttonBlockSize.Text = string.Format("{0}: {1}", ActivityMain.GetPageString(pageInfo, "button_adapter_config_block_size"), blockSize);
buttonBlockSize.Click += delegate
{
blockSize += 2;
if (blockSize > 8)
{
blockSize = 0;
}
adapterCmd = 0x00;
adapterValue = blockSize;
buttonBlockSize.Text = string.Format("{0}: {1}", ActivityMain.GetPageString(pageInfo, "button_adapter_config_block_size"), blockSize);
};
buttonLayout.AddView(buttonBlockSize, buttonLayoutParams);
buttonSepTime0 = new Button(activity);
buttonSepTime0.Text = ActivityMain.GetPageString(pageInfo, "button_adapter_config_sep_time0");
buttonSepTime0.Click += delegate
{
adapterCmd = 0x01;
adapterValue = 0x00;
};
buttonLayout.AddView(buttonSepTime0, buttonLayoutParams);
buttonSepTime1 = new Button(activity);
buttonSepTime1.Text = ActivityMain.GetPageString(pageInfo, "button_adapter_config_sep_time1");
buttonSepTime1.Click += delegate
{
adapterCmd = 0x01;
adapterValue = 0x01;
};
buttonLayout.AddView(buttonSepTime1, buttonLayoutParams);
buttonCan500 = new Button(activity);
buttonCan500.Text = ActivityMain.GetPageString(pageInfo, "button_adapter_config_can_500");
buttonCan500.Click += delegate
{
adapterCmd = 0x02;
adapterValue = 0x01;
};
buttonLayout.AddView(buttonCan500, buttonLayoutParams);
buttonCan100 = new Button(activity);
buttonCan100.Text = ActivityMain.GetPageString(pageInfo, "button_adapter_config_can_100");
buttonCan100.Click += delegate
{
adapterCmd = 0x02;
adapterValue = 0x09;
};
buttonLayout.AddView(buttonCan100, buttonLayoutParams);
buttonCanOff = new Button(activity);
buttonCanOff.Text = ActivityMain.GetPageString(pageInfo, "button_adapter_config_can_off");
buttonCanOff.Click += delegate
{
adapterCmd = 0x02;
adapterValue = 0x00;
};
buttonLayout.AddView(buttonCanOff, buttonLayoutParams);
LinearLayout.LayoutParams layoutParams = new LinearLayout.LayoutParams(
ViewGroup.LayoutParams.MatchParent,
ViewGroup.LayoutParams.WrapContent);
pageLayout.AddView(buttonLayout, layoutParams);
adapterCmd = -1;
}
public void DestroyLayout(JobReader.PageInfo pageInfo)
{
if (buttonBlockSize != null)
{
buttonBlockSize.Dispose();
buttonBlockSize = null;
}
if (buttonSepTime0 != null)
{
buttonSepTime0.Dispose();
buttonSepTime0 = null;
}
if (buttonSepTime1 != null)
{
buttonSepTime1.Dispose();
buttonSepTime1 = null;
}
if (buttonCan500 != null)
{
buttonCan500.Dispose();
buttonCan500 = null;
}
if (buttonCan100 != null)
{
buttonCan100.Dispose();
buttonCan100 = null;
}
if (buttonCanOff != null)
{
buttonCanOff.Dispose();
buttonCanOff = null;
}
//Android.Util.Log.Info("Custom", "Destroyed");
}
public void UpdateLayout(JobReader.PageInfo pageInfo, bool pageValid, bool threadActive)
{
if ((buttonCan500 == null) || (buttonCan100 == null) || (buttonCanOff == null))
{
return;
}
bool enabled = pageValid && threadActive;
buttonBlockSize.Enabled = enabled;
buttonSepTime0.Enabled = enabled;
buttonSepTime1.Enabled = enabled;
buttonCan500.Enabled = enabled;
buttonCan100.Enabled = enabled;
buttonCanOff.Enabled = enabled;
}
}
```
The resulting page will look like this:
![Adapter page](Page_specification_AdapterConfigSmall.png)
## Receiving broadcasts (BroadcastReceived)
For interaction of the user code with other apps the broadcast `de.holeschak.bmw_deep_obd.Action.Command` could by processed by the function `BroadcastReceived`.
Here is an example from the axis page, that changes the axis direction with the broadcast.
``` xml
```
# Grouping pages
If the same of pages are required in multiple configuration, it's useful to group the together. This could be done with `*.ccpages` files. Simply include the `*.ccpage` files withing the `pages` node. The specifified path is relative to the `*.ccpages` file location. The file has the following layout:
``` xml
```
# The configuration file
Now all `*.page` or `*.pages` can be added to a configuration file `*.cccfg`. This file could be loaded by _[Deep OBD for BMW and VAG](Deep_OBD_for_BMW_and_VAG.md)_. In the `global` node of the file the following properties could be specified:
* `ecu_path`: Directory of the ecu files (`*.grp` and `*.prg`) relative to the configuration file.
* `log_path`: Directory for the data logging files. Logging could be enabled by adding a `log_tag` property to the `display` node of the `*.page` file. If the directory is not existing it will be created.
* `append_log`: Setting this property to true will always append the log file.
* `manufacturer`: Select the car manufacturer with this property. Possible values are `BWM`, `VW`, `Audi`, `Seat` and `Skoda`.
* `interface`: Specify the communication interface in this property. Possible values are `BLUETOOTH` , `ENET`, `ELMWIFI`, `DEEPOBDWIFI` and `FTDI`. When using a manufacturer from the VAG group, only `BLUETOOTH` and `DEEPOBDWIFI` is allowed.
``` xml
```
# Broadcasts
The received OBD data could be broadcasted to other apps if broadcast sending is enabled in the [global settings](GlobalSettings.md). This way it's possible to display or process data individually.
The broadcast name is `de.holeschak.bmw_deep_obd.Notification.Info`. It contains the following intent data:
* `action` (string): Change of operation status:
* `connect`: OBD connection is connected.
* `disconnect`: OBD connection is disconnected.
* `page_change`: The current display page changes.
* `obd_data` (string): JSON object that contains the current OBD data. It has the following format:
``` json5
{
"PageName":"",
"ObdData":
[
{
"Name":"",
"Result":"",
"Value":""
},
{
"Name":"",
"Result":"",
"Value":""
},
]
}
```
Additionally the broadcast `de.holeschak.bmw_deep_obd.Action.Command` could be received by the App.
The following intent data is defined:
* `action` (string): Action to be processed by the app:
* `new_page:`: Switches to the new page (configuration) with the name ``. `` is the name in the node ``.
The broadcast could be also received by the [`BroadcastReceived`](#receiving-broadcasts-broadcastreceived) user function.
# Special jobs
There are some job, that require special handling:
* With `STATUS_MESSWERTBLOCK_LESEN` or `STATUS_BLOCK_LESEN` multiples values could be requested simultanously.
The job requires the entries from the table `MESSWERTETAB` or `SG_FUNKTIONEN` with column `ARG` as arument.
The first argument `JA` or `NEIN` specifies if the last ECU request is reused.
The number of arguments is limited by the ECU, the typical limit is 10.
* For reading `STATUS_MESSWERTBLOCK_X` the corresponding `MESSWERTBLOCK_X_SCHREIBEN` is to be called first once (`MS450DS0.PRG` only).