arduino

Connection to the Arduino hardware

Description

An arduino object represents a connection to Arduino^® hardware. Use the arduino function to connect Arduino hardware to MATLAB^®. After you create the object, you can program your hardware and use custom add-on libraries directly from MATLAB using the object functions.

Creation

Syntax

a = arduino

a = arduino(port,board)

a = arduino(___,Name,Value)

a = arduino(btaddress,board)

a = arduino(btname,board)

a = arduino(ipaddress,board)

a = arduino(ipaddress,board,tcpipport)

Description

a = arduino recreates the last successful connection to the Arduino hardware. If there is no last successful connection or that connection failed, it creates a connection to the first official Arduino hardware connected to your host computer via USB.

a = arduino(port,board) creates a connection to Arduino hardware on the specified serial port. The serial port can be either a USB serial port or the Adafruit^® EZ-Link Bluetooth^® serial port, depending on how you have configured the Arduino hardware.

a = arduino(___,Name,Value) creates a connection with additional options specified by one or more Name,Value pair arguments.

a = arduino(btaddress,board) uses the Bluetooth address of the HC-05 or HC-06 device to create a connection to Arduino hardware.

a = arduino(btname,board) uses the name of the HC-05 or HC-06 Bluetooth device to create a connection to the Arduino hardware.

a = arduino(ipaddress,board) creates a connection to the WiFi supported Arduino boards at the specified IP address.

a = arduino(ipaddress,board,tcpipport) creates a connection to the WiFi supported Arduino boards at the specified IP address and TCP/IP remote port.

Input Arguments

port — Hardware port

character vector | string array

Hardware port that your Arduino is connected to, specified as a character vector or string array. The port can be a USB serial port or the Adafruit EZ-Link Bluetooth serial port, depending on how you have configured the Arduino hardware. To identify the USB serial port number, see Find Arduino Port on Windows, Mac, and Linux. To identify the Bluetooth device address or serial port, see Pair a Bluetooth Device and Retrieve the Bluetooth Device Address. This argument can be specified on its own if connected via USB serial port, or with a board name.

Example: a = arduino('COM5')

board — Name of Arduino enabled board

character vector | string array

Name of the Arduino enabled board, specified as a character vector or string array. This argument must be specified with a valid serial port, IP address, Bluetooth address, or Bluetooth name. See Supported Boards for all supported boards.

Example: a = arduino('COM5','Uno') creates a connection to an Arduino Uno board using port 5.

btaddress — Bluetooth address of the HC-05 or HC-06 device

character vector | string array

Bluetooth address of the HC-05 or HC-06 device, specified as a character vector or string array of the form btspp:// followed by the 12-digit hexadecimal value of the address. To identify the Bluetooth device address, see Pair a Bluetooth Device and Retrieve the Bluetooth Device Address.

Example: a = arduino('btspp://98d331fb3b77','Uno') creates a Bluetooth connection to an Arduino Uno board.

btname — Bluetooth name of the device

character vector | string array

Bluetooth name of the device, specified as a character vector or string array.

Example: a = arduino('HC-05','Uno') creates a wireless Bluetooth connection to an Arduino Uno board that uses an HC-05 Bluetooth device.

ipaddress — IP address of Arduino board with WiFi support

character vector | string array

IP address of the Arduino board with WiFi support, specified as a character vector or string array.

Example: a = arduino('192.168.1.15','MKR1000') creates a WiFi connection to an Arduino MKR1000 board that uses the IP address 192.168.1.15.

tcpipport — TCP/IP port on Arduino board

numeric

TCP/IP port on the Arduino board, specified as a number.

Example: a = arduino('192.168.1.15','MKR1000',9500) creates a WiFi connection to an Arduino MKR1000 board that uses the TCP/IP port at 9500.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Note

If you are connecting an Arduino board using a wireless network, you cannot specify Name,Value arguments.

Example: a = arduino('COM3','Uno','Libraries','I2C')

'Libraries' — Name of Arduino library

{'I2C' 'Servo' 'SPI'} (default) | 'Adafruit/MotorShieldV2' | 'ShiftRegister' | character vector | cell array of character vectors

Name of the Arduino library, specified as the comma-separated pair consisting of 'Libraries' and a character vector or a cell array of character vectors. Libraries installed by default extend the Arduino environment.

Note

When you first connect to your Arduino hardware, your Arduino connection is created with these default libraries {'I2C' 'Servo' 'SPI'}. However, if you create an Arduino connection with libraries other than the defaults, your Arduino connection will have only the libraries that you specified, even after you disconnect and reconnect your Arduino hardware.

Example: a = arduino('COM9','Uno','Libraries','spi') limits the environment to the specified library.

Example: a = arduino('COM9','Uno','Libraries','Adafruit/MotorShieldV2') limits the environment to the Adafruit Motor Shields V2 library and its dependent libraries.

Example: a = arduino('COM9','Uno','Libraries','ShiftRegister') limits the environment to shift register library.

'AnalogReferenceMode' — Type of reference voltage

internal (default) | external | character vector

Type of reference voltage, specified as internal or external. In the external mode, an external voltage is applied at the AREF pin. In the internal mode, the internal voltage supported by the Arduino boards is used.

See Supported Boards for supported internal voltages of the Arduino boards.

Note

In the external mode, you must specify the external voltage applied at the AREF pin using AnalogReference. In the internal mode, you can specify the internal voltage supported on the boards. If you do not specify a voltage in the internal mode, the default internal reference voltage of the Arduino boards is used.

Example: a = arduino('COM9','Uno','AnalogReferenceMode','external' 'AnalogReference',1.1) sets the reference voltage externally to 1.1V.

'AnalogReference' — Analog reference voltage

double

Reference voltage of the analog input, specified as a double.

Before using an external reference voltage on the AREF pin, ensure the following for safety:

• Connect the external voltage to the AREF pin through a 5K resistor to prevent damaging the board. If AnalogReferenceMode is internal and a reference voltage is still connected externally at the AREF pin, you will short the internal reference voltage and the AREF pin, thus damaging the board.

• Do not use a voltage less than 0V or more than the maximum voltage supported by the boards.

Note

When you change the analog reference voltage, the output of readVoltage may not be accurate. Run readVoltage until you see the expected value. For Arduino Uno and Mega boards, see Incorrect readVoltage results.

Example: a = arduino('COM9','Uno','AnalogReferenceMode','external' 'AnalogReference',1.1) sets the reference voltage externally to 1.1V.

'ForceBuildOn' — Reprogramming of the Arduino board

false (default) | true

If 'ForceBuildOn' is not set as true, MATLAB does not reprogram the Arduino board and uses the existing Arduino server if the libraries that you specify match with libraries that are already on the existing Arduino server. Use this setting to update the Arduino server with different source code when you work with custom Arduino libraries.

Example: a = arduino('COM9','Uno','Libraries','CustomLibrary','ForceBuildOn',true) reprograms the Arduino board using your latest C++ source code for CustomLibrary.

Note

MATLAB does not reprogram the Arduino board and uses the existing Arduino server if the libraries that you specify match with libraries that are already on the existing Arduino server.

'TraceOn' — Program log and Arduino commands log

false (default) | true

Program log and Arduino commands log, specified as the comma-separated pair consisting of 'TraceOn' and either false or true. If you fail to connect to your Arduino board, set 'TraceOn' to true to print compilation and upload errors of Arduino IDE at the MATLAB command window. You can also set 'TraceOn' to true to print the Arduino commands executed on the Arduino board for each MATLAB command.

Example: a = arduino('COM9','Uno','TraceOn',true)

Note

When creating the I2C device object, and for the serial device functions read and write, the TraceOn with the tab completion is not supported.

'BaudRate' — Bit transmission rate

The rate at which information is transferred in the communication channel. For Arduino Pro Mini, and Digital Sandbox use the BaudRate value of 57600. For all the other boards listed in Find Board Name use the BaudRate value of 115200.

Note

Ensure that the Arduino board you are using supports the BaudRate before creating the arduino object with the value other than the default value.

Example: a = arduino('COM9','Uno','BaudRate',115200);

Dependencies

For streaming data from multiple sensors with Navigation Toolbox™ or Sensor Fusion and Tracking Toolbox™, set the BaudRate to 921600. This change on Arduino enables MATLAB to acquire real-time data from the GPS receivers and IMU sensors. For other applications use the default BaudRate of the Arduino board.

Properties

Port — Hardware port

'COM4' | 'COM5' | character vector | ...

This property is read-only.

Hardware port that your Arduino is connected to, specified as a character vector or string array. The port can be a USB serial port or the Adafruit EZ-Link Bluetooth Bluetooth serial port, depending on how you have configured the Arduino hardware. Specify the port when you create the arduino object. To identify the USB serial port number, see Find Arduino Port on Windows, Mac, and Linux. To identify the Bluetooth serial port, see Pair a Bluetooth Device and Retrieve the Bluetooth Device Address.

Example:

>> a.Port

ans =

    'COM4'

Data Types: char

Board — Name of Arduino enabled board

'Uno' | 'Due' | 'Mega2560' | character vector | ...

This property is read-only.

Name of the Arduino enabled board, specified as a character vector or string array. It is the type of Arduino hardware connected to your system. Specify the board type when you create the arduino object. See Supported Boards for all supported boards.

Example:

>> a.Board

ans =

    'Uno'

Data Types: char

AvailablePins — Pins available on Arduino device

{'D2-D13', 'A0-A5'} | cell array of character vectors | ...

This property is read-only.

Pins available on Arduino device connected to your system, specified as cell array of character vectors.

Example:

a.AvailablePins

ans =

  1×18 cell array

  Columns 1 through 12

    {'D2'}    {'D3'}    {'D4'}    {'D5'}    {'D6'}    {'D7'}    {'D8'}    {'D9'}    {'D10'}    {'D11'}    {'D12'}    {'D13'}

  Columns 13 through 18

    {'A0'}    {'A1'}    {'A2'}    {'A3'}    {'A4'}    {'A5'}

Data Types: cell

AvailableDigitalPins — Digital pins available on Arduino device

{'D2-D13', 'A0-A5'} (default) | cell array of character vectors

This property is read-only.

Digital pins available on Arduino device connected to your system, specified as cell array of character vectors.

Example:

a.AvailableDigitalPins

ans =

  Columns 1 through 12

    {'D2'}    {'D3'}    {'D4'}    {'D5'}    {'D6'}    {'D7'}    {'D8'}    {'D9'}    {'D10'}    {'D11'}    {'D12'}    {'D13'}

  Columns 13 through 18

    {'A0'}    {'A1'}    {'A2'}    {'A3'}    {'A4'}    {'A5'}

Data Types: cell

AvailablePWMPins — PWM pins available on Arduino device

{'D3', 'D5-D6', 'D9-D11'} (default) | cell array of character vectors

This property is read-only.

PWM pins available on Arduino device connected to your system, specified as cell array of character vectors.

Example:

a.AvailablePWMPins

ans =

  {'D3'}    {'D5'}    {'D6'}    {'D9'}    {'D10'}    {'D11'}

Data Types: cell

AvailableAnalogPins — Analog pins available on Arduino device

{'A0-A5'} (default) | cell array of character vectors

This property is read-only.

Analog pins available on Arduino device connected to your system, specified as cell array of character vectors.

Example:

a.AvailableAnalogPins

ans =

  1×6 cell array

    {'A0'}    {'A1'}    {'A2'}    {'A3'}    {'A4'}    {'A5'}

Data Types: cell

AvailableI2CBusIDs — Analog pins available on Arduino device

0 (default) | numeric

This property is read-only.

The ID of I2C bus available on Arduino device connected to your system.

Example:

a.AvailableI2CBusIDs

ans =

  [0]

Data Types: double

AvailableSerialPortIDs — Serial ports available on Arduino device

numeric

The serial bus ID available on Arduino device connected to your system.

Note

The Arduino Mega2560, and MegaADK boards have three serial ports available while the Arduino Leonardo, Micro, MKR1000, and MKR1010 have one serial port available.

Example:

a.AvailableSerialPortIDs

ans =

  1

Dependencies

This property is valid only when the serial library is used to create a connection to the Arduino hardware.

Data Types: double

Libraries — Installed Arduino add-on libraries

{'I2C', 'Servo', 'SPI'} (default) | 'Adafruit/MotorShieldV2' | 'ShiftRegister' | character vector | cell array of character vectors

This property is read-only.

Installed Arduino add-on libraries downloaded to your hardware, specified as a character vector or cell array of character vectors. Check the available libraries with listArduinoLibraries to specify the add-on library you want to use.

Example:

a.Libraries

ans =

  1×3 cell array

    {'I2C'}    {'Servo'}    {'SPI'}

Data Types: cell | char

AnalogReferenceMode — Type of reference voltage

internal (default) | external | character vector

This property is read-only.

Type of reference voltage, specified as internal or external. In the external mode, an external voltage is applied at the AREF pin. In the internal mode, the internal voltage supported by the Arduino boards is used.

In the external mode, you must specify the external voltage applied at the AREF pin using AnalogReference. In the internal mode, you can specify the internal voltage supported on the boards. If you do not specify a voltage in the internal mode, the default internal reference voltage of the Arduino boards is used.

Example:

a.AnalogReferenceMode

ans =

    'internal'

AnalogReference — Analog reference voltage

double

This property is read-only.

Reference voltage of the analog input, specified as a double.

Before using an external reference voltage on the AREF pin, ensure the following for safety:

• Connect the external voltage to the AREF pin through a 5K resistor to prevent damaging the board. If AnalogReferenceMode is internal and a reference voltage is still connected externally at the AREF pin, you will short the internal reference voltage and the AREF pin thus damaging the board.

• Do not use a voltage less than 0V or more than the maximum voltage supported by the boards.

See Supported Boards for supported internal voltages of the Arduino boards.

When you change the analog reference voltage, the output of readVoltage may not be accurate. Run readVoltage until you see the expected value. For Arduino Uno and Mega boards, see Incorrect readVoltage results.

Example:

a.AnalogReference

ans =

    5.0

Supported Boards

The board input argument currently support these boards:

Arduino Board	Input Argument	WiFi Support	Supported Internal Voltage (V)
Arduino Uno	'Uno'	No	5.0(default), 1.1
Arduino Due	'Due'	No	3.3(default)
Arduino Mega 2560	'Mega2560'	No	5.0(default), 1.1, 2.56
Arduino Leonardo	'Leonardo'	No	5.0(default), 2.56
Arduino Mega ADK	'MegaADK'	No	5.0(default), 1.1, 2.56
Arduino Micro	'Micro'	No	5.0(default), 2.56
Arduino MKR1000	'MKR1000'	Yes	3.3(default), 1.0, 1.65, 2.23
Arduino MKR WiFi1010	'MKR1010'	Yes	3.3(default), 1.0, 1.65, 2.23
Arduino MKR Zero	'MKRZero'	No	3.3(default), 1.0, 1.65, 2.23
Arduino Nano 3.1	'Nano3'	No	5.0(default), 1.1
Arduino Nano 33 IoT	'Nano33IoT'	Yes	3.3(default), 1.0, 1.65, 2.23
Arduino Pro Mini	ProMini328_3V ProMini328_5V	No	3.3(default), 1.1 5.0(default), 1.1
Sparkfun Digital Sandbox	DigitalSandbox	No	3.3(default), 1.1

Object Functions

The object functions device, shiftRegister, rotaryEncoder, servo, addon , and ultrasonic are used to create objects for each of their respective peripheral devices. Other functions are used to interact with the pins on your Arduino hardware.

device	Connection to device on I2C bus on Arduino hardware
shiftRegister	Connection to shift register on Arduino hardware
rotaryEncoder	Connection to quadrature encoder on Arduino hardware
servo	Connection to servo motor on Arduino hardware
addon	Connection to add-on device for Arduino hardware
ultrasonic	Connection to ultrasonic sensor on Arduino hardware

configurePin	Set Arduino pin mode
readDigitalPin	Read data from digital pin on Arduino hardware
writeDigitalPin	Write data to digital pin on Arduino hardware
writePWMVoltage	Generate PWM signal with specified voltage on digital pin
writePWMDutyCycle	Generate PWM signal with specified duty cycle on digital pin
playTone	Play tone on piezo speaker using digital pin
readVoltage	Read voltage from analog pin on Arduino hardware
scanI2CBus	Scan I2C bus on Arduino hardware for device address

Examples

Connect to Arduino Hardware

Autodetect an Arduino Uno.

a = arduino()

a = 
  arduino with properties:

                  Port: 'COM9'
                 Board: 'Uno'
         AvailablePins: {'D2-D13', 'A0-A5'}
  AvailableDigitalPins: {'D2-D13', 'A0-A5'}
      AvailablePWMPins: {'D3', 'D5-D6', 'D9-D11'}
   AvailableAnalogPins: {'A0-A5'}
    AvailableI2CBusIDs: [0]
             Libraries: {'Adafruit/BNO055', 'I2C'}
Show all properties

Specify Port Number and Arduino Board Type

Connect to an Arduino Uno on port 9. The port and board names depend on your configuration.

a = arduino('COM9','Uno')

Updating server code on board Uno (COM9). This may take a few minutes.

a = 
  arduino with properties:

                  Port: 'COM9'
                 Board: 'Uno'
         AvailablePins: {'D2-D13', 'A0-A5'}
  AvailableDigitalPins: {'D2-D13', 'A0-A5'}
      AvailablePWMPins: {'D3', 'D5-D6', 'D9-D11'}
   AvailableAnalogPins: {'A0-A5'}
    AvailableI2CBusIDs: [0]
             Libraries: {'SPI'}
Show all properties

Specify Bluetooth Address and Arduino Board Type

Connect to an Arduino Uno using Bluetooth. Instrument Control Toolbox software is required to connect to an HC-05 or HC-06 Bluetooth module.

a = arduino('btspp://98D331FB3B77','Uno')

a = 

  arduino with properties:

           DeviceAddress: 'btspp://98D331FB3B77'
                   Board: 'Uno' 
           AvailablePins: {'D2-D13', 'A0-A5'} 
    AvailableDigitalPins: {'D2-D13', 'A0-A5'} 
        AvailablePWMPins: {'D3', 'D5-D6', 'D9-D11'} 
     AvailableAnalogPins: {'A0-A5'} 
      AvailableI2CBusIDs: [0] 
               Libraries: {'I2C', 'Servo', 'SPI'}  
  Show all properties
               

Specify Bluetooth Device Name and Arduino Board Type

Connect to an Arduino Uno using Bluetooth. Instrument Control Toolbox software is required to connect to an HC-05 or HC-06 Bluetooth module.

a = arduino('HC-06','Uno')

a = 

  arduino with properties:

           DeviceAddress: 'HC-06'
                   Board: 'Uno' 
           AvailablePins: {'D2-D13', 'A0-A5'} 
    AvailableDigitalPins: {'D2-D13', 'A0-A5'} 
        AvailablePWMPins: {'D3', 'D5-D6', 'D9-D11'} 
     AvailableAnalogPins: {'A0-A5'} 
      AvailableI2CBusIDs: [0]
               Libraries: {'I2C', 'Servo', 'SPI'}
  Show all properties

Specify IP Address to Connect to Arduino MKR1000 Board

Connect to an Arduino MKR1000 board using WiFi.

a = arduino('10.10.10.55','MKR1000')

a = 
  arduino with properties:

         DeviceAddress: '10.10.10.55'
                  Port: 9500
                 Board: 'MKR1000'
         AvailablePins: {'D0-D14', 'A0-A6'}
  AvailableDigitalPins: {'D0-D14', 'A0-A6'}
      AvailablePWMPins: {'D0-D8', 'D10', 'A3-A4'}
   AvailableAnalogPins: {'A0-A6'}
    AvailableI2CBusIDs: [0]
AvailableSerialPortIDs: [1]
             Libraries: {'I2C', 'SPI', 'Serial', 'Servo'}

Specify IP Address and TCP/IP Port to Connect to an Arduino MKR1000 Board

a = arduino('10.10.10.55','MKR1000',9500)

a = 
  arduino with properties:

         DeviceAddress: '10.10.10.55'
                  Port: 9500
                 Board: 'MKR1000'
         AvailablePins: {'D0-D14', 'A0-A6'}
  AvailableDigitalPins: {'D0-D14', 'A0-A6'}
      AvailablePWMPins: {'D0-D8', 'D10', 'A3-A4'}
   AvailableAnalogPins: {'A0-A6'}
    AvailableI2CBusIDs: [0]
AvailableSerialPortIDs: [1]
             Libraries: {'I2C', 'SPI', 'Serial', 'Servo'}

Connect to an Arduino Board on a Mac

Connect to an Arduino Uno on port /dev/tty.usbmodem1421.

a = arduino('/dev/tty.usbmodem1421','Uno')

a = 

  arduino with properties:

                    Port: 'dev/tty.usbmodem1421'
                   Board: 'Uno'
           AvailablePins: {'D2-D13', 'A0-A5'}
    AvailableDigitalPins: {'D2-D13', 'A0-A5'}
        AvailablePWMPins: {'D3', 'D5-D6', 'D9-D11'}
     AvailableAnalogPins: {'A0-A5'}
      AvailableI2CBusIDs: [0]
               Libraries: {'Adafruit/MotorShieldV2', 'I2C', 'SPI', 'Servo'}
  Show all properties

Specify an Arduino Library

Limit the Arduino environment to use only an I2C library.

a = arduino('COM9','Uno','Libraries','I2C')

Updating server code on board Uno (COM9). This may take a few minutes.

a = 
  arduino with properties:

                  Port: 'COM9'
                 Board: 'Uno'
         AvailablePins: {'D2-D13', 'A0-A5'}
  AvailableDigitalPins: {'D2-D13', 'A0-A5'}
      AvailablePWMPins: {'D3', 'D5-D6', 'D9-D11'}
   AvailableAnalogPins: {'A0-A5'}
    AvailableI2CBusIDs: [0]
             Libraries: {'I2C'}
Show all properties

Limit the Arduino Environment to Use Only Two Libraries

Limit the Arduino environment to use only the servo and shift register libraries.

a = arduino('COM9','Uno',"Libraries",{"Servo","ShiftRegister"},'ForceBuildOn',true)

Updating server code on board Uno (COM9). This may take a few minutes.

a = 
  arduino with properties:

                  Port: 'COM9'
                 Board: 'Uno'
         AvailablePins: {'D2-D13', 'A0-A5'}
  AvailableDigitalPins: {'D2-D13', 'A0-A5'}
      AvailablePWMPins: {'D3', 'D5-D6', 'D9-D11'}
   AvailableAnalogPins: {'A0-A5'}
    AvailableI2CBusIDs: [0]
             Libraries: {'Servo', 'ShiftRegister'}
Show all properties

Specify Analog Reference Voltage

Set AnalogReference internally to 1.1 V

a = arduino('COM9','Uno','AnalogReferenceMode','internal','AnalogReference',1.1) 

Updating server code on board Uno (COM9). This may take a few minutes.

a = 
  arduino with properties:

                  Port: 'COM9'
                 Board: 'Uno'
         AvailablePins: {'D2-D13', 'A0-A5'}
  AvailableDigitalPins: {'D2-D13', 'A0-A5'}
      AvailablePWMPins: {'D3', 'D5-D6', 'D9-D11'}
   AvailableAnalogPins: {'A0-A5'}
    AvailableI2CBusIDs: [0]
             Libraries: {'Adafruit/BNO055', 'I2C'}
Show all properties

More About

Code Generation Using MATLAB Function Block

• Use arduino in a MATLAB Function block with the Simulink^® Support Package for Arduino Hardware to generate code that can be deployed on Arduino Hardware.

• Specifying arguments to create the arduino object is not supported in code generation. For more information see Deploy Arduino Functions to Arduino Hardware Using MATLAB Function Block.