Skip to content

Commit

Permalink
Merge pull request #66 from robotpy/2024-updates
Browse files Browse the repository at this point in the history 
Initial 2024 updates
  • Loading branch information
@virtuald
virtuald authored Jan 18, 2024
2 parents 6019b0d + eca17a1 commit b95aea2
Show file tree
Hide file tree
Showing 44 changed files with 185 additions and 3,031 deletions.
2 changes: 1 addition & 1 deletion .readthedocs.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ sphinx:
build:
os: ubuntu-22.04
tools:
python: "3.10"
python: "3.11"

python:
install:
Expand Down
2 changes: 2 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ become increasingly more difficult to introduce all of the pieces to new
users. This is the foundation for a unified documentation site for all
RobotPy projects, in hopes of reducing that confusion.

Now that Python is an officialy supported language, this site still aims to unify the various API documentation for RobotPy projects. However, much of our documentation has been moved to the [WPILib documentation](https://docs.wpilib.org).

All of our documentation is built using Sphinx, and is hosted at
http://robotpy.readthedocs.io/

Expand Down
72 changes: 41 additions & 31 deletions conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,11 +70,9 @@
copyright = f"2014-{date.today().year}, RobotPy development team"


frc_docs = "https://docs.wpilib.org/en/stable"

intersphinx_mapping = {
"commandsv1": (
"https://robotpy.readthedocs.io/projects/commands-v1/en/%s/" % rtd_version,
None,
),
"commandsv2": (
"https://robotpy.readthedocs.io/projects/commands-v2/en/%s/" % rtd_version,
None,
Expand All @@ -83,40 +81,60 @@
"https://robotpy.readthedocs.io/projects/pyfrc/en/%s/" % rtd_version,
None,
),
"ntcore": (
"https://robotpy.readthedocs.io/projects/pyntcore/en/%s/" % rtd_version,
None,
),
"wpilib": (
"https://robotpy.readthedocs.io/projects/wpilib/en/%s/" % rtd_version,
None,
),
"hal": (
"https://robotpy.readthedocs.io/projects/hal/en/%s/" % rtd_version,
"robotpy": (
"https://robotpy.readthedocs.io/projects/robotpy/en/%s/" % rtd_version,
None,
),
"robotpy_ext": (
"https://robotpy.readthedocs.io/projects/utilities/en/%s/" % rtd_version,
None,
),
"cscore": (
"https://robotpy.readthedocs.io/projects/cscore/en/%s/" % rtd_version,
None,
),
"frc": ("https://docs.wpilib.org/en/stable", None),
"frc": (frc_docs, None),
}

redirects = {
"getting_started": f"{frc_docs}/docs/zero-to-robot/introduction.html",
"2020_notes": "upgrade_notes.html",
"install/pynetworktables": "pyntcore.html"
"install/pynetworktables": "pyntcore.html",
"frameworks/command": f"{frc_docs}/docs/software/commandbased/",
"guide/anatomy": f"{frc_docs}/docs/zero-to-robot/step-4/creating-test-drivetrain-program-cpp-java-python.html",
"guide/index": f"{frc_docs}/docs/software/python/",
"guide/deploy": f"{frc_docs}/docs/software/python/subcommands/deploy.html",
"guide/examples": "https://github.com/robotpy/examples",
"guide/guidelines": "guidelines",
"guide/nt": f"{frc_docs}/docs/software/networktables/index.html",
"guide/running": f"{frc_docs}/docs/software/python/subcommands/index.html",
"guide/python": "https://docs.python-guide.org/en/latest/intro/learning/",
"guide/simulator": f"{frc_docs}/docs/software/wpilib-tools/robot-simulation/introduction.html",
"guide/testing": "testing",
"hw": f"{frc_docs}/docs/hardware/hardware-basics/index.html",
"install/computer": f"{frc_docs}/docs/zero-to-robot/step-2/python-setup.html",
"install/components": f"{frc_docs}/docs/zero-to-robot/step-2/python-setup.html",
"install/packages": f"{frc_docs}/docs/zero-to-robot/step-2/python-setup.html",
"install/robot": f"{frc_docs}/docs/zero-to-robot/step-2/python-setup.html",
"install/commands": f"{frc_docs}/docs/software/vscode-overview/3rd-party-libraries.html",
"install/cscore": f"{frc_docs}/docs/zero-to-robot/step-2/python-setup.html",
"install/ctre": f"{frc_docs}/docs/software/vscode-overview/3rd-party-libraries.html",
"install/navx": f"{frc_docs}/docs/software/vscode-overview/3rd-party-libraries.html",
"install/pathplannerlib": f"{frc_docs}/docs/software/vscode-overview/3rd-party-libraries.html",
"install/pwfusion": f"{frc_docs}/docs/software/vscode-overview/3rd-party-libraries.html",
"install/pyfrc": f"{frc_docs}/docs/zero-to-robot/step-2/python-setup.html",
"install/pyntcore": f"{frc_docs}/docs/zero-to-robot/step-2/python-setup.html",
"install/rev": f"{frc_docs}/docs/software/vscode-overview/3rd-party-libraries.html",
"vision/code": f"{frc_docs}/docs/software/vision-processing/index.html",
"vision/index": f"{frc_docs}/docs/software/vision-processing/index.html",
"vision/other": f"{frc_docs}/docs/software/vision-processing/index.html",
"vision/roborio": f"{frc_docs}/docs/software/vision-processing/roborio/index.html",
}

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = subprocess.check_output(("git", "describe", "--tags"), text=True).split(".")[0]
version = subprocess.check_output(("git", "describe", "--tags"), text=True).split(".")[
0
]
# The full version, including alpha/beta/rc tags.
release = version

Expand All @@ -133,15 +151,7 @@

# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = "default"

if not on_rtd: # only import and set the theme if we're building docs locally
import sphinx_rtd_theme

html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
else:
html_theme = "default"
html_theme = "sphinx_rtd_theme"

# Output file base name for HTML help builder.
htmlhelp_basename = "RobotPy"
Expand Down Expand Up @@ -187,7 +197,7 @@
epub_title = "RobotPy"
epub_author = "RobotPy development team"
epub_publisher = "RobotPy development team"
epub_copyright = "2014-2022, RobotPy development team"
epub_copyright = "2014-2024, RobotPy development team"

# A list of files that should not be packed into the epub file.
epub_exclude_files = ["search.html"]
Expand Down
39 changes: 20 additions & 19 deletions dev/deploy.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,26 @@
Deploy process details
======================

When the code is uploaded to the robot, the following steps occur:
TODO

* SSH/sftp operations are performed as the ``lvuser`` user (this is REALLY important, don't use the ``admin`` user!)
* pyfrc does some checks to make sure the environment is setup properly
* The directory containing ``robot.py`` is recursively copied to the the directory ``/home/lvuser/py``
* The files ``robotCommand`` and ``robotDebugCommand`` are created
* ``/usr/local/frc/bin/frcKillRobot.sh -t -r`` is called, which causes any existing robot code to be killed, and the new code is launched
..
This is mostly the same, but has a lot of additional steps as of 2024
If you wish for the 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.
When the code is uploaded to the robot, the following steps occur:

These steps are compatible with what C++/Java does when deployed by GradleRIO,
so you should be able to seamlessly switch between python and other FRC
languages!
* SSH/sftp operations are performed as the ``lvuser`` user (this is REALLY important, don't use the ``admin`` user!)
* robotpy-installer does some checks to make sure the environment is setup properly
* The directory containing ``robot.py`` is recursively copied to the the directory ``/home/lvuser/py``
* The files ``robotCommand`` and ``robotDebugCommand`` are created
* ``/usr/local/frc/bin/frcKillRobot.sh -t -r`` is called, which causes any existing robot code to be killed, and the new code is launched

If you wish for the 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.

These steps are compatible with what C++/Java does when deployed by GradleRIO,
so you should be able to seamlessly switch between python and other FRC
languages!

.. _manual_code_deploy:

Expand Down Expand Up @@ -67,16 +72,12 @@ Example code:
print(data)
if __name__ == "__main__":
wpilib.run(MyRobot)
How to manually run code
------------------------

.. note:: Generally, you shouldn't need to use this process.

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

1. Make sure you have RobotPy installed on the robot
Expand All @@ -86,10 +87,10 @@ pretty simple too.

::

python3 robot.py run
python3 -m robotpy run

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

.. note:: This is good for running experimental code, but it won't start the
code when the robot starts up. Use pyfrc to do that.
code when the robot starts up. Use robotpy-installer to do that.
51 changes: 3 additions & 48 deletions dev/design.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,52 +3,7 @@ Design

.. _robotpy_extension_options:

Adding options to robot.py
--------------------------
Adding options to the ``robotpy`` command
-----------------------------------------

When :func:`wpilib.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']},
...
)
As of 2024 the ``robotpy`` command (also accessed via ``python -m robotpy``) is located in the `robotpy-cli <https://github.com/robotpy/robotpy-cli>`__ package. Instructions for adding custom subcommands is located in the README file.
71 changes: 29 additions & 42 deletions faq.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ Installing and Running RobotPy
How do I install RobotPy?
~~~~~~~~~~~~~~~~~~~~~~~~~

See our :ref:`getting started guide <getting_started>`.
RobotPy installation documentation is now at :doc:`frc-docs <frc:docs/zero-to-robot/step-2/python-setup>`.

What version of Python do RobotPy projects use?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -38,8 +38,8 @@ documentation <https://docs.python.org/3/>`__ instead of the Python
2.x documentation.

- RobotPy WPILib on the roboRIO uses the latest version of Python 3 at kickoff.
In 2023, this was Python 3.11. When using pyfrc or similar projects,
you should use a Python 3.7 or newer interpreter (the latest is recommended).
In 2024, this was Python 3.12. When using pyfrc or similar projects,
you should use a Python 3.8 or newer interpreter (the latest is recommended).
- RobotPy 2014.x is based on Python 3.2.5.

`pynetworktables <https://github.com/robotpy/pynetworktables>`__ is
Expand Down Expand Up @@ -71,15 +71,19 @@ Prior to 2015, the API matched the C++ version of WPILib.
Is Command-based programming available?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Of course! Check out the :mod:`commands2 <commands2>` package. There
is also some :ref:`python-specific documentation available <command_framework_docs>`.
Of course! Check out the :mod:`commands2 <commands2>` package.

Is there an easy way to test my code outside of the robot?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Are Vendor libraries available?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Glad you asked! Our pyfrc project has a built in :ref:`lightweight robot simulator <simulator>`
you can use to run your code, and also has builtin support for unit testing
with `py.test <http://pytest.org>`_.
We encourage vendors to make Python versions of their libraries available. Since
Python support has only been official since 2024, not all vendors do this. If
you are a vendor, please reach out to our team and we'd be happy to assist.

The RobotPy project also provides unofficial wrappers for vendor libraries that don't
take a lot of effort to create and maintain.

.. seealso:: :doc:`frc:docs/software/vscode-overview/3rd-party-libraries`

Competition
-----------
Expand All @@ -89,46 +93,19 @@ Competition
Is RobotPy competition-legal?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Python is not an official FRC language yet, but we are working with
the WPILib team to make it official in 2024. See
https://wpilib.org/blog/bringing-python-to-frc for the announcement.

As RobotPy was not written by anyone involved with the GDC, we can't
provide a guaranteed answer (particularly not for future years).
However, we see no reason that RobotPy would not be legal: to the
cRIO/RoboRIO, it looks just like any other C++ WPILib-using program that
reads text files. RobotPy itself should be considered COTS software as
it is freely available to all teams. Teams have been using RobotPy since
2010 without any problems from FIRST, and we expect that to continue.

Caveat emptor: while RobotPy is almost certainly legal to use, your team
should carefully consider the risk of using such a large piece of
unofficial software; unless RobotPy is used by many teams, if you run
into trouble at a competition, there may not be anyone else there to
help! However, we've found that most problems teams run into are
problems with WPILib itself, and not RobotPy.

Also, be sure to keep in mind the fact that Python is a dynamic language
and is NOT compiled. This means that typos can easily go undetected
until your robot runs that particular line of code, resulting in an
exception and 5 second restart. Make sure to test your code thoroughly
(see our :ref:`unit testing documentation <unit_tests>`).

As of 2024, Python is officially supported for use in FRC.

.. _is_stable:

Is RobotPy stable?
~~~~~~~~~~~~~~~~~~

Yes! While Python is not an officially supported language, teams have been
Yes! Teams have been
using RobotPy since 2010, and the maintainer of RobotPy is a member of the
WPILib team. Much of the time when bugs are found, they are found in the
underlying WPILib, instead of RobotPy itself.

One caveat to this is that because RobotPy doesn't have a beta period like
WPILib does, bugs tend to be found during the first half of competition season.
However, by the time build season ends, RobotPy is just as stable as any of
the officially suported languages.
One caveat to this is that because RobotPy is not yet widely adopted, bugs tend to be found during the first half of competition season. However, by the time build season ends, RobotPy is just as stable.

How often does RobotPy get updated?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -170,8 +147,17 @@ Ross Light, FRC Team 973. Peter is a member of the FIRST WPILib team,
and also created the `ntcore <https://github.com/wpilibsuite/ntcore/>`_
and `cscore <https://github.com/wpilibsuite/cscore/>`_ libraries.

The current RobotPy maintainer is `Dustin
Spicuzza <http://github.com/virtuald>`_, also a member of the FIRST WPILib team.
How is RobotPy different from WPILib?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

All current RobotPy developers are members of the FIRST WPILib team, so in some sense RobotPy is a subgroup of WPILib. However, RobotPy is still separate from WPILib in many ways and has it's own shiny logo, but as time goes on we are aiming to integrate more into the greater WPILib whole.

One thing that makes RobotPy different from WPILib is that we also maintain separate libraries for interacting with various 3rd party vendors, but we expect as Python gets more traction in FRC that vendors will develop and maintain their own libraries.

Who develops RobotPy?
---------------------

The current RobotPy maintainer is `Dustin Spicuzza <http://github.com/virtuald>`_.

Current RobotPy developers include:

Expand All @@ -186,6 +172,7 @@ RobotPy is an open project that all members of the FIRST community can
easily and quickly contribute to. If you find a bug, or have an idea
that you think others can use:

- Add Python documentation to :doc:`the official WPILib documentation <frc:index>`
- Test and report any issues you find.
- Port and test a useful library.
- Write a Python module and share it with others (and contribute it to
Expand Down
Loading

0 comments on commit b95aea2

Please sign in to comment.