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:
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:
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:
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 connect Marty to your Wi-Fi network and 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.
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:
my_marty.dance()
In a fresh Python shell, the complete USB example is:
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.
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
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!
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:
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.
To request just one step, use my_marty.walk(1).
More steps
The first argument to walk is the number of steps. For example:
my_marty.walk(10)
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:
my_marty.walk(5, step_length=8)
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:
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.
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 Python Function Reference.