Matthew Chea, MathWorks
Learn how to write a custom Arduino® add-on library. Using the DHT22 temperature and humidity sensor as an example, learn how to create the add-on library to interface your Arduino hardware with MATLAB®. A custom Arduino add-on allows you to use your Arduino hardware and attach shields or sensors easily in MATLAB.
This video shows how to create a custom Arduino add-on library. As an example, I’ll show you how to write an add-on library for the DHT22 temperature and humidity sensor.
An add-on library allows you to interface your MATLAB code with the Arduino hardware.
Before we start, make sure you have the MATLAB Arduino Support Package installed and also downloaded the third-party Arduino libraries you will use and drag them into your Arduino/Libraries folder. Depending on your operating system, the default folder path may be different.
For the add-on library, you only need to write two files: a C++ header file which is downloaded to the Arduino, and the second file is a MATLAB class to send commands to the Arduino and get responses.
There are three steps to create an add-on. The first step is to set up the folders. The next step is to write the C++ Header File. And the last step to write the MATLAB Add-On Class file.
Firstly, you must create a folder called “+arduinoioaddons” with a subfolder whose name starts with a “+”. This is where you will keep your MATLAB Class File and another subfolder called “src” which has the C++ header file.
C++ Header File
Now let’s look at how to write the C++ header file.
Be sure to include “LibraryBase.h” to extend the class needed to create your add-on library.
Also include any header files needed for your custom code. In my case, I included "DHT.h".
Next, define a set of command IDs for later use, to deal with commands sent from MATLAB.
As you can see, I have defined these four command IDs for my sensor.
Now, define your add-on class and make it inherit from LibraryBase since it is a required for the add-on framework.
You can also define any members needed for your class.
For the constructor, make sure the name matches your class, then define the name of your add-on library.
Next override the commandHandler method, which is called every time MATLAB sends a command to the Arduino. We are past the command ID, dataIn, and the size of that data.
The Arduino uses the command ID to determine which method to execute. Here you can wrap the third-party methods. In my case, I wrap methods from the Adafruit DHT library.
When you send a command from MATLAB, you can pass data to use here. In this example, I had MATLAB send the sensor ID and the pin to create the new sensor object.
It is required by the framework that for every command, you must send data back to MATLAB using the method sendResponseMsg().
If you'd like to get debug information, you can also define debug strings and send the information back to MATLAB using debugPrint().
In my code, I do the same for all the command ID’s: create, delete, read temperature, and read humidity.
MATLAB Add-On Class
Now you need to write the MATLAB class. Create the file in your +Adafruit folder.
This class must inherit from LibraryBase. Set these properties as the same command IDs we used in the header file.
These properties are also required for the framework. Replace the LibraryName with your library, add any dependent and third-party libraries, and change these to match your C++ header file and class name.
You can also add more properties, depending on what you need for your add-on.
Write a constructor to initialize the add-on. You must assign the Arduino object as the add-on object’s parent, which is inherited from LibraryBase.
Here I do some error handling. Then I initialized the Pin property, configured the pin to Digital Input, and called a method to create the sensor.
For each method you want to execute on the Arduino, you must use sendCommand(). You must pass the command ID, library name, and any necessary data to the Arduino. Here I pass the sensor ID and terminal.
To receive data back from the Arduino, save the returned data from sendCommand(). For example, in the readHumidity method, I save the humidity value that is returned.
After writing those two files, in the command window use addpath() to add the location of your add-on folder. You can check by using the command listArduinoLibraries to see if your library is available.
Connect the Arduino hardware to MATLAB using the arduino() method with the port, board, and library. To see the debug messages, use ‘TraceOn’, true.
a = arduino(‘com8’, ‘Uno’, ‘libraries’, ‘Adafruit/DHT22’, ‘TraceOn’, true)
Now connect to the sensor using the addon() method. In my case, I will pass the Arduino object, library, and pin.
s = addon(a, ‘Adafruit/DHT22’, ‘A0’)
We can call the readTemperature(s) and readHumidity(s) methods to read the measurements from the sensor and use the data in MATLAB.
That’s all you need to do to write your own add-on libraries.
For more help, refer to the documentation on how to create a custom add-on library for Arduino.