matlab/matlab-agentic-toolkit / skills-catalog/ai-and-statistics/matlab-deploy-embedded-ai
matlab-deploy-embedded-ai
VerifiedDeploy AI models to embedded hardware using MathWorks tools (MATLAB, Simulink, Embedded Coder). Covers two workflow patterns: (1) MathWorks-native or imported models rebuilt as dlnetwork for lean hardware, (2) direct C/C++ code generation from PyTorch and LiteRT models. Both patterns support all targets (Cortex-M/A/R, x86, GPU). Trigger when: user wants to deploy AI to embedded targets; generate C/CUDA from neural networks; compress AI models for MCU; 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, loadLiteRTModel, importNetworkFromPyTorch, importNetworkFromONNX, importNetworkFromTensorFlow, importNetworkFromKeras, 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 startsWith(cls, "nnet.onnx.") || startsWith(cls, "nnet.pytorch.") || ...
startsWith(cls, "nnet.tensorflow.") || contains(cls, "PlaceholderLayer")
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. Use `/matlab-import-external-ai-model` to guide the user through exporting the
network to ONNX format from Python and importing via `importNetworkFromONNX`.
3. 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)
numLayers = numel(net.Layers);
isUnsupported = false(numLayers, 1);
for i = 1:numLayers
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);
isUnsupported(i) = true;
end
end
unsupportedLayers = find(isUnsupported);
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 quantizer before calibration.
**Fix:**
```matlab
qObj = dlquantizer(net, 'ExecutionEnvironment', 'MATLAB');
prepareNetwork(qObj); % Takes the dlquantizer object, mutates in place
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
**Possible causes (check in order):**
1. **Wide output range:** If `(max - min) / 256 > acceptable_error`, INT8 cannot
represent the output accurately. Check:
```matlab
outputs = zeros(numTests, 1);
for i = 1:numTests
y = predict(baseNet, dlarray(single(testInputs{i}), fmt));
outputs(i) = extractdata(y);
end
fprintf('Output range: [%.1f, %.1f]\n', min(outputs), max(outputs));
```
If range exceeds ~100, consider INT16 (via Fixed-Point Designer) or stay FP32.
2. **Unrepresentative calibration data:** If the calibration set does not cover the
real input distribution, scale/zero-point estimates are wrong. Ensure at least 100
representative samples from the deployment domain.
3. **Sensitive intermediate layers:** Some layers (e.g., normalization, attention
projections) lose more precision than others. Use `quantizationDetails(qNet)` to
inspect per-layer ranges, and consider excluding high-error layers via the
`ExcludedLayers` option.
4. **Missing `prepareNetwork`:** Without preparation, batch normalization layers are
not fused and layer equalization is not applied, leading to cascading quantization
error. `prepareNetwork(quantObj)` handles both fusion and equalization.
### 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 generates placeholder blocks
**Cause:** Network contains custom layers that cannot be mapped to native Simulink
layer blocks. The export does not fail — it succeeds but inserts **placeholder
subsystems** (empty stubs with `Inport -> Assertion -> Outport`) for each
unsupported layer. These placeholders block both simulation and code generation.
**Fix:** Either complete the native rebuild (replace all custom layers with
standard MATLAB types), or implement the placeholder layers manually using the
workflow in `placeholder-blocks.md`.
**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. **NaN or Inf in input data:** Check `any(isnan(inputData(:)) | isinf(inputData(:)))`.
Missing sensor readings or division-by-zero in preprocessing propagate as NaN
through the network.
2. **Input timeseries has wrong time vector:** Must start at 0 and match StopTime.
3. **Input shape does not match what the block expects:** Verify dimensions with
`analyzeNetwork(net)` and compare to the signal feeding the block.
### 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.
### Checking for Hardware Support Packages
Many embedded deployment workflows require hardware support packages (HSPs) in
addition to toolboxes. HSPs are not detected by `ver` or `detect_matlab_toolboxes`.
```matlab
% Check for a specific HSP (e.g., ARM Cortex-M support)
pkgs = matlabshared.supportpkg.getInstalled;
if isempty(pkgs)
fprintf('No support packages installed.\n');
else
hasARM = any(contains({pkgs.Name}, "ARM Cortex-M"));
fprintf('ARM Cortex-M HSP: %s\n', string(hasARM));
end
```
If the required HSP is missing, direct the user to install it via MATLAB Add-On
Explorer. Do not attempt to install support packages programmatically.
### Embedded Coder not available
Embedded Coder is optional — MATLAB Coder alone is sufficient for generating C/C++
code from deep learning networks. If Embedded Coder is available, it provides
additional optimizations (smaller code footprint, target-specific tuning, MISRA
compliance). Proceed with MATLAB Coder if EC is not installed.
### Codegen predict function requirements
The entry-point function for code generation must load the network internally
(not accept it as an input) and wrap the raw input in `dlarray` with the correct
format label. Type information can be provided via the `-args` flag to `codegen`
or via an `arguments` block in the entry-point function (both are valid).
**Correct pattern (dlnetwork):**
```matlab
function y = predictDLNet(x)
%#codegen
persistent net;
if isempty(net)
net = coder.loadDeepLearningNetwork('trainedNet.mat');
end
dlX = dlarray(x, 'BC'); % x is [1 x numFeatures] (Batch x Channel)
dlY = predict(net, dlX);
y = extractdata(dlY);
end
```
**Invoking codegen with `-args`:**
```matlab
inputType = coder.typeof(single(0), [1 numFeatures]);
codegen predictDLNet -args {inputType} -config cfg
```
The `-args` flag specifies the input type and size. Alternatively, an `arguments`
block inside the entry-point function can provide type information — if `-args` is
omitted, MATLAB Coder uses the `arguments` block for type inference. Both approaches
are valid; `-args` is more flexible for variable-size specifications.
**Common failure:** Missing `dlarray` wrapping inside the function. Without it,
codegen fails with: "Input data argument to predict must be dlarray type."
### Input specification errors during codegen
**Symptom:** `codegen` fails with errors about input size, type, or format mismatch.
**Common causes and fixes:**
1. **Wrong `-args` specification:** The `-args` type must match what the entry-point
function actually receives. For a `[numFeatures × 1]` column vector input:
```matlab
inputType = coder.typeof(single(0), [numFeatures 1]);
codegen predictDLNet -args {inputType} -config cfg
```
2. **Variable-size inputs:** Some targets support variable-size inputs, but for
resource-constrained MCUs, fixed-size is typically preferred. Use
`coder.typeof(single(0), [numFeatures 1])` for fixed-size, or
`coder.typeof(single(0), [numFeatures 1], [true false])` for variable first dim.
3. **dlarray format mismatch:** The format label in `dlarray(x, 'BC')` must match
the network's expected input format. Check with:
```matlab
net.Layers(1) % Shows expected input size and format
```
4. **Batch dimension confusion:** For single-sample inference on embedded targets,
the batch dimension is 1. Use `"BC"` (batch=1 × channels) for feature inputs,
`"SSCB"` for image inputs, `"CB"` for single-timestep stateful sequence inputs.
### 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
This matrix covers the most common single-cause failures. For persistent issues,
also check: input data quality (NaN/Inf), dlarray format labels, and whether
`prepareNetwork` was called before calibration.
| 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 | Use `/matlab-import-external-ai-model` to fall back to ONNX path |
| 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 dlarray format or wrong `-args` | Wrap input in `dlarray` with format label; check `-args` type matches |
| Embedded Coder not installed | Missing toolbox | Warn user; code may be unoptimized for target |
Copyright 2026 The MathWorks, Inc.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| 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: 197k | Updated | Claude CodeCodex | Verified | Install |
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |