matlab-create-custom-arduino-library

name	matlab-create-custom-arduino-library
description	Use when the user wants to use Arduino sensors or peripherals from MATLAB that are not directly supported by the MATLAB Support Package for Arduino Hardware. Triggers on requests to create, wrap, or expose a custom Arduino library to MATLAB. Also triggers on indirect questions like "How do I read humidity in MATLAB?" or "How do I display text on an LCD from MATLAB?" where the answer requires a custom Arduino add-on library. Covers: custom addon creation, third-party Arduino library integration, LibraryBase class, C++ header files, DependentLibraries, arduinoioaddons namespace, I2C/SPI/GPIO peripheral wrappers.
license	https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md
metadata	{"author":"MathWorks","version":"1.0"}

Create Custom Arduino Library

Help the user interface with Arduino sensors or peripherals from MATLAB by creating a custom arduino library that bridges MATLAB and Arduino C++ code.

When to Use

• User wants to read sensors not natively supported (DHT11, DHT22, IMU, air quality)
• User wants to control peripherals not natively supported (OLED displays, motor drivers, NeoPixels)
• User asks "How do I use [sensor/actuator/peripheral] from MATLAB with Arduino?"
• User wants to wrap an existing Arduino C++ library for MATLAB access
• User mentions LibraryBase, arduinoioaddons, or custom addon creation

When NOT to Use

• Peripheral is already supported natively (use listArduinoLibraries to check)
• User needs to discover or connect to an Arduino board (see matlab-connect-arduino)
• User wants generic I2C/SPI communication (built-in)
• User wants to deploy standalone Arduino code (no MATLAB connection)
• User wants Simulink Arduino deployment (different workflow)
• User wants to fix Arduino hardware setup screens

Workflow

MANDATORY GATE — do not skip, but keep it fast:

Before creating a custom addon, you MUST run Steps 0 and 1 below. These are quick checks (one MATLAB command + one sentence about File Exchange), not deep research. Report findings in 1-2 lines and move on. If native support or a community addon exists, stop. Otherwise proceed to Step 2 immediately.

STEP 0: Check Native Support (ALWAYS DO FIRST)

listArduinoLibraries

If the peripheral is in the list, tell the user and STOP. Do NOT proceed to Step 2 or beyond. Do NOT generate custom library code. Common built-in: I2C, SPI, Serial, Servo, RotaryEncoder, Ultrasonic, ShiftRegister

STEP 1: Search File Exchange (MathWorks contributions only)

Search for existing add-ons contributed by the MathWorks MATLAB Hardware Team:

• Search: site:mathworks.com/matlabcentral/fileexchange Arduino <peripheral>
• Look for packages with +arduinoioaddons folder structure
• Only use results authored by MathWorks — filter by author "MathWorks Hardware Team" or "MathWorks". Do NOT recommend community contributions from unknown third parties.

If a MathWorks-contributed add-on is found, guide the user through installation:

1. Download/extract the addon package
2. addpath the folder containing +arduinoioaddons
3. Install third-party Arduino libraries via arduinoio.customLibrary.downloadLibrary
4. Verify with listArduinoLibraries

STOP here if a MathWorks add-on is found — do NOT proceed to Step 2 or beyond.

STEP 2: Gather Required Inputs

Before creating a custom library, the user MUST provide:

1. Custom library name (e.g., MyDHT22)
2. Third-party Arduino library name (if wrapping one; e.g., DHT22, U8g2)
3. Target output directory for the MATLAB add-on files

Do NOT proceed to any further steps until all required inputs are provided. If any are missing, ask the user explicitly and wait for their response.

STEP 3: Install Third-Party Arduino Library

% R2025a+ — use downloadLibrary (preferred)
arduinoio.customLibrary.downloadLibrary("<ArduinoLibraryName>")

% Accepts: library name, name@version, GitHub URL, or local .zip path
% Examples:
arduinoio.customLibrary.downloadLibrary("DHT22")
arduinoio.customLibrary.downloadLibrary("U8g2")
arduinoio.customLibrary.downloadLibrary("https://github.com/olikraus/u8g2")

Verify installation:

dir(fullfile(arduinoio.CLIRoot, 'user', 'libraries'))

For R2024a-R2024b (no downloadLibrary): manually extract the library zip into fullfile(arduinoio.CLIRoot, 'user', 'libraries', '<LibName>').

For pre-R2024a (no CLIRoot): use arduinoio.IDERoot instead of arduinoio.CLIRoot.

STEP 4: Scaffold the Add-On

% R2025a+ — use createLibraryTemplate (preferred)
arduinoio.customLibrary.createLibraryTemplate("<CustomLibraryName>")

This creates the folder structure in the current working directory (pwd) and adds the path automatically. After calling it, the generated files are at:

<pwd>/+arduinoioaddons/+<CustomLibraryName>Folder/<CustomLibraryName>.m
<pwd>/+arduinoioaddons/+<CustomLibraryName>Folder/src/<CustomLibraryName>.h

Do NOT search other locations — the files are always in pwd.

Naming: createLibraryTemplate("X") creates +XFolder/X.m — it appends "Folder" to the package name automatically. The generated setup() has placeholder comments — clear the body (no .begin() calls). The generated loop() is unused and can be deleted.

For pre-R2025a: create the folder structure manually:

<targetDir>/+arduinoioaddons/+<FolderName>/<ClassName>.m
<targetDir>/+arduinoioaddons/+<FolderName>/src/<HeaderName>.h

Then register:

addpath('<targetDir>');
savepath;

STEP 5: Configure the MATLAB Class

Update the generated .m file. See "MATLAB Class Property Rules" below for exact values.

Add minimal comments to the generated .m file for user understanding:

• A file-level comment block stating the class purpose and the peripheral it wraps
• Brief comments on non-obvious property values (e.g., why DependentLibraries is empty)
• A one-line comment above each public method explaining what it does

STEP 6: Write the C++ Header

Update the generated .h file. See "C++ Header Rules" below and read references/cpp-patterns.md for templates.

Add minimal comments to the generated .h file for user understanding:

• A file-level comment stating the addon name and peripheral it supports
• A one-line comment above each command ID #define explaining the command
• A brief comment in commandHandler for each case describing what it does

STEP 7: Verify

listArduinoLibraries  % Must show your library name
a = arduino("<port>", "<board>", "Libraries", "<FolderName>/<ClassName>");
obj = addon(a, "<FolderName>/<ClassName>", <args>);

MATLAB Class Property Rules

Property	Format	Example	Notes
LibraryName	'FolderName/ClassName'	'Adafruit/DHT22'	Must match namespace
DependentLibraries	Cell of MATLAB addon names	{} or {'I2C'}	See decision table below
LibraryHeaderFiles	'<ArduinoLibFolder>/<header.h>'	'DHT/DHT.h'	Folder name in CLIRoot + header filename
CppHeaderFile	fullfile(arduinoio.FilePath(mfilename('fullpath')), 'src', '<Name>.h')	—	Always this pattern
CppClassName	Must match C++ class name	'DHT22Base'	Exact match required

DependentLibraries Decision Table

Scenario	Value	Reason
GPIO-only peripheral (DHT, NeoPixel)	{}	No MATLAB bus dependency
I2C device using SW_I2C (displays, most sensors)	{}	Software I2C bypasses MATLAB's bus
I2C device delegating to MATLAB's I2C infrastructure	{'I2C'}	MATLAB manages Wire init and pins
SPI device	{}	MATLAB does not own SPI bus
Uses another custom addon	{'OtherAddon/Name'}	Chain dependency

LibraryHeaderFiles Format

Format: '<FolderNameInCLIRoot>/<HeaderFilename>'

% GOOD — folder name matches what's in CLIRoot/user/libraries/
LibraryHeaderFiles = {'DHT/DHT.h'}
LibraryHeaderFiles = {'U8g2/U8g2lib.h'}
LibraryHeaderFiles = {'Adafruit_Motor_Shield_V2_Library/Adafruit_MotorShield.h'}

% BAD — just filename without folder
LibraryHeaderFiles = {'DHT.h'}

% BAD — subdirectory path (NEVER include src/ even if the file physically lives there)
LibraryHeaderFiles = {'U8g2/src/U8g2lib.h'}

% BAD — Arduino library name (Wire is not in CLIRoot/user/libraries)
LibraryHeaderFiles = {'Wire/Wire.h'}

The Arduino build system automatically searches the src/ subdirectory within the library folder, so NEVER include src/ in this path. This is the most common mistake — even though headers like U8g2lib.h physically reside in <LibFolder>/src/, you must write 'U8g2/U8g2lib.h' NOT 'U8g2/src/U8g2lib.h'.

C++ Header Rules

Read references/cpp-patterns.md for full templates. Critical rules:

1. setup() MUST NOT initialize hardware — calling .begin(), Wire.begin(), SPI.begin() etc. in setup() causes "Internal error: The initialization of the server code is incorrect." Simple variable assignments (e.g., cursorRow = 0) are safe.
2. Use lazy initialization — init hardware on first command via a dedicated INIT command
3. sendResponseMsg must send >= 1 byte — sendResponseMsg(cmdID, 0, 0) crashes ARM boards (UNO R4, ESP32)
4. NEVER #include <Wire.h> in your addon header — causes I2C bus conflict with MATLAB. Your code must never contain this line. Third-party libraries may include it internally (that is fine — you don't control their code), but YOUR .h file must not.
5. #include <SPI.h> is safe — MATLAB does not own SPI
6. Use angle brackets for third-party headers: #include <U8g2lib.h>
7. Use constructor initializer list for member objects, not in-class initialization

I2C Bus Conflict — Read references/bus-conflicts.md

MATLAB owns the hardware I2C bus (Wire). If your peripheral uses I2C:

• Preferred: Use software I2C constructors (e.g., U8G2_..._SW_I2C) with DependentLibraries = {}
• Do NOT call Wire.begin() directly
• Do NOT #include <Wire.h> in your own addon header

If the third-party library requires hardware I2C (e.g., SGP30, motor shields): set DependentLibraries = {'I2C'} and let MATLAB manage the bus. The third-party library may include Wire.h internally — this is safe because MATLAB has already initialized Wire. Your C++ code must NOT call Wire.begin() since MATLAB already did.

Common Mistakes

Mistake	Why It's Wrong	Correct Approach
DependentLibraries = {'Wire'}	Wire is not in listArduinoLibraries	Use {} or {'I2C'}
Third-party lib in +arduinoioaddons/src/	Wrong location; build can't find it	arduinoio.CLIRoot/user/libraries/
LibraryHeaderFiles = {'U8g2lib.h'}	Missing folder prefix	{'U8g2/U8g2lib.h'}
U8G2_..._HW_I2C constructor	Conflicts with MATLAB's Wire management	Use _SW_I2C constructor
.begin() calls in setup()	Server handshake fails	Init hardware via command; variable assignments are OK
sendResponseMsg(cmdID, 0, 0)	Crashes ARM boards (nullptr)	Send >= 1 byte always
#include <Wire.h> in your addon header	Conflicts with MATLAB I2C server	Omit; use SW_I2C or DependentLibraries = {'I2C'}
Installing via Arduino IDE Library Manager	MATLAB uses its own CLIRoot path	Use downloadLibrary()
Not calling addpath after creating addon	listArduinoLibraries won't find it	addpath + savepath

Conventions

• Always check native support first, File Exchange second, create last
• Always use downloadLibrary (R2025a+) or manual copy to CLIRoot for third-party libs
• Always verify with listArduinoLibraries after registration
• Never call .begin() or hardware init in setup() — use lazy init via dedicated command
• Always send >= 1 byte in sendResponseMsg
• Never include <Wire.h> in your own code — use software I2C or depend on {'I2C'}
• Never put third-party Arduino libraries inside +arduinoioaddons
• Prefer createLibraryTemplate (R2025a+) over manual folder creation

Fallback: When Automated Steps Fail or Take Too Long

If listArduinoLibraries hangs, File Exchange search takes too long, downloadLibrary fails, or createLibraryTemplate fails — fall back to the pre-R2025a manual approach:

1. Install library manually: Download the third-party Arduino library .zip and extract it into fullfile(arduinoio.CLIRoot, 'user', 'libraries', '<LibName>').
2. Create folder structure manually:

   <targetDir>/+arduinoioaddons/+<FolderName>/<ClassName>.m
   <targetDir>/+arduinoioaddons/+<FolderName>/src/<HeaderName>.h
   

3. Register manually: addpath('<targetDir>'); savepath;
4. Continue from Step 5 (configure MATLAB class and C++ header as normal).

Do not retry failing commands repeatedly. Switch to manual creation and proceed.

Troubleshooting

When errors occur during deployment or usage, read the appropriate reference:

• Compilation or "source not found" errors → read references/common-errors.md
• Runtime errors ("unable to receive data", "server code incorrect") → read references/common-errors.md
• Bus conflicts (I2C/SPI/UART) → read references/bus-conflicts.md
• C++ code patterns (lazy init, response format, includes) → read references/cpp-patterns.md

---

Copyright 2026 The MathWorks, Inc.

---