simulink-customize-a2l

# Customize A2L Files Customize A2L (ASAP2) files generated from Simulink models using the `coder.asap2` and `coder.mapping` APIs, avoiding silent errors and undocumented pitfalls. ## When to Use - Adding or modifying COMPU_METHODs (LINEAR, RAT_FUNC, TAB_VERB, IDENTICAL) - Creating or modifying GROUPs in the A2L file - Converting STD_AXIS to COM_AXIS for lookup tables - Adding BIT_OPERATION (LEFT_SHIFT, RIGHT_SHIFT, SIGN_EXTEND) to measurements - Creating VARIANT_CODING (VarCriterion, VarCharacteristic) - Excluding inports, outports, or struct elements from the A2L - Removing DEFAULT_EVENT_LIST or other IF_DATA blocks - Any customization passed via `CustomEcuDescriptions` to `coder.asap2.export` ## When NOT to Use - Reading or parsing existing A2L files (use Vehicle Network Toolbox `a2lfile`) - Configuring XCP/CAN transport layers - Setting up Simulink model code generation (storage classes, data dictionaries) - General Embedded Coder build workflows without A2L customization ## Core Workflow ### Decision: Direct export vs. customization workflow - **No element customization needed** (only configuration like excluding struct elements or DEFAULT_EVENT_LIST): call `coder.asap2.export` directly with name-value options. No `getEcuDescriptions` needed. - **Element customization needed** (adding/modifying/deleting measurements, characteristics, groups, etc.): use the full `getEcuDescriptions` → customize → export workflow. ```matlab % === Path A: Config-only (no element changes) === load_system(modelName); slbuild(modelName); coder.asap2.export(modelName, SupportStructureElements=false, IncludeDefaultEventList=false); % === Path B: Element customization === load_system(modelName); slbuild(modelName); % 1. Create ECU descriptions — pass ALL configuration options here descObj = coder.asap2.getEcuDescriptions(modelName, ... SupportStructureElements=false, ... IncludeDefaultEventList=false); % 2. Customize elements add(descObj, newElement); set(descObj, 'ElementType', 'Name', Prop=value); info = get(descObj, 'ElementType', 'Name'); names = find(descObj, 'ElementType'); delete(descObj, 'ElementType', 'Name'); % 3. Export — MUST pass descObj back or all customizations are silently lost coder.asap2.export(modelName, CustomEcuDescriptions=descObj); ``` **Critical:** When using Path B, omitting `CustomEcuDescriptions=descObj` in the export call silently discards all customizations with no error. **Critical:** When using Path B, construction-time options (SupportStructureElements, etc.) CANNOT be passed to `export` alongside `CustomEcuDescriptions` — they must be passed to `getEcuDescriptions`. ## Key Functions | Function | Purpose | |----------|---------| | `coder.asap2.getEcuDescriptions` | Create ECU description object (construction-time config) | | `coder.asap2.export` | Export A2L file with customizations | | `coder.asap2.CompuMethod` | Create computation method | | `coder.asap2.Characteristic` | Create characteristic (parameter) | | `coder.asap2.Measurement` | Create measurement (signal) | | `coder.asap2.Group` | Create A2L group | | `coder.asap2.RecordLayout` | Create record layout | | `coder.asap2.AxisInfo` | Create axis points or axis descriptor | | `coder.asap2.VarCriterion` | Create variant criterion | | `coder.asap2.VarCharacteristic` | Create variant characteristic | | `coder.asap2.Function` | Create FUNCTION object for grouping measurements/characteristics | | `coder.mapping.api.get` | Get code mapping object (persistent settings) | | `setInport` / `setOutport` | Control inport/outport A2L export (persistent) | See `references/object-properties.md` for mandatory fields, valid types, and creation order for each `coder.asap2.*` class. ## Pattern Routing Match the user's task to the correct reference for detailed guidance: | Task | Key Rule | Reference | |------|----------|-----------| | Add COMPU_METHOD (RAT_FUNC, LINEAR, TAB_VERB) | RAT_FUNC COEFFS direction is **PHYS→INT** — invert the desired formula | `references/compu-method-guidance.md` | | Convert STD_AXIS to COM_AXIS (shared breakpoints) | Use `ForceShared=true` on the Characteristic — do NOT manually create AXIS_PTS | `references/customization-patterns.md` | | Add BIT_OPERATION to a measurement | Must set BOTH `BitMask` AND `MaskData` — either alone produces no output | `references/customization-patterns.md` | | Exclude inports/outports persistently | Use `coder.mapping.api` + `setInport`/`setOutport` + `slbuild` | `references/customization-patterns.md` | | Create VARIANT_CODING | Must create supporting CHARACTERISTIC objects (selection + variant-dependent) with RecordLayouts and CompuMethods BEFORE VarCriterion/VarCharacteristic. All multi-value properties must be string arrays (not char/cell). | `references/variant-coding-guidance.md` | | Create Characteristic (CURVE, MAP, CUBOID) | RecordLayout struct array must match axis count for STD_AXIS types | `references/object-properties.md` | | Create Measurement | Set `DataType='SWORD'`, `EcuAddress='@ECU_Address@name@'`, `CompuMethodName='NO_COMPU_METHOD'` as defaults | `references/object-properties.md` | | Create Group | See mandatory fields and ROOT constraint | `references/object-properties.md` | | Create RecordLayout | Struct array required for multi-axis types (MAP, CUBOID); single struct for VALUE/VAL_BLK | `references/object-properties.md` | | Create AxisInfo / AXIS_PTS | Dual role: `add(descObj, axisInfo)` creates AXIS_PTS; `characteristic.AxisInfo = [...]` creates AXIS_DESCR | `references/object-properties.md` | | Control construction-time options (SupportStructureElements, IncludeDefaultEventList, etc.) | Must pass at `getEcuDescriptions()` — cannot set after construction or pass to `export` with `CustomEcuDescriptions` | `references/construction-time-properties.md` | ## Release Requirements | Feature | Minimum Release | |---------|----------------| | COMPU_METHOD, Measurement, Characteristic, BIT_OPERATION | R2022b | | RecordLayout, AxisInfo (STD_AXIS, CUBOID) | R2023a | | Group (ROOT groups) | R2023b | | VarCriterion, VarCharacteristic (variant coding) | R2025a | If the user's release is too old, inform them. Do not attempt workarounds — the APIs do not exist on older releases. ## Common Mistakes These cause silent failures or incorrect calibration data. Always check before generating code: | Mistake | Why It's Wrong | Correct Approach | |---------|---------------|-----------------| | `coder.asap2.export(modelName)` without `CustomEcuDescriptions=descObj` | Silently discards all customizations — no error, exports default A2L | Always pass `descObj` back when using the customization workflow | | RAT_FUNC `Coefficients = [0 0.5 -40 0 0 1]` for "PHYS = 0.5×INT - 40" | COEFFS is PHYS→INT, not INT→PHYS — produces the inverse conversion | Invert: INT = 2×PHYS + 80 → `[0 2 80 0 0 1]`. See `references/compu-method-guidance.md` | | `set(descObj, ..., 'CompuMethodName', name)` before adding the CompuMethod | `set()` auto-creates a placeholder that blocks subsequent `add()` | `delete()` the auto-created placeholder, then `add()` the user's version | | `MaskData.Shift` without `BitMask` | BIT_OPERATION block is only emitted when both are set | Always set `BitMask` (e.g., `'0xFF'`) alongside `MaskData` | | `MaskData.Shift = 3` expecting LEFT_SHIFT | Positive = RIGHT_SHIFT; sign is counterintuitive | Use `-3` for LEFT_SHIFT 3 | | Manually creating AXIS_PTS for STD→COM_AXIS | Unnecessary complexity; error-prone struct array handling | Use `set(descObj, 'Characteristic', name, 'ForceShared', true)` | | `descObj.SupportStructureElements = false` | Not a settable property after construction | Pass at creation: `getEcuDescriptions(mdl, SupportStructureElements=false)` | | `VarAddress = '0x5000'` (char vector) | Char vector silently produces empty output — no addresses, no criterion name | Must be string array: `["0x5000","0x5008"]` | | `CompuVTabValues.Integers = [0,1,2]` | Property does not exist | Use `CompuVTabValues.Values = [0, 1, 2]` | | `CompuVTabValues.Literals = {'A','B'}` (cell array) | Accepted without error but exports 0 elements | Must be string array: `["A","B"]` | | Skipping `slbuild` after `setInport`/`setOutport` | Export silently produces stale A2L with old settings | Always `slbuild` after code mapping changes before export | | Hardcoding `EcuAddress = '0x0000'` | Calibration tools cannot resolve the address at import time | Use `'@ECU_Address@<elementName>@'` for linker resolution | | Leaving mandatory fields unset on new objects | Blank fields produce invalid A2L — calibration tools reject the file | See `references/object-properties.md` for required fields per class | | Creating VarCriterion/VarCharacteristic without supporting CHARACTERISTICs | VARIANT_CODING references characteristics that don't exist — calibration tool rejects the file | Create selection CHARACTERISTIC (with TAB_VERB CompuMethod) and variant-dependent CHARACTERISTIC (with RecordLayout) BEFORE VarCriterion/VarCharacteristic. See `references/variant-coding-guidance.md` | ## Conventions - Verify A2L output with `fileread` after export — use `contains` for additions, `~contains` for deletions/exclusions - Use string arrays (not char vectors or cell arrays) for all multi-value properties - Pass all configuration at `getEcuDescriptions()` construction time - Use `ForceShared=true` for STD→COM_AXIS (never build AXIS_PTS manually for this) - Use `delete(descObj, 'ElementType', 'Name')` to remove auto-created placeholders — this is the only recovery from the auto-creation trap caused by `set()` on a reference name before the referenced object exists - Prefer `coder.mapping.api` over `coder.asap2` when settings should persist with the model ---- Copyright 2026 The MathWorks, Inc. ----