\input texinfo @c -*-texinfo-*-
@c Copyright (c) 2018-2024, John Donoghue <john.donoghue@ieee.org>
@c Octave Arduino - a somewhat Matlab compatible Arduino toolkit for GNU octave.

@c For manually generating the documentation use
@c   LANGUAGE=en makeinfo --html --no-split arduino.texi

@c %*** Start of HEADER
@setfilename arduino.info
@settitle Arduino Toolkit - a somewhat Matlab compatible arduino toolkit for GNU octave.
@afourpaper
@paragraphindent 0
@finalout
@set COPYRIGHT_DATE 2018-2024
@c @afourwide
@c %*** End of the HEADER

@include version.texi
@include macros.texi

@macro boxnote {args}
@cartouche
@strong{NOTE}

\args\
@end cartouche
@end macro


@c %*** Start of TITLEPAGE
@titlepage
@title Arduino Toolkit @value{VERSION}
@subtitle  a somewhat MATLAB compatible Arduino toolkit for @acronym{GNU} Octave.
@author John Donoghue
@page
@vskip 0pt plus 1filll
Copyright @copyright{} @value{COPYRIGHT_DATE} John Donoghue

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the same conditions as for modified versions.

@page
@heading Distribution
The @acronym{GNU} Octave arduino package is @dfn{free} software.
Free software is a matter of the users' freedom to run, copy, distribute,
study, change and improve the software.
This means that everyone is free to use it and free to redistribute it
on certain conditions.  The @acronym{GNU} Octave arduino package
is not, however, in the public domain.  It is copyrighted and there are
restrictions on its distribution, but the restrictions are designed to
ensure that others will have the same freedom to use and redistribute
Octave that you have.  The precise conditions can be found in the
@acronym{GNU} General Public License that comes with the @acronym{GNU}
Octave arduino package and that also appears in @ref{Copying}.

To download a copy of the @acronym{GNU} Octave arduino package, please visit
@url{https://github.com/gnu-octave/octave-arduino/releases}.

@end titlepage
@c %*** End of TITLEPAGE

@c %*** Start of BODY

@dircategory Math
@direntry
* Arduino for Octave: (arduino).         Arduino Toolbox for Octave 
@end direntry

@contents
@ifnottex
@node Top
@top Introduction
The Arduino toolkit is a somewhat Matlab compatible arduino toolkit for GNU octave.
@end ifnottex

@menu
* Installing and loading::    Installing and loading the Arduino toolkit
* Hardware setup::            Setting up the Arduino hardware
* Connecting to an arduino::  Making a connection to an arduino device
* Basic Input and Output Overview::    Performing basic I/O
* Protocol based I/O Overview::    Performing protocol based I/O
* Addons Overview::           Arduino Addons
* Sensors Overview::          Sensors
* Examples::                  Examples using the Arduino toolkit
* Function Reference::        Arduino toolkit functions
* Copying::                   Copying
* Index::                     Index
@end menu

@c -------------------------------------------------------------------------
@node Installing and loading
@chapter Installing and loading
@cindex Installing and loading

The Arduino toolkit must be installed and then loaded to be used.

It can be installed in @acronym{GNU} Octave directly from octave-forge,
or can be installed in an off-line mode via a downloaded tarball.

@boxnote{The toolkit requires the @url{https://www.arduino.cc/en/software, Arduino IDE} in order to program Arduino devices.}

@boxnote{The toolkit has a dependency on the instrument-control package, so it must be installed in order
to successfully install the Arduino toolkit}

The toolkit must be then be loaded once per each @acronym{GNU} Octave session in order to use its functionality.

@section Online Direct install
@cindex Online install
With an internet connection available, the Arduino package can be installed from
octave-forge using the following command within @acronym{GNU} Octave:

@example
pkg install -forge arduino
@end example

The latest released version of the toolkit will be downloaded and installed.

@section Off-line install
@cindex Off-line install
With the arduino toolkit package already downloaded, and in the current directory when running
@acronym{GNU} Octave, the package can be installed using the following command within @acronym{GNU} Octave:

@example
pkg install arduino-@value{VERSION}.tar.gz
@end example

@section Loading
@cindex Loading
Regardless of the method of installing the Arduino toolkit, in order to use its functions,
the toolkit must be loaded using the pkg load command:

@example
pkg load arduino
@end example

The toolkit must be loaded on each @acronym{GNU} Octave session.

@c -------------------------------------------------------------------------
@node Hardware setup
@chapter Hardware setup
@cindex Hardware setup

In order to use the arduino hardware with the toolkit, it must be programmed with
special firmware.

@section Programming the Arduino
@cindex Programming the Arduino
To program the hardware, using a default configuration, run the arduinosetup command:

@example
arduinosetup
@end example

A temporary Arduino project will be created, with the Arduino toolkit files copied to it and the Arduino IDE will open.

Set the board type and port correctly for the connected Arduino and press the upload button on the IDE.

The sources will be compiled and then uploaded to the connected arduino board.

After successful upload the Arduino IDE should be closed.

@boxnote{The arduino programming is not compatible with the Matlab arduino library, so must be programmed by
the Octave Arduino toolkit to communicate to the arduino, even if it was previously used to work with Matlab.}

@boxnote{The toolkit requires the @url{https://www.arduino.cc/en/software, Arduino IDE} in order to program the Arduino device.

The binary can set using the 'arduinobinary' property when running setup.

For arduino IDEs before version 2, if the toolkit can not find the IDE, run the IDE manually, close it and retry programming
the Arduino. Otherwise, use the 'arduino' binary property.}

@section Known Arduino Board Types
@cindex Known Arduino Board Types
The board type must be known in order to successfully detect and connect to the Arduino board after programming.

Currently, known boards are:
@itemize @bullet
@item
Arduino Due
@item
Arduino UNO
@item
Arduino Mega 2560
@item
Arduino Nano
@item
Arduino Nano Every
@item
Arduino Nano 33 BLE
@item
Arduino Nano RP2040 Connect
@item
Arduino Pro/Pro Mini
@item
Arduino Pro Micro
@item
Arduino Leonardo
@item
Arduino Micro
@item
Arduino MKR1000
@item
Arduino MKRZero
@item
Sparkfun SAMD21
@item
Arduino Lilypad
@item
Arduino UNO WiFi rev2
@boxnote{The Arduino servo library code may require modifications to
 eliminate conflicts between servos and the tone library}
@item
Arduino UNO WiFi r4
@item
Arduino UNO Minima r4
@item
Raspberry Pi Pico
@item
EPS32 Dev
@end itemize

Additional boards can be added easily, however require minor code changes.

@c -------------------------------------------------------------------------
@node Connecting to an arduino
@chapter Connecting to an arduino
@cindex Connecting to an arduino

To control an arduino device, a connection must be made to it by creating an arduino object.

@section Connecting to a single arduino
@cindex Connecting to a single arduino
Assuming a single arduino device is connected to the computer, creating an arduino object with no arguments will
find the connected arduino and connect to it:

@example
ar = arduino()
@end example

@section Connecting to a specific arduino
@cindex Connecting to a specific arduino
Where multiple arduinos may be connected to the computer, a specific board can be connected by
specifying the name of the port it is connected to:

@example
ar = arduino("/dev/ttyACM0")
@end example

The port name will be operating system dependent.

@section Querying available arduinos
@cindex Querying available arduinos
To list the ports of all @emph{programmed} available arduinos, the scanForArduinos function can be used:

@example
scanForArduinos
@end example

It will provide a list of all available boards it can find with the port they are connected to.

@boxnote{The scanForArduinos function will only detect boards that have been programmed using the arduinosetup command}

@c -------------------------------------------------------------------------
@node Basic Input and Output Overview
@chapter Basic Input and Output Overview
@cindex Basic Input and Output Overview

Basic input and output can be performed on a connected arduino device using by calling the read and write functions
for a specific named pin on the arduino.

A list of available pins can get found from the pins property of the connected arduino object and are also displayed
as part of the default shown properties:

@example
ar = arduino();
% get the pin names
pins = ar.availablepins
@end example

Pin generally follow a naming scheme of D<number> for digital pins and A<number> for analog pins.

Digital pins can be used to read and write digital data, but can not read analog voltages.
Analog pins can perform digital I/O as well as reading voltages.

@section Performing Digital I/O
@cindex Performing Digital I/O

A pin's digital logic value can be true (1) or false (0) and can be set using the writeDigitalPin function.

The following example attempts to set the D2 pin of the connected arduino object "ar" to true, waits 5 seconds and
then sets it to false:

@example
writeDigitalPin (ar,  "d2", true);
pause 5
writeDigitalPin (ar,  "d2", false);
@end example


Using the readDigitalPin will read the current logic state of the pin.

@example
value = readDigitalPin (ar,  "d2");
@end example

@section Performing Analog Input
@cindex Performing Analog Input

For analog pins, the voltage level can be read using a analog to digital conversion and will return a voltage level
between 0 and the boards voltage (nominally 5V):

@example
value = readVoltage (ar,  "a0");
@end example


The raw digital value of the pin can also be read instead of a voltage, giving a value between 0 and 2^x where x is
the number of bits used by the analog to digital converter.

@example
value = readAnalogPin (ar,  "a0");
@end example


@c -------------------------------------------------------------------------
@node Protocol based I/O Overview
@chapter Protocol based I/O Overview
@cindex Protocol based I/O Overview

The arduino toolkit supports more complex I/O for SPI, I2C, Servo control and more.

@section SPI communication
@cindex SPI communication

SPI communication can be performed by creating a SPI device object and then calling the writeRead function:

@example
spi = device (ar,  "spichipselectpin", "d2");
@end example

The function call expects a connected arduino object as the first argument, followed by the chip select pin of the SPI device.

After a device is created, a write to device followed by read can can be made using the writeRead function:

@example
spi = device (ar,  "spichipselectpin", "d2");
data = writeRead (spi,  100);
@end example


@section I2C communication
@cindex I2C communication

I2C communication can be performed by creating an I2C device object for a specific I2C address.

The following example creates an I2C device that will communicate with a I2C device at address 100"
@example
i2c = device (ar,  "i2caddress", 100);
@end example

After creating an I2C device, data can be read and written using read, write, readRegister and writeRegister. The data to send 
and receive will be device dependent.

@section Servo communication
@cindex Servo communication

Servo communication can be performed after creating a servo device object to operate on a PWM pin:

@example
servoobj = servo(ar, "d9", "minpulseduration", 1.0e-3, ...
  "maxpulseduration", 2e-3);
@end example

The servo function expects the connected arduino object and the PWM pin that the servo is connected to. Optional properties 
can be specified to control the setup of device.

In the example, the min and max pulse width values are set.


Using the servo object the current position and be read or set with values ranging between 0 to 1, with 0 being the minimum 
pulse width and 1 being the maximum.

The following example sets the servo to its middle position.

@example
servoobj = servo(ar, "d9", "minpulseduration", 1.0e-3, ...
  "maxpulseduration", 2e-3);

writePosition (servoobj, 0.5);
@end example


@section Shift Registers
@cindex Shift Registers

A shift register can be controlled by creating a shiftRegister object:

@example
registerobj = shiftRegister(ar, '74hc164', "d2", "d3");
@end example

The parameters required are dependent on the type of shift register created.

Once a register object has been created, it can be read and written to using the read and write functions.

@section Rotary Encoders
@cindex Rotary Encoder

A rotary encoder can be created by creating a rotaryEncoder object.

@example
encoder = rotaryEncoder(ar, "d2", "d3", 180);
@end example

Using the created object, the rotary encoder value and speed can be read.

@section Ultrasonic Sensors
@cindex Ultrasonic Sensors

An ultrasonic sensor can be read by creating an ultrasonic object.

@example
sensor = ultrasonic(ar, "d9", "d10");
@end example

Using the created object, the sensor distance and echo time and be read.

@section Serial communication
@cindex Serial communication

Serial communication can be performed on devices that support multiple serial devices such as the leonardo and mega2560 boards. 
The communications port to Octave is reserved and can not be used as a user controlled communications port.


Serial communication can be performed by creating a serial device object and then calling the read and write functions:

@example
ser = device (ar,  "serial", 1);
@end example

The function call expects a connected arduino object as the first argument, followed "serial" and serial id.

After a device is created, the device can be read and written:

@example
ser = device (ar,  "serial", 1);
write(ser, "hello");
data = read(ser, 100);
@end example

@c -------------------------------------------------------------------------
@node Addons Overview
@chapter Addons Overview
@cindex Addons Overview

This chapter provides an overview of the arduino package addon functionality for adding
additional addons to arduino.

@section Addon Introduction
@cindex Addon Introduction

Addons provide a way of adding additional functionality to the arduino toolkit
that provides Matlab access directly to the arduino hardware.

Addons are implemented in two parts.
@enumerate
@item code running on the arduino that implements the required functionality
@item a octave wrapper class that provides the Matlab interface and communication to the code.
@end enumerate

Both parts are required to create a plugin.

The arduino toolkit provides a number of pre-created addons. These can be seen using
the following command:

@example
@code {
listArduinoLibraries
}
@end example

The command will display all known arduino libraries (addons as well as core libraries), however
addons typically use a "foldername/classname" for this naming.

@xseealso{listArduinoLibraries}

@section Creating an addon
@cindex Creating an addon

An addon requires at minimum 3 things:
@enumerate
@item A addon package directory that will contain the addon files
@item A Matlab file within that directory that is a subclass of arduinoio.LibraryBase
@item A arduino source/header file that contains the arduino code to load, sub-classed for LibraryBase
@end enumerate

So the addon directory structure at a minimum will be:
@example
@code {
  +arduinoioaddons  (dir) [somewhere in the octave load path]
    +MyAddons (dir)
      MyAddon1.m 
      MyAddon1.h
}
@end example

@subsection  Addon package directory
@cindex  Addon package directory

The addon architecture looks for plugins in the octave load path in a package directory called 
+arduinoioaddons

So this directory must be created somewhere within the paths that octave will check for 
functions.

In addition, the addon architecture expects plugins to be contained in a sub directory within
the +arduinoioaddons folder. The subdirectory must begin with a '+'.

Multiple plugin .m files can be within the same sub directory.

@subsection  Addon package .m file
@cindex  Addon package .m file

The Matlab interface file within the addon directory provides the Matlab interface for the arduino code
as well as provides information about the addon.

@subsubheading Class inheritance and required properties
The interface file must be a subclass of arduinoio.LibraryBase and must contain some constant properties values that provide the information.

A minimum example of required is below:
@example
@code {
classdef MyAddon1 < arduinoio.LibraryBase
  properties(Access = protected, Constant = true)
    LibraryName = 'MyAddons/MyAddon1';
    CppHeaderFile = fullfile(arduinoio.FilePath(mfilename('fullpath')), 'MyAddon1.h');
    CppClassName = 'MyAddon1';
  endproperties
  .
  .
  .
endclassdef
}
@end example

The following constant properties can be set within the addon:
@table @asis
@item LibraryName
(Required) The name of the addon. My convention this is usually the directoryname / theclassname
@item CppHeaderFile
(Required) The header file for the arduino code
@item CppSourceFile
(Optional) The source file (if any) for the arduino code
@item CppClassName
(Required) The classname used within the cppheaderfile for the arduino library
@item DependantLibraries
(Optional) Any additional addons or cores that are needed for this library to be used
@item ArduinoLibraryHeaderFiles
(Optional) Any additional header files that need to be included
@end table

@subsubheading Class constructor
The Matlab class constructor will be called from the addon function when creating a
instance of the addon and should initialize at least two properties in inherited from
arduinoio.LibraryBase:

@enumerate
@item Parent
should be set to the first input argument (the arduino class)
@item Pins
should be set to a list of pins that are used for the plugin
@end enumerate

@example
@code {
classdef MyAddon1 < arduinoio.LibraryBase
  .
  .
  methods
    function obj = MyAddon1(parentObj, varargin)
      obj.Parent = parentObj;
      # no pins being used
      obj.Pins = [];
      # send any command to the arduino during setup ?
    endfunction
    .
    .
  endmethods
endclassdef
}
@end example

@subsubheading Class functions

The class functions will usually communicate to the arduino and use the response for 
what is returned to the user.

By convention, the commands sent to the arduino are defined as constants in the class file but do not have to be.
@example
@code {
classdef MyAddon1 < arduinoio.LibraryBase
  properties(Access = private, Constant = true)
    INIT_COMMAND = hex2dec('00');
    FUNC1_COMMAND = hex2dec('01');
  endproperties
  .
  .
  methods
    function obj = MyAddon1(parentObj, varargin)
      obj.Parent = parentObj;
      # no pins being used
      obj.Pins = [];
      # send any command to the arduino during setup ?
      sendCommand(obj.Parent, obj.LibraryName, obj.INIT_COMMAND, []);
    endfunction

    function retval = func1(obj)
       cmdID = obj.FUNC1_COMMAND;
       retval = sendCommand(obj.Parent, obj.LibraryName, cmdID, []);
    endfunction
    .
    .
  endmethods
endclassdef
}
@end example

@boxnote{the sendCommand uses the objects parent for the arduino,  the objects library name and the command id}

@xseealso{sendCommand}

@subsection  Addon package header file
@cindex  Addon package header file

The header file should contain a class that matches the functionally and information of the matlab file
and provides the ability to register the code on the arduino.

The following things should occur in the arduino class files:
@enumerate
@item The class name within the file must be the same as the one set in the .m file
CppClassName property.

@item The libName variable must be the same as the LibraryName property.

@item The constructor should call registerLibrary

@item the commandHandler function to act on cmdID values that match the commands that will be sent from .m file and send
 data back using sendResponseMsg

@item on receiving unknown cmdID values, the commandHandler should use sendUnknownCmdIDMsg

@end enumerate

An example, matching the previous .m file code is below:
@example
@code {
#include "LibraryBase.h"

#define MYADDON1_INIT  0x00
#define MYADDON1_FUNC1 0x01

class MyAddon1 : public LibraryBase
@{
  uint8_t cnt;
public:
  MyAddon1(OctaveArduinoClass& a)
  @{
    libName = "MyAddons/MyAddon1";
    a.registerLibrary(this);
  @}
  void commandHandler(uint8_t cmdID, uint8_t* data, uint8_t datasz)
  @{
    switch (cmdID)
      @{
      case MYADDON1_INIT:
        @{
          cnt = 0;
          sendResponseMsg(cmdID, 0,0);
          break;
        @}
      case MYADDON1_FUNC1:
        @{
          // func 1 is just returning a uint8 count of number of times called
          cnt ++;
          sendResponseMsg(cmdID, &cnt, 1);
          break;
        @}
      default:
        @{
          // notify of invalid cmd
          sendUnknownCmdIDMsg();
        @}
      @}
  @}
@}
};
@end example

The body of functions can be in the CppSourceFile file is it is defined or within the header file as illustrated above.

@subsection  Verify octave can see the addon
@cindex  Verify octave can see the addon

Use the listArduinoLibaries command to verify that the new addon appears in the list of known libraries.

If it does not, ensure that the +arduinoioaddons directory is within one of the octave class paths, and that the directory
structure and inheritance requirements have been met.

@section Using addons
@cindex  Using Addons

@subsection  Programming the arduino with the addon
@cindex  Programming the arduino with the addon

To use a addon, the code must be programmed onto the arduino.

Using the libraries command, when creating a arduino object, the arduino can be reprogrammed if the library does not already
exist on the arduino.

@example
@code {
  ar = arduino([],[], 'libraries', 'MyAddons/MyAddon1', 'forcebuild', true)
}
@end example

The libraries property of the arduino object should list the libraries programmed on the arduino.

Alternatively, the library can be added using the libraries property and arduinosetup

@xseealso{arduino, arduinosetup}

@subsection  Creating a addon object
@cindex  Creating a addon object

An object of the addon type can be created using the addon command.

@example
@code {
  ar = arduino([],[], 'libraries', 'MyAddons/MyAddon1', 'forcebuild', true)
  obj = addon(ar, "MyAddons/MyAddon1");
}
@end example

@c -------------------------------------------------------------------------
@node Sensors Overview
@chapter Sensors Overview
@cindex Sensors Overview

There are two types of sensors available:
@enumerate
@item
Matlab compatible(ish) sensors for environment and IMU.
@item
Additional lightweight wrappers for some chips in a arduinosensor namespace.
@end enumerate

@section Matlab Compatible Sensors
@cindex Matlab Compatible Sensor

@subsection Overview
Matlab compatible functions are provided for a number of sensors, using a similar function naming as
provided by the Matlab arduino package.

@subsection Available Sensors
@cindex Available Sensors

The functions for each sensor is listed in the function reference, @ref{Sensors} and provides for:

@table @asis
@item bme280
BME280 temperature, pressure and humidity sensor
@item bno005
BNO055 acceleration, angular velocity, orientation and magnetic field sensor
@item lis3dh
LIS3DH acceleration sensor
@item lps22hb
LPS22HB temperature and pressure sensor
@item lsm6dso
LSM6DSO acceleration, angular velocity sensor
@item mpu6050
MPU-6050  acceleration, angular velocity sensor
@item SI7021
SI7021 temperature and humidity sensor
@end table


@section Lightweight Arduino Sensors
@cindex Arduino Sensor

@subsection Overview
Arduino sensors are a collection of lightweight wrappers around other underlying protocols for 
providing specific sensor functionality.

For instance a DS1307 chip communicates using I2C protocol and so a DS1307 class exists that
provides the conversion/commands in order to communicate to the chip.

Using the class, providing the functionality is very easy:
@example
@code {
a = arduino()
rtc = arduinosensor.DS1307(a)
# get and display rtc time as a date string
datestr(rtc.clock)
}
@end example

It is lightweight compared to the addon functionality, as it only requires a wrapper class rather than add on code,
however it is limited to then using available addon and core codes rather than creating new ones.

Currently the are only a small number of sensors available, however this will be built upon in future versions.

@subsection Available Sensors
@cindex Available Sensors

The functions for each sensor is listed in the function reference, @ref{Arduino Sensors} and provides for:

@table @asis
@item DS1307
DS1307 RTC clock using i2c.
@item MPC3002
MPC3002 ADC using SPI
@item SI7021
SI7021 temperature and humidity sensor
@item GUVAS12SD
GUVAS12SD analog UV-B sensor
@end table

@c -------------------------------------------------------------------------
@node Examples
@chapter Examples
@cindex Examples

@section Blinking an LED
@cindex Blinking an LED

This example shows blinking the inbuilt LED on the Arduino board. Code is available by running:
@example
edit examples/example_blink
@end example

@heading Hardware setup
This example uses in the builtin LED, so requires only a connection of the Arduino board to
computer for communication.

@heading Create an Arduino object

@example
ar = arduino ();
@end example

If you have more than one Arduino board connected, you may need to specify the port in order to
connect to the correct device.

@heading Query Device for pins connected to builtin LED

The pin connected to the Arduino UNO built in led if D13.

@example
led_pin = "d13";
@end example

The connected pins can be queried programatically if desired.

@example
pins = getLEDTerminals (ar);
@end example

Connected to a Arduino UNO would return a list pins containing only one item '13'.

The terminal number can be converted to a pin using getPinsFromTerminals:

@example
led_pin = getPinsFromTerminals (ar, pins@{1@});
@end example


@heading Turn the LED off

Write a 0 value to the pin to turn it off.

@example
writeDigitalPin (ar, led_pin, 0);
@end example

@heading Turn the LED on

Write a 1 value to the pin to turn it on

@example
writeDigitalPin (ar, led_pin, 1);
@end example

@heading Making the LED blink

Add a while loop with a pause between the changes in the pin state to blink.

@example
while true
  writeDigitalPin (ar, led_pin, 0);
  pause (0.5)
  writeDigitalPin (ar, led_pin, 1);
  pause (0.5)
endwhile
@end example

@section Using I2C to communicate with an EEPROM
@cindex Using I2C to communicate with an EEPROM

This example shows using I2C to communicate with a EEPROM chip. Code is available by running:
@example
edit examples/example_i2c_eeprom
@end example

@heading Hardware setup
Using an Arduino UNO, the board should be configured with the following connections between the board and a 24XX256 EEPROM chip:

@table @asis
@item A4
Connected to pin 5 of EEPROM
@item A5
Connected to pin 6 of EEPROM
@item 5V
Connected to pin 8 of EEPROM
@item GND
Connected to pin 1,2,3,4 of EEPROM
@end table

@heading Create an Arduino object

@example
ar = arduino ();
@end example

If you have more than one Arduino board connected, you may need to specify the port in order to
connect to the correct device.

@heading Query I2C pins
Display the I2C terminals of the board:

@example
getI2CTerminals(ar)
@end example

@heading Scan the arduino for the connected device

@example
scanI2Cbus(ar)
@end example

The devices listed should contain 0x50, the address of the EEPROM chip.

@heading Create an I2C object to communicate to the EEPROM
@example
eeprom = device (ar, "i2caddress", 0x50)
@end example

@heading Write data to the EEPROM

The EEPROM expects the first byte to be the page number, the second the offset, followed by data,
so to write 1 2 3 4, starting address 0 (page 0, offset 0):

@example
write(eeprom, [0 0 1 2 3 4])
@end example

@heading Reading from the EEPROM

Reading from the EEPROM requires first writing the address to read from, in this case, if we
want to read the 3, 4, this would be page 0, offset 2:

@example
write(eeprom, [0 2])
@end example

Next read the 2 bytes:

@example
data = read(eeprom, 2)
@end example

@c -------------------------------------------------------------------------
@section Using SPI to communicate with a mcp3002 10 bit ADC
@cindex Using SPI to communicate with a mcp3002 10 bit ADC

This example shows using SPI to communicate with an mcp3002 10 bit ADC. Code is available by running:
@example
edit examples/example_spi_mcp3002
@end example

@heading Hardware setup
Using an Arduino UNO, the board should be configured with the following connections between the board and a mcp3002 chip:

@table @asis
@item D10
Connected to pin 1 (CS) of MCP3002
@item D11
Connected to pin 5 (DI) of MCP3002
@item D12
Connected to pin 6 (DO) of MCP3002
@item D13
Connected to pin 7 (CLK) MCP3002
@item VCC
Connected to pin 8 (VDD) MCP3002
@item GND
Connected to pin 4 (VSS) MCP3002
@item Analog input
Connected from pin 2 of the MCP3002 to a LOW (< 5V) voltage to measure
@end table

@heading Create an Arduino object

@example
ar = arduino ();
@end example

If you have more than one Arduino board connected, you may need to specify the port in order to
connect to the correct device.

@heading Create an SPI object to communicate to the MCP3002
@example
adc = device(ar, "spichipselectpin", "d10")
@end example

The d10 is the chip select pin connected from the Arduino to the MCP3002.

@heading Read the ADC

The MCP3002 expects specific commands in order to read a channel.

For illustration for the command to read chan 0 in single ended mode:
@example
command (bits) in MSB mode to device:
[START SGL ODN MSBF X X X X] [ X X X X X X X X ] 
   1    1   0    1   1 1 1 1    1 1 1 1 1 1 1 1 
      [chan 0 ] MSB    
data back:
   X    X  X     X   X 0 D D    D D D D D D D D
@end example

D is a output data bit

X is a don't care what value is input/output

The first byte contains the command and start of the data read back, the second bytes is written to clock out
the rest of the ADC data.

In hex, this corresponds to 0xDF 0xFF,

@example
data = writeRead(adc, [hex2dec("DF") hex2dec("FF")])
@end example

Of the data returned, the last 10 bits is the actual data, so convert data to a 16 bit value:
@example
val = uint16(data(1))*256 + uint16(data(2))
@end example

Then bitand it to remove the non value parts, to get the ADC value:
@example
val = bitand (val, hex2dec('3FF'))
@end example

To make the value correspond to a voltage it needs to be scaled as 0 will be 0 Volts, 1023 will be 5 Volts.
@example
volts = double(val) * 5.0 / 1023.0;
@end example

@c -------------------------------------------------------------------------
@node Function Reference
@chapter Function Reference
@cindex Function Reference

The functions currently available in the Arduino toolkit are described below;

@include functions.texi

@c -------------------------------------------------------------------------

@include gpl.texi

@c -------------------------------------------------------------------------
@node Index 
@unnumbered Index 
 
@printindex cp
 
@bye