\chapter {Interfacing a Light Emitting Diode}
\thispagestyle{empty}
\label{led}
\newcommand{\LocLEDfig}{\Origin/user-code/led/figures}
\newcommand{\LocLEDscicode}{\Origin/user-code/led/scilab}
\newcommand{\LocLEDscibrief}[1]{{\tt \seqsplit{
    Origin/user-code/led/scilab/#1}}, see \fnrefp{fn:file-loc}} 
\newcommand{\LocLEDardcode}{\Origin/user-code/led/arduino}
\newcommand{\LocLEDardbrief}[1]{{\tt \seqsplit{
    Origin/user-code/led/arduino/#1}}, see \fnrefp{fn:file-loc}}

In this chapter, we will learn how to control the LEDs on the shield
and on the \arduino\ board.  We will do this through the Arduino IDE,
Scilab scripts and Scilab Xcos.  These are beginner level experiments,
and often referred to as the \emph{hello world} task of Arduino.
Although simple, controlling LED is a very important task in all
kinds of electronic boards.

\section{Preliminaries}
\label{sec:led-pril}
A light emitting diode (LED) is a special type of semiconductor diode,
which emits light when voltage is applied across its terminals. A typical LED has 2 leads: Anode, the positive terminal and Cathode, the negative terminal.  When sufficient voltage is applied, electrons combine with the holes,
thereby releasing energy in the form of photons.  These photons emit
light and this phenomenon is known as electroluminescence.  The
symbolic representation of an LED is shown in \figref{fig:ledsym}.
Generally, LEDs are capable of emitting different colours.  Changing
the composition of alloys that are present in LED helps produce
different colours.  A popular LED is an RGB LED that actually has
three LEDs: red, green and blue.

\begin{figure}
\centering
\includegraphics[width=0.2\linewidth]{\LocLEDfig/led.png}
\caption{Light Emitting Diode}
\label{fig:ledsym}
\end{figure}

%\subsection{Connection diagram}
An RGB LED is present on the shield provided in the kit.  In this
section, we will see how to light each of the LEDs present in the RGB
LED.  As a matter of fact, it is possible to create many colours by
combining these three.  A schematic of the RGB LED in the shield is
given in \figref{fig:ledblock}.
\begin{figure}
\centering
\includegraphics[width=\smfig]{\LocLEDfig/schematic.png}
\caption{Internal connection diagram for LED on the shield}
\label{fig:ledblock}
\end{figure}
The anode pins of red, green and blue are, respectively, connected to
pins 11, 10 and 9.  Common Cathode is connected to the ground.

It should be pointed out, however, that no wire connections are to be made by the learner: all the required connections are already internally made available.  The LED of any colour can be turned on by putting a high voltage on the
corresponding anode pin.  

\begin{figure}
\centering
\includegraphics[width=\smfig]{\LocLEDfig/arduino-shield.JPG}
\caption{Connecting Arduino and Shield}
\label{fig:uno-shield-connect}
\end{figure}

One should remember to connect the shield on to the \arduino\ board, as
shown in \figref{fig:uno-shield-connect}. All the experiments in this
chapter assume that the shield is connected to the \arduino\ board.
It is also possible to do some of the experiments without the shield,
which is pointed out in the next section.

\section{Lighting the LED from the Arduino IDE}
\label{sec:light-ard}
In this section, we will describe some experiments that will help the
LED light up based on the command given from the Arduino IDE.  We will
also give the necessary code.  We will present four experiments in
this section.  The shield has to be attached to the \arduino\ board
before doing these experiments.  The reader should go through the
instructions given in \secref{sec:ard-start} before getting started.
\begin{enumerate}
\item First, we will see how to light up the LED in different
colours.  An extremely simple code is given in \ardref{ard:led-blue}.
On uploading this code, you can see that the LED on the shield turns
blue.  It is extremely easy to explain this code.  Recall from the
above discussion that we have to put a high voltage (5V) on pin 9 to
turn the blue light on.  This is achieved by the following command:
\lstinputlisting[firstline=3,lastline=3]
{\LocLEDardcode/led-blue/led-blue.ino}
Before that, we need to define pin 9 as the
output pin.  This is achieved by the command,
\lstinputlisting[firstline=2,lastline=2]
{\LocLEDardcode/led-blue/led-blue.ino}
One can see that the blue light will be on continuously.  

\item Next, we will modify the code slightly so that the blue light
  remains on for two seconds and then turns off.
  \ardref{ard:led-blue-delay} helps achieve this.  In this, we
  introduce a new command {\tt delay} as below:
  \lstinputlisting[firstline=4,lastline=4]
  {\LocLEDardcode/led-blue-delay/led-blue-delay.ino} This delay
  command halts the code for the time passed as in input argument. In our case, it is 2,000  milliseconds, or 2 seconds.  The next command,
  \lstinputlisting[firstline=5,lastline=5]
  {\LocLEDardcode/led-blue-delay/led-blue-delay.ino} puts a low
  voltage on pin 9 to turn it off.

  What is the role of the {\tt delay} command?  To find this,
  comment the delay command.  That is, replace the above delay command
  with the following and upload the code.
  \begin{lstlisting}[style=nonumbers]
    // delay(2000);
  \end{lstlisting}
  If you observe carefully, you will see that the LED turns blue
  momentarily and then turns off.
 
\item We mentioned earlier that it was possible to light more than one
  LED simultaneously.  We will now describe this with another
  experiment.  In this, we will turn on both blue and red LEDs.  We
  will keep both of them on for 5 seconds and then turn blue off,
  leaving only red on.  After 3 seconds, we will turn red also off.
  This code is given in \ardref{ard:led-blue-red}.  Remember that
  before writing either {\tt HIGH} or {\tt LOW} on to any pin, its
  mode has to be declared as {\tt OUTPUT}, as given in the code.  All
  the commands in this code are self explanatory.

\item Finally, we will give a hint of how to use the programming
  capabilities of the Arduino IDE.  For this, we will use
  \ardref{ard:led-blink}.  It makes the LED blink 5 times.  Recall
  from the previous section that a {\tt HIGH} on pin 10 turns on the
  green LED.  This cycle is executed for a total of five times.  In each
  iteration, it will turn the green LED on for a second by giving the
  {\tt HIGH} signal and then turn it off for a second by giving the
  {\tt LOW} signal.  This cycle is carried out for a total of 5 times,
  because of the {\tt for loop}.
\end{enumerate}

\paragraph{Note:}
All the above four experiments have been done with
the shield affixed to the \arduino\ board.  One may run these
experiments without the shield as well.  But in this case, pin number
13 has to be used in all experiments, as pin 13 lights up the LED that
is on the \arduino\ board.  For example, in \ardref{ard:led-blue}, one
has to replace both occurrences of number 9 with 13.  In this case,
one will get the LED of \arduino\ board light up, as shown in
\figref{fig:led-uno}.
\begin{figure}
\centering
\includegraphics[width=\hgfig]{\LocLEDfig/led_output.png}
\caption{LED experiments directly on \arduino\ board, without the
  shield}
\label{fig:led-uno}
\end{figure}


\paragraph{Note:} It should also be pointed out that only one colour
is available in \arduino\ board.  As a result, it is not possible to
conduct the experiments that produce different colours if the
shield is not used.

\begin{exercise}
Carry out the following exercise:
\begin{enumerate}
\item In \ardref{ard:led-blue-delay}, remove the delay, as discussed
  above, and check what happens.
\item Light up all three colours simultaneously, by modifying
  \ardref{ard:led-blue-red}.  Change the
  combination of colours to get different colours.
\item Incorporate some of the features of earlier experiments into
  \ardref{ard:led-blink} and come up with different ways of blinking
  with different colour combinations.
\end{enumerate}
\end{exercise}

\section{Lighting the LED from Scilab Scripts}
\label{sec:light-sci}
In this section, we discuss how to carry out the experiments of the
previous section from Scilab.  We will list the same four experiments,
in the same order.  The shield has to be attached to the \arduino\
before carrying out these experiments, as in \secref{sec:light-ard}.
The reader should go through the instructions given in
\secref{sec:sci-start} before getting started.
\begin{enumerate}
\item In the first experiment, we will light up the blue LED on the
  shield.  The code for this is given in \sciref{sci:led-blue}.  It
  begins with a command of the form
  \begin{lstlisting}[style=nonumbers]
     ok = open_serial(1,PORT NUMBER,BAUD RATE)
  \end{lstlisting}
  We have used 2 for {\tt PORT NUMBER} and 115200 for {\tt BAUD RATE}.
  As a result, this command becomes
  \lstinputlisting[firstline=1,lastline=1]{\LocLEDscicode/led-blue.sce}
  This command is used to open the serial port.  When the port is
  opened successfully, it returns a value of 0, which gets stored in
  the variable {\tt ok}.

  Sometimes, the serial port does not open, as mentioned in the above
  command.  This is typically due to not closing the serial port
  properly in a previous experiment.  If this condition is not
  trapped, the program will wait forever, without any information
  about this difficulty.  One way to address this difficulty is to
  terminate the program if the serial port does not open.  This is
  achieved using the error message of the following form:
  \begin{lstlisting}[style=nonumbers]
     if ok~=0, error(Error Message in Quotes);
  \end{lstlisting}
  It checks if {\tt ok=0}.  If not, it flashes an error message and
  terminates.  This line gets implemented in the following way in
  \sciref{sci:led-blue}.  
  \lstinputlisting[firstline=2,lastline=2]{\LocLEDscicode/led-blue.sce}

  We turn the LED on in the next line.  This is achieved using a
  command of the form
  \begin{lstlisting}[style=nonumbers]
    cmd_digital_out(1,PIN NUMBER,VALUE)
  \end{lstlisting}
  As we want to turn on the blue light in the shield, as discussed in
  \secref{sec:light-ard}, we choose {\tt PIN NUMBER} as 9.  We can put
  any positive integer in the place of {\tt VALUE}.  We arrive at the
  following command:
  \lstinputlisting[firstline=3,lastline=3]{\LocLEDscicode/led-blue.sce}

  The last line in the code closes the serial port.  As mentioned
  above, it is extremely important to close the serial port properly.
  If not closed properly, there could be difficulties in running
  subsequent programs.

\item \sciref{sci:led-blue-delay} does the same thing as what
  \ardref{ard:led-blue-delay} does.  It does two more things than what
  \sciref{sci:led-blue} does: It makes the blue LED light up for two
  seconds.  This is achieved by the command
  \lstinputlisting[firstline=4,lastline=4]{\LocLEDscicode/led-blue-delay.sce}
  The second thing this code does is to turn the blue LED off.  This
  is achieved by the command
  \lstinputlisting[firstline=5,lastline=5]{\LocLEDscicode/led-blue-delay.sce}
  It is easy to see that this code puts a 0 on pin 9.

\item \sciref{sci:led-blue-red} does the same thing as what
  \ardref{ard:led-blue-red} does.  It turns blue and red LEDs on for
  five seconds.  After that, it turns off blue first.  After 3
  seconds, it turns off red also.  So, when the program ends, no LED is
  lit up.

\item \sciref{sci:led-green-blink} does exactly what its counterpart
  in the Arduino IDE does.  It makes the green LED blink five times.
\end{enumerate}

\begin{exercise}
Repeat the exercise of the previous section.
\end{exercise}

\section{Lighting the LED from Scilab Xcos}
\label{sec:light-xcos}
In this section, we will see how to light the LEDs from Scilab Xcos.
We will carry out the same four experiments as in the previous
sections.  For each, we will give the location
of the zcos file and the parameters to set.  The reader should go
through the instructions given in \secref{sec:xcos-start} before
getting started.

\begin{enumerate}
\item First we will see how to turn on the blue LED.  When the file
  required for this experiment is invoked, one gets the GUI as in 
  \figref{fig:led-blue}.  In the caption of this figure, one can see
  where to locate the file.

  \begin{figure}
    \centering
    \includegraphics[width=\smfig]{\LocLEDfig/led-blue.png}
    \caption[Turning the blue LED on through Xcos]{Turning the blue
      LED on through Xcos.  This is what one sees when
        \LocLEDscibrief{led-blue.zcos} is invoked.}
    \label{fig:led-blue}
  \end{figure}

  We will next explain how to set the parameters for this simulation.
  To set value on any block, one needs to right click and open the
  {\tt Block Parameters} or double click.  The values for each block
  is tabulated in \tabref{tab:led-blue}.  All other parameters are to
  be left unchanged.
  \begin{table}
    \centering
    \caption{Parameters to light the blue LED in Xcos}
    \label{tab:led-blue}
    \begin{tabular}{llc} \hline
      Name of the block & Parameter name & Value \\ \hline
      ARDUINO\_SETUP & Identifier of Arduino Card & 1 \\
      & Serial com port number & 2\portcmd \\ \hline
      TIME\_SAMPLE & Duration of acquisition(s) & 10 \\
      & Sampling period(s) & 0.1 \\ \hline
      DIGITAL\_WRITE\_SB & Digital pin & 9 \\
      & Arduino card number & 1 \\ \hline
    \end{tabular}
  \end{table}

\item In the second experiment, we will show how to turn on the blue LED on
  for two seconds and then to turn it off.  When the file required for
  this experiment is invoked, one gets the GUI as in
  \figref{fig:led-blue-delay}.  In the caption of this figure, one can
  see where to locate the file.

  \begin{figure}
    \centering
    \includegraphics[width=\smfig]{\LocLEDfig/led-blue-delay.png}
    \caption[Turning the blue LED on through Xcos for two
      seconds]{Turning the blue LED on through Xcos for two
      seconds.  This is what one sees when
        \LocLEDscibrief{led-blue-delay.zcos} is invoked.}
    \label{fig:led-blue-delay}
  \end{figure}

  The values for each block required in this program are tabulated in
  \tabref{tab:led-blue-delay}.  All other parameters are to be left
  unchanged.
  \begin{table}
    \centering
    \caption{Parameters to light the blue LED in Xcos for two seconds}
    \label{tab:led-blue-delay}
    \begin{tabular}{llc} \hline
      Name of the block & Parameter name & Value \\ \hline
      ARDUINO\_SETUP & Identifier of Arduino Card & 1 \\
      & Serial com port number & 2\portcmd \\ \hline
      TIME\_SAMPLE & Duration of acquisition(s) & 10 \\
      & Sampling period(s) & 0.1 \\ \hline
      DIGITAL\_WRITE\_SB & Digital pin & 9 \\
      & Arduino card number & 1 \\ \hline
      STEP\_FUNCTION & Step time & 2 \\
      & Initial value & 1 \\
      & Final value & 0 \\ \hline
    \end{tabular}
  \end{table}

\item In the third experiment, we will show how to turn the blue LED
  and the red LED on for five seconds, turn off the blue LED and three
  seconds later, turn off the red LED also.  When the file required for
  this experiment is invoked, one gets the GUI as in
  \figref{fig:led-blue-red}.  In the caption of this figure, one can
  see where to locate the file.

  \begin{figure}
    \centering
    \includegraphics[width=\smfig]{\LocLEDfig/led-blue-red.png}
    \caption[Turning the blue and red LEDs on through Xcos and turning
      them off one by one]{Turning the blue and red LEDs on through
      Xcos and turning them off one by one.  This is what one sees
      when \LocLEDscibrief{led-blue-red.zcos} is invoked.}
    \label{fig:led-blue-red}
  \end{figure}

  The values for each block required in this program are tabulated in
  \tabref{tab:led-blue-red}.  All other parameters are to be left
  unchanged.
  \begin{table}
    \centering
    \caption{Parameters to turn the blue and red LEDs on and then turn
      them off one by one}
    \label{tab:led-blue-red}
    \begin{tabular}{llc} \hline
      Name of the block & Parameter name & Value \\ \hline
      ARDUINO\_SETUP & Identifier of Arduino Card & 1 \\
      & Serial com port number & 2\portcmd \\ \hline
      TIME\_SAMPLE & Duration of acquisition(s) & 10 \\
      & Sampling period(s) & 0.1 \\ \hline
      DIGITAL\_WRITE\_SB 1 & Digital pin & 9 \\
      & Arduino card number & 1 \\ \hline
      STEP\_FUNCTION 1 & Step time & 5 \\
      & Initial value & 1 \\
      & Final value & 0 \\ \hline
      DIGITAL\_WRITE\_SB 2 & Digital pin & 11 \\
      & Arduino card number & 1 \\ \hline
      STEP\_FUNCTION 2 & Step time & 8 \\
      & Initial value & 1 \\
      & Final value & 0 \\ \hline
    \end{tabular}
  \end{table}

\item We will conclude this section with an experiment to blink the
  green LED on and off.  When the file required for
  this experiment is invoked, one gets the GUI as in
  \figref{fig:led-green-blink}.  In the caption of this figure, one can
  see where to locate the file.

  \begin{figure}
    \centering
    \includegraphics[width=\smfig]{\LocLEDfig/led-green-blink.png}
    \caption[Blinking the green LED every second through
      Xcos]{Blinking the green LED every second through Xcos.
      This is what one sees when
        \LocLEDscibrief{led-green-blink.zcos} is invoked.}
    \label{fig:led-green-blink}
  \end{figure}

  The values for each block required in this program are tabulated in
  \tabref{tab:led-green-blink}.  All other parameters are to be left
  unchanged.
  \begin{table}
    \centering
    \caption{Parameters to make the green LED blink every second}
    \label{tab:led-green-blink}
    \begin{tabular}{llc} \hline
      Name of the block & Parameter name & Value \\ \hline
      ARDUINO\_SETUP & Identifier of Arduino Card & 1 \\
      & Serial com port number & 2\portcmd \\ \hline
      TIME\_SAMPLE & Duration of acquisition(s) & 10 \\
      & Sampling period(s) & 0.1 \\ \hline
      DIGITAL\_WRITE\_SB & Digital pin & 10 \\
      & Arduino card number & 1 \\ \hline
      PULSE\_SC & Pulse width(\% of period) & 50 \\
      & Period(secs) & 2 \\ 
      & Phase delay(secs) & 0.1 \\
      & Amplitude & 1 \\ \hline
    \end{tabular}
  \end{table}
\end{enumerate}

% \section{Control through Xcos}
% This experiment implements digital write functionality of Arduino board.
% % \begin{figure}
% % \centering
% % \includegraphics[width=\smfig]{\LocLEDfig/xcos-wri.png}
% % \caption{Digital write functionality}
% % \label{fig:xcoswri}
% % \end{figure}

% \begin{figure}
% \centering
% \includegraphics[width=\smfig]{\LocLEDfig/xcos-led.png}
% \caption{Xcos diagram for LED interfacing}
% \label{fig:xcosblk}
% \end{figure}

% \begin{figure}
% \centering
% \includegraphics[width=\smfig]{\LocLEDfig/xcos-desc.png}
% \caption{Xcos blocks}
% \label{fig:xcosdesc}
% \end{figure}

% \section{Experiment: Blink LED for limited number of iterations}
% This experiment is about continuous switching on and switching off the LED a fixed number of times. Here we use  for loop to carry out limited number of iterations of the code.  The structure of for loop is:

% \begin{lstlisting}      
% for variable = start_point:end_point
%    instructions
% end
% \end{lstlisting}   

% Here variable is incremented by 1 in every iteration, till the condition variable=end\_point is met. Thus before each iteration, the above condition is verified. Figure shows the flow-chart of the operation.
% \begin{figure}
% \centering
% \includegraphics[width=\smfig]{\LocLEDfig/LEDflowchart.png}
% \caption{Flow chart}
% \label{fig:ledfc}
% \end{figure}



\begin{exercise}
Carry out the following exercise:
\begin{enumerate}
\item Change the blink pattern for an array of LEDs
\item Change the delays
\end{enumerate}
\end{exercise}
\clearpage
\section{Arduino Code}
\lstset{style=mystyle}
\label{sec:led-arduino-code}
\addtocontents{ard}{\protect\addvspace{\codclr}}

\begin{ardcode}
\acaption{Turning on the blue LED}{Turning on the blue LED.  Available
  at \LocLEDardbrief{led-blue/led-blue.ino}.}
\label{ard:led-blue}
\lstinputlisting{\LocLEDardcode/led-blue/led-blue.ino}
\end{ardcode}

\begin{ardcode}
\acaption{Turning on the blue LED and turning it off after two
  seconds}{Turning on the blue LED and turning it off after two
  seconds.  Available  
  at \LocLEDardbrief{led-blue-delay/led-blue-delay.ino}.}
\label{ard:led-blue-delay}
\lstinputlisting{\LocLEDardcode/led-blue-delay/led-blue-delay.ino}
\end{ardcode}

\begin{ardcode}
  \acaption{Turning on blue and red LEDs for 5 seconds and then turning
    them off one by one}{Turning on blue and red LEDs for 5 seconds and
  then turning them off one by one.  Available at
  \LocLEDardbrief{led-blue-red/led-blue-red.ino}.}
\label{ard:led-blue-red}
\lstinputlisting{\LocLEDardcode/led-blue-red/led-blue-red.ino}
\end{ardcode}

\begin{ardcode}
  \acaption{Blinking the green LED}{Blinking the green LED.  Available
  at \LocLEDardbrief{led-blink/led-blink.ino}.}
\label{ard:led-blink}
\lstinputlisting{\LocLEDardcode/led-blink/led-blink.ino}
\end{ardcode}

\section{Scilab Code}
\lstset{style=mystyle}
\label{sec:led-scilab-code}
\addtocontents{cod}{\protect\addvspace{\codclr}}

\begin{scicode}
\ccaption{Turning on the LED}
{Turning on the LED.  Available at
  \LocLEDscibrief{led-blue.sce}.}
\label{sci:led-blue}
\lstinputlisting{\LocLEDscicode/led-blue.sce}
\end{scicode}

\begin{scicode}
\ccaption{Turning on the blue LED and turning it off after two
  seconds}{Turning on the blue LED and turning it off after two
  seconds.  Available  
  at \LocLEDscibrief{led-blue-delay.sce}.}
\label{sci:led-blue-delay}
\lstinputlisting{\LocLEDscicode/led-blue-delay.sce}
\end{scicode}

\begin{scicode}
  \ccaption{Turning on blue and red LEDs for 5 seconds and then turning
    them off one by one}{Turning on blue and red LEDs for 5 seconds and
  then turning them off one by one.  Available at
  \LocLEDscibrief{led-blue-red.sce}.}
\label{sci:led-blue-red}
\lstinputlisting{\LocLEDscicode/led-blue-red.sce}
\end{scicode}

\begin{scicode}
  \ccaption{Blinking the green LED}{Blinking the green LED.  Available
  at \LocLEDscibrief{led-green-blink.sce}.}
\label{sci:led-green-blink}
\lstinputlisting{\LocLEDscicode/led-green-blink.sce}
\end{scicode}
