===== Using Arduino with Marty the Robot =====

<note>
**Note:** This interface is in early beta and is subject to change
</note>

You can connect an Arduino to Marty via the expansion port on Marty's control board, RIC. This will provide power and a serial data connection to the Arduino, and you can write Arduino programs to control Marty

<note warning>
Marty's logic level is 3.3v, so if you are using a cable without any level shifting you **must only use 3.3v Arduinos**. Using a 5V Arduino may damage your Marty's control board
</note>

==== You will need ====

  * An expansion cable providing a four wire interface
    * GND
    * 5v
    * TX
    * RX
  * An Arduino with a 3v3 logic level

<blockquote width="400" align="center">
{{ :martyv2:userguides:arduinocable.jpg?nolink&400 |}}
The Arduino connector cable with four wires
</blockquote>

===== Set Up =====

==== The Arduino Library ====

  - Download the {{ :martyv2:userguides:martyarduino.zip |}} file with the Marty Arduino Library in it
  - In the Arduino IDE select from the menu select Sketch -> Include Library -> Add .ZIP Library...
  - Select the MartyArduino.zip file you just downloaded, the Marty library will be added to your sketch

==== Connecting to Marty ====

=== Connect the cable to Marty's control board ===

Open Marty's face plate by opening the back cover of Marty, removing the top plate, and pushing down on the two small clips at the top of the face

{{ :martyv2:userguides:openfaceplate.jpg?nolink&600 |}}

The face plate should be pivoted forward and held in place by the clip at the bottom

Next, attach the Arduino cable to the expansion port at the front of the control board

{{ :martyv2:userguides:arduinocableconnectionric.jpg?nolink&600 |}}

Close the face plate again and ensure the two clips at the top of the face are clicked back into position

{{ :martyv2:userguides:faceplatereattached.jpg?nolink&600 |}}

Feed the wires through the slot in the top plate, and reassemble the head

{{ :martyv2:userguides:headwitharduinowires.jpg?nolink&600 |}}

=== Connect the wires to your Arduino ===

The four wires should be connected as follows

^ Wire ^ Arduino Connection ^ Note ^
| Black | GND ||
| Red | VCC | Leave this unconnected while programming the Arduino |
| Blue | RXD ||
| Purple | TXD ||

{{ :martyv2:userguides:arduinowireconnections.jpg?nolink&600 |}}

==== Writing an Arduino Program ====

=== A simple example ===

A really simple Arduino program for Marty looks like this

```cpp
#include "MartyArduino.h"

Marty marty(Serial);

void setup() {
  // put your setup code here, to run once:
  marty.init();
}

void loop() {
  // put your main code here, to run repeatedly:
  marty.dance();
  sleep(10);
}

```

You must include the `#include "MartyArduino.h`and `Marty marty(Serial)` lines at the beginning of your program to get access to Marty's functions and instantiate a `marty` object that will let you talk to Marty. The `Serial` here specifies which serial port on the Arduino to use - in this case we're using the default one

You must also include the `marty.init()` line inside your setup function to open the connection to Marty

After that, you can send commands to Marty by calling the appropriate function in the main loop. This example program makes Marty dance repeatedly, waiting 10 seconds in between each dance

=== Programming the Arduino ===

Unless you are using a serial port other than the primary one on the Arduino, it is necessary to turn Marty off before programming the Arduino. In this case you will also need to disconnect the 5v power line

{{ :martyv2:userguides:arduinonopower.jpg?nolink&600 |}}

A suggested method for programming Marty with the Arduino is this
  - Leave the 5v wire disconnected from the Arduino
  - With Marty turned off connect the USB cable to your Arduino and program it
  - Turn Marty on, and it will run the program you have made
  - If you want to change the program, turn Marty off by pressing and holding the power button
  - Then you can update the program
  - Once you are happy with your program:
    - Disconnect the USB cable from the Arduino
    - Connect the 5V wire from Marty to the VCC pin on your Arduino
    - Turn Marty on. This will power up the Arduino as well, and your Marty will run your program without needing any external connections!

===== Function Reference =====

These are just some starter functions as the library is in a very early stage right now, they will be added to in due course

==== dance ====

```cpp
void dance(uint16_t move_time=3000, bool blocking=true)
```

Makes Marty dance

**Arguments**:
  * ''%%move_time%%'' - a number in milliseconds for the length of the movement. Defaults to 3000ms
  * ''%%blocking%%'' - Blocking mode override; whether to wait for the physical movement to finish before returning. Defaults to true

==== wiggle ====

```cpp
void wiggle(uint16_t move_time=4000, bool blocking=true);
```

A bit like dance, but without the hip movements

**Arguments**:
  * ''%%move_time%%'' - a number in milliseconds for the length of the movement. Defaults to 4000ms
  * ''%%blocking%%'' - Blocking mode override; whether to wait for the physical movement to finish before returning. Defaults to true

==== sidestep ====

```cpp
void sidestep(String side="left", uint8_t steps=1, uint8_t step_length=35, uint16_t move_time=1000, bool blocking=true);
```

Take a number of sidesteps to the left or right

**Arguments**:
  * ''%%side%%'' - `left` or `right`. Defaults to `left`
  * ''%%steps%%'' - how many steps to take. Defaults to 1
  * ''%%step_length%%'' - attempted step size in mm. Defaults to 35mm
  * ''%%move_time%%'' - a number in milliseconds for the length of each step. Defaults to 1000ms
  * ''%%blocking%%'' - Blocking mode override; whether to wait for the physical movement to finish before returning. Defaults to true

==== arms ====
```cpp
void arms(int8_t left_angle=0, int8_t right_angle=0, uint16_t move_time=1000, bool blocking=true);
```

Move Marty's arms to specified angles

**Arguments**:
  * ''%%left_angle%%'' - the angle to move the left arm to in degrees between -100 and 100. Defaults to 0
  * ''%%right_angle%%'' - the angle to move the right arm to in degrees between -100 and 100. Defaults to 0
  * ''%%move_time%%'' - a number in milliseconds for the length of the movement. Defaults to 1000ms
  * ''%%blocking%%'' - Blocking mode override; whether to wait for the physical movement to finish before returning. Defaults to true

==== walk ====

```cpp
void walk(uint8_t steps=1, int8_t turn=0, int8_t step_length=25, uint16_t move_time=1500, bool blocking=true);
```

Take a number of steps forwards or backwards, with an optional turn

**Arguments**:
  * ''%%steps%%'' - how many steps to take. Defaults to 1
  * ''%%turn%%'' - how much to turn on each step, in degrees. Defaults to 0
  * ''%%step_length%%'' - attempted step size in mm. Defaults to 25mm
  * ''%%move_time%%'' - a number in milliseconds for the length of each step. Defaults to 1500ms
  * ''%%blocking%%'' - Blocking mode override; whether to wait for the physical movement to finish before returning. Defaults to true