Skip to content

matlab/agent-skills-playground / demos/embedded-ai-deployment/skills/embedded-ai-deployment

embedded-ai-deployment

Verified

Deploy AI models to embedded hardware using MathWorks tools (MATLAB, Simulink, Embedded Coder). Covers two workflow patterns: (1) MathWorks-native or 3P-imported models rebuilt as dlnetwork for lean hardware (Cortex-M, DSP), (2) direct C/C++ code generation from PyTorch and LiteRT models for high-performance hardware (Cortex-A, x86, GPU). Trigger when: user wants to deploy AI to embedded targets; generate C/CUDA from neural networks; compress AI models for MCU/DSP; integrate AI in Simulink for system-level simulation; import PyTorch/ONNX/TensorFlow models for embedded deployment; optimize AI for resource-constrained hardware; or use loadPyTorchExportedProgram, importNetworkFromPyTorch, dlquantizer, exportNetworkToSimulink, or Embedded Coder with AI models.

references/pattern1/troubleshooting.md

View on GitHub
# Troubleshooting -- Pattern 1

Common errors in the import, native dlnetwork rebuild, compression, code generation,
and Simulink workflow for embedded AI deployment.

---

## Import and Rebuild Errors

### "Layer X does not support code generation"

**Cause:** The network still contains autogenerated custom layers from import.

**Fix:** You have not finished the rebuild. Find and replace all custom layers:
```matlab
for i = 1:numel(net.Layers)
    cls = class(net.Layers(i));
    if contains(cls, 'Autogenerated') || contains(cls, '+')
        fprintf('Still custom: %s [%s]\n', net.Layers(i).Name, cls);
    end
end
```

Replace each one with a native equivalent. See `native-rebuild-patterns.md` and
`custom-layers-codegen.md`.

### PyTorch import failure -- fallback to ONNX

If `importNetworkFromPyTorch` fails or produces custom autogenerated layers that
are NOT supported for code generation (check with `analyzeNetwork`):

1. Do NOT attempt to fix the layers manually in MATLAB as a first step.
2. Advise the user to export the network to ONNX format from Python instead.
3. Provide this Python code snippet for the user to run in their own Python
   environment -- do NOT run this code for them:

```python
import torch
import torch.onnx

# Load the model
model = torch.load("model.pt")
model.eval()

# Create dummy input matching model's expected input shape
dummy_input = torch.randn(1, num_features)  # Adjust shape to match your model

# Export to ONNX
torch.onnx.export(
    model,
    dummy_input,
    "model.onnx",
    opset_version=13,
    input_names=["input"],
    output_names=["output"],
    dynamic_axes=None  # Use fixed shapes for embedded deployment
)
print("Exported to model.onnx")
```

4. Tell the user: "Please run this Python code in your Python environment and
   provide the resulting `.onnx` file. I cannot run Python code for you."
5. Once the user returns with the `.onnx` file, proceed with `importNetworkFromONNX`.
6. If the ONNX import also produces unsupported layers, proceed to a full native
   rebuild using `native-rebuild-patterns.md`.

### Post-import validation -- detecting unsupported layers

After importing any external model, always check for placeholder, autogenerated,
or unsupported layers:

```matlab
analyzeNetwork(net)

unsupportedLayers = [];
for i = 1:numel(net.Layers)
    layerClass = class(net.Layers(i));
    if contains(layerClass, "PlaceholderLayer") || ...
       contains(layerClass, "nnet.onnx") || ...
       contains(layerClass, "nnet.pytorch") || ...
       contains(layerClass, "nnet.tensorflow") || ...
       contains(layerClass, "autogenerated")
        warning("Layer '%s' (%s) may not support code generation.", ...
            net.Layers(i).Name, layerClass);
        unsupportedLayers = [unsupportedLayers; i]; %#ok<AGROW>
    end
end

if ~isempty(unsupportedLayers)
    fprintf("Found %d layers that may not support code generation.\n", ...
        numel(unsupportedLayers));
end
```

### Weight shape mismatch during transfer

**Cause:** PyTorch and MATLAB use different dimension orderings for some layer types.

**Common fixes:**
```matlab
% Conv weights: PyTorch [O,I,H,W] -> MATLAB [H,W,I,O]
matlabW = permute(pytorchW, [3, 4, 2, 1]);

% FC weights from ONNX MatMul: [input, output] -> MATLAB [output, input]
matlabW = onnxW';

% Position embeddings: [numTokens, embedDim] -> [embedDim, numTokens]
matlabPE = pytorchPE';
```

### Numerical mismatch after rebuild (error > 1e-3)

**Possible causes:**
1. **Missing weight:** A learnable parameter was not transferred. Check that
   `net.Learnables` row counts match between the imported and rebuilt networks.
2. **Wrong weight mapped:** Layer name matching was ambiguous. Use explicit
   index-based transfer.
3. **FC OperationDimension:** After replacing mean with GAP+flatten in CNNs,
   the FC layer's `OperationDimension` is still set for PyTorch convention.
   Rebuild the FC layer from scratch:
   ```matlab
   fcNew = fullyConnectedLayer(fcOld.OutputSize, 'Name', fcOld.Name, ...
       'Weights', fcOld.Weights, 'Bias', fcOld.Bias);
   lgraph = replaceLayer(lgraph, fcOld.Name, fcNew);
   ```
4. **dlarray format mismatch:** The rebuilt network expects a different format
   string. Check what `analyzeNetwork(net)` shows for input expectations.

### analyzeNetworkForCodegen reports issues

**Fix:** Run and read each issue:
```matlab
analyzeNetworkForCodegen(net, TargetLibrary='none');
```

Common issues and fixes:

| Issue | Fix |
|-------|-----|
| "Layer not supported for target 'none'" | Replace with codegen-compatible equivalent |
| "State properties not supported" | Remove layers with State (or use stateless equivalent) |
| "Variable-size not supported" | Ensure all dimensions are fixed in `coder.typeof` |

---

## Compression Errors

### fi() type error during calibrate()

**Cause:** `prepareNetwork()` was not called on the network before creating the quantizer.

**Fix:**
```matlab
net = prepareNetwork(net);  % <-- MUST come before creating dlquantizer
qObj = dlquantizer(net, 'ExecutionEnvironment', 'MATLAB');
calibrate(qObj, ds);
```

### dlquantizer fails on network with custom layers

**Cause:** Custom autogenerated layers do not support the quantization framework.

**Fix:** This is the whole reason for the native rebuild. Ensure ALL layers in
the network are standard MATLAB types. If you still have custom layers, the
rebuild is incomplete.

### INT8 quantization has 50%+ error

**Cause:** Model output range is too wide for 256 INT8 levels.

**Check:**
```matlab
outputs = [];
for i = 1:numTests
    y = predict(baseNet, dlarray(single(testInputs{i}), fmt));
    outputs(end+1) = extractdata(y);
end
fprintf('Output range: [%.1f, %.1f]\n', min(outputs), max(outputs));
```

If the range exceeds ~100, INT8 is inadequate. Stay with FP32 or use FP16.

### quantize() output is NOT supported for code generation

**Cause:** The output of `quantize()` is for simulation and emulation only.
MATLAB Coder does NOT support code generation from quantized networks produced
by `quantize()`.

**Fix:** For embedded deployment, use the uncompressed, pruned, or unpacked
projected network for code generation. Quantization via `dlquantizer` validates
quantization effects, but the quantized `dlnetwork` cannot be deployed through
`coder.loadDeepLearningNetwork`.

### Projection fails accuracy budget

**Cause:** Compression goal is too aggressive for the data distribution.

**Fix:**
1. Reduce `LearnablesReductionGoal`, or omit it entirely and let the default
   (driven by `ExplainedVarianceGoal=0.95`) choose. If you don't know the
   right goal, sweep a few values and compare accuracy.
2. Verify calibration data covers the real input distribution
3. Do not use synthetic random data for fine-tuning
4. Combine projection at a conservative goal with INT8 quantization instead

### compressNetworkUsingProjection returns worse accuracy at any goal

**Cause:** The test/calibration data has an extremely narrow distribution. Even
small dimensionality reduction loses critical information.

**Fix:** Use INT8 quantization alone (without projection). The 75% savings from
INT8 may be sufficient without adding projection.

### ProjectedLayer wrapping a stateful LSTM/GRU fails code generation

**Cause:** `lstmProjectedLayer` and `gruProjectedLayer` (the unpacked
recurrent forms) are supported for generic C/C++ codegen via
`coder.loadDeepLearningNetwork`. A `ProjectedLayer` wrapper is supported
only when its contents are stateless — conv/FC, or LSTM/GRU configured in
stateful-I/O mode (`HasStateInputs=true`, `HasStateOutputs=true`). A
wrapped stateful LSTM/GRU does not generate code.

**Fix:** Unpack to the recurrent form before saving for
`coder.loadDeepLearningNetwork`:

```matlab
% Unpack projected layers — produces lstmProjectedLayer / gruProjectedLayer
unpackedNet = unpackProjectedLayers(projectedNet);
save("deployableNet.mat", "unpackedNet");

% Alternative: set UnpackProjectedLayers=true during projection
projectedNet = compressNetworkUsingProjection(net, calibData, ...
    UnpackProjectedLayers=true);
```

---

## Simulink Errors

### exportNetworkToSimulink fails

**Cause 1:** Network contains custom layers.
**Fix:** Complete the native rebuild -- all layers must be standard MATLAB types.

**Cause 2:** Stale Simulink artifacts.
**Fix:**
```matlab
if exist([mdl '.slx'], 'file'), delete([mdl '.slx']); end
if exist([mdl '.slxc'], 'file'), delete([mdl '.slxc']); end
if bdIsLoaded(mdl), close_system(mdl, 0); end
exportNetworkToSimulink(net, 'ModelName', mdl);
```

**Cause 3:** Quantized network not exportable.
**Fix:** Fall back to float32 baseline, then apply quantization via Simulink
tools instead.

### Simulink simulation output is NaN

**Possible causes:**
1. Input timeseries has wrong time vector (must start at 0, match StopTime)
2. Input shape does not match what the Predict block expects
3. Solver configuration issue -- ensure `FixedStepDiscrete` is set

### slbuild fails on Embedded Coder generation

**Fix:**
```matlab
% Ensure ERT target is set
set_param(mdl, 'SystemTargetFile', 'ert.tlc');
set_param(mdl, 'TargetLang', 'C');

% Enable portable word sizes for cross-compilation
set_param(getActiveConfigSet(mdl), 'PortableWordSizes', 'on');
```

---

## Code Generation Errors

### DeepLearningConfig not set

```matlab
% Always set explicitly for library-free C
cfg.DeepLearningConfig = coder.DeepLearningConfig('none');
```

### InstructionSetExtensions on wrong object

```matlab
% WRONG -- dlcfg doesn't have this property
dlcfg.InstructionSetExtensions = 'Neon v7';

% CORRECT -- property of cfg
cfg.InstructionSetExtensions = 'Neon v7';
```

### Linker errors with LargeConstantThreshold = 0

On bare-metal MCU without filesystem, the generated code tries to `fopen` .bin
weight files.

**Fix:** Do not set `LargeConstantThreshold` -- let weights embed inline in the
.c file. Or provide a filesystem abstraction on the MCU.

### Embedded Coder missing warning

If Embedded Coder is NOT available, always inform the user:

> "Warning: Embedded Coder is not installed. Code generated by MATLAB Coder
> or Simulink Coder alone may not be optimized for your embedded target.
> Without Embedded Coder, you may experience:
> - Larger code footprint (ROM/RAM)
> - Suboptimal execution speed
> - Limited target-specific optimizations
> - No direct IDE integration
> - Code may not meet production coding standards (MISRA, CERT)
>
> For production deployment on resource-constrained hardware, installing
> Embedded Coder is strongly recommended."

### Codegen predict function requirements

The predict function wrapped for code generation must follow strict conventions.
Common causes of failure:

1. **Missing arguments block:** The predict function MUST use an `arguments`
   block to declare input types explicitly. Without it, codegen cannot infer
   types.

2. **Missing dlarray format:** Input data must be wrapped in `dlarray` with the
   correct format label inside the predict function. Without `dlarray` wrapping,
   codegen fails with: "Input data argument to predict must be dlarray type."

**For tabular/image dlnetwork:**
```matlab
function y = predictDLNet(net, x)
    arguments
        net     dlnetwork
        x       (1,:) single
    end

    dlX = dlarray(x, "CB");
    dlY = predict(net, dlX);
    y = extractdata(dlY);
end
```

**For LSTM/GRU sequence models (one time step at a time):**
```matlab
function y = predictSeqDLNet(net, x)
    arguments
        net     dlnetwork
        x       (1,:) single
    end

    dlX = dlarray(x, "TC");  % Time x Channels for sequence models
    dlY = predict(net, dlX);
    y = extractdata(dlY);
end
```

### Network codegen compatibility matrix

| Network Type | Codegen Support | Action Required |
|-------------|----------------|-----------------|
| Standard `dlnetwork` | Supported | None |
| Projected network with `lstmProjectedLayer` / `gruProjectedLayer` | Supported (generic C/C++ only) | None |
| Projected network with `ProjectedLayer` over conv/FC or stateful-I/O LSTM/GRU | Supported (generic C/C++ only) | None |
| Projected network with `ProjectedLayer` over a stateful LSTM/GRU | NOT supported | Call `unpackProjectedLayers(net)` first |
| Quantized network from `quantize()` | NOT supported | Use the pre-quantized network for codegen |

---

## Diagnostic Commands

```matlab
% List all layers and their types
for i = 1:numel(net.Layers)
    fprintf('%3d  %-40s [%s]\n', i, net.Layers(i).Name, class(net.Layers(i)));
end

% Check codegen compatibility
analyzeNetworkForCodegen(net, TargetLibrary='none');

% Check single custom layer
checkLayer(myLayer, inputSize, 'CheckCodegenCompatibility', true)

% List supported layers for target
coder.getDeepLearningLayers('none')

% Inspect Learnables table
disp(net.Learnables)

% Count parameters
totalParams = 0;
for i = 1:height(net.Learnables)
    totalParams = totalParams + numel(net.Learnables.Value{i});
end
fprintf('Total parameters: %d (%.1f KB float32)\n', totalParams, totalParams*4/1024);

% Check for installed compression library
pkgs = matlabshared.supportpkg.getInstalled;
hasCompLib = false;
if ~isempty(pkgs)
    hasCompLib = any(contains({pkgs.Name}, "Model Compression"));
end

% Estimate model size after code generation
codeDir = "codegen/lib/predictDLNet/";
files = dir(fullfile(codeDir, "*.c"));
totalCodeSize = sum([files.bytes]);
dataFiles = dir(fullfile(codeDir, "*_data.c"));
totalDataSize = sum([dataFiles.bytes]);
fprintf("Generated code size: %.1f KB\n", totalCodeSize / 1024);
fprintf("Data (weights) size: %.1f KB\n", totalDataSize / 1024);
fprintf("Total: %.1f KB\n", (totalCodeSize + totalDataSize) / 1024);
```

---

## Quick-Reference Decision Matrix

| Symptom | Cause | Fix |
|---------|-------|-----|
| Codegen fails on layer | Custom autogenerated layer | Replace with native (see `custom-layers-codegen.md`) |
| PyTorch import produces unsupported layers | Autogenerated layers from PyTorch converter | Fall back to ONNX export from Python, then `importNetworkFromONNX` |
| dlquantizer calibrate fails | `prepareNetwork` not called | Create the `dlquantizer` first, then call `prepareNetwork(quantObj)` (R2026a mutates the object in place) |
| INT8 accuracy terrible | Wide output range | Use FP32 or reduce output scaling |
| `quantize()` output fails codegen | Quantized nets not supported for codegen | Use uncompressed/pruned/unpacked net for codegen |
| Projection fails accuracy | Goal too aggressive | Lower `LearnablesReductionGoal`, or omit it and use the default (`ExplainedVarianceGoal=0.95`); sweep goals to find the budget |
| ProjectedLayer codegen error | `ProjectedLayer` wrapping a stateful LSTM/GRU is not codegen-compatible | Call `unpackProjectedLayers(net)` to expose the underlying `lstmProjectedLayer`/`gruProjectedLayer` (which are codegen-supported) |
| Simulink export fails | Custom layers remain | Complete native rebuild |
| Simulink NaN output | Input shape or time vector mismatch | Check timeseries format and solver settings |
| `slbuild` fails | ERT target or config issue | Set `SystemTargetFile` to `ert.tlc`, enable PortableWordSizes |
| DeepLearningConfig not set | Missing codegen config | Set `cfg.DeepLearningConfig = coder.DeepLearningConfig('none')` |
| Linker errors on MCU | `LargeConstantThreshold = 0` causes `fopen` | Remove threshold, let weights embed inline |
| C output wrong values | Column-major mismatch | Transpose input in C harness |
| Weight transfer wrong | Dimension ordering | Check PyTorch vs MATLAB conventions (permute/transpose) |
| Predict function codegen fails | Missing `arguments` block or dlarray format | Add `arguments` block and wrap input in `dlarray` with format label |
| Embedded Coder not installed | Missing toolbox | Warn user; code may be unoptimized for target |
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall