E5Shield User's Guide

Written by Nicole Aaron ('14) and Erik Cheever

The E5Shield is a hardware/software combination that enables a real-world interface to MATLAB.  This document assumes you have an E5Shield board (it has "E5 Shield" written on the top) connected to an Arduino processor (the bottom of the board has "Arduino" printed on it) connected via a USB cable to your computer.  This document assumes the hardware and software are configured properly.  If not, please consult the hardware/software guide.

The E5Shield lets you use MATLAB to control real world devices (including LED's, servo motors, and low voltage relays and motors, and anything that responds to a logic level - 0 to 5 volt low power - output), and to sense voltages from the real world (0 to 5 volts).  It also allows for communication with a Wii Nunchuck.  A diagram of the shield is shown to the right (click on image get higher resolution).  The connections you are likely to use in E5 are labeled in red, other connections are blue.

The E5Shield software functions fall into three general categories: 1) Initialization, 2) Sensing, and 3) Control. 

  1. Initialization
  2. Sensing
  3. Control

1) Initialization

Before using the E5Shield for real world sensing and control an E5Shield "object" must be created within MATLAB (this uses a MATLAB command "E5Shield").  This object is used to let MATLAB interact with the real world.  Second, any pins that are to be used for input or output must be specified using the "pinMode" function.  Third, it is possible to change the voltage reference used for analog inputs using "analogReference."  The second and third commands are generally not of interest for E5.

E5Shield

The Arduino/E5Shield is connected to your computer through a USB port (see diagram above).  The computer sees this connection as a serial port, or COM (short for communications) port, with a number.  The serial port is "COMx" where "x" is a one or two digit number.  To determine this number

  1.  Click on the Start button (a Windows icon in a circle at the lower left of the screen).
  2.  Click on "Control Panel" (this may take a few seconds to open).
  3.  Select "Device Manager" by clicking on it.

This sequence is illustrated in the image below.

 In the Device Manager, click the triangle to the left of "Ports" to see the available COM (or serial) ports.  If there is one that is called Arduino UNO R3, or something similar (shown below), the COM port listed in parentheses is the one you should use (COM19 in this case).

 

Otherwise, the one whose Manufacturer is Arduino LLC or www.arduino.cc is the COM port that should be used. 

If the Arduino does not appear among the available ports, or if MATLAB still cannot connect, then unplug the Arduino board from the USB port for at least ten seconds then reconnect it and enter the command into MATLAB again.

Once the serial port is determined, an E5Shield object can be created.  In the example below, the name of the object is "a." Note: In this document MATLAB commands that you enter will be shown in green and with a Courier font, output from MATLAB will have a gray background.

>> a=E5Shield('COM19')
Attempting connection: 3,2,1,0
E5Shield Script detected!
E5Shield successfully connected!
a = 
E5Shield object connected to COM19 port
E5Shield Server running on the E5Shield board
 
Digital Pin 02 is currently UNASSIGNED
Digital Pin 03 is currently UNASSIGNED
       ⋮ Pins 04 through 11 omitted for brevity
Digital Pin 12 is currently UNASSIGNED
Digital Pin 13 is currently UNASSIGNED

At this point the I/O pins (Pin 02 through 13) are unassigned.  Leave them this way unless you need them for some purpose.  If you prefer not to have the long printout, simply put a semicolon at the end of the MATLAB command.

pinMode

This function specifies the modes of the Digital I/O pins.  Before the digital pins can be used, you must set whether they will be used as inputs or outputs.  The pinMode function can be used to set an individual pin as an input or output, show the status of a specific pin, or show the status of all pins.  The syntax of a call to this function is as follows (where it is assumed that "a" is an initialized "E5Shield" object - see Initialization directions on how to create an "E5Shield" object).

>> a.pinMode(pin,str)

The pin number is determined by "pin" which must be between 2 and 13, and "str" specifies the status (either 'input' or 'output').  The pinMode command can also be used without the "str" argument to access pin modes.  A few examples of the uses of this function:

>> a.pinMode(11,'output')  % sets digital pin #11 as output
>> a.pinMode(10,'input')   % sets digital pin #10 as input
>> a.pinMode(5)            % prints the status of digital pin #5
>> a.pinMode               % prints the status of all pins

analogReference

This function changes the voltage reference on the analog input pins, setting the reference voltage used at the top of the input ranges.  The syntax of a call to this function is as follows.

>> a.analogReference(str)

The "str" argument that defines the reference can be either 'default,' 'internal' or 'external.'

2) Sensing

digitalRead

This function can be used to display the state (high=1 or low=0) of a Digital I/O pin.  This function has one argument that defines which pin is to be read (valid numbers 2 through 13).

>> a.digitalRead(2)       % prints the state of digital pin #2
>> val=a.digitalRead(7);  % returns the state of digital pin #7

analogRead

This function displays the analog value of a pin.  The argument defines which pin is to be read (valid pins are 0-3, the Analog Input pins).  The returned value ranges from 0 to 1023, with 0 corresponding to an input voltage of 0 volts and 1023 to a reference value that is typically 5 volts (this voltage can be set up by the analogReference function).

>> a.analogRead(3)        % prints the analog value of analog pin #3
>> val=a.analogRead(1);   % returns the analog value of analog pin #1

Assuming a range from 0 to 5 V, the voltage can be calculated via the formula

voltage = (returned value)*0.0049

3) Control

digitalWrite

This function is used to assign either a high or low state to a Digital I/O pin.  The syntax of a call to this function is as follows.

>> a.digitalWrite(pin,st)

The "pin" argument defines which digital pin will be assigned the state, "st," which can be either 0 or 1 (low or high). Note: You can only use "digitalWrite" on output pins - see pinMode for directions on how to set a pin as an output.

analogWrite

This function assigns an analog value to a digital pin.  The analog pins on the E5Shield can only be used as inputs, so they cannot be written to.  Therefore, "analogWrite" must perform the analog output on a digital pin.  The syntax of a call to this function is as follows.

>> a.analogWrite(pin,val)

The "pin" argument defines which digital pin will be assigned the value (valid pins for analog output are 3, 5, 6, 9, 10 and 11 - these digital pins are indicated on the Arduino and E5Shield circuit boards by tildes, ~), and the "val" argument specifies the analog value (0 to 255). Note: You can only use "analogWrite" on output pins - see pinMode for directions on how to set a pin as an output.

servoWrite

This command sets the angle of a servo connected to one of the sets of three pins labeled J0 through J7.  Note that to control a servo an external voltage source is needed on the lines labeled "Motor Power" at the top of this document (the red wire goes to the positive voltage, black goes to ground (or negative) voltage.  Note also that servo connectors have three wires, one black, one red and one yellow; make sure these are attached to the pins labeled "B," "R," and "Y," respectively.

Important: The polarity of the connector is very important.  Hooking it up backwards can destroy the functionality of that particular ouput.

Servo motors have approximately 180° of rotation controlled by the width of a pulse sent on the yellow wire.  The width of the pulse varies between 0.5 mS and 2.5 mS as the angle varies from 0 to 180° in the clockwise.  The syntax of a call to this function is as follows.

>> a.servoWrite(n,val)

The motor is determined by "n" (valid motor numbers 0-7), and the number "val" (0-2000) determines the pulse width via the formula

pulse width = (500 + val) μSec

In other words each increment of "val" by 1 unit corresponds to an increase in pulse width of 1μS.  So if val=0, then the pulse width is 0.5 mS.  If val=250, the pulse width is 0.75 mS.  If val=1000, the pulse width is 1.5 mS... Note: This value is ±5% if you compare one E5Shield board against another - but should be almost constant for any given board; in other words it is very precise, but not completely accurate. The command

>> a.servoWrite(3,112);

will set the pulse width for motor 3 to 0.612  mS (=500+112 μS);.

The variables "n" and "val" may be vectors if you want to set several motors all at the same time.   For example,

>> a.servoWrite([1 3 7],[1000 0 250]);

will set the pulse widths for motor 1 to 1.5 mS, motor 3 to 0.5 mS and motor 7 to 0.75 mS.

To set the first several motors all to the same value, you can let "val" be a scalar. So,

>> a.servoWrite(0:3,500);

sets the first 4 motors to a pulse width of 1 mS.

servoDisable

This function disables a servo motor by setting its pulse width value out of range.  The motor to be disabled is determined by the argument of the function, which can range from 0 to 7.

>> a.servoDisable(4)   % disable servo motor #4

statLED

Calling this function determines the state of the status LED on the E5Shield board.  If the argument is zero, the LED is turned off.  Any nonzero value will turn the LED on.

>> a.statLED(0)       % Turn LED off
>> a.statLED(100)     % Turn LED on

nunchuck

This command allows MATLAB to communicate with the Wii nunchuck and in turn access the values of the joystick, accelerometer and C- and Z-buttons.  The joystick values range from 0-250 with 0 being the far left position horizontally (i.e., the x-direction), and the bottom in the vertical (the y-direction).  There are three accelerometer values (one for each of the x-, y-, and z-planes), ranging from 0-750.  For the buttons, a value of 0 indicates that the button is being pressed and 1 that it is released.  The values are all returned in a structure.

>> nunch = a.nunchuck
nunch = 
    JoystickX: 124
    JoystickY: 122
       AccelX: 245
       AccelY: 464
       AccelZ: 562
      CButton: 1
      ZButton: 1

Individual values within the structure are accessed in the normal way

>> nunch.AccelY
ans =
   464

There is a slight bug with this function.  When you call it the first time, the result is all zeros.  After that the JoystickX and JoystickY values are correct, but all of the other elements of the structure will get the value from the nunchuck that existed at the previous function call.  In a loop this doesn't matter (because subsequent calls are made rapidly), but it may give unexpected results if the function call is not within a loop.