E5Shield Hardware/Software Guide

The E5Shield is a hardware/software combination that enables a real-world interface to MATLAB.  This document shows you how to properly configure the hardware and software.  It also explains the interactions between the three computer programs that work together to make the E5Shield program efficient and easy to use.

The preceding diagram is a basic sketch showing the interactions between MATLAB, Arduino, and the MSP430.  The MATLAB initialization commands are shown in orange.  The green text indicates what Arduino does when sent the MATLAB command.  The red text explains what the MSP430 does with the information once it is sent by the Arduino.  The information sent from one program to another is shown on the arrows connecting the commands and actions.

This document contains an introduction to the interactions, a more detailed description of the interactions involved in each MATLAB command, and some information on error reporting.


Introduction to Hardware/Software Interactions

Three different programming tools (MATLAB, Arduino, and the MSP430) work together so that the E5Shield's capabilities can be easily and efficiently accessed.  The MATLAB code's user-friendly interface allows one to use simple, straightforward commands to control many features of an Arduino circuit board.  The Arduino is connected to the E5Shield circuit board, which in turn can be connected to many different types of hardware (e.g. servo motors, Wii nunchuck, DC motors).

The MATLAB code is where the commands are initialized by the user.  It allows the various functions of the E5Shield code to be called easily.  The MATLAB functions send data to the Arduino IDE software, which controls the circuit board's hardware.  This Arduino sketch is set up as a state machine, which means that specific input characters correspond to different states, each of which has some unique purpose.  When the serial port receives a string, the program reads it one character at a time, moving step-by-step through the states and their functions.  The software can be used to set the digital and analog pins as inputs or outputs as well as to read and alter the values across the pins.  When a servo motor is to be altered, the Arduino code sends information to the MSP430.  The MSP430 then controls the servos, as it can drive many motors at once without affecting the performance of the rest of the system.  The MSP430 is also used to access the Wii nunchuck values.


Interactions in More Detail

Below is a state diagram illustrating the process followed by the Arduino program.  The center state, WAITING, is the default.  When one of the characters shown ('P,' 'd,' 'D,' 'a,' 'A,' 'S,' 'R,' 'n,' or '?') is sent to the serial port (from the MATLAB E5Shield program or the serial monitor in the Arduino software), the state shifts from WAITING to a new state.  To determine which state will be next, follow the arrow containing that character, and it will point to the resulting state.  Then the state returns to WAITING unless the listed conditions are met.

For example, if the letter 'P' was entered from the WAITING state, you shift into PINMODE.  From there, if a valid pin number (2-13) is entered, the state shifts to PINSET before going back to WAITING.  If the number entered is not a valid pin, the WAITING state will be returned to straight from PINMODE.


State machine model illustrating how the Arduino code navigates from one state to another.

For the list below, bulleted is an example of a MATLAB command that initializes a certain function.  Then you can see the string that MATLAB sends to Arduino, followed by a description of the communication between MATLAB, Arduino, and the MSP430 that results from the listed command.


Errors and Error Reporting

  • MATLAB

    MATLAB checks for errors at each step of the E5Shield code.  It is the program that reports the errors, printing a message in the command window explaining what went wrong.  In many cases, there is a suggested resolution to the error.  For more information about an error message, you can use >> explainError to open a window explaining the problem and solutions in more depth.

    When the E5Shield object is first called (using a=E5Shield('COM&')), MATLAB first checks that there is one argument, the serial port to which the Arduino is connected.  Next it checks whether the selected serial port is already being used by MATLAB.  If these two conditions are met, then MATLAB creates the E5Shield serial object.

    Next MATLAB tries to open the COM port, and prints an error message if it could not be done.  Then MATLAB sends the script query command to Arduino (by writing the string '??' to the serial port).  This checks whether the Arduino board is responding to input from MATLAB.  If there was no answer, a message appears saying that the connection between the computer and the circuit board was unsuccessful.  If there was an unexpected answer (MATLAB expects for Arduino to return a value of 1 in the event of a successful connection), a message is printed explaining that the script received was unknown.

    Every time you enter a MATLAB function, the program checks a few aspects of what you have typed.  First it checks that there were a valid number of arguments (for example, digitalRead must have exactly two arguments, the E5Shield object and the pin number).  Next it checks the arguments themselves, making sure they are valid entry types for that function (e.g. digital pins must be numbers between 2 and 13).

    For the digitalWrite and analogWrite functions, MATLAB also checks whether the selected pin is an output.  Because the servo and pulse width entries can be vectors, the servoWrite function checks that the number of servos equals the number of pulse widths.


  • Arduino

    If at any point an unexpected character is read in the Arduino sketch, it will return to the WAITING state.  There are no error messages printed by Arduino.  If you are testing functions from the Arduino sketch monitor and an error occurs, no text will appear and you will be sent to the WAITING state.


  • MSP430

    Incorrect statements are not sent to the MSP430 because of the error checking that occurs in MATLAB and Arduino.  If an invalid command was sent through a MATLAB script using the E5Shield program, MATLAB will have already caught and displayed the error without sending a string to Arduino.  If the command was sent from the serial monitor in the Arduino software, the Arduino code will have caught the error and returned to the WAITING state without sending any values to the MSP430.