Automated installation¶

RobotPy is truly cross platform, and can be installed from Windows, most Linux distributions, and from Mac OSX also. Here’s how you do it:

• Download RobotPy from github
• Make sure Python 3.4 or newer is installed

Unzip the RobotPy zipfile somewhere on your computer (not on the roboRIO), and there should be an installer.py there. Open up a command line, change directory to the installer location, and run this:

Windows:   py -3 installer.py install-robotpy

Linux/OSX: python3 installer.py install-robotpy

It will ask you a few questions, and copy the right files over to your robot and set things up for you.

Next, you’ll want to create some code (or maybe use one of our examples), and upload it to your robot! Refer to our Programmer’s Guide for more information.

Windows:   py installer.py download-robotpy

Linux/OSX: python3 installer.py download-robotpy

Windows:   py installer.py install-robotpy

Linux/OSX: python3 installer.py install-robotpy

Manual installation (release)¶

If you really want to do this, it’s not so bad, but then you lose out on the benefits of the automated installer – in particular, this method requires internet access to install the files on the roboRIO in case you need to reimage your roboRIO.

• Connect your roboRIO to the internet

• SSH in, and copy the following to /etc/opkg/robotpy.conf:

  src/gz robotpy http://www.tortall.net/~robotpy/feeds/2017
  

• Run this:

  opkg install python36 netconsole-host
  

• Then run this:

  pip3 install robotpy-hal-roborio wpilib
  

Upgrading requires you to run the same commands, but with the appropriate flags set to tell pip3/opkg to upgrade the packages for you.

Install via pip on Windows¶

The easiest installation is by using pip. pip is installed by default with Python 3.4. Run the following command from the command line:

py -3 -m pip install pyfrc

To upgrade, you can run this:

py -3 -m pip install --upgrade pyfrc

If you don’t have administrative rights on your computer, either use virtualenv/virtualenvwrapper-win, or or you can install to the user site-packages directory:

py -3 -m pip install --user pyfrc

Install via pip on OSX/Linux¶

The easiest installation is by using pip. pip is installed by default with Python 3.4 (though on Linux it may not be installed). On a Linux or OSX system that has pip installed, just run the following command from the Terminal applciation (may require admin rights):

pip3 install pyfrc

To upgrade, you can run this:

pip3 install --upgrade pyfrc

If you don’t have administrative rights on your computer, either use virtualenv/virtualenvwrapper, or or you can install to the user site-packages directory:

pip3 install --user pyfrc

Manual install (without pip)¶

While this is possible to do, due to the large number of dependencies this is not recommended nor is it supported.

code coverage support¶

If you wish to run code coverage testing, then you must install the coverage package. It requires a compiler to install from source. However, if you are using a supported version of Python and a modern version of pip, it may install a binary wheel instead, which removes the need for a compiler.

Windows:   py -3 -m pip install coverage

Linux/OSX: pip3 install coverage

If you run into compile errors, then you will need to install a compiler on your system.

• On Windows you can download the Visual Studio compilers for Python (be sure to download the one for your version of Python).
• On OSX it requires XCode to be installed
• On Linux you will need to have python3-dev/python3-devel or a similar package installed

Install via pip on Windows¶

The latest versions of Python on Windows come with pip, but you may need to install it by hand if you’re using an older version. Once pip is installed, run the following command from the command line:

Python 2.7: py -2 -m pip install pynetworktables
Python 3.x: py -3 -m pip install pynetworktables

To upgrade, you can run this:

Python 2.7: py -2 -m pip install --upgrade pynetworktables
Python 3.x: py -3 -m pip install --upgrade pynetworktables

If you don’t have administrative rights on your computer, either use virtualenv/virtualenvwrapper-win, or or you can install to the user site-packages directory:

Python 2.7: py -2 -m pip install --user pynetworktables
Python 3.x: py -3 -m pip install --user pynetworktables

Install via pip on OSX/Linux¶

On a Linux or OSX system that has pip installed, just run the following command from the Terminal application (may require admin rights):

Python 2.7: pip install pynetworktables
Python 3.x: pip3 install pynetworktables

To upgrade, you can run this:

Python 2.7: pip install --upgrade pynetworktables
Python 3.x: pip3 install --upgrade pynetworktables

If you don’t have administrative rights on your computer, either use virtualenv/virtualenvwrapper-win, or or you can install to the user site-packages directory:

Python 2.7: pip -m pip install --user pynetworktables
Python 3.x: pip3 -m pip install --user pynetworktables

Manual install (without pip)¶

You can download the source code, extract it, and run this:

python setup.py install

If you are using Python 2.7, you will need to also install the monotonic package from pypi

Getting Started¶

See the NetworkTables guide to learn more about using pynetworktables to communicate with your robot.

RoboRIO installation¶

If you have robotpy-installer on your computer, then installing robotpy-cscore is very simple:

# While connected to the internet
robotpy-installer download-opkg python36-robotpy-cscore

# While connected to the network with a RoboRIO on it
robotpy-installer install-opkg python36-robotpy-cscore

For additional details about running robotpy-installer on your computer, see the robotpy-installer documentation.

Compile from source¶

If you’re not installing on a RoboRIO, then installation of cscore has a few additional steps that you need to do:

1. Install a newer C++ compiler that supports C++11

   Note

   robotpy-cscore has not been tested on Windows

2. Install Python 3 (cscore is not supported on Python 2) and development headers

3. Install Numpy (either via pip3 or using a Linux package manager)

4. Install OpenCV (either via a Linux package manager or compile from source)

   • If you compile from source, you must enable shared library support, cscore cannot use a statically compiled OpenCV python module at this time

5. Install pybind11 via pip3: pip3 install pybind11

6. Install robotpy-cscore via pip3. It should be as easy as running pip3 install robotpy-cscore – though be warned, it takes several minutes to compile!

In the future we may provide binaries that can be installed on commonly used platforms, but there are a number of technical challenges that need to be solved and so that won’t be until at least 2018 if not later.

Installing/Executing the installer¶

To install/use the installer, you must have Python 3 installed. You can install the installer via pip (recommended) or you can use installer.py directly (see below).

On Windows:

py -3 -m pip install robotpy-installer

On Linux/OSX:

pip3 install robotpy-installer

To upgrade the installed version of the installer, you need to add the -U flag to pip.

py -3 -m robotpy_installer [command..]

robotpy-installer [command..]

py -3 installer.py [command..]

python3 installer.py [command..]

RobotPy¶

These commands allow you to install/upgrade RobotPy without needing to download a new version from github.

robotpy-installer install-robotpy

robotpy-installer download-robotpy

Python Packages¶

If you want to use a python package hosted on Pypi in your robot code, these commands allow you to easily download and install those packages.

robotpy-installer download-pip PACKAGE [PACKAGE ..]

robotpy-installer download-pip -r requirements.txt

robotpy-installer install PACKAGE [PACKAGE ..]

robotpy-installer install-pip -r requirements.txt

IPK (binary) packages¶

The RobotPy project maintains a number of custom binary packages that are useful for FRC teams. For a list of packages that you can install, see https://www.tortall.net/~robotpy/feeds/2017/. These commands can be used to install those and other precompiled Linux packages that NI makes available.

robotpy-installer download-opkg PACKAGE [PACKAGE ..]

robotpy-installer install-opkg PACKAGE [PACKAGE ..]

Language elements¶

# This is a comment. It starts with a '#' character

# this is good
if x == True:
    do_something()

# this is bad and will not work
if x == True:
do_something()

if False:
    pass

# A number
1

# Multiplying two numbers
2*2

"This is a string"
'This is also a string'
'''This is a string that can
   be extended to multiple lines'''
"""This is also
   a multiline string"""

Variables¶

Variables are used to store some information (strings, numbers, objects, etc). They can be assigned values, and referred to later on.

x = 1
x = 'some value'

Control Flow¶

if statement is True:
    # do_something here
elif other_statement is True:
    # do something lese here
else:
    # otherwise do this

Operations¶

Python supports various types of operations on variables and constants:

# Addition
1 + 2
x + 1

# Multiplication
1 * 2
x * 2

# Equality operator (evaluated to True or False)
1 == 1
x == 1

# Less than
x < 2

# Lots more!

Functions¶

Functions are blocks of code that can be reused and are useful for grouping code. They can return a value to the caller. The code that is contained inside of a function is not executed until you call the function.

def function_name():
    '''String that describes what the function does'''
    pass

def function_name(parameter1, parameter2):
    pass

def function_returns_computation(parameter1, parameter2):
    return parameter1 + parameter2

def function_returns_a_variable():
    x = 1
    return x

def function_returns_a_value():
    return True

# Calling a function that takes no parameters
function_name()

# Calling a function with two constant parameters
return_value = function_name(1, 2)

# Calling a function with two variables
return_value = function_name(x, y)

Classes¶

A collection of functions (also called methods) and variables can be put into a logical group called a ‘class’.

class Foo(object):
    '''String that describes the class'''

    def __init__(self):
        '''Constructor -- this function gets called when an instance is created'''

        # store a variable in the class for use later
        self.variable = 1

    def method(self, parameter1, optional_parameter=None):
        '''A function that belongs to the Foo class. It takes
           two arguments, but you can specify only one if you desire'''
        pass

class Bar(Foo):
    '''This class inherits from the Foo class, so anything in
       Foo is transfered (and accessible) here'''

    def __init__(self, parameter1):
        pass

foo = Foo()

# These are two separate instances of the Bar class, and operations on one
# do not affect the other
bar1 = Bar(1)
bar2 = Bar(1)

x = Foo()          # creates an instance of Foo
y = x.variable     # get the value from the instance
x.variable = 1     # set the value in the instance

x = Foo()     # this creates an instance of Foo
x.method()    # this calls the function

Loops¶

for i in a_list_of_things:
    print(i)

while statement is True:
    do_this_until_statement_is_not_true()

Exceptions¶

try:
    do_something_that_might_cause_an_exception()
    if bad_thing is True:
        raise SomeException()
except ExceptionType as e:
    # this code is only executed if an ExceptionType exception is raised
    print("Error: " + e)
finally:
    # This is always executed
    clean_up()

try:
    import wpilib
except ImportError:
    import fake_wpilib as wpilib

Future topics¶

• Lists, dictionaries, tuples
• Scope

Next Steps¶

Learn about the basic structure of Robot code at Anatomy of a robot.

Create your Robot code¶

Your robot code must start within a file called robot.py. Your code can do anything a normal python program can, such as importing other python modules & packages. Here are the basic things you need to know to get your robot code working!

Importing necessary modules¶

All of the code that actually interacts with your robot’s hardware is contained in a library called WPILib. This library was originally implemented in C++ and Java. Your robot code must import this library module, and create various objects that can be used to interface with the robot hardware.

To import wpilib, it’s just as simple as this:

import wpilib

Robot object¶

Every valid robot program must define a robot object that inherits from either wpilib.IterativeRobot or wpilib.SampleRobot. These objects define a number of functions that you need to override, which get called at various times.

• wpilib.IterativeRobot functions
• wpilib.SampleRobot functions

An incomplete version of your robot object might look like this:

class MyRobot(wpilib.IterativeRobot):

    def robotInit(self):
        self.motor = wpilib.Jaguar(1)

The robotInit function is where you initialize data that needs to be initialized when your robot first starts. Examples of this data includes:

• Variables that are used in multiple functions
• Creating various wpilib objects for devices and sensors
• Creating instances of other objects for your robot

In python, the constructor for an object is the __init__ function. Instead of defining a constructor for your main robot object, you can override robotInit instead. If you do decide that you want to override __init__, then you must call super().__init__() in your __init__ method, or an exception will be thrown.

Adding motors and sensors¶

Everything that interacts with the robot hardware directly must use the wpilib library to do so. Starting in 2015, full documentation for the python version of WPILib is published online. Check out the API documentation (wpilib) for details on all the objects available in WPILib.

self.motor = wpilib.Jaguar(4)

self.motor.set(1)

self.robot_drive = wpilib.RobotDrive(0,1)

l_motor = wpilib.Talon(0)
r_motor = wpilib.Talon(1)
self.robot_drive = wpilib.RobotDrive(l_motor, r_motor)

Robot Operating Modes (IterativeRobot)¶

During a competition, the robot transitions into various modes depending on the state of the game. During each mode, functions on your robot class are called. The name of the function varies based on which mode the robot is in:

• disabledXXX - Called when robot is disabled
• autonomousXXX - Called when robot is in autonomous mode
• teleopXXX - Called when the robot is in teleoperated mode
• testXXX - Called when the robot is in test mode

Each mode has two functions associated with it. xxxInit is called when the robot first switches over to the mode, and xxxPeriodic is called 50 times a second (approximately – it’s actually called as packets are received from the driver station).

For example, a simple robot that just drives the robot using a single joystick might have a teleopPeriodic function that looks like this:

def teleopPeriodic(self):
    self.robot_drive.arcadeDrive(self.stick)

This function gets called over and over again (about 50 times per second) while the robot remains in teleoperated mode.

Main block¶

Languages such as Java require you to define a ‘static main’ function. In python, because every .py file is usable from other python programs, you need to define a code block which checks for __main__. Inside your main block, you tell WPILib to launch your robot’s code using the following invocation:

if __name__ == '__main__':
    wpilib.run(MyRobot)

This simple invocation is sufficient for launching your robot code on the robot, and also provides access to various RobotPy-enabled extensions that may be available for testing your robot code, such as pyfrc and robotpy-frcsim.

Putting it all together¶

If you combine all the pieces above, you end up with something like this below, taken from one of the samples in our github repository:

#!/usr/bin/env python3
"""
    This is a good foundation to build your robot code on
"""

import wpilib

class MyRobot(wpilib.IterativeRobot):

    def robotInit(self):
        """
        This function is called upon program startup and
        should be used for any initialization code.
        """
        self.robot_drive = wpilib.RobotDrive(0,1)
        self.stick = wpilib.Joystick(1)

    def autonomousInit(self):
        """This function is run once each time the robot enters autonomous mode."""
        self.auto_loop_counter = 0

    def autonomousPeriodic(self):
        """This function is called periodically during autonomous."""

        # Check if we've completed 100 loops (approximately 2 seconds)
        if self.auto_loop_counter < 100:
            self.robot_drive.drive(-0.5, 0) # Drive forwards at half speed
            self.auto_loop_counter += 1
        else:
            self.robot_drive.drive(0, 0)    #Stop robot

    def teleopPeriodic(self):
        """This function is called periodically during operator control."""
        self.robot_drive.arcadeDrive(self.stick)

    def testPeriodic(self):
        """This function is called periodically during test mode."""
        wpilib.LiveWindow.run()

if __name__ == "__main__":
    wpilib.run(MyRobot)

There are a few different python-based robot samples available, and you can find them in our github examples repository.

Next Steps¶

This is a good foundation for building your robot, next you will probably want to know about Running robot code.

How to execute the script¶

py -3 robot.py

python3 robot.py

Commands¶

When you run your code without additional arguments, you’ll see an error message saying something like robot.py: error: the following arguments are required: command. RobotPy tools install various commands that you can run from your robot code. To discover the various features that are installed, you can use the --help command:

Windows:   py -3 robot.py --help

Linux/OSX: python3 robot.py --help

Next steps¶

There are two ways you can run the code: on the robot, and on the simulator:

• Deploying to the robot
• Robot Simulator

Immediate feedback via Netconsole¶

Note that when you run the deploy command like that, you won’t get any feedback from the robot whether your code actually worked or not. If you want to see the feedback from your robot without launching a separate NetConsole window, a really useful option is --nc. This will cause the deploy command to show your program’s console output, by launching a netconsole listener.

Windows:   py -3 robot.py deploy --nc

Linux/OSX: python3 robot.py deploy --nc

Skipping Tests¶

Now perhaps your tests are failing, but you really need to upload the code, and don’t care about the tests. That’s OK, you can still upload code to the robot:

Windows:   py -3 robot.py deploy --skip-tests

Linux/OSX: python3 robot.py deploy --skip-tests

Starting deployed code at boot¶

If you wish for the deployed code to be started up when the roboRIO boots up, you need to make sure that “Disable RT Startup App” is not checked in the roboRIO’s web configuration. See the FIRST documentation for more information.

Manually deploying code¶

Generally, you you just use the steps above. However, if you really want to, then see How to manually run code.

Next Steps¶

Let’s talk about the robot simulator next.

Communicating with SmartDashboard¶

The simulator can be used to communicate with the SmartDashboard or other NetworkTables clients. For this to work, you need to tell SmartDashboard to connect to the IP address that your simulator is listening on (typically this is 127.0.0.1). Using the original SmartDashboard, you need to launch the jar using the following command:

$ java -jar SmartDashboard.jar ip 127.0.0.1

If you are using the SFX dashboard, there is a configuration option that you can tweak to get it to connect to a different IP. You can also launch it from the command line using the following command:

$ java -jar sfx.jar 127.0.0.1

Real Joystick support via pygame¶

If you have pygame installed for Python 3, when you run the simulator any supported joysticks you have plugged in should automatically provide joystick input to the simulator.

Gazebo simulation¶

This is currently experimental, and hasn’t been updated in awhile. If you want to play with it now (and help us fix the bugs!), check out the robotpy-frcsim github repository.

Next Steps¶

The next section discusses a very important part of writing robot code – Unit testing robot code.

Builtin unit tests¶

pyfrc comes with testing functions that can be used to test basic functionality of just about any robot, including running through a simulated practice match. As of pyfrc 2016.1.1, to add these standardized tests to your robot code, you can run the following:

Windows:   py -3 robot.py add-tests

Linux/OSX: python3 robot.py add-tests

Running this command creates a directory called ‘tests’ if it doesn’t already exist, and then creates a file in your tests directory called pyfrc_test.py, and put the following contents in the file:

from pyfrc.tests import *

Unlike previous years, all tests work on all types of robots now.

As of pyfrc 2015.0.2, the --builtin option allows you to run the builtin tests without needing to create a tests directory.

Writing your own test functions¶

Often it’s useful to create custom tests to test specific things that the generic tests aren’t able to test. When running a test, py.test will look for functions in your test modules that start with ‘test_’. Each of these functions will be ran, and if any errors occur the tests will fails. A simple test function might look like this:

def two_plus(arg):
    return 2 + arg

def test_addition():
    assert two_plus(2) == 4

The assert keyword can be used to test whether something is True or False, and if the condition is False, the test will fail.

Pytest supports something called a ‘fixture’, which allows you to add an argument to your test function and it will call the fixture and pass the result to your test function as that argument. pyfrc has a custom pytest plugin that it uses to provide this special functionality to your tests.

For more information:

• RobotPy example code
• py.test documentation

code coverage for tests¶

pyfrc supports measuring code coverage using the coverage.py module. This feature can be used with any robot.py commands and provide coverage information.

For example, to run the ‘test’ command to run unit tests:

Windows:   py -3 robot.py coverage test

Linux/OSX: python3 robot.py coverage test

Or to run coverage over the simulator:

Windows:   py -3 robot.py coverage sim

Linux/OSX: python3 robot.py coverage sim

Running code coverage while the simulator is running is nice, because you don’t have to write unit tests to make sure that you’ve completely covered your code. Of course, you should write unit tests anyways... but this is good for developing code that needs to be run on the robot quickly and you need to make sure that you tested everything first.

When using the code coverage feature, what actually happens is robot.py gets executed again, except this time it is executed using the coverage module. This allows coverage.py to completely track code coverage, otherwise any modules that are imported by robot.py (and much of robot.py itself) would not be reported as covered.

Next Steps¶

Learn more about some Best Practices when creating robot code.

Make sure you’re running the latest version of RobotPy!¶

Seriously. We try to fix bugs as we find them, and if you haven’t updated recently, check to see if you’re out of date! This is particularly true during build season.

Don’t use the print statement/logger excessively¶

Printing output can easily take up a large proportion of your robot code CPU usage if you do it often enough. Try to limit the amount of things that you print, and your robot will perform better.

Instead, you may want to use this pattern to only print once every half second (or whatever arbitrary period):

# Put this in robotInit
self.printTimer = wpilib.Timer()
self.printTimer.start()

..

# Put this where you want to print
if self.printTimer.hasPeriodPassed(0.5):
    self.logger.info("Something happened")

Remember, during a competition you can’t actually see the output of Netconsole (it gets blocked by the field network), so there’s not much point in using these except for diagnostics off the field. In a competition, disable it.

Don’t die during the competition!¶

If you’ve done any amount of programming in python, you’ll notice that it’s really easy to crash your robot code – all you need to do is mistype something and BOOM you’re done. When python encounters errors (or components such as WPILib or HAL), then what happens is an exception is raised.

There’s a lot of things that can cause your program to crash, and generally the best way to make sure that it doesn’t crash is test your code. RobotPy provides some great tools to allow you to simulate your code, and to write unit tests that make sure your code actually works. Whenever you deploy your code using pyfrc, it tries to run your robot code’s tests – and this is to try and prevent you from uploading code that will fail on the robot.

However, invariably even with all of the testing you do, something will go wrong during that really critical match, and your code will crash. No fun. Luckily, there’s a good technique you can use to help prevent that!

What you need to do is set up a generic exception handler that will catch exceptions, and then if you detect that the FMS is attached (which is only true when you’re in an actual match), just continue on instead of crashing the code.

Here’s what I mean:

try:
    # some code goes here
except:
    if not self.isFmsAttached():
        raise

What this does is run some code, and if an exception occurs in that code block, and the FMS is connected, then execution just continues and hopefully everything continues working. However (and this is important), if the FMS is not attached (like in a practice match), then the raise keyword tells python to raise the exception anyways, which will most likely crash your robot. But this is good in practice mode – if your driver station is attached, the error and a stack trace should show up in the driver station log, so you can debug the problem.

Now, a naive implementation would just put all of your code inside of a single exception handler – but that’s a bad idea. What we’re trying to do is make sure that failures in a single part of your robot don’t cause the rest of your robot code to not function. What we generally try to do is put each logical piece of code in the main robot loop (teleopPeriodic) in its own exception handler, so that failures are localized to specific subsystems of the robot.

With these thoughts in mind, here’s an example of what I mean:

def teleopPeriodic(self):

    try:
        if self.joystick.getTrigger():
            self.arm.raise_arm()
    except:
        if not self.isFmsAttached():
            raise

    try:
        if self.joystick.getRawButton(2):
            self.ball_intake.()
    except:
        if not self.isFmsAttached():
            raise

    # and so on...

    try:
        self.robot_drive.arcadeDrive(self.joystick)
    except:
        if not self.isFmsAttached():
            raise

Consider using a robot framework¶

If you’re creating anything more than a simple robot, you may find it easier to use a robot framework to help you organize your code and take care of some of the boring details for you. While frameworks sometimes have a learning curve associated with them, once you learn how they work you will find that they can save you a lot of effort and prevent you from making certain kinds of mistakes.

See our documentation on Robot Code Frameworks

Robot Configuration¶

FIRST introduced the mDNS based addressing for the RoboRIO in 2015, and generally teams that use additional devices have found that while it works at home and sometimes in the pits, it tends to not work correctly on the field at events. For this reason, if you use pynetworktables on the field, we strongly encourage teams to ensure every device has a static IP address.

• Static IPs are 10.XX.XX.2
• mDNS Hostnames are roborio-XXXX-frc.local (don’t use these!)

For example, if your team number was 1234, then the static IP to connect to would be 10.12.34.2.

For information on configuring your RoboRIO and other devices to use static IPs, see the WPILib screensteps documentation.

Server initialization (Robot)¶

WPILib automatically starts NetworkTables for you, and no additional configuration should need to be done.

Client initialization (Driver Station/Coprocessor)¶

As of 2017, this is very easy to do. Here’s the code:

from networktables import NetworkTables

NetworkTables.initialize(server='10.xx.xx.2')

The key is specifying the correct server hostname. See the above section on robot configuration for this.

Theory of operation¶

In its most abstract form, NetworkTables can be thought of as a dictionary that is shared across multiple computers across the network. As you change the value of a table on one computer, the value is transmitted to the other side and can be retrieved there.

The keys of this dictionary must be strings, but the values can be numbers, strings, booleans, various array types, or raw binary. Strictly speaking, the keys can be any string value, but they are typically path-like values such as /SmartDashboard/foo.

When you call NetworkTables.getTable, this retrieves a NetworkTable instance that allows you to perform operations on a specified path:

table = NetworkTables.getTable('SmartDashboard')

# This retrieves a boolean at /SmartDashboard/foo
foo = table.getBoolean('foo', True)

There is also an concept of subtables:

subtable = table.getSubTable('bar')

# This retrieves /SmartDashboard/bar/baz
baz = table.getNumber('baz', 1)

As you may have guessed from the above example, once you obtain a NetworkTable instance, there are very simple functions you can call to send and receive NetworkTables data.

• To retrieve values, call table.getXXX(name, default)
• To send values, call table.putXXX(name, value)

NetworkTables can also be told to call a function when a particular key in the table is updated.

External tools¶

WPILib’s OutlineViewer (requires Java) is a great tool for connecting to networktables and seeing what’s being transmitted.

• Download OutlineViewer

The Basics¶

The structure of a Command based program is simple and predictable. You inherit from the IterativeRobot class, configure the robot in robotInit(), and then run the Scheduler inside the *Periodic() methods.

Writing it can be done rather quickly, but the robotpy-wpilib-utilities package contains a pre-built skeleton class you can inherit, meaning that your program only needs to implement functions unique to your robot. Here is an example:

import wpilib
from commandbased import CommandBasedRobot

from commands import AutonomousCommandGroup

class MyRobot(CommandBasedRobot):

    def robotInit(self):
        '''Initialize things like subsystems'''

        self.autonomous = AutonomousCommandGroup()


    def autonomousInit(self):
        self.autonomous.start()

Setting up the scheduler and running it are handled by the CommandBasedRobot class. You only need to write the code for *Init() methods you want to use. Since you are overriding that class, you can easily change any functionality that doesn’t work for your robot, though the default implementation should work for most cases.

Error Handling¶

Crashes happen. Even the most careful programmer can write a command that breaks under unexpected conditions. Normally this will cause your program to reboot, costing precious seconds during a competition. With this in mind, the Scheduler is run inside an exception handler. If a crash happens inside a Command while your robot is connection to the Field Management System (i.e. - during a competition) the exception will be caught, running commands will be canceled, the error will be printed on the driver’s station, and the Scheduler loop will continue running normally.

If you need more advanced error handling functionality, you can override the `handleCrash()` method in your robot.py.

Pythonic Command Based Programming¶

All the classes you know from C++ and Java still exists in Python, allowing you to directly port your code with minimal changes. However, you can use some of the advantages of Python to make a few things a bit easier.

from subsystemtype import SubsystemType

subsystem1 = None

def init():
    global subsystem1

    subsystem1 = SubsystemType()

import subsystems
from wpilib.command import InstantCommand

class ExampleCommand(InstantCommand):

    def __init__(self):
        self.requires(subsystems.subsystem1)

    def initialize(self):
        subsystems.subsystem1.do_something()

drive_front_left = 1
drive_front_right = 2
drive_rear_left = 3
drive_rear_right = 4

drive = {
    'front_left': 1,
    'front_right': 2,
    'rear_left': 3,
    'rear_right': 4
}

class PortList():
    pass

drive = PortList()

drive.front_left = 1
drive.front_right = 2
drive.rear_left = 3
drive.rear_right = 4

import robotmap
from wpilib.command import Subsystem

class DriveSubsystem(Subsystem):
    def __init__():
        front_left_motor = robotmap.drive_front_left

Final Thoughts¶

Welcome to FRC programming with Python. This documentation is still developing, so if you find a great trick to make programming your robot in the Command based paradigm more “pythonic”, please update it with your ideas.

Philosophy¶

You should use the MagicRobot class as your base robot class. You’ll note that it’s similar to IterativeRobot:

import magicbot
import wpilib

class MyRobot(magicbot.MagicRobot):

    def createObjects(self):
        '''Create motors and stuff here'''
        pass

    def teleopInit(self):
        '''Called when teleop starts; optional'''

    def teleopPeriodic(self):
        '''Called on each iteration of the control loop'''

if __name__ == '__main__':
    wpilib.run(MyRobot)

A robot control program can be divided into several logical parts (think drivetrain, forklift, elevator, etc). We refer to these parts as “Components”.

from components import Elevator, Forklift

class MyRobot(MagicRobot):

    elevator = Elevator
    forklift = Forklift

    def teleopPeriodic(self):

        # self.elevator is now an instance of Elevator

class MyRobot(MagicRobot):

    elevator = Elevator

    def createObjects(self):
        self.elevator_motor = wpilib.Talon(2)


class Elevator:

    elevator_motor = wpilib.Talon

    def execute(self):
        # self.elevator_motor is a reference to the Talon instance
        # created in MyRobot.createObjects

class MyRobot(MagicRobot):

    front_swerve = SwerveModule
    back_swerve = SwerveModule

    def createObjects(self):

        # this is injected into the front_swerve instance of SwerveModule as 'motor'
        self.front_swerve_motor = wpilib.Talon(1)

        # this is injected into the back_swerve instance of SwerveModule as 'motor'
        self.back_swerve_motor = wpilib.Talon(2)

class SwerveModule:
    motor = wpilib.Talon

from collections import namedtuple
ShooterConfig = namedtuple("ShooterConfig", ['param1', 'param2', 'param3'])

class MyRobot(MagicRobot):

    shooter = Shooter
    shooter_cfg = ShooterConfig(param1=1, param2=2, param3=3)

class Shooter:
    cfg = ShooterConfig

    def execute(self):
        # you can access self.cfg.param1, self.cfg.param2, etc...

try:
    if self.joystick.getTrigger():
        self.component.doSomething()
except:
    self.onException()

with self.consumeExceptions():
    if self.joystick.getTrigger():
        self.component.doSomething()

Autonomous mode¶

MagicBot supports loading multiple autonomous modes from a python package called ‘autonomous’. To create this package, you must:

• Create a folder called ‘autonomous’ in the same directory as robot.py
• Add an empty file called ‘__init__.py’ to that folder

Any .py files that you add to the autonomous package will automatically be loaded at robot startup.

Dashboard & coprocessor communications¶

The simplest method to communicate with other programs external to your robot code (examples include dashboards and image processing code) is using NetworkTables. NetworkTables is a distributed keystore, or put more simply, it is similar to a python dictionary that is shared across multiple processes.

Magicbot provides a simple way to interact with NetworkTables, using the tunable property. It provides a python property that has get/set functions that read and write from NetworkTables. The NetworkTables key is automatically determined by the name of your object instance and the name of the attribute that the tunable is assigned to.

In the following example, this would create a NetworkTables variable called /components/mine/foo, and assign it a default value of 1.0:

class MyComponent:

    foo = tunable(default=1.0)

...

class MyRobot:
    mine = MyComponent

To access the variable, in MyComponent you can read or write self.foo and it will read/write to NetworkTables.

For more information about creating custom dashboards, see the following:

• pynetworktables2js docs
• Smartdashboard docs

Example Components¶

class Shooter:

    shooter_motor = wpilib.Talon

    # speed is tunable via NetworkTables
    shoot_speed = tunable(1.0)

    def __init__(self):
        self.enabled = False

    def enable(self):
        '''Causes the shooter motor to spin'''
        self.enabled = True

    def is_ready(self):
        # in a real robot, you'd be using an encoder to determine if the
        # shooter were at the right speed..
        return True

    def execute(self):
        '''This gets called at the end of the control loop'''
        if self.enabled:
            self.shooter_motor.set(self.shoot_speed)
        else:
            self.shooter_motor.set(0)

        self.enabled = False

from magicbot import StateMachine, state, timed_state

class ShooterControl(StateMachine):
    shooter = Shooter
    intake = Intake

    def fire(self):
        '''This function is called from teleop or autonomous to cause the
           shooter to fire'''
        self.engage()

    @state(first=True)
    def prepare_to_fire(self):
        '''First state -- waits until shooter is ready before going to the
           next action in the sequence'''
        self.shooter.enable()

        if self.shooter.is_ready():
            self.next_state_now('firing')

    @timed_state(duration=1, must_finish=True)
    def firing(self):
        '''Fires the ball'''
        self.shooter.enable()
        self.intake.feed_shooter()

class MyRobot(magicbot.MagicRobot):

    # High level components go first
    shooter_control = ShooterControl

    # Low level components come last
    intake = Intake
    shooter = Shooter

    ...

    def teleopPeriodic(self):

        if self.joystick.getTrigger():
            self.shooter_control.fire()

API Reference¶

Installation¶

robotpy-cscore can be easily installed with the RobotPy installer. See these instructions for details.

Automatic camera streaming¶

If you do not wish to modify or process the images from your camera, and only wish to stream a single camera via HTTP to a dashboard, then you only need to add the following to your robotInit function:

wpilib.CameraServer.launch()

That’s it! You should be able to connect to the camera using SmartDashboard, the default LabVIEW Dashboard, or if you point your browser at http://roborio-XXXX-frc.local:1181.

The quick vision example can be found in the RobotPy examples repository.

Image processing¶

Because the GIL exists (see above), RobotPy’s WPILib implementation provides a way to run your image processing code in a separate process. This introduces a number of rules that your image processing code must follow to efficiently and safely run on the RoboRIO:

• Your image processing code must be in its own file

• Never import the cscore package from your robot code, it will just waste memory

• Never import the wpilib or hal packages from your image

  Warning

  wpilib may not be imported from two programs on the RoboRIO. If this happens, the second program will attempt to kill the first program.

# Import the camera server
from cscore import CameraServer

# Import OpenCV and NumPy
import cv2
import numpy as np

def main():
    cs = CameraServer.getInstance()
    cs.enableLogging()

    # Capture from the first USB Camera on the system
    camera = cs.startAutomaticCapture()
    camera.setResolution(320, 240)

    # Get a CvSink. This will capture images from the camera
    cvSink = cs.getVideo()

    # (optional) Setup a CvSource. This will send images back to the Dashboard
    outputStream = cs.putVideo("Name", 320, 240)

    # Allocating new images is very expensive, always try to preallocate
    img = np.zeros(shape=(240, 320, 3), dtype=np.uint8)

    while True:
        # Tell the CvSink to grab a frame from the camera and put it
        # in the source image.  If there is an error notify the output.
        time, img = cvSink.grabFrame(img)
        if time == 0:
            # Send the output the error.
            outputStream.notifyError(cvSink.getError());
            # skip the rest of the current iteration
            continue

        #
        # Insert your image processing logic here!
        #

        # (optional) send some image back to the dashboard
        outputStream.putFrame(img)

wpilib.CameraServer.launch('vision.py:main')

wpilib.CameraServer.launch('camera/targeting.py:run')

Multiple Cameras¶

cscore easily supports multiple cameras! Here’s a really simple vision.py file that will get you started streaming two cameras to the FRC Dashboard program:

from cscore import CameraServer

def main():
    cs = CameraServer.getInstance()
    cs.enableLogging()

    usb1 = cs.startAutomaticCapture(dev=0)
    usb2 = cs.startAutomaticCapture(dev=1)

    cs.waitForever()

One thing to be careful of: if you get USB Bandwidth errors, then you probably need to do one of the following:

• Reduce framerate (FPS). The default is 30, but you can get by with 10 or even as low as 5 FPS.
• Lower image resolution: you’d be surprised how much you can do with a 160x120 image!

More information¶

• The WPILib screensteps documentation for cscore may be useful to explain concepts (though some details are different)
• robotpy-cscore API documentation

Installation¶

See installing robotpy-cscore.

Automatic camera streaming¶

See the quick_cameraserver.py example in the robotpy-cscore examples folder

Image Processing¶

See the intermediate_cameraserver.py example in the robotpy-cscore examples folder

Launching your script at startup¶

TODO: Add section about launching your script at coprocessor startup

opencv-python¶

robotpy-cscore is not currently able to use the opencv-python package on pypi, you will need to install python bindings for OpenCV some other way.

USB Camera Support¶

The cscore library currently only supports USB cameras on Linux. On other platforms you will want to use OpenCV to open a VideoCamera object. You can check at runtime to see if cscore is compiled with USB camera support by checking for the presence of a ‘UsbCamera’ class. If it’s not there, it’s not supported.

See the cvstream.py example for using OpenCV in this manner.

Goals¶

The python implementation of WPILib/HAL is derived from the Java implementation of WPILib. In particular, we strive to keep the python implementation of WPILib as close to the spirit of the original WPILib java libraries as we can, only adding language-specific features where it makes sense.

Things that you won’t find in the original WPILib can be found in the _impl package.

If you have a suggestion for things to add to WPILib, we suggest making a request to the WPILib team directly, or if appropriate you can add it to the robotpy_ext package, which is a separate package for “high quality code of things that should be in WPILib, but aren’t”. This package is installed by the RobotPy installer by default.

HAL Loading¶

Currently, the HAL is split into two python packages:

• hal - Provided by the robotpy-hal-base package
• hal_impl - Provided by either robotpy-hal-roborio or robotpy-hal-sim

You can only have a single hal_impl package installed in a particular python installation.

The hal package provides the definition of the functions and various types & required constants.

The hal_impl package provides the actual implementation of the HAL functions, or links them to a shared DLL via ctypes.

Adding options to robot.py¶

When run() is called, that function determines available commands that can be run, and parses command line arguments to pass to the commands. Examples of commands include:

• Running the robot code
• Running the robot code, connected to a simulator
• Running unit tests on the robot code
• And lots more!

python setuptools has a feature that allows you to extend the commands available to robot.py without needing to modify WPILib’s code. To add your own command, do the following:

• Define a setuptools entrypoint in your package’s setup.py (see below)

• The entrypoint name is the command to add

• The entrypoint must point at an object that has the following properties:

  • Must have a docstring (shown when --help is given)
  • Constructor must take a single argument (it is an argparse parser which options can be added to)
  • Must have a ‘run’ function which takes two arguments: options, and robot_class. It must also take arbitrary keyword arguments via the **kwargs mechanism. If it receives arguments that it does not recognize, the entry point must ignore any such options.

If your command’s run function is called, it is your command’s responsibility to execute the robot code (if that is desired). This sample command demonstrates how to do this:

class SampleCommand:
    '''Help text shown to user'''

    def __init__(self, parser):
        pass

    def run(self, options, robot_class, **static_options):
        # runs the robot code main loop
        robot_class.main(robot_class)

To register your command as a robotpy extension, you must add the following to your setup.py setup() invocation:

from setuptools import setup

setup(
      ...
      entry_points={'robotpy': ['name_of_command = package.module:CommandClassName']},
      ...
      )

Installing WPILib from git¶

1. Install python on the roboRIO using one of the methods in the installation guide.
2. Checkout the robotpy-wpilib git repository, and make your changes there
3. To deploy your changes, you can run devtools/build_and_deploy.sh from the root of the git repository.

How to manually run code¶

If you don’t have (or don’t want) to install pyfrc, running code manually is pretty simple too.

1. Make sure you have RobotPy installed on the robot
2. Use scp or sftp (Filezilla is a great GUI product to use for this) to copy your robot code to the roboRIO
3. ssh into the roboRIO, and run your robot code manually

python3 robot.py run

Your driver station should be able to connect to your code, and it will be able to operate your robot!

Using git-source-track¶

First, you need to checkout the git repo for allwpilib and the RobotPy WPILib next to each other in the same directory like so:

allwpilib/
robotpy-wpilib/

The way git-source-track works is it looks for a comment in the header of each tracked file that looks like this:

# validated: 2015-12-24 DS 6d854af athena/java/edu/wpi/first/wpilibj/Compressor.java

This stores when the file was validated to match the original source, initials of the person that did the validation, what commit it was validated against, and the path to the original source file.

git source-track diff FILENAME

git source-track set-valid FILENAME

Syntax/Style Guide¶

Except where it makes sense, developers should try to retain the structure and naming conventions that the Java implementation of WPILib follows. There are a few guidelines that can be helpful when translating Java to Python:

• Member variables such as m_foo should be converted to self.foo
• Private/protected functions (but NOT variables) should start with an underscore
• Always retain original javadoc documentation, and convert it to the appropriate standard python docstring (see below)

class SomeObject:

    class MyEnum:
        VALUE1 = 1
        VALUE2 = 2

def someSynchronizedFunction(self):
    with self.lock:
        # do something here...