===== Marty's First Steps with Python =====

Use **MartyPy** to make your **Marty V2** dance and walk from Python. This guide starts with an interactive Python shell, then shows how to save the same commands as a program.

==== Before you begin ====

Install Python 3 and MartyPy on the computer that will run your code:

  * [[:martyv2:userguides:python:setting_up_python_on_your_computer|Set up Python on your computer]]
  * [[:martyv2:userguides:python:setting_up_python_on_raspberry_pi|Set up Python on a Raspberry Pi]]

Open the Python shell in your chosen editor, such as IDLE or Thonny. Run the examples in the environment where you installed MartyPy. If you are using a Raspberry Pi remotely, run the code on the Pi.

Turn on Marty and place it on a flat surface with room to move. Disconnect the Robotical app and stop any other program controlling the same Marty before starting these examples.

==== Choose a connection ====

Use **one** of the following connection methods. You do not need Wi-Fi when using USB.

=== USB ===

Connect your computer to the USB-C port on the back of Marty using a **data-capable USB cable**. With one Marty connected, MartyPy can find its serial port automatically:

```python
from martypy import Marty
my_marty = Marty("usb")
```

If automatic detection fails, or more than one Marty is connected, specify the correct serial port. For example, on Windows:

```python
from martypy import Marty
my_marty = Marty("usb", "COM3")
```

Replace `COM3` with your Marty's actual port. On macOS or Linux, use its serial-device path instead, such as `/dev/tty.SLAB_USBtoUART` or `/dev/ttyUSB0`. These are examples, not fixed port names. To list the ports visible to Python, run `python -m serial.tools.list_ports` in your terminal using the same Python environment.

When several Martys are detected, automatic detection selects one of them; it does not identify the Marty you intended to use. Specify its port or connect only one Marty.

=== Wi-Fi ===

First [[:martyv2:userguides:marty:wifi|connect Marty to your Wi-Fi network]] and [[:martyv2:support_faqs:connectivity:find_ip|find its current IP address]]. The computer running your code must be on a network that can reach Marty; for this guide, use the same local network.

```python
from martypy import Marty
my_marty = Marty("wifi", "192.168.1.15")
```

Replace `192.168.1.15` with your Marty's current IP address. It may change when Marty reconnects to the network. In the current Robotical app, connect Marty and open **Robot settings → Wi-Fi** to check its network connection. Disconnect the app before opening the MartyPy connection.

The screenshots below illustrate a Wi-Fi session in IDLE. The commands are the same when you use USB; your editor, Python version and IP address may look different.

==== Make Marty Dance ====

After importing Marty and opening **one** connection as shown above, enter:

```python
my_marty.dance()
```

In a fresh Python shell, the complete USB example is:

```python
from martypy import Marty
my_marty = Marty("usb")
my_marty.dance()
```

For Wi-Fi, replace the connection line with `my_marty = Marty("wifi", "192.168.1.15")`, using your Marty's address. Do not open a second connection if you already have `my_marty` connected in this shell.

Type the commands without the shell's `>>>` prompt. Python comments start with `#` and explain the code without being executed.

=== Line 1: Import martypy ===

`from martypy import Marty` imports the `Marty` class from the MartyPy library. This lets us use `Marty(...)` in the next line.

{{:martyv2:userguides:python:martypy-idle-ex1-line1.png?600&direct|Importing the Marty class from martypy in an IDLE shell}}

Another valid style is `import martypy`, followed by `martypy.Marty(...)`. Use one style consistently: `import martypy` alone does not create the name `Marty` in your shell.

=== Line 2: Establish connection ===

{{:martyv2:userguides:python:martypy-idle-ex1-line2.png?600&direct|Creating a Wi-Fi connection to Marty with an example IP address}}

`my_marty` is a variable holding the connection to your Marty. The `=` sign assigns the new `Marty` object to that variable.

The first argument chooses the connection method: `"usb"` or `"wifi"`. The second argument, when supplied, is the USB serial port or Wi-Fi IP address. For USB with one detected Marty, the port can be omitted. For Wi-Fi, supply your robot's address.

=== Line 3: Dance! ===

{{:martyv2:userguides:python:martypy-idle-ex1-line3.png?600&direct|Calling my_marty.dance in the connected Python shell}}

`my_marty.dance()` calls the `dance` method on your connected Marty. A method is an action or operation associated with an object; the dot selects it and the brackets call it.

Movement commands use **blocking mode by default**: Python waits for Marty to finish moving before continuing. In an interactive shell, a successful command may display `True`, meaning Marty accepted the request. Wait for the prompt to return before entering the next command.

Keep using this same `my_marty` variable for the walking examples below. Import and connect again only when you start a new session or after you have closed the connection.

==== Make Marty Walk ====

=== First Step ===

With `my_marty` still connected, enter:

```python
my_marty.walk()
```

With no arguments, `walk()` requests **two steps forward**, with an approximate step length of **25 mm**. You do not need to import or connect again in the same session.

{{:martyv2:userguides:python:martypy-idle-ex2-1.png?600&direct|Calling walk with its default two steps in the existing Marty session}}

To request just one step, use `my_marty.walk(1)`.

=== More steps ===

The first argument to `walk` is the number of steps. For example:

```python
my_marty.walk(10)
```

{{:martyv2:userguides:python:martypy-idle-ex2-2.png?600&direct|Requesting ten walking steps from Marty}}

An **argument** is information passed to a function or method. Here, `10` sets `num_steps`. Leave enough room for Marty to complete the requested movement.

=== Short steps ===

Use the named `step_length` argument to change how far each step moves. This requests five short steps of approximately 8 mm each:

```python
my_marty.walk(5, step_length=8)
```

{{:martyv2:userguides:python:martypy-idle-ex2-3.png?600&direct|Requesting five short steps with the named step_length argument}}

We name `step_length` because the second positional argument to `walk` is `start_foot`, not the step length. The distance is approximate and depends on Marty's calibration and the surface.

**Challenge:** Can you make Marty walk backwards? Try a negative `step_length`, such as `my_marty.walk(2, step_length=-8)`.

==== Finish the session ====

When your commands have finished, close the connection:

```python
my_marty.close()
```

Closing the connection releases its communication resources. It does not send a stop command to Marty. After closing it, create a new `Marty` object before sending more commands.

==== Save a Python program ====

To run the commands as a program, save the following in a file such as `marty_first_steps.py`, then run it from your editor. Choose a different filename from `martypy.py` so your file does not hide the installed library.

```python
from martypy import Marty

my_marty = Marty("usb")
# For Wi-Fi, replace the line above with:
# my_marty = Marty("wifi", "192.168.1.15")

try:
    my_marty.dance()
    my_marty.walk()
finally:
    my_marty.close()
```

Replace the example IP address if using Wi-Fi. The `finally` block closes the connection when the program leaves the `try` block, including if a movement call raises an exception. The movement calls keep their default blocking behaviour.

==== If something goes wrong ====

  * **MartyPy import error:** if Python reports `ModuleNotFoundError` for `martypy`, install MartyPy in the Python environment selected by your editor. See the setup guides above.
  * **Marty class not found:** if Python reports `NameError` for `Marty`, run `from martypy import Marty`, or use `martypy.Marty(...)` after `import martypy`.
  * **USB connection error:** check that the cable carries data, Marty is on, and the chosen port is correct. Close any other program using that serial port. If no port appears, follow your platform's USB driver and serial-access setup instructions.
  * **Wi-Fi connection error:** check Marty's current IP address and that the computer can reach it on the local network. School or guest networks may isolate devices; ask your network administrator if needed.
  * **Command does not finish:** stop other programs controlling Marty and check the connection. Closing and reopening the Python connection does not replace checking why the movement failed.

For more commands and their arguments, see the [[:martyv2:documentation:python_function_reference|Python Function Reference]].