Create and Configure C++ Header File
R2026bIf 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:
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);
See Also
Create Custom Arduino Library Package Folder | Create and Configure MATLAB Custom Arduino Library Class
