From b0da04b0d5d094a10cad7f17d752a0e8f0cfa373 Mon Sep 17 00:00:00 2001 From: Dustin Spicuzza Date: Sat, 6 Jan 2024 07:46:44 -0500 Subject: [PATCH] Initial 2024 updates --- conf.py | 57 +++++++------- dev/deploy.rst | 2 +- faq.rst | 48 ++++-------- frameworks/command.rst | 16 ---- frameworks/index.rst | 4 +- frameworks/magicbot.rst | 2 - getting_started.rst | 4 - guide/anatomy.rst | 6 +- guide/deploy.rst | 17 ++--- guide/examples.rst | 9 --- guide/index.rst | 3 +- guide/nt.rst | 2 - guide/running.rst | 13 ++-- guide/simulator.rst | 6 +- guide/testing.rst | 25 +++---- hw.rst | 18 ----- index.rst | 27 ++++++- install/commands.rst | 53 ------------- install/components.rst | 7 +- install/cscore.rst | 63 ---------------- install/ctre.rst | 76 ------------------- install/index.rst | 25 +------ install/navx.rst | 59 --------------- install/pathplannerlib.rst | 65 ---------------- install/photonvision.rst | 65 ---------------- install/pwfusion.rst | 65 ---------------- install/pyfrc.rst | 53 ------------- install/pyntcore.rst | 73 ------------------ install/rev.rst | 75 ------------------- troubleshooting.rst | 42 ++--------- upgrade_notes.rst | 26 ++----- vision/code.rst | 147 ------------------------------------- vision/index.rst | 28 ------- vision/other.rst | 95 ------------------------ vision/roborio.rst | 118 ----------------------------- 35 files changed, 118 insertions(+), 1276 deletions(-) delete mode 100644 frameworks/command.rst delete mode 100644 guide/examples.rst delete mode 100644 hw.rst delete mode 100644 install/commands.rst delete mode 100644 install/cscore.rst delete mode 100644 install/ctre.rst delete mode 100644 install/navx.rst delete mode 100644 install/pathplannerlib.rst delete mode 100644 install/photonvision.rst delete mode 100644 install/pwfusion.rst delete mode 100644 install/pyfrc.rst delete mode 100644 install/pyntcore.rst delete mode 100644 install/rev.rst delete mode 100644 vision/code.rst delete mode 100644 vision/index.rst delete mode 100644 vision/other.rst delete mode 100644 vision/roborio.rst diff --git a/conf.py b/conf.py index 1cdf463..655c2ee 100644 --- a/conf.py +++ b/conf.py @@ -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, @@ -83,32 +81,37 @@ "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 = { "2020_notes": "upgrade_notes.html", - "install/pynetworktables": "pyntcore.html" + "install/pynetworktables": "pyntcore.html", + "frameworks/command": f"{frc_docs}/docs/software/commandbased/index", + "guide/examples": "https://github.com/robotpy/examples", + "guide/nt": f"{frc_docs}/docs/software/networktables/index.html", + "hw": f"{frc_docs}/docs/hardware/hardware-basics/index.html", + "install/commands": "install/components", + "install/cscore": "install/components", + "install/ctre": "install/components", + "install/navx": "install/components", + "install/pathplannerlib": "install/components", + "install/pwfusion": "install/components", + "install/pyfrc": "install/components", + "install/pyntcore": "install/components", + "install/rev": "install/components", + "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 @@ -116,7 +119,9 @@ # 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 @@ -133,15 +138,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" diff --git a/dev/deploy.rst b/dev/deploy.rst index a2a9c36..38c760a 100644 --- a/dev/deploy.rst +++ b/dev/deploy.rst @@ -86,7 +86,7 @@ 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! diff --git a/faq.rst b/faq.rst index 332d9f9..6685a3a 100644 --- a/faq.rst +++ b/faq.rst @@ -38,8 +38,8 @@ documentation `__ 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 `__ is @@ -71,15 +71,17 @@ Prior to 2015, the API matched the C++ version of WPILib. Is Command-based programming available? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Of course! Check out the :mod:`commands2 ` package. There -is also some :ref:`python-specific documentation available `. +Of course! Check out the :mod:`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 ` -you can use to run your code, and also has builtin support for unit testing -with `py.test `_. +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. Competition ----------- @@ -89,38 +91,14 @@ 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 `). - +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. diff --git a/frameworks/command.rst b/frameworks/command.rst deleted file mode 100644 index 7b21afe..0000000 --- a/frameworks/command.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _command_framework_docs: - -Command Framework -================= - -If you're coming from C++ or Java, you are probably familiar with the Command based robot paradigm. All of the pieces you're used to are still available in RobotPy. - -.. note:: Unfortunately, nobody has written any Python specific documentation for - the new command framework. Please refer to the :doc:`WPILib documentation` for now. - - If you're interested in contributing a Python-specific guide to - the command framework, we'd love your help! - -.. seealso:: :ref:`command_v2_api` - -.. seealso:: :ref:`magicbot_framework_docs` diff --git a/frameworks/index.rst b/frameworks/index.rst index 1a5881d..7dbf22f 100644 --- a/frameworks/index.rst +++ b/frameworks/index.rst @@ -12,11 +12,11 @@ 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. -* :ref:`command_framework_docs`: this framework comes with WPILib +* :doc:`Command Framework `: this framework comes with WPILib * :ref:`magicbot_framework_docs`: Created as a pythonic alternative to the Command framework .. toctree:: :maxdepth: 2 + :hidden: - command magicbot diff --git a/frameworks/magicbot.rst b/frameworks/magicbot.rst index 0800a44..fb373ed 100644 --- a/frameworks/magicbot.rst +++ b/frameworks/magicbot.rst @@ -300,8 +300,6 @@ 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. - -.. note:: For more information about NetworkTables, see :ref:`networktables_guide` Magicbot provides a simple way to interact with NetworkTables, using the :func:`tunable ` property. diff --git a/getting_started.rst b/getting_started.rst index 150ace7..c877bbc 100644 --- a/getting_started.rst +++ b/getting_started.rst @@ -19,7 +19,3 @@ the following steps: Once you've played around with some code in simulation, then you should :ref:`install RobotPy on your robot `. - -If you're looking to use NetworkTables on the driver station or on a -coprocessor, then check out the :ref:`pyntcore install docs `. - diff --git a/guide/anatomy.rst b/guide/anatomy.rst index 12bb2be..eb37c47 100644 --- a/guide/anatomy.rst +++ b/guide/anatomy.rst @@ -77,7 +77,7 @@ 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 (:external+wpilib:doc:`wpilib`) +of WPILib is published online. Check out the API documentation (:external+robotpy:doc:`wpilib`) for details on all the objects available in WPILib. .. note:: @@ -90,7 +90,7 @@ Creating individual devices ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Let's say you wanted to create an object that interacted with a Jaguar motor -controller via PWM. First, you would read through the table (:external+wpilib:doc:`wpilib`) and +controller via PWM. First, you would read through the table (:external+robotpy:doc:`wpilib`) and see that there is a :class:`.Jaguar` object. Looking further, you can see that the constructor takes a single argument that indicates which PWM port to connect to. You could create the `Jaguar` object that is using port 4 using the @@ -142,7 +142,7 @@ Once you have one of these objects, it has various methods that you can use to control the robot via joystick, or you can specify the control inputs manually. -.. seealso:: Documentation for the :external+wpilib:doc:`wpilib.drive`, and the FIRST WPILib Programming Guide. +.. seealso:: Documentation for the :external+robotpy:doc:`wpilib.drive`, and the FIRST WPILib Programming Guide. Robot Operating Modes (TimedRobot) -------------------------------------- diff --git a/guide/deploy.rst b/guide/deploy.rst index a106fb8..30bfd5d 100644 --- a/guide/deploy.rst +++ b/guide/deploy.rst @@ -12,21 +12,20 @@ code, and if they pass then it will upload the robot code to the roboRIO. Running the tests is really important, it allows you to catch errors in your code before you run it on the robot. -1. Make sure you have RobotPy installed on the robot (:ref:`RobotPy install guide `) -2. Make sure you have pyfrc installed (:ref:`pyfrc install guide `) -3. Once that is done, you can just run the following command and it will upload the code and start it immediately. +1. Make sure you have RobotPy installed on the robot (:ref:`RobotPy install guide `) and on your computer +2. Once that is done, you can just run the following command and it will upload the code and start it immediately. .. tab:: Windows .. code-block:: sh - py -3 robot.py deploy + py -3 -m robotpy deploy .. tab:: Linux/macOS .. code-block:: sh - python3 robot.py deploy + python3 -m robotpy deploy You can watch your robot code's output (and see any problems) by using the netconsole program (you can either use NI's tool, or `pynetconsole `_. @@ -49,13 +48,13 @@ your program's console output, by launching a netconsole listener. .. code-block:: sh - py -3 robot.py deploy --nc + py -3 -m robotpy deploy --nc .. tab:: Linux/macOS .. code-block:: sh - python3 robot.py deploy --nc + python3 -m robotpy deploy --nc .. note:: This requires the driver station software to be connected to your robot @@ -69,13 +68,13 @@ don't care about the tests. That's OK, you can still upload code to the robot: .. code-block:: sh - py -3 robot.py deploy --skip-tests + py -3 -m robotpy deploy --skip-tests .. tab:: Linux/macOS .. code-block:: sh - python3 robot.py deploy --skip-tests + python3 -m robotpy deploy --skip-tests Starting deployed code at boot ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/guide/examples.rst b/guide/examples.rst deleted file mode 100644 index d0385b3..0000000 --- a/guide/examples.rst +++ /dev/null @@ -1,9 +0,0 @@ -Example Code -============ - -Sometimes the documentation just isn't enough. To help you get started, the -RobotPy project provides many example programs that can be a good starting -point. - -* `Robot Code examples `_ -* `RobotPy CSCore examples `_ diff --git a/guide/index.rst b/guide/index.rst index 1020c04..50d63a8 100644 --- a/guide/index.rst +++ b/guide/index.rst @@ -18,5 +18,4 @@ Programmer's Guide simulator testing guidelines - nt - examples \ No newline at end of file + nt \ No newline at end of file diff --git a/guide/nt.rst b/guide/nt.rst index d0a4690..4adad3a 100644 --- a/guide/nt.rst +++ b/guide/nt.rst @@ -37,8 +37,6 @@ Resources - :doc:`Networktables concepts and documentation ` -- :ref:`pyntcore installation ` - - :ref:`NTCore API Reference ` - :ref:`NetworkTables troubleshooting ` diff --git a/guide/running.rst b/guide/running.rst index c225bc7..0eccd45 100644 --- a/guide/running.rst +++ b/guide/running.rst @@ -8,9 +8,6 @@ Now that you've created your first Python robot program, you probably want to know how to run the code. The process to run a python script is slightly different for each operating system. -.. note:: This section assumes that you've already :ref:`installed pyfrc `. - If you haven't, now's a great time to do so! - How to execute the script ------------------------- @@ -22,7 +19,7 @@ How to execute the script .. code-block:: sh - py -3 robot.py + py -3 -m robotpy .. tab:: Linux/macOS @@ -32,7 +29,7 @@ How to execute the script .. code-block:: sh - python3 robot.py + python3 -m robotpy Commands -------- @@ -47,16 +44,16 @@ robot code. To discover the various features that are installed, you can use the .. code-block:: batch - py -3 robot.py --help + py -3 -m robotpy --help .. tab:: Linux/macOS .. code-block:: sh - python3 robot.py --help + python3 -m robotpy --help .. note:: RobotPy supports an extension mechanism that allows advanced users the - ability to create their own custom ``robot.py`` commandline options. + ability to create their own custom ``robotpy`` commandline options. For more information, see :ref:`robotpy_extension_options` Next steps diff --git a/guide/simulator.rst b/guide/simulator.rst index 29b00eb..acbe798 100644 --- a/guide/simulator.rst +++ b/guide/simulator.rst @@ -20,13 +20,13 @@ To run the GUI simulator, run your robot.py with the following arguments: .. code-block:: sh - py -3 robot.py sim + py -3 -m robotpy sim .. tab:: Linux/macOS .. code-block:: sh - python3 robot.py sim + python3 -m robotpy sim User interface -------------- @@ -52,7 +52,7 @@ calculate robot position for common drivetrain types. We have a variety of examples and documentation available: * :ref:`PyFRC API docs ` -* :external+wpilib:doc:`wpilib.simulation` +* :external+robotpy:doc:`wpilib.simulation` * `RobotPy Examples Repository `_ .. _smartdashboard: diff --git a/guide/testing.rst b/guide/testing.rst index d3d24f7..bcda3fe 100644 --- a/guide/testing.rst +++ b/guide/testing.rst @@ -3,9 +3,6 @@ Unit testing robot code ======================= -.. warning:: Testing is currently still broken, but expected to be available - later in the 2022 season - pyfrc comes with robot.py extensions that support testing robot code using the py.test python testing tool. To run the unit tests for your robot, just run your robot.py with the following arguments: @@ -14,13 +11,13 @@ robot.py with the following arguments: .. code-block:: sh - py -3 robot.py test + py -3 -m robotpy test .. tab:: Linux/macOS .. code-block:: sh - python3 robot.py test + python3 -m robotpy test Your tests must be in a directory called 'tests' either next to robot.py, or in the directory above where robot.py resides. See 'samples/simple' for an example @@ -39,13 +36,13 @@ tests to your robot code, you can run the following: .. code-block:: sh - py -3 robot.py add-tests + py -3 -m robotpy add-tests .. tab:: Linux/macOS .. code-block:: sh - python3 robot.py add-tests + python3 -m robotpy 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, @@ -84,7 +81,7 @@ plugin that it uses to provide this special functionality to your tests. For more information: * `RobotPy example code `_ -* `py.test documentation `_ +* `pytest documentation `_ Code coverage for tests ----------------------- @@ -99,13 +96,13 @@ For example, to run the 'test' command to run unit tests: .. code-block:: sh - py -3 robot.py coverage test + py -3 -m robotpy coverage test .. tab:: Linux/macOS .. code-block:: sh - python3 robot.py coverage test + python3 -m robotpy coverage test Or to run coverage over the simulator: @@ -113,13 +110,13 @@ Or to run coverage over the simulator: .. code-block:: sh - py -3 robot.py coverage sim + py -3 -m robotpy coverage sim .. tab:: Linux/macOS .. code-block:: sh - python3 robot.py coverage sim + python3 -m robotpy 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 @@ -133,13 +130,13 @@ 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. -.. note:: There is a py.test module called pytest-cov that is supposed to allow +.. note:: There is a pytest module called pytest-cov that is supposed to allow you to run code coverage tests. However, I've found that it doesn't work particularly well for me, and doesn't appear to be maintained anymore. .. note:: For some reason, when running the simulation under the code coverage tool, the output is buffered until the process exits. This does not happen - under py.test, however. It's not clear why this occurs. + under pytest, however. It's not clear why this occurs. Next Steps ---------- diff --git a/hw.rst b/hw.rst deleted file mode 100644 index ff61416..0000000 --- a/hw.rst +++ /dev/null @@ -1,18 +0,0 @@ -Hardware & Sensors -================== - -FIRST has put together a lot of great documentation that can tell you how to -connect hardware devices and interact with it from robot code. - -* :doc:`Hardware APIs ` -* :doc:`Using CAN Devices ` -* :doc:`WPILib Sensors ` -* :doc:`Driver Station Inputs and Feedback ` - -While their documentation code samples are in C++ and Java, it's fairly -straightforward to translate them to python -- RobotPy includes support for all -components that are supported by WPILib's Java implementation, and generally -the objects have the same name and method names. - -If you have problems translating their code samples into Python, you can -use our support resources to get help (see :ref:`Support`). \ No newline at end of file diff --git a/index.rst b/index.rst index 88b3d3b..c4e5e85 100644 --- a/index.rst +++ b/index.rst @@ -9,6 +9,8 @@ students dedicated to developing python-related projects for the FIRST Robotics Competition. This documentation site contains information about various projects that RobotPy supports, including guides and API references. +Some of the tools RobotPy project + Please read our :ref:`Upgrade Notes` page for things that have changed this season that you should be aware of. @@ -27,7 +29,6 @@ FRC robot code using Python, and we have several projects related to this: * `robotpy-wpilib `_: the python implementation of WPILib for FRC * `pyfrc `_: provides unit testing, realtime robot simulation, and easy upload capabilities for your RobotPy code -* `roborio-packages `_: Various python packages for the RoboRIO platform installable by opkg, including the python interpreter and numpy * `robotpy-wpilib-utilities `_: Community focused extensions for WPILib Additionally, RobotPy is home to several projects that are useful for all teams, @@ -43,8 +44,32 @@ even if they aren’t writing their robot code in python: There is a lot of good documentation, but there's still room for improvement. We welcome contributions from all members of the FIRST community! +.. toctree:: + :caption: RobotPy + :maxdepth: 2 + + getting_started + upgrade_notes + install/index + guide/index + frameworks/index + .. include:: _sidebar.rst.inc +.. toctree:: + :caption: Additional Info + :maxdepth: 2 + + troubleshooting + support + faq + +.. toctree:: + :caption: RobotPy Developers + :maxdepth: 2 + + dev/index + Indices and tables ================== diff --git a/install/commands.rst b/install/commands.rst deleted file mode 100644 index 13111de..0000000 --- a/install/commands.rst +++ /dev/null @@ -1,53 +0,0 @@ - -.. _install_commands: - -.. _install_commandsv1: - -Commands install -================ - -The WPILib command framework is distributed separately from WPILib, and is -called robotpy-commands-v2. The instructions below discuss installing the -new command framework. - -Setup (tests/simulator) ------------------------ - -If you intend to use the command framework in your *robot tests* or in the -simulator, you must install this package locally: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m pip install -U robotpy[commands2] - -.. tab:: Linux/macOS - - .. code-block:: sh - - pip3 install -U robotpy[commands2] - -Setup (RoboRIO) ---------------- - -Even if you have robotpy-commands-v2 installed locally, you **must** install it -on your robot **separately**. - -Use the RobotPy installer and run the following on your computer while connected -to the internet: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy_installer download robotpy[commands2] - -.. tab:: Linux/macOS - - .. code-block:: sh - - python3 -m robotpy_installer install robotpy[commands2] - -For additional details about running robotpy-installer on your computer, see -the :ref:`robotpy-installer documentation `. diff --git a/install/components.rst b/install/components.rst index cee8dec..3b17139 100644 --- a/install/components.rst +++ b/install/components.rst @@ -16,16 +16,17 @@ RobotPy wrappers around WPILib will be installed. However there are several groups of optional components that you can install. Vendor categories: -* ``ctre`` - Cross The Road Electronics motor controllers * ``navx`` - Kauai Labs NavX MXP Robotics Navigation * ``pathplannerlib`` - PathPlannerLib path planning vendor library -* ``photonvision`` - PhotonVision computer vision vendor library +* ``phoenix5`` - CTRE Phoenix v5 +* ``phoenix6`` - CTRE Phoenix v6 +* ``playingwithfusion`` - Playing With Fusion vendor library * ``rev`` - REV Robotics motor controllers and color sensors Optional WPILib component categories: * ``apriltag`` - WPILib apriltag library -* ``commands2`` - WPILib Commands framework (2020+) +* ``commands2`` - WPILib Commands framework v2 (2020+) * ``cscore`` - WPILib cscore library * ``romi`` - Romi robot specific components * ``sim`` - WPILib extra simulation support diff --git a/install/cscore.rst b/install/cscore.rst deleted file mode 100644 index ca7fbdc..0000000 --- a/install/cscore.rst +++ /dev/null @@ -1,63 +0,0 @@ - -.. _install_cscore: - -robotpy-cscore install -====================== - -RoboRIO installation --------------------- - -If you have robotpy-installer on your computer, then installing ``robotpy-cscore`` -is very simple: - -.. tab:: Windows - - .. code-block:: sh - - # While connected to the internet - py -3 -m robotpy_installer download robotpy[cscore] - - # While connected to the network with a RoboRIO on it - py -3 -m robotpy_installer install robotpy[cscore] - -.. tab:: Linux/macOS - - .. code-block:: sh - - # While connected to the internet - robotpy-installer download robotpy[cscore] - - # While connected to the network with a RoboRIO on it - robotpy-installer install robotpy[cscore] - -For additional details about running robotpy-installer on your computer, see -the :ref:`robotpy-installer documentation `. - -Non-roboRIO installation ------------------------- - -We now distribute pre-built wheels for CSCore, so you can just use pip to install it: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m pip install -U robotpy[cscore] - -.. tab:: Linux/macOS - - .. code-block:: sh - - pip3 install -U robotpy[cscore] - -.. tab:: ARM Coprocessor - - .. code-block:: sh - - pip3 install -U robotpy[cscore] --find-links=https://tortall.net/~robotpy/wheels/2023/raspbian/ - - -Next steps ----------- - -See our :ref:`cscore documentation ` for examples and deployment thoughts. diff --git a/install/ctre.rst b/install/ctre.rst deleted file mode 100644 index 477ecd9..0000000 --- a/install/ctre.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. _install_ctre: - -robotpy-ctre install -==================== - - -Setup (tests/simulator) ------------------------ - -If you intend to use robotpy-ctre in your *robot tests* or via the robot -*simulator*, you must install this package locally. It is recommended to -install using the robotpy meta package: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m pip install -U robotpy[ctre] - -.. tab:: Linux/macOS - - .. code-block:: sh - - pip3 install -U robotpy[ctre] - -Setup (RoboRIO) ---------------- - -Even if you have robotpy-ctre installed locally, you **must** install it on your -robot **separately**. See below. - -Python package -~~~~~~~~~~~~~~ - -You really don't want to compile this yourself, so don't download this from pypi -and install it. Use the RobotPy installer and run the following on your computer -while connected to the internet: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy_installer download robotpy[ctre] - -.. tab:: Linux/macOS - - .. code-block:: sh - - robotpy-installer download robotpy[ctre] - -Then, when connected to the roborio's network, run: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy_installer install robotpy[ctre] - -.. tab:: Linux/macOS - - .. code-block:: sh - - robotpy-installer install robotpy[ctre] - -For additional details about running robotpy-installer on your computer, see -the :ref:`robotpy-installer documentation `. - -NI Web Dashboard (optional) -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -CTRE Phoenix can integrate with the NI Web Dashboard on the RoboRIO. This is not required to -run robotpy-ctre on the RoboRIO, but it can be a useful diagnostic tool. To install this, you -will need to use the CTRE Lifeboat tool to install it separately. - -Refer to `the CTRE documentation `_ -for more details. diff --git a/install/index.rst b/install/index.rst index 4e0b1fd..40e213e 100644 --- a/install/index.rst +++ b/install/index.rst @@ -16,11 +16,11 @@ Using NetworkTables from Python: * To install NetworkTables on a system that does not have RobotPy or pyfrc installed on it (such as a coprocessor like the Raspberry Pi), see the - :ref:`pyntcore installation documentation `. + :ref:`pyntcore installation documentation `. Using cscore from Python: -* See the :ref:`robotpy-cscore installation documentation `. +* See the :ref:`robotpy-cscore installation documentation `. Installing extra software packages on the RoboRIO: @@ -33,24 +33,5 @@ Installing extra software packages on the RoboRIO: components computer - robot - cscore - -Package notes -------------- - -Notes specific to individual packages - -.. toctree:: - :maxdepth: 1 - - pyfrc - pyntcore - commands - ctre - navx - pathplannerlib - photonvision - pwfusion - rev packages + robot diff --git a/install/navx.rst b/install/navx.rst deleted file mode 100644 index e3ba47b..0000000 --- a/install/navx.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. _install_navx: - -robotpy-navx install -==================== - -Setup (tests/simulator) ------------------------ - -If you intend to use robotpy-navx in your *robot tests* or via the *pyfrc -simulator*, you must install this package locally. It is recommended to -install using the robotpy meta package: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m pip install -U robotpy[navx] - -.. tab:: Linux/macOS - - .. code-block:: sh - - pip3 install -U robotpy[navx] - -Setup (RoboRIO) ---------------- - -Even if you have robotpy-navx installed locally, you **must** install it on your -robot **separately**. Use the RobotPy installer and run the following on your -computer while connected to the internet: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy_installer download robotpy[navx] - -.. tab:: Linux/macOS - - .. code-block:: sh - - robotpy-installer download robotpy[navx] - -Then, when connected to the roborio's network, run: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy_installer install robotpy[navx] - -.. tab:: Linux/macOS - - .. code-block:: sh - - robotpy-installer install robotpy[navx] - -For additional details about running robotpy-installer on your computer, see -the :ref:`robotpy-installer documentation `. diff --git a/install/pathplannerlib.rst b/install/pathplannerlib.rst deleted file mode 100644 index 62214aa..0000000 --- a/install/pathplannerlib.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. _install_pathplannerlib: - -robotpy-pathplannerlib install -============================== - -Setup (tests/simulator) ------------------------ - -If you intend to use robotpy-pathplannerlib in your *robot tests* or via the *pyfrc -simulator*, you must install this package locally. It is recommended to -install using the robotpy meta package: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m pip install -U robotpy[pathplannerlib] - -.. tab:: Linux/macOS - - .. code-block:: sh - - pip3 install -U robotpy[pathplannerlib] - -Setup (RoboRIO) ---------------- - -Even if you have robotpy-pathplannerlib installed locally, you **must** install it on your -robot **separately**. See below. - -Python package -~~~~~~~~~~~~~~ - -You really don't want to compile this yourself, so don't download this from pypi -and install it. Use the RobotPy installer and run the following on your computer -while connected to the internet: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy_installer download robotpy[pathplannerlib] - -.. tab:: Linux/macOS - - .. code-block:: sh - - robotpy-installer download robotpy[pathplannerlib] - -Then, when connected to the roborio's network, run: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy_installer install robotpy[pathplannerlib] - -.. tab:: Linux/macOS - - .. code-block:: sh - - robotpy-installer install robotpy[pathplannerlib] - -For additional details about running robotpy-installer on your computer, see -the :ref:`robotpy-installer documentation `. diff --git a/install/photonvision.rst b/install/photonvision.rst deleted file mode 100644 index 09c81b2..0000000 --- a/install/photonvision.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. _install_photonvision: - -robotpy-photonvision install -============================ - -Setup (tests/simulator) ------------------------ - -If you intend to use robotpy-photonvision in your *robot tests* or via the *pyfrc -simulator*, you must install this package locally. It is recommended to -install using the robotpy meta package: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m pip install -U robotpy[photonvision] - -.. tab:: Linux/macOS - - .. code-block:: sh - - pip3 install -U robotpy[photonvision] - -Setup (RoboRIO) ---------------- - -Even if you have robotpy-photonvision installed locally, you **must** install it on your -robot **separately**. See below. - -Python package -~~~~~~~~~~~~~~ - -You really don't want to compile this yourself, so don't download this from pypi -and install it. Use the RobotPy installer and run the following on your computer -while connected to the internet: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy_installer download robotpy[photonvision] - -.. tab:: Linux/macOS - - .. code-block:: sh - - robotpy-installer download robotpy[photonvision] - -Then, when connected to the roborio's network, run: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy_installer install robotpy[photonvision] - -.. tab:: Linux/macOS - - .. code-block:: sh - - robotpy-installer install robotpy[photonvision] - -For additional details about running robotpy-installer on your computer, see -the :ref:`robotpy-installer documentation `. diff --git a/install/pwfusion.rst b/install/pwfusion.rst deleted file mode 100644 index 377e70c..0000000 --- a/install/pwfusion.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. _install_pwfusion: - -robotpy-playingwithfusion install -================================= - -Setup (tests/simulator) ------------------------ - -If you intend to use robotpy-playingwithfusion in your *robot tests* or via the *pyfrc -simulator*, you must install this package locally. It is recommended to -install using the robotpy meta package: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m pip install -U robotpy[playingwithfusion] - -.. tab:: Linux/macOS - - .. code-block:: sh - - pip3 install -U robotpy[playingwithfusion] - -Setup (RoboRIO) ---------------- - -Even if you have robotpy-playingwithfusion installed locally, you **must** install it on your -robot **separately**. See below. - -Python package -~~~~~~~~~~~~~~ - -You really don't want to compile this yourself, so don't download this from pypi -and install it. Use the RobotPy installer and run the following on your computer -while connected to the internet: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy_installer download robotpy[playingwithfusion] - -.. tab:: Linux/macOS - - .. code-block:: sh - - robotpy-installer download robotpy[playingwithfusion] - -Then, when connected to the roborio's network, run: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy_installer install robotpy[playingwithfusion] - -.. tab:: Linux/macOS - - .. code-block:: sh - - robotpy-installer install robotpy[playingwithfusion] - -For additional details about running robotpy-installer on your computer, see -the :ref:`robotpy-installer documentation `. diff --git a/install/pyfrc.rst b/install/pyfrc.rst deleted file mode 100644 index e09be68..0000000 --- a/install/pyfrc.rst +++ /dev/null @@ -1,53 +0,0 @@ - -.. _install_pyfrc: - -pyfrc install -============= - -Installing pyfrc will install all of the packages needed to help you write and -test Python-based Robot code on your development computer. These tools include -WPILib, pynetworktables, unit testing support, and the -:ref:`robot simulator `. - -It is recommended to install using the robotpy meta package: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m pip install robotpy - -.. tab:: Linux/macOS - - .. code-block:: sh - - pip3 install robotpy - -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. - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m pip install coverage - -.. tab:: Linux/macOS - - .. code-block:: sh - - 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 macOS it requires XCode to be installed -* On Linux you will need to have python3-dev/python3-devel or a similar package - installed diff --git a/install/pyntcore.rst b/install/pyntcore.rst deleted file mode 100644 index 7cb369b..0000000 --- a/install/pyntcore.rst +++ /dev/null @@ -1,73 +0,0 @@ - -.. _install_pynetworktables: - -.. _install_pyntcore: - -pyntcore install -================ - -pyntcore is a python package that allows FRC teams to use Python to communicate -with their robots via NetworkTables. It can be used on your Driver Station, on a -coprocessor such as a Raspberry Pi, or any platform supported by the WPILib team. - -.. note:: If you're looking for a pure python implementation of NetworkTables, - check out the `pynetworktables `_ - project. It only supports NT2/NT3. - -RoboRIO installation --------------------- - -``pyntcore`` is installed as part of the core RobotPy installation. - -.. tab:: Windows - - .. code-block:: sh - - # While connected to the internet - py -3 -m robotpy_installer download robotpy - - # While connected to the network with a RoboRIO on it - py -3 -m robotpy_installer install robotpy - -.. tab:: Linux/macOS - - .. code-block:: sh - - # While connected to the internet - robotpy-installer download robotpy - - # While connected to the network with a RoboRIO on it - robotpy-installer install robotpy[cscore] - -For additional details about running robotpy-installer on your computer, see -the :ref:`robotpy-installer documentation `. - -Non-roboRIO installation ------------------------- - -Pre-built wheels of ``pyntcore`` can be installed by installing the ``robotpy`` -package, or installed separately via pip (shown below): - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m pip install -U pyntcore - -.. tab:: Linux/macOS - - .. code-block:: sh - - pip3 install -U pyntcore - -.. tab:: ARM Coprocessor - - .. code-block:: sh - - pip3 install -U --find-links=https://tortall.net/~robotpy/wheels/2023/raspbian/ pyntcore - -Getting Started ---------------- - -See the :ref:`NetworkTables guide ` to learn more about -using NetworkTables to communicate with your robot. diff --git a/install/rev.rst b/install/rev.rst deleted file mode 100644 index 791e152..0000000 --- a/install/rev.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. _install_rev: - -robotpy-rev install -==================== - -Setup (tests/simulator) ------------------------ - -If you intend to use robotpy-rev in your *robot tests* or via the *pyfrc -simulator*, you must install this package locally. It is recommended to -install using the robotpy meta package: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m pip install -U robotpy[rev] - -.. tab:: Linux/macOS - - .. code-block:: sh - - pip3 install -U robotpy[rev] - -Setup (RoboRIO) ---------------- - -Even if you have robotpy-rev installed locally, you **must** install it on your -robot **separately**. See below. - -Python package -~~~~~~~~~~~~~~ - -You really don't want to compile this yourself, so don't download this from pypi -and install it. Use the RobotPy installer and run the following on your computer -while connected to the internet: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy_installer download robotpy[rev] - -.. tab:: Linux/macOS - - .. code-block:: sh - - robotpy-installer download robotpy[rev] - -Then, when connected to the roborio's network, run: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy_installer install robotpy[rev] - -.. tab:: Linux/macOS - - .. code-block:: sh - - robotpy-installer install robotpy[rev] - -For additional details about running robotpy-installer on your computer, see -the :ref:`robotpy-installer documentation `. - -REV Firmware and Diagnostics -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -robotpy-rev supports all the control features of -the C++ Spark Max library. Firmware, diagnostics, and other things -must be installed separately using the tools released by REV. - -Refer to `the REV C++ documentation `_ -for more details. diff --git a/troubleshooting.rst b/troubleshooting.rst index af58bee..1167dea 100644 --- a/troubleshooting.rst +++ b/troubleshooting.rst @@ -58,23 +58,19 @@ Problem: no module named ... If you're using a non-WPILib vendor library, it must be installed separately. -* :ref:`install_ctre` -* :ref:`install_navx` -* :ref:`install_photonvision` -* :ref:`install_pwfusion` -* :ref:`install_rev` +* :ref:`robotpy_components` If you're on your local computer, did you :ref:`install robotpy via pip `? If you're on the roboRIO, did you :ref:`install RobotPy `? -Problem: pyfrc cannot connect to the robot, or appears to hang -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Problem: deploy cannot connect to the robot, or appears to hang +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -1. Can you ping your robot from the machine that you're deploying code from? If not, pyfrc isn't going to be able to connect to the robot either. -2. Try to ssh into your robot, using `PuTTY `_ or the ``ssh`` command on Linux/macOS. The username to use is ``lvuser``, and the password is an empty string. If this doesn't work, pyfrc won't be able to copy files to your robot -3. If all of that works, it might just be that you typed the wrong hostname to connect to. There's a file called ``.deploy_cfg`` next to your ``robot.py`` that pyfrc created. Delete it, and try again. +1. Can you ping your robot from the machine that you're deploying code from? If not, the deploy process isn't going to be able to connect to the robot either. +2. Try to ssh into your robot, using `PuTTY `_ or the ``ssh`` command on Linux/macOS. The username to use is ``lvuser``, and the password is an empty string. If this doesn't work, the deploy process won't be able to copy files to your robot +3. If all of that works, it might just be that you typed the wrong hostname to connect to. Delete ``.wpilib/wpilib_preferences.json``, and try again. Problem: I deploy successfully, but the driver station still shows 'No Robot Code' @@ -85,32 +81,6 @@ Problem: I deploy successfully, but the driver station still shows 'No Robot Cod python3 /home/lvuser/py/robot.py run -Problem: When I run deploy, it complains that the WPILib versions don't match -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Not surprisingly, the error message is correct. - -During deployment, pyfrc does a number of checks to ensure that your robot is setup properly for running python robot code. One of these checks is testing the WPILib version number against the version installed on your computer (it's installed when you install pyfrc). - -You should either: - -* Upgrade the RobotPy installation on the robot to match the newer version on your computer. See the :ref:`RobotPy install guide ` for more info. -* Upgrade the robotpy installation on your computer to match the version on the robot. Just run: - - .. tab:: Windows - - .. code-block:: sh - - py -3 -m pip install --upgrade robotpy - - .. tab:: Linux/macOS - - .. code-block:: sh - - pip3 install --upgrade robotpy - -If you `really` don't want pyfrc to do the version check and need to deploy the code `now`, you can specify the ``--no-version-check`` option. However, this isn't recommended. - Problem: My code segfaulted and there's no Python stack trace! ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/upgrade_notes.rst b/upgrade_notes.rst index 432fbf7..df65b41 100644 --- a/upgrade_notes.rst +++ b/upgrade_notes.rst @@ -4,25 +4,9 @@ Upgrade Notes ============= -Here are major things that have changed for the 2023 season: +Here are major things that have changed for the 2024 season: -* See below for NT4 related changes -* cscore is much easier to build now, and we distribute wheels for Windows/Linux/macOS -* robotpy-commands is no longer supported, only commands v2 -* There are two new packages: robotpy-apriltag and robotpy-wpinet - -NetworkTables 4 (NT4) ---------------------- - -pynetworktables will not be upgraded to support NT4. We will still fix bugs in -its NT3 support, but we recommend all users to switch to pyntcore. - -pyntcore now provides a similar API to networktables, but it lives in the -:py:mod:`ntcore` package now. - -Linux specific notes --------------------- - -Linux requires Ubuntu 22.04 or a distribution with an equivalent (or newer) -glibc installation. See :ref:`linux installation page ` for -more information. +* Python is now an officially supported language +* robotpy-commands-v2 is now a pure python implementation of the Command framework +* Instead of executing ``robot.py`` directly, we now require that you execute the ``robotpy`` module +* Robot projects now can contain a ``pyproject.toml`` which lists the pip requirements for a particular robot project. The packages can be downloaded via the ``sync`` command, and are now installed at deploy time. diff --git a/vision/code.rst b/vision/code.rst deleted file mode 100644 index f5d5124..0000000 --- a/vision/code.rst +++ /dev/null @@ -1,147 +0,0 @@ - -.. _vision_code: - -Custom Image processing -======================= - -vision file ------------ - -.. warning:: If you merely wish to display a single camera stream and do not - want to process the images, do **NOT** use this code. Instead, - see one of the following sections about automatic streaming: - - * :ref:`RoboRIO automatic streaming ` - * :ref:`non-RoboRIO automatic streaming ` - -The first step you need to do is create a file -- let's call it ``vision.py``. -``vision.py`` must contain some function to be called, let's call it ``main``, -and at the minimum it needs to do the following operations: - -* Create a CameraServer instance -* Start capturing from USB -* Get a cvSink object that images can be retrieved from -* Loop and capture images - -Here's a full example:: - - # 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) - -This code will work both on a RoboRIO and on other platforms. The exact mechanism -to run it differs depending on whether you're on a RoboRIO or a coprocessor: - -* :ref:`RoboRIO ` -* :ref:`Other ` - -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! - -Sometimes the first and second camera swap!? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When using multiple USB cameras, Linux will sometimes order the cameras -unpredictably -- so camera 1 will become camera 0. Sometimes. - -The way to deal with this is to tell cscore to use a specific camera by its path -on the file system. First, identify the cameras ``dev`` paths by using SSH to -access the robot and execute ``find /dev/v4l``. You should see output similar -to this: - -.. code-block:: none - - /dev/v4l - /dev/v4l/by-path - /dev/v4l/by-path/pci-0000:00:1a.0-usb-0:1.4:1.0-video-index0 - /dev/v4l/by-path/pci-0000:00:1d.0-usb-0:1.4:1.2-video-index0 - /dev/v4l/by-id - ... - -What you need to do is figure out what paths belong to which camera, and then -when you start the camera server, pass it a name and a path via:: - - usb1 = cs.startAutomaticCapture(name="cam1", path='/dev/v4l/by-id/some-path-here') - usb2 = cs.startAutomaticCapture(name="cam2", path='/dev/v4l/by-id/some-other-path-here') - -Generally speaking, if your cameras have unique IDs associated with them (you -can tell because the by-id path has a random string of characters in it), then -using by-id paths are the best, as they'll always be the same regardness which -port the camera is plugged into. - -However, if your camera does NOT have unique IDs associated with them, then -you should use the by-path versions instead. These device paths are unique to -each USB port plugged in. They should be fairly deterministic, but sometimes -with USB hubs they have been known to change. - -.. note:: The Microsoft Lifecam cameras commonly used in FRC don't have unique - IDs associated with them, so you'll want to use the ``by-path`` - versions of the links if you are using two Lifecams. - -More information ----------------- - -* The :doc:`WPILib documentation for cscore ` - may be useful to explain concepts (though some details are different) -* :ref:`robotpy-cscore API documentation ` -* :ref:`CSCore Troubleshooting ` diff --git a/vision/index.rst b/vision/index.rst deleted file mode 100644 index 187bb88..0000000 --- a/vision/index.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. _vision: - -Camera & Vision -=============== - -The RobotPy project provides `robotpy-cscore `_, -which are python bindings for `cscore `_, -a high performance camera access and streaming library introduced by FIRST in -2017. It can be used to: - -* Stream a USB/HTTP camera to SmartDashboard or the LabVIEW dashboard via HTTP -* Capture images from USB or HTTP camera, modify them using OpenCV/Numpy, and - send them via HTTP to SmartDashboard, the LabVIEW dashboard, or a web browser. - -``robotpy-cscore`` is intended to be usable on any platform supported by OpenCV -and Numpy, and is a more flexible and powerful alternative to solutions such as -mjpg-streamer. - -.. note:: cscore is potentially useful outside of the FIRST Robotics Competition, - as it has very high performance and ease of use compared to other - solutions. - -.. toctree:: - :maxdepth: 2 - - roborio - other - code diff --git a/vision/other.rst b/vision/other.rst deleted file mode 100644 index 2e3ace8..0000000 --- a/vision/other.rst +++ /dev/null @@ -1,95 +0,0 @@ - -Other platforms -=============== - -``robotpy-cscore`` is a great solution for running image processing on a -coprocessor such as the Raspberry Pi or on the Driver Station. - -Installation ------------- - -See :ref:`installing robotpy-cscore `. - -.. _vision_other_automatic: - -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 can use the -cscore ``__main__`` module to start a CameraServer automatically:: - - $ python3 -m cscore - -That's it! You can point your browser to that host at port 1181, and you should -see the cscore default webpage. - -.. _vision_other_runcustom: - -Running a custom cscore program -------------------------------- - -.. seealso:: :ref:`vision_code` - -The easiest way to launch a cscore program is via the cscore ``__main__`` -module helper. It will automatically configure python logging for you, and -also provides useful exception handling and NetworkTables configuration -for you automatically. - -You can instruct the ``__main__`` module to run your custom code via a command -line parameter. The parameter is of the form ``FILENAME:FUNCTION``. For -example, if your code was located in a file called ``targeting.py``, and your -function was called ``run``, then you would do: - -.. code:: sh - - $ python3 -m cscore targeting.py:run - -Examples -~~~~~~~~ - -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 - -Viewing streams via the LabVIEW dashboard or Shuffleboard ---------------------------------------------------------- - -The LabVIEW dashboard and Shuffleboard both retrieve information about the -camera stream via NetworkTables. If you use the :class:`cscore.CameraServer` -class to manage your streams (which you should!) it will automatically publish -the correct information to NetworkTables. In order for the dashboard program -to receive the NetworkTables information, you need to tell your cscore -program to connect to a NetworkTables server (your robot), and the robot -code must be actually running. - -If you're using the cscore ``__main__`` module to launch your code you can -tell it configure NetworkTables to connect to your robot. Use the -``--robot`` or ``--team`` options: - -.. code:: sh - - $ python3 -m cscore --team XXXX - -Or if running custom code: - -.. code:: sh - - $ python3 -m cscore --team XXXX vision.py:run - -If you're writing your own custom code/launcher, at some point you should -initialize NetworkTables and point it at your robot:: - - import networktables - networktables.startClientTeam(1234) - -More information ----------------- - -* The :doc:`WPILib documentation for cscore ` - may be useful to explain concepts (though some details are different) -* :ref:`CSCore Troubleshooting ` diff --git a/vision/roborio.rst b/vision/roborio.rst deleted file mode 100644 index 8f74801..0000000 --- a/vision/roborio.rst +++ /dev/null @@ -1,118 +0,0 @@ - -.. _vision_roborio: - -On the RoboRIO -============== - -.. _vision_gil_warning: - -.. warning:: Image processing is a CPU intensive task, and because of the Python - Global Interpreter Lock (GIL) **we do NOT recommend using robotpy-cscore - directly in your robot process**. Don't do it. Really. - - Instead, we provide easy to use ways to launch your camera/image - processing code from your Python robot code, and it won't break - simulation either! See below for details. - - For more information on the GIL and its effects, you may wish to - read the following resources: - - * `Python Wiki: Global Interpreter Lock `_ - * `Efficiently Exploiting Multiple Cores with Python `_ - -.. note:: The following assumes you're writing your robot code and your image - processing code using RobotPy. However, if you're writing your Robot - code using Java, we do have an example which would allow you to - launch Python image processing code from your Java Robot code. `See - this file for details `_. - -Installation ------------- - -``robotpy-cscore`` can be easily installed with the RobotPy installer. See -:ref:`these instructions ` for details. - -.. _vision_roborio_automatic: - -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 (:ref:`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 processing - code - - .. 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. - -vision file -~~~~~~~~~~~ - -The first step you need to do is create a file -- let's call it ``vision.py``, -and stick it in the same directory as your ``robot.py`` file. You can also put -it in a subdirectory underneath your robot code, and the robot deploy command -will copy it to the robot. - -.. seealso:: :ref:`vision_code` - -.. _vision_roborio_runcustom: - -robot.py -~~~~~~~~ - -Once you have written your cscore code, in the ``robotInit`` function in -your ``robot.py`` file you need to add the following line:: - - wpilib.CameraServer.launch('vision.py:main') - -The parameter provided to launch is of the form ``FILENAME:FUNCTION``. For example, -if your code was located in the ``camera`` subdirectory in a file called -``targeting.py``, and your function was called ``run``, then you would do:: - - wpilib.CameraServer.launch('camera/targeting.py:run') - -Important notes -~~~~~~~~~~~~~~~ - -* Your image processing code will be launched via a stub that will setup logging - and initialize NetworkTables to talk to your robot code -* The child process will NOT be launched when running the robot code in - simulation or unit testing mode -* If your image processing code contains a ``if __name__ == '__main__':`` block, - the code inside that block will NOT be executed when the code is launched from - ``robot.py`` -* The camera code will be killed when the ``robot.py`` program exits. If you - wish to perform cleanup, you should register an atexit handler. - -The `intermediate vision example `_ -can be found in the RobotPy examples repository. - -More information ----------------- - -* The :doc:`WPILib documentation for cscore ` - may be useful to explain concepts (though some details are different) -* :ref:`CSCore Troubleshooting `