Main Content

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

Description

example

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.

example

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.

example

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

example

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

example

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

example

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

example

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

expand all

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')

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.

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.

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.

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.

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')

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.

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.

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.

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.

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.

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

expand all

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

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

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

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

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

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

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

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

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

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'

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 BoardInput ArgumentWiFi SupportSupported Internal Voltage (V)
Arduino Uno'Uno'No5.0(default), 1.1
Arduino Due'Due'No3.3(default)
Arduino Mega 2560'Mega2560'No5.0(default), 1.1, 2.56
Arduino Leonardo'Leonardo'No5.0(default), 2.56
Arduino Mega ADK'MegaADK'No5.0(default), 1.1, 2.56
Arduino Micro'Micro'No5.0(default), 2.56
Arduino MKR1000'MKR1000'Yes3.3(default), 1.0, 1.65, 2.23
Arduino MKR WiFi1010'MKR1010'Yes3.3(default), 1.0, 1.65, 2.23
Arduino MKR Zero'MKRZero'No3.3(default), 1.0, 1.65, 2.23
Arduino Nano 3.1'Nano3'No5.0(default), 1.1
Arduino Nano 33 IoT'Nano33IoT'Yes3.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 SandboxDigitalSandboxNo3.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.

deviceConnection to device on I2C bus on Arduino hardware
shiftRegisterConnection to shift register on Arduino hardware
rotaryEncoderConnection to quadrature encoder on Arduino hardware
servoConnection to servo motor on Arduino hardware
addonConnection to add-on device for Arduino hardware
ultrasonicConnection to ultrasonic sensor on Arduino hardware
configurePinSet Arduino pin mode
readDigitalPinRead data from digital pin on Arduino hardware
writeDigitalPinWrite data to digital pin on Arduino hardware
writePWMVoltageGenerate PWM signal with specified voltage on digital pin
writePWMDutyCycleGenerate PWM signal with specified duty cycle on digital pin
playTonePlay tone on piezo speaker using digital pin
readVoltageRead voltage from analog pin on Arduino hardware
scanI2CBusScan I2C bus on Arduino hardware for device address

Examples

collapse all

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

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

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
               

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

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'}

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 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

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 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

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

expand all

Introduced in R2014b