9.2 Arduino Functions

9.2.1 @arduino/arduino

: retval = arduino ()
: retval = arduino (port)
: retval = arduino (port, board)
: retval = arduino (port, board[, [propname, propvalue]*)
: retval = arduino (iaddress)
: retval = arduino (ipaddress, board)

Create a arduino object with a connection to an arduino board.

Inputs

port - full path of serial port to connect to. For Linux, usually /dev/ttySXXX, for windows COMXX.

board - name of board to connect (default is ’uno’).

propname, propvalue - property name and value pair for additional properties to pass to the creation of the arduino object.

Currently properties are ignored.

if the arduino function is called without parameters, it will scan for the first available arduino it can find and connect to it.

Outputs

retval - a successfully connected arduino object.

Properties

The arduino object has the following public properties:

name

name assigned to the arduino object

debug

true / false flag for whether debug in turned on

forcebuildon

true / false flag for whether to force show of the arduino IDE to reprogram the arduino

port (read only)

the communications port the board is connected to.

board (read only)

The name of the board type that the arduino connected to

libraries (read only)

The libraries currently programmed onto the board

availablepins

The pins available for use on the board

analogreference

The analog voltage reference

See also: scanForArduinos, arduinosetup.

9.2.2 @arduino/checkI2CAddress

: retval = checkI2CAddress (ar, address)
: retval = checkI2CAddress (ar, address, bus)

Check that an address of given address responds on the I2C bus

Inputs

ar - arduino object connected to a arduino board.

address - I2C address number to check

bus - bus number to check for I2C device, when multiple buses are available. If the bus is not specified, it will default to 0.

Outputs

retval - boolean value of true if address responds on the I2C bus

Example

 
 # create arduino connection.
 ar = arduino();
 # scan for devices on the I2C bus
 checkI2CAddress (ar)
 # output if a device using that address is attached
 ans =
   1
 
 

See also: arduino, scanI2Cbus.

9.2.3 @arduino/configurePin

: currmode = configurePin (ar, pin)
: configurePin (ar, pin, mode)

Set/Get pin mode for a specified pin on arduino connection.

configurePin (ar, pin) will get the current mode of the specified pin.

configurePin (ar, pin, mode) will attempt set the pin to the specified mode if the mode is unset.

Inputs

ar - the arduino object of the connection to an arduino board.

pin - string name of the pin to set/get the mode of.

mode - string mode to set the pin to.

Outputs

mode - string current mode of the pin.

Valid modes can be:

  • AnalogInput - Acquire analog signals from pin
  • DigitalInput - Acquire digital signals from pin
  • DigitalOutput - Generate digital signals from pin
  • I2C - Specify a pin to use with I2C protocol
  • Pullup - Specify pin to use a pullup switch
  • PWM - Specify pin to use a pulse width modulator
  • Servo - Specify pin to use a servo
  • SPI - Specify a pin to use with SPI protocol
  • Interrupt - Specify a pin to use for with interrupts
  • Reserved - Specify a pin to be reserved
  • Unset - Clears pin designation. The pin is no longer reserved and can be automatically set at the next operation.

See also: arduino.

9.2.4 @arduino/configurePinResource

: currmode = configurePinResource (ar, pin)
: configurePinResource (ar, pin, owner, mode)
: configurePinResource (ar, pin, owner, mode, force)

Set/Get pin mode for a specified pin on arduino connection.

configurePinResource (ar, pin) will get the current mode of the specified pin.

configurePinResource (ar, pin, owner, mode) will attempt set the pin to the specified mode and owner.

If the pin is already owned by another owner, the configure will fail unless the force option is used. If the mode is already set, configure will fail unless force is used.

Inputs

ar - the arduino object of the connection to an arduino board.

pin - string name of the pin to set/get the mode of.

mode - string mode to set the pin to.

owner - string name to use as the pin owner.

force - boolean to force mode change. If not set, it will be false.

Outputs

currmode - current string mode of the pin.

Valid modes can be:

  • AnalogInput - Acquire analog signals from pin
  • DigitalInput - Acquire digital signals from pin
  • DigitalOutput - Generate digital signals from pin
  • I2C - Specify a pin to use with I2C protocol
  • Pullup - Specify pin to use a pullup switch
  • PWM - Specify pin to use a pulse width modulator
  • Servo - Specify pin to use a servo
  • SPI - Specify a pin to use with SPI protocol
  • Interrupt - Specify a pin to use with interrupts
  • Reserved - Pin marked reserved, but not for of any particular mode
  • Unset - Clears pin designation. The pin is no longer reserved and can be automatically set at the next operation.

See also: arduino, configurePin.

9.2.5 @arduino/decrementResourceCount

: count = decrementResourceCount (ar, resource)

Decrement the count of a named resource by 1 and return the new count.

Inputs

ar - connected arduino object

resource - name of resource to decrement count.

Outputs

count = count of uses registered to resource.

See also: getResourceCount. incrementResourceCount.

9.2.6 @arduino/delete

: delete (dev)

Free resources of an arduino object.

Inputs

dev - object to free

See also: arduino.

9.2.7 @arduino/display

: display (ar)

Display the arduino object in a verbose way, showing the board and available pins.

Inputs

ar - the arduino object.

If the arduino object has debug mode set, additional information will be displayed.

See also: arduino.

9.2.8 @arduino/getEndian

: mcu = getEndian (ar)

Get the endian used by the connected arduino.

Inputs

ar - arduino object connected to a arduino board.

Outputs

endian - string representing the endian used by the arduino board.

’L’ means little endian, ’B’ means big endian

See also: arduino, getMCU.

9.2.9 @arduino/getI2CTerminals

: pinlist = getI2CTerminals (ar)
: pinlist = getI2CTerminals (ar, bus)

Get a cell list of pin Ids available are used for I2C mode.

Inputs

ar - the arduino object.

bus - optional bus number 0 or 1 for boards that support more than 1 bus.

Outputs

pinlist - cell list of pin numbers available for I2C use.

See also: arduino.

9.2.10 @arduino/getInterruptTerminals

: pinlist = getInterruptTerminals (ar)

Get a cell list of pin Ids available have interrupt functionality

Inputs

ar - the arduino object.

Outputs

pinlist - cell list of pin numbers available for interrupt use.

See also: arduino.

9.2.11 @arduino/getLEDTerminals

: pinlist = getLEDTerminals (ar)

Get a cell list of pin Ids available are connected natively to LEDs.

Inputs

ar - the arduino object.

Outputs

pinlist - cell list of pin numbers available for LED use.

See also: arduino.

9.2.12 @arduino/getMCU

: mcu = getMCU (ar)

Get the MCU used by the connected arduino.

Inputs

ar - arduino object connected to a arduino board.

Outputs

mcu - string representing the mcu used by the arduino board.

See also: arduino.

9.2.13 @arduino/getPWMTerminals

: pinlist = getPWMTerminals (ar)

Get a cell list of pin Ids available for PWM use.

Inputs

ar - the arduino object.

Outputs

pinlist - cell list of pin numbers available for PWM use.

See also: arduino.

9.2.14 @arduino/getPinAlias

: ouy = getPinAlias (ar, pin)

Get the pin actual pin name from a pin alias.

For example, the arduino Leonardo, pin "D4" is also "A6".

Inputs

ar - the connected arduino object.

pin - a pin name.

Outputs

out - alias pin name, or same as pin if the pin doesnt have any alias names.

See also: arduino, configurePinResource, getResourceOwner.

9.2.15 @arduino/getPinInfo

: pininfo = getPinInfo (ar, pin)
: pininfoarray = getPinInfo (ar, pinarray)

Get the pin information from the input pins values.

getPinInfo (ar, pin) will get information for a single pin.

getPinInfo (ar, pinarray) will get a cell array of pin information

Inputs

ar - the connected arduino object.

pin - a pin number or pin name.

pinarray - the array of pin numbers or names

The pininfo struct contains the following fields:

terminal

Terminal number of the pin

name

String name of the pin

owner

Current item owner of the pin

mode

Current configured mode for the pin

Outputs

pininfo - struct on pin information.

pininfolist - cell array of pin info

See also: arduino, configurePinResource, getResourceOwner.

9.2.16 @arduino/getPinsFromTerminals

: pinnames = getPinsFromTerminals (ar, terminals)

Get the pin names from the input terminal values.

Inputs

ar - the connected arduino object.

terminals - the numeric pin number, or array of pin numbers to get pin names.

Outputs

pinnames - the string names of each input pin. If terminals was a single value, the return will be a single string, otherwise it will return a cell array of each pin name.

See also: arduino, getTerminalsFromPins.

9.2.17 @arduino/getResourceCount

: count = getResourceCount (ar, resource)

Get the count of uses of a given resource.

Inputs

ar - connected arduino object

resource - name of resource to get count for.

Outputs

count = count of uses registered to resource.

See also: incrementResourceCount. decrementResourceCount.

9.2.18 @arduino/getResourceOwner

: owner = getResourceOwner (ar, terminal)

Get the owner of pin allocated previously by configurePinResource.

Inputs

ar - connected arduino object

terminal - terminal number to get owner of.

Outputs

owner = owner of the terminal pin, or "" if not owned.

See also: configurePinResource.

9.2.19 @arduino/getSPITerminals

: pinlist = getSPITerminals (ar)

Get a cell list of pin Ids available for SPI mode.

Inputs

ar - the arduino object.

Outputs

pinlist - cell list of pin numbers available for SPI use.

See also: arduino.

9.2.20 @arduino/getServoTerminals

: pinlist = getServoTerminals (ar)

Get a cell list of pin Ids available for servo use.

Inputs

ar - the arduino object.

Outputs

pinlist - cell list of pin numbers available for servo use.

See also: arduino, getPWMTerminals.

9.2.21 @arduino/getSharedResourceProperty

: count = getSharedResourceProperty (ar, resource, property)

Get the value of a property from a given resource.

Inputs

ar - connected arduino object

resource - name of resource to get property for.

property - name of property from the resource.

Outputs

propvalue - value of the property

See also: getResourceCount, setSharedResourceProperty.

9.2.22 @arduino/getTerminalMode

: mode = getTerminalMode (ar, terminal)

Get the mode of a pin allocated previously by configurePinResource.

Inputs

ar - connected arduino object

terminal - terminal number to get owner of.

Outputs

mode - mode of the terminal pin, or "not_set" if not owned.

See also: configurePinResource, getResourceOwner.

9.2.23 @arduino/getTerminalsFromPins

: pinnums = getTerminalsFromPins (ar, pins)

Get the terminal number for each pin.

Inputs

ar - connected arduino object

pins - single pin name or cell or vector array of pin names.

Outputs

pinnums - pin number of each named pin. If the input was a single string, returns a number. if the input pins was a vector or cell array, return a cell array of pin numbers corresponding to each input pin name.

See also: arduino, getPinsFromTerminals.

9.2.24 @arduino/incrementResourceCount

: count = incrementResourceCount (ar, resource)

Increment the count value of a named resource by 1 and return the new count

Inputs

ar - connected arduino object

resource - name of resource to increment count.

Outputs

count = count of uses registered to resource.

See also: getResourceCount. decrementResourceCount.

9.2.25 @arduino/isTerminalAnalog

: ret = isTerminalAnalog (obj, terminal)

Return true if pin is capable of analog input

Inputs

ar - the connected arduino object

terminal is a terminal number to check

Outputs

ret return 1 if terminal is a analog pin, 0 otherwise

9.2.26 @arduino/isTerminalDigital

: ret = isTerminalDigital(obj, terminal)

Return true if pin is capable of digital functions

Inputs

ar - the connected arduino object

terminal is a terminal number to check

Outputs

ret return 1 if terminal is a digital pin, 0 otherwise

9.2.27 @arduino/playTone

: playTone (ar, pin, freq, duration)

Play a tone of a given frequency on a specified pin.

Inputs

ar - connected arduino object

pin - digital pin to play tone on

freq - frequency in hertz to play between 0 and 32767Hz.

duration duration in seconds to play tone between 0 and 30 seconds

If duration is 0 or not specified, tone will continue to play until next tone is commanded. If frequency is 0, tone will stop playing

NOTE: use of playTone can interfere with PWM output.

9.2.28 @arduino/readAnalogPin

: value = readAnalogPin (ar, pin)

Read analog voltage of pin.

Inputs

ar - connected arduino object.

pin - string name of the pin to read.

Outputs

value - analog value of the pin

Example

 
 ar = arduino ();
 readAnalogPin(ar, "A4");
 ans =
     87
 
 

See also: arduino, readVoltage.

9.2.29 @arduino/readDigitalPin

: value = readDigitalPin (obj, pin)

Read digital value from a digital I/O pin.

Inputs

ar - connected arduino object.

pin - string name of the pin to read.

Outputs

value - the logical value (0, 1, true false) of the current pin state.

Example

 
 a = arduino ();
 pinvalue = readDigitalPin (a, 'D5');
 
 

See also: arduino, writeDigitalPin.

9.2.30 @arduino/readVoltage

: voltage = readVoltage (ar, pin)

Read analog voltage of a pin.

Inputs

ar - connected arduino.

pin - pin name or number to query for voltage

Outputs

voltage - scaled pin value as a voltage

Example

 
 ar = arduino ();
 readVoltage(ar, "A4");
 ans =
     1.401
 
 

See also: arduino, readAnalogPin.

9.2.31 @arduino/reset

: reset (ar)

Send reset command to arduino hardware to force a hardware reset.

Inputs

ar - connected arduino object.

See also: arduino.

9.2.32 @arduino/sendCommand

: outdata, outsize = sendCommand (ar, libname, commandid)
: outdata, outsize = sendCommand (ar, libname, commandid, data)
: outdata, outsize = sendCommand (ar, libname, commandid, data, timeout)

Send a command with option data to the connected arduino, waiting up to a specified number of seconds for a response.

Inputs

ar - connected arduino object.

libname - library sending the command. The name should match a programmed library of the arduino, or an error will be displayed.

commandid - integer value for the command being sent to the arduino.

data - optional data sent with the command.

timeout - optional timeout to wait for data

Outputs

outdata - data returned back from the arduino in response to command

outsize - size of data received

If the arduino fails to respond with a valid reply, sendCommand will error.

See also: arduino.

9.2.33 @arduino/setSharedResourceProperty

: setSharedResourceProperty (ar, resource, propname, propvalue)
: setSharedResourceProperty (ar, resource, propname, propvalue, ___)

Set property values for a given resource.

Inputs

ar - connected arduino object

resource - name of resource to get property for.

propname - name of property from the resource.

propvalue - value of property from the resource.

Multiple propname, propvalue pairs can be given.

Outputs

None

Example

 
 ar = arduino();
 setSharedResourceProperty(ar, "myresource", "myproperty", [1 2 3])
 
 

See also: getSharedResourceProperty.

9.2.34 @arduino/uptime

: sec = uptime (ar)

Get the number of seconds the arduino board has been running concurrently.

Inputs

ar - the arduino object of the connection to an arduino board.

Outputs

sec - the number seconds the board has been running. Note that the count will wrap around after approximately 50 days.

See also: arduino.

9.2.35 @arduino/validatePin

: validatePin (ar, pin, type)

Validate that the mode is allowed for specified pin

If the mode is not valid, and error will be thrown.

Inputs

ar - connected arduino object

pin - name of pin to query mode validity of

mode - mode to query

Known modes are:

  • ’I2C’
  • ’SPI’
  • ’PWM’
  • ’Servo’
  • ’analog’
  • ’digital’

See also: arduino, configurePin.

9.2.36 @arduino/version

: ver = version (ar)

Get version of library code installed on arduino board

Inputs

ar - the arduino object of the connection to an arduino board.

Outputs

ver - version string in format of X.Y.Z.

See also: arduino.

9.2.37 @arduino/writeDigitalPin

: writeDigitalPin (ar, pin, value)

Write digital value to a digital I/O pin.

Inputs

ar - connected arduino object.

pin - string name of the pin to write to.

value - the logical value (0, 1, true false) to write to the pin.

If pin was unconfigured before using, pin is set into digital mode.

Example

 
 a = arduino();
 writeDigitalPin(a,'D5',1);
 
 

See also: arduino, readDigitalPin.

9.2.38 @arduino/writePWMDutyCycle

: writePWMDutyCyle (ar, pin, value)

Set pin to output a square wave with a specified duty cycle.

Inputs

ar - connected arduino object

pin - pin to write to.

value - duty cycle value where 0 = off, 0.5 = 50% on, 1 = always on.

Example

 
 a = arduino();
 writePWMDutyCycle(a,'D5',0.5);
 
 

See also: arduino, writePWMVoltage.

9.2.39 @arduino/writePWMVoltage

: writePWMVoltage (ar, pin, voltage)

Emulate an approximate voltage out of a pin using PWM.

Inputs

ar - connected arduino object

pin - pin to write to.

voltage - voltage to emulate with PWM, between 0 - 5.0

Example

 
 a = arduino();
 writePWMVoltage(a,'D5',1.0);
 
 

See also: arduino, writePWMDutyCycle.


Next: Arduino I2C Functions, Previous: General Functions, Up: Function Reference   [Contents][Index]