
@chapter Using Searduino

In the previous chapter we looked a bit at the digpins example, so we
now have some feeling for using Searduino. We will now proceed by
writing our first Arduino program using Searduino.

@section Writing the first program

@subsection Let Searduino generate the first C file and Makefile 
@*
@*
Let's assume you want to create a program and you want to store it in
a directory called blinker. Then, all you have to do is to run the
following command:
@*
@*
@code{/opt/searduino/bin/searduino-builder --create blinker }
@*
@*
Searduino will now create a main.c file and a Makefile. Let's have a look:
@*
@*
@code{cd}
@*
@code{cd searduino/blinker}
@*
@code{ls -al}
@*
@*
Let's build the example and run it in the simulator:
@*
@*
@code{make}
@*
@code{make sim-start}
@*
@*
@*
@*
Let's build the example and run it on a board (Uno in this example):
@*
@*
@code{make}
@*
@code{make uno-upload}
@*
@*
Nice :)

@subsection Write first C file on your own
@*
@*
There are a couple of steps needed to get a program built and loaded
in to ether an Arduino board or any of the Searduino simulators. In
short the steps are:
@itemize @bullet
@item write a main function
@item call init() explicitly
@item write an eternal loop in your program's main function
@end itemize
@*
@*
Open up your favorite editor (emacs?) and begin....
@*
@*
To use the Arduino functionality you need to include Arduino.h and searduino.h, so
we need to add this to our file:
@*
@*
@code{#include <Arduino.h>}
@*
@code{#include <searduino.h>}
@*
@*
@*
When using Arduino IDE you've seen the @code{loop} function as the
starting point for the program. With Searduino we're back to the
normal C way of doing this with a @code{main} function, so we need to define a main function.
@*
@*
@code{int main(void)}
@{
@}
@*
@*
As with the loop function you're writing when you're using the Arduino IDE,
the main function needs to never exit or return. It's a simple control
loop (see @uref{http://en.wikipedia.org/wiki/Embedded_system#Simple_control_loop}).
@*
@*
So a very simple main function looks like this
@*
@*
@include example_01.texi

@*
@*
@i{Note: this program sets pin 13 high and low with 0.1 secs
interval. You don't need to connect a led to output pin 13, since
pin 13 already has a built in led on the board.}

@subsection Write the first Makefile on your own

@b{Inporant settings in the Makefile}
@itemize @bullet
@item SEARDUINO_PATH - should be set to the directory of your
Searduino installation
@item PROG - name of the program to build
@item SHLIB - name of the shared library to build
@item SRC_C - a list (separated with space) of C files to compile
@item SRC_CXX - a list (separated with space) of C++ files to compile
@item ARDUINO - should be set to the type of software you want to
build (see @b{Build types} below)
@end itemize
@*
@*
@b{Include the searduino makefile}
@*
You need to include some settings, targets and rules from
Searduino. This is done by adding the following line to your Makefile.
@*
@*
@code{include $(SEARDUINO_PATH)/share/searduino/mk/searduino.mk}
@*
@*
@*
A Makefile to build the code above can look like this:
@*
@*
@include example_m_01.texi


@i{Note: You don't have to use the makefiles provided by
Searduino. The makefiles do however provide a lot of help (board settings etc).}



@subsection Building the program for your local computer
To build your software to be executed on your local computer, and not
for a real Arduino board:

make sure the the variable @b{ARDUINO} in the Makefile is set to
@b{stub}.


 and type:
@*
@*
@code{make clean}
@*
@code{make prog}
@*

To run the program
@*
@*
@code{./seardex}


@subsection Building a shared library for use in the simulators
To build your software to be executed on your PC:
make sure the the variable @b{ARDUINO} in the Makefile is set to
@b{stub}.

 and type:
@*
@*
@code{make clean}
@*
@code{make shlib}
@*
@*
To run the code in the stream simulator
@*
@*
@code{/opt/searduino/bin/searduino-stream-sim --arduino-code ./seardex.so}
@*
@*
To run the code in the Jearduino simulator
@*
@*
@code{/opt/searduino/bin/searduino-jearduino.sh --arduino-code ./seardex.so}


@subsection Building the program for UNO
To build your software to be executed on your PC:

make sure the the variable @b{ARDUINO} in the Makefile is set to
@b{uno} and type:
@*
@*
By setting ARDUINO to uno the Searduino makefiles will use the
settings for building and uploading for the Arduino UNO board. 
@*
To build the program, all we have to do now is to type:
@*
@*
@code{make clean}
@*
@code{make prog}
@*
@*
@*
To upload and run the program on the Arduino UNO board:
@*
@*
@code{make upload}
@*
@*
You should now be able to see the built in led (pin 13) flash. If not,
the author of this document need to his homework.
@*
@i{You can also upload to the board with the safe-upload makefile
target. Searduino scans your program for objects known to cause
problems on the Arduino boards before uploading to the board.}

@section Searduino Makefile variables 
You can fine tune the compilation and linking of your Arduino programs
using the Searduino Makefile variables. 

@multitable  @columnfractions .0 .35 .65
@item 
@tab @b{Variable}
@tab @b{Description}

@item
@tab @code{USER_C_FLAGS}
@tab Adds the value of the variable to both Arduino and simulation C compilation

@item
@tab @code{USER_CXX_FLAGS}
@tab Adds the value of the variable to both Arduino and simulation C++
compilation

@item
@tab @code{USER_LD_FLAGS}
@tab Adds the value of the variable to both Arduino and simulation C/C++
linking

@item
@tab @code{USER_STUB_C_FLAGS}
@tab Adds the value of the variable to simulation C compilation

@item
@tab @code{USER_STUB_CXX_FLAGS}
@tab Adds the value of the variable to simulation C++ compilation

@item
@tab @code{USER_STUB_LD_FLAGS}
@tab Adds the value of the variable to simulation linking

@item
@tab @code{USER_ARDUINO_C_FLAGS}
@tab Adds the value of the variable to Arduino C compilation

@item
@tab @code{USER_ARDUINO_CXX_FLAGS}
@tab Adds the value of the variable to Arduino C++ compilation

@item
@tab @code{USER_ARDUINO_LD_FLAGS}
@tab Adds the value of the variable to Arduino linking

@end multitable



@section Setting the USB port to use for uploading to Arduino boards
@*
Searduino tries to find the USB port to use automatically for you. In some
cases, e g if you have more than one Arduino board attached yo your
computer, it is not possible for Searduino to know which port you aim
to program.
@*
You can bypass Searduino's method of finding correct device. You do
this by the environment variable @code{USER_PORT}. 
@*
@subsection Setting USER_PORT in bash
@*
Here's an example of how to instruct Searduino to use
@code{/dev/ttyACM0} for programming.
@*
@code{export USER_PORT=/dev/ttyACM0}
@*
After this you can invoke make on your makefile as usual.
@*
@subsection Setting USER_PORT in a Makefile
@*
Here's an example of how to instruct Searduino to use
@code{/dev/ttyACM0} for programming.
@*
Add the following to your Makefile, before you include the file @code{searduino.mk}
@*
@code{USER_PORT=/dev/ttyACM0}
@*
After this you can invoke make on your makefile as usual.


@section Checking version of Searduino
@*
In your makefile you can specify the earliest version you want to
use. If this requirement is not met, including the file
@code{searduino.mk} will yield an error. Set the variable
@code{REQUESTED_SEARDUINO_VERSION} 
to the version you (at least) want, e g 0.60:
@*
@*
@code{REQUESTED_SEARDUINO_VERSION=0.60}
@*


@section I2C devices
@* 
Searduino provies an API to write software to simulate I2C devices.
@*
@subsection Registering an I2C device
@*
To register an I2C device you us the function @code{int  seasim_i2c_add_device (unsigned int device_nr, const char  *setup_fun)}. 
@*

The argument (device_nr) corespond to the device number of the device
you want to simulate and the name of the function that setups up your
I2C code.
@*
When calling the i2c_add_device function Searduino will find the
setup function you provide and call it.
@*

@*
@subsection Build the I2C device
@*
To build your I2C code and prepare it to be loaded by the simulator,
simply write a Makefile and follow the procedures as in the section
``Building a shared library for use in the simulators''.




