Create and Configure C++ Header File

R2026b

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

The C++ header requires you to override several properties and methods from the base class:

Note

Use only ASCII characters for file include path, C++ class name, and variables.

Install Third-Party Libraries

If you have third-party Arduino^® libraries for your Arduino hardware, use the arduinoio.customLibrary.downloadLibrary function to install the libraries. Run the function in the MATLAB^® Command Window with one of the following inputs:

Library name: Replace <LIBRARY_NAME> with the name of the library that you want to install.
```
libpath = arduinoio.customLibrary.downloadLibrary("<LIBRARY_NAME>")
```
GitHub^® repository URL: Replace <GIT_URL> with the repository URL.
```
libpath = arduinoio.customLibrary.downloadLibrary("<GIT_URL>")
```
Full path to a local ZIP file: Replace <ZIP_FILE_PATH> with the full path to the ZIP file.
```
libpath = arduinoio.customLibrary.downloadLibrary("<ZIP_FILE_PATH>")
```

LibraryBase

The LibraryBase class provides all the necessary functionality for executing the code from the MATLAB Custom Arduino Library Class. At the beginning of the C++ header file, include LibraryBase.h:

#include "LibraryBase.h"

You can include additional libraries following LibraryBase.h. Typically, these libraries are third-party Arduino libraries for your Arduino hardware that provide direct access to specific functionality.

Your base custom Arduino library class C++ header must extend the LibraryBase class:

class HelloWorld : public LibraryBase {
    ...
};

Note

If you have included additional third-party libraries, make sure the name of your custom Arduino library class (for example, HelloWorld.m) is not the same as the name of any of the classes defined in the third-party libraries.

Extending the LibraryBase.h class provides access to the appropriate methods and properties. The following diagram shows the typical method inheritance for a custom Arduino library:

Class hierarchy diagram showing LibraryBase.h as the parent class with property libName and methods getLibraryName, commandHandler, setup, and loop. Three child classes inherit from it: I2CBase.h, ServoBase.h, and myAddonDev.h, each overriding the same methods.

Constructor

The constructor defines the name of your library and registers it with the main Arduino program. Your class must override the default constructor method of the LibraryBase. The constructor uses the same name as the class and takes a reference to a MWArduinoClass object.

public:
   HelloWorld(MWArduinoClass& a)
   {
 	
      libName = "HelloWorldFolder/HelloWorld";
      	
      a.registerLibrary(this);
   }

The library name property, libName, must be the same string defined in the Library Specification of the MATLAB Custom Arduino Library Class:

<AddonNameFolder>/<AddonName>

The custom Arduino library is registered with the general MWArduinoClass object using the registerLibrary method. For example, the constructor below initializes a HelloWorld object that registers itself as a custom Arduino library with the MATLAB.

public:
        HelloWorld(MWArduinoClass& a)
        {            
            libName = "HelloWorldFolder/HelloWorld";            
            a.registerLibrary(this);
        }

Command Handler

The commandHandler method is the entry point for the commands that sendCommand sends to your MATLAB Custom Arduino Library Class. Your custom Arduino library class must override the default commandHandler method of the LibraryBase class.

public:
   void commandHandler(byte cmdID, byte* dataIn, unsigned int payloadSize)
   {            
   
      switch (cmdID){
               
         case 0x01:{  
            …                    
            sendResponseMsg(cmdID, val, 13);
            break;
         }

	  … // Other cases with appropriate cmdIDs  

         default:{
            // Do nothing
         }
      }
   }

The switch statement uses the command identifiers, cmdID, to determine the segment of code to execute. The cmdIDs must match those defined in the MATLAB Custom Arduino Library Class. At the end of each switch statement, the commandHandler must call the sendResponseMsg function:

sendResponseMsg(byte commandID, byte* dataOut, unsigned int payloadSize)

The data assigned to the input arguments dataOut and payloadSize is returned to the output arguments of the sendCommand function.

The MATLAB Custom Arduino Library Class holds execution of the sendCommand until either a sendResponseMsg executes or the timeout condition is reached.

The commandHandler method from below shows how a string, 'Hello from Arduino', can be created in the C++ code and returned to the MATLAB Custom Arduino Library Class through the commandHandler:

public:
        void commandHandler(byte cmdID, byte* dataIn, unsigned int payloadSize)
        {      
            switch (cmdID){
                
                case 0x01:{  
                    byte val [13] = "Hello from Arduino";
                    sendResponseMsg(cmdID, val, 13);
                    break;
                }

                default:{
                    // Do nothing
                }
            }
}

Setup

Use the setup method to set initial values. Your custom Arduino library class can override the default setup method of the LibraryBase class to initialize variables. The Enable Support for LCD Using Custom Arduino Library example overrides the default setup method to reset the cursor to the first row on initialization as shown:

public:
	void setup()
	{
		cursorRow=0;

	}

Loop

Use the loop method to perform certain repetitive tasks. Your custom Arduino library class can override the default loop method of the LibraryBase class. In the example below, if mcused is true, the controller remains on.

	void loop()
         {
          if(mcused)
          {
               controllerMW.ping();
          }
         }

Make sure to not use any blocking operation in the loop method.

Debugging

The LibraryBase also provides a convenient function, debugPrint, to display messages to the MATLAB command line to help in development of your custom Arduino library.

The debugPrint function uses the same syntax as the C++ printf function:

debugPrint(MSG_EXAMPLE_DEBUG);

The debug message must be declared in the C++ header file using the following syntax:

const char MSG_EXAMPLE_DEBUG[]     PROGMEM = "This is a debug message.\n";

where the string PROGMEM is the message displayed. Additional information can be included in the debug message using format specifiers. To display debugPrint messages in the MATLAB command line during run time, set the additional Name-Value property ‘trace’ in the arduino function:

The following example prints a debug message to the command line that includes the command ID, inserted using a format specifier.

const char MSG_EXAMPLE_DEBUG[]  PROGMEM = "Example debug message: cmdID %d\n";

...

debugPrint(MSG_EXAMPLE_DEBUG, cmdID);