Create and Configure MATLAB Custom Arduino Library Class

R2026b

If you used arduinoio.customLibrary.createLibraryTemplate, a MATLAB® class file was generated automatically. This section describes how to customize it or create one from scratch.

The MATLAB class for your library must inherit from the matlabshared.addon.LibraryBase class:

classdef MyAddon < matlabshared.addon.LibraryBase
    …
end

Use only ASCII characters for class, package, function, script, and variable names in your MATLAB class.

The matlabshared.addon.LibraryBase class includes a variety of properties and methods. The following diagram shows a typical class inheritance for your custom Arduino® library:

Class hierarchy diagram showing LibraryBase as the parent class with properties Parent, LibraryName, DependentLibraries, LibraryHeaderFiles, CppHeaderFile, CppClassName, and method sendCommand. AddonBase inherits from LibraryBase. Two custom classes, mySensor.m and myShield.m, inherit from AddonBase with a zero-to-many relationship.

To implement your MATLAB custom Arduino library class, you must override the following properties and method:

Depending on the design of your custom Arduino library, you might also be required to override the following property and method:

Command Identifiers

The command identifiers, typically named commandID, are 8-bit hexadecimal values. The sendCommand function uses the commandID to provide a consistent mapping to the commandHandler method in the C++ Header File.

Use the following syntax to specify a commandID property in your MATLAB class:

properties(Access = private, Constant = true)
    ADDON_OPERATION = hex2dec(cmdID)
    …
end

The Enable Support for LCD Using Custom Arduino Library example shows the commandIDs in the LCDAddon.m classdef file as:

properties(Access = private, Constant = true)
    LCD_CREATE     = hex2dec('00')
    LCD_INITIALIZE = hex2dec('01')
    LCD_CLEAR      = hex2dec('02')
    LCD_PRINT      = hex2dec('03')
    LCD_DELETE     = hex2dec('04')
end

Similarly, the LCDAddon.h defines the commandIDs:

#define LCD_CREATE      0x00
#define LCD_INITIALIZE  0x01
#define LCD_CLEAR       0x02
#define LCD_PRINT       0x03
#define LCD_DELETE      0x04

For consistent behavior, the command identifiers in the MATLAB class must match the commandIDs used in the commandHandler method from the C++ header file.

Library Specification

The library specification defines the name of the custom Arduino library and locations of the required C++ source files and libraries. Set the library specification with this code:

properties(Access = protected, Constant = true)
    LibraryName = 'LCDAddonFolder/LCDAddon'
    DependentLibraries = {}
    LibraryHeaderFiles = {}
    CppHeaderFile = fullfile(arduinoio.FilePath(mfilename('fullpath')), 'src', 'LCDAddon.h')
    CppClassName = 'LCDAddon'
end

The five library specification properties must be defined as in matlabshared.addon.LibraryBase or as shown in the following table.

PropertyDescription
LibraryName

Name of your library as a string. The string uses the same syntax as your library folder structure: <AddonFolder>/<AddonName>

DependentLibraries

Other libraries required by your library, specified as a cell array of strings.

LibraryHeaderFiles

Any C++ header files needed by your custom Arduino library. See LibraryBase for details on including header files. Provide the absolute path if you have created a new header file or provide the path with respect to the Arduino CLI library folder structure if you are using the Arduino header files. Use arduinoio.customLibrary.downloadLibrary to install third-party libraries.

CppHeaderFile

Full path and name of the C++ header file as a string.

CppClassName

Name of the class in your C++ header file as a string.

The sample library shows a typical naming of these properties:

properties(Access = protected, Constant = true)
    LibraryName = 'LCDAddonFolder/LCDAddon'
    DependentLibraries = {}
    LibraryHeaderFiles = 'LiquidCrystal/LiquidCrystal.h'
    CppHeaderFile = fullfile(arduinoio.FilePath(mfilename('fullpath')), 'src', 'LCDAddon.h')
    CppClassName = 'LCDAddon'
end

If your custom Arduino library has a C++ header file specified in LibraryHeaderFiles, make sure the CppClassName is not the same as the name of any of the classes defined in the header file. In this example, LCDAddon is different from the C++ class defined in LiquidCrystal.h.

If your custom Arduino library requires I2C support, set the property as follows: 

DependentLibraries = {'i2c'};

Constructor

The constructor for your custom Arduino library initializes the add-on object in two ways:

  • Parent the add-on object to the Arduino object.

  • Define the set of hardware pins used by the add-on

Here is the minimum form of the constructor:

methods

    function obj = AddonName(parentObj)            
        obj.Parent = parentObj;
    end

    …
end

Typically, the constructor registers library resources with the parent Arduino object and performs checks to prevent resource usage conflicts. The constructor in the Enable Support for LCD Using Custom Arduino Library example shows how a resource can be checked and then acquired to prevent two LCD custom Arduino libraries existing simultaneously:

% InputPins is user input and contains the pins that connect the LCD and the arduino
function obj = LCDAddon(parentObj,varargin)
             if(nargin ~= 7)
                 matlabshared.hwsdk.internal.localizedError('MATLAB:narginchk:notEnoughInputs');
             end  

             try
                p = inputParser;
                addParameter(p, 'RegisterSelectPin',[]);
                addParameter(p, 'EnablePin', []);
                addParameter(p, 'DataPins', []);
                parse(p, varargin{1:end});
             catch e
                 throwAsCaller(e);
             end
            obj.Parent = parentObj;            
            obj.RegisterSelectPin = p.Results.RegisterSelectPin;
            obj.EnablePin = p.Results.EnablePin;
            obj.DataPins = p.Results.DataPins;
            inputPins = [cellstr(obj.RegisterSelectPin) cellstr(obj.EnablePin) obj.DataPins];
            obj.Pins = inputPins;
            count = getResourceCount(obj.Parent,obj.ResourceOwner);
            % Since this example allows implementation of only 1 LCD
            % shield, error out if resource count is more than 0
            if count > 0
                error('You can only have 1 LCD shield');
            end 
            incrementResourceCount(obj.Parent,obj.ResourceOwner);    
            createLCD(obj,inputPins);
        end

Destructor

By default, you do not need to write a destructor for your custom Arduino library. The destructor from the matlabshared.addon.LibraryBase class is called implicitly. Custom Arduino libraries that use hardware resources from the parent Arduino object or allocate memory in the C++ header must include a destructor to release these resources.

Warning

If you do not release resources in the destructor, memory leaks and failures can occur when you create a new instance of your custom Arduino library.

A destructor for your custom Arduino library class must:

  • Override the delete method of the matlabshared.addon.LibraryBase class.

  • Execute a command in your C++ commandHandler method to deallocate any memory resources used by your library.

  • Not throw an error or exception. To prevent errors or exceptions being thrown during the destructor, wrap the contents in a try-catch statement.

The destructor in the Enable Support for LCD Using Custom Arduino Library example shows how a resource can be checked and released safely:

methods(Access = protected)
        function delete(obj)
            try
                parentObj = obj.Parent;
                % Clear the pins that have been configured to the LCD shield
                inputPins = [cellstr(obj.RegisterSelectPin) cellstr(obj.EnablePin) obj.DataPins];
                for iLoop = inputPins
                    configurePinResource(parentObj,iLoop{:},obj.ResourceOwner,'Unset');
                end
                % Decrement the resource count for the LCD
                decrementResourceCount(parentObj, obj.ResourceOwner);
                cmdID = obj.LCD_DELETE;
                inputs = [];
                sendCommand(obj, obj.LibraryName, cmdID, inputs);
            catch
                % Do not throw errors on destroy.
                % This may result from an incomplete construction.
            end
        end  
    end

Resource Ownership

Your custom library can optionally specify certain hardware resources that are unique and cannot be shared. The Enable Support for LCD Using Custom Arduino Library can only have a single instance because you can attach only one LCD shield to the Arduino device at a time.

Note

Explicitly defining hardware resource ownership of your custom Arduino library prevents resource acquisition and usage conflicts during run time.

You can specify the resource ownership through the following set of properties in your custom Arduino library class:

properties(Access = private)
    ResourceOwner = 'LCDAddonFolder/LCDAddon;
end

See Also

|