6.2.1 Addon package directory

The addon architecture looks for plugins in the octave load path in a package directory called +arduinoioaddons

So this directory must be created somewhere within the paths that octave will check for functions.

In addition, the addon architecture expects plugins to be contained in a sub directory within the +arduinoioaddons folder. The subdirectory must begin with a ’+’.

Multiple plugin .m files can be within the same sub directory.

6.2.2 Addon package .m file

The Matlab interface file within the addon directory provides the Matlab interface for the arduino code as well as provides information about the addon.

Class inheritance and required properties

The interface file must be a subclass of arduinoio.LibraryBase and must contain some constant properties values that provide the information.

A minimum example of required is below:

classdef MyAddon1 < arduinoio.LibraryBase
  properties(Access = protected, Constant = true)
    LibraryName = 'MyAddons/MyAddon1';
    CppHeaderFile = fullfile(arduinoio.FilePath(mfilename('fullpath')), 'MyAddon1.h');
    CppClassName = 'MyAddon1';
  endproperties
  .
  .
  .
endclassdef

The following constant properties can be set within the addon:

LibraryName

(Required) The name of the addon. My convention this is usually the directoryname / theclassname

CppHeaderFile

(Required) The header file for the arduino code

CppSourceFile

(Optional) The source file (if any) for the arduino code

CppClassName

(Required) The classname used within the cppheaderfile for the arduino library

DependantLibraries

(Optional) Any additional addons or cores that are needed for this library to be used

ArduinoLibraryHeaderFiles

(Optional) Any additional header files that need to be included

Class constructor

The Matlab class constructor will be called from the addon function when creating a instance of the addon and should initialize at least two properties in inherited from arduinoio.LibraryBase:

1. Parent should be set to the first input argument (the arduino class)
2. Pins should be set to a list of pins that are used for the plugin

classdef MyAddon1 < arduinoio.LibraryBase
  .
  .
  methods
    function obj = MyAddon1(parentObj, varargin)
      obj.Parent = parentObj;
      # no pins being used
      obj.Pins = [];
      # send any command to the arduino during setup ?
    endfunction
    .
    .
  endmethods
endclassdef

Class functions

The class functions will usually communicate to the arduino and use the response for what is returned to the user.

By convention, the commands sent to the arduino are defined as constants in the class file but do not have to be.

classdef MyAddon1 < arduinoio.LibraryBase
  properties(Access = private, Constant = true)
    INIT_COMMAND = hex2dec('00');
    FUNC1_COMMAND = hex2dec('01');
  endproperties
  .
  .
  methods
    function obj = MyAddon1(parentObj, varargin)
      obj.Parent = parentObj;
      # no pins being used
      obj.Pins = [];
      # send any command to the arduino during setup ?
      sendCommand(obj.Parent, obj.LibraryName, obj.INIT_COMMAND, []);
    endfunction

    function retval = func1(obj)
       cmdID = obj.FUNC1_COMMAND;
       retval = sendCommand(obj.Parent, obj.LibraryName, cmdID, []);
    endfunction
    .
    .
  endmethods
endclassdef

See also: sendCommand.

6.2.3 Addon package header file

The header file should contain a class that matches the functionally and information of the matlab file and provides the ability to register the code on the arduino.

The following things should occur in the arduino class files:

1. The class name within the file must be the same as the one set in the .m file CppClassName property.
2. The libName variable must be the same as the LibraryName property.
3. The constructor should call registerLibrary
4. the commandHandler function to act on cmdID values that match the commands that will be sent from .m file and send data back using sendResponseMsg
5. on receiving unknown cmdID values, the commandHandler should use sendUnknownCmdIDMsg

An example, matching the previous .m file code is below:

#include "LibraryBase.h"

#define MYADDON1_INIT  0x00
#define MYADDON1_FUNC1 0x01

class MyAddon1 : public LibraryBase
{
  uint8_t cnt;
public:
  MyAddon1(OctaveArduinoClass& a)
  {
    libName = "MyAddons/MyAddon1";
    a.registerLibrary(this);
  }
  void commandHandler(uint8_t cmdID, uint8_t* data, uint8_t datasz)
  {
    switch (cmdID)
      {
      case MYADDON1_INIT:
        {
          cnt = 0;
          sendResponseMsg(cmdID, 0,0);
          break;
        }
      case MYADDON1_FUNC1:
        {
          // func 1 is just returning a uint8 count of number of times called
          cnt ++;
          sendResponseMsg(cmdID, &cnt, 1);
          break;
        }
      default:
        {
          // notify of invalid cmd
          sendUnknownCmdIDMsg();
        }
      }
  }
}
;

The body of functions can be in the CppSourceFile file is it is defined or within the header file as illustrated above.

6.2.4 Verify octave can see the addon

Use the listArduinoLibaries command to verify that the new addon appears in the list of known libraries.

If it does not, ensure that the +arduinoioaddons directory is within one of the octave class paths, and that the directory structure and inheritance requirements have been met.

6.3.1 Programming the arduino with the addon

To use a addon, the code must be programmed onto the arduino.

Using the libraries command, when creating a arduino object, the arduino can be reprogrammed if the library does not already exist on the arduino.

  ar = arduino([],[], 'libraries', 'MyAddons/MyAddon1', 'forcebuild', true)

The libraries property of the arduino object should list the libraries programmed on the arduino.

Alternatively, the library can be added using the libraries property and arduinosetup

See also: arduino, arduinosetup.

6.3.2 Creating a addon object

An object of the addon type can be created using the addon command.

  ar = arduino([],[], 'libraries', 'MyAddons/MyAddon1', 'forcebuild', true)
  obj = addon(ar, "MyAddons/MyAddon1");