Updates for kickoff

conf.py

@@ -83,8 +83,8 @@
         "https://robotpy.readthedocs.io/projects/pyfrc/en/%s/" % rtd_version,
         None,
     ),
-    "networktables": (
-        "https://robotpy.readthedocs.io/projects/pynetworktables/en/%s/" % rtd_version,
+    "ntcore": (
+        "https://robotpy.readthedocs.io/projects/pyntcore/en/%s/" % rtd_version,
         None,
     ),
     "wpilib": (
@@ -186,7 +186,7 @@
 epub_title = "RobotPy"
 epub_author = "RobotPy development team"
 epub_publisher = "RobotPy development team"
-epub_copyright = "2014-2020, RobotPy development team"
+epub_copyright = "2014-2022, RobotPy development team"
 
 # A list of files that should not be packed into the epub file.
 epub_exclude_files = ["search.html"]

faq.rst

@@ -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 2022, this was Python 3.10.  When using pyfrc or similar projects,
-   you should use a Python 3.6 or newer interpreter (the latest is recommended).
+   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).
 -  RobotPy 2014.x is based on Python 3.2.5.
 
 `pynetworktables <https://github.com/robotpy/pynetworktables>`__ is
@@ -71,7 +71,7 @@ Prior to 2015, the API matched the C++ version of WPILib.
 Is Command-based programming available?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Of course! Check out the :mod:`wpilib.command <wpilib.command>` package. There
+Of course! Check out the :mod:`commands2 <commands2>` package. There
 is also some :ref:`python-specific documentation available <command_framework_docs>`.
 
 Is there an easy way to test my code outside of the robot?
@@ -81,8 +81,6 @@ Glad you asked! Our pyfrc project has a built in :ref:`lightweight robot simulat
 you can use to run your code, and also has builtin support for unit testing
 with `py.test <http://pytest.org>`_.
 
-.. note:: These are in the process of being updated for 2020
-
 Competition
 -----------
 
@@ -91,6 +89,10 @@ 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

guide/examples.rst

@@ -6,5 +6,4 @@ RobotPy project provides many example programs that can be a good starting
 point.
 
 * `Robot Code examples <https://github.com/robotpy/examples>`_
-* :ref:`NetworkTables samples <pynetworktables_examples>`
 * `RobotPy CSCore examples <https://github.com/robotpy/robotpy-cscore/tree/main/examples>`_

guide/nt.rst

@@ -4,6 +4,8 @@
 Using NetworkTables
 ===================
 
+.. warning:: This documentation has not been documented for the 2023 season yet
+
 NetworkTables is a communications protocol used in FIRST Robotics. It provides a
 simple to use mechanism for communicating information between several computers.
 There is a single server (typically your robot) and zero or more clients. These
@@ -126,10 +128,7 @@ table is updated.
 Code Samples
 ~~~~~~~~~~~~
 
-There are many code samples showing various aspects of NetworkTables operation.
-See the :ref:`pynetworktables examples <pynetworktables_examples>` page.
-
-.. seealso:: :ref:`NetworkTables API Reference <pynetworktables_api>`
+.. seealso:: :ref:`NTCore API Reference <ntcore_api>`
 
 Troubleshooting
 ~~~~~~~~~~~~~~~

index.rst

@@ -16,6 +16,9 @@ changed this season that you should be aware of.
           officially supported by FIRST. Please see the
           :ref:`FAQ <faq>` for more information.
 
+          We are working with the WPILib team to make Python an officially
+          supported language in 2024. See https://wpilib.org/blog/bringing-python-to-frc for the announcement.
+
 Projects
 --------
 
@@ -30,10 +33,11 @@ FRC robot code using Python, and we have several projects related to this:
 Additionally, RobotPy is home to several projects that are useful for all teams,
 even if they aren’t writing their robot code in python:
 
-* `pynetworktables <https://github.com/robotpy/pynetworktables>`_: python bindings for NetworkTables that you can use to communcate with SmartDashboard and/or your robot.
-* `pynetworktables2js <https://github.com/robotpy/pynetworktables2js>`_: Forwards NetworkTables traffic to a web page, allowing you to write custom dashboards for your robot using HTML/Javascript
+* `pyntcore <https://github.com/robotpy/pyntcore>`_: python bindings for NetworkTables that you can use to communcate with a dashboard and/or your robot.
+* `pynetworktables <https://github.com/robotpy/pynetworktables>`_: legacy NetworkTables implementation that you can use to communcate with SmartDashboard and/or your robot.
 * `pynetconsole <https://github.com/robotpy/pynetconsole>`_: A simple netconsole implementation in python
 * `robotpy-cscore <https://github.com/robotpy/robotpy-cscore>`_: Python bindings for cscore, a powerful camera/streaming library
+* `robotpy-apriltag <https://github.com/robotpy/robotpy-apriltag>`_: Python bindings for the WPILib apriltag library
 * `roborio-vm <https://github.com/robotpy/roborio-vm>`_: Scripts to create a QEMU virtual machine from the RoboRIO image file
 
 There is a lot of good documentation, but there's still room for improvement.

install/commands.rst

@@ -6,12 +6,9 @@
 Commands install
 ================
 
-As of 2020, the command frameworks are distributed as separate packages. The
-latest command framework is available as robotpy-commands-v2, and the
-legacy command framework is available in robotpy-commands-v1.
-
-The instructions below discuss installing the new command framework. To install
-the legacy framework replace ``commands2`` with ``commands``.
+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)
 -----------------------

install/components.rst

@@ -3,11 +3,10 @@
 RobotPy Components
 ==================
 
-New in 2021, RobotPy now provides a meta installation package that makes it
-simpler to install and upgrade RobotPy. The meta package allows you to run
-``pip install robotpy`` and this install all of the core RobotPy packages. This
-meta package is used both for installation on your computer and on your 
-robot.
+RobotPy provides a meta installation package that makes it simpler to install
+and upgrade RobotPy. The meta package allows you to run ``pip install robotpy``
+and this install all of the core RobotPy packages. This meta package is used
+both for installation on your computer and on your robot.
 
 Optional/Vendor Components
 --------------------------
@@ -17,17 +16,18 @@ RobotPy wrappers around WPILib will be installed. However there are several
 groups of optional components that you can install. 
 Vendor categories:
 
-* ``adi`` - Analog Devices 6-axis accelerometer support
 * ``ctre`` - Cross The Road Electronics motor controllers
 * ``navx`` - Kauai Labs NavX MXP Robotics Navigation 
-* ``playingwithfusion`` - PlayingWithFusion motor controllers
+* ``photonvision`` - PhotonVision computer vision vendor library
+* ``pathplannerlib`` - PathPlannerLib path planning vendor library
 * ``photonvision`` - PhotonVision computer vision vendor library
 * ``rev`` - REV Robotics motor controllers and color sensors
 
 Optional WPILib component categories:
 
+* ``apriltag`` - WPILib apriltag library 
 * ``commands2`` - WPILib Commands framework (2020+)
-* ``commands`` - WPILib old Commands framework
+* ``cscore`` - WPILib cscore library
 * ``romi`` - Romi robot specific components
 * ``sim`` - WPILib extra simulation support
 

install/computer.rst

@@ -6,7 +6,7 @@ Computer Installation
 
 .. note:: installation via pip typically requires internet access
 
-RobotPy requires Python 3.7/3.8/3.9/3.10 to be installed on your computer. We
+RobotPy requires Python 3.7/3.8/3.9/3.10/3.11 to be installed on your computer. We
 no longer support 32-bit installations of Python, you must have a 64-bit
 python installed.
 
@@ -51,8 +51,6 @@ not recommended nor is it supported.
 
 .. tab:: macOS
 
-     .. warning:: Due to WPILib dependencies, RobotPy only supports non-ARM MacOS 10.15+
-
      On a macOS system that has pip installed, just run the following command from the
      Terminal application (may require admin rights):
 
@@ -83,7 +81,7 @@ not recommended nor is it supported.
      .. _install_linux:
 
      Since 2021, RobotPy distributes manylinux binary wheels on PyPI. However,
-     installing these requires a distro that has glibc 2.27 or newer, and
+     installing these requires a distro that has glibc 2.35 or newer, and
      an installer that implements :pep:`600`, such as pip 20.3 or newer.
      You can check your version of pip with the following command:
 
@@ -113,8 +111,8 @@ not recommended nor is it supported.
      The following Linux distributions are known to work, but this list is not
      necessarily comprehensive:
 
-     * Ubuntu 18.04+
-     * Fedora 31+
+     * Ubuntu 22.04+
+     * Fedora 36+
      * Arch Linux
 
      If you manage to install the packages and get the following error or
@@ -134,12 +132,12 @@ not recommended nor is it supported.
          Mixing our pre-built wheels with source installs may cause runtime errors.
          This is due to internal ABI incompatibility between compiler versions.
 
-         Our wheels are built on Ubuntu 18.04 with GCC 7.
+         Our wheels are built on Ubuntu 22.04 with GCC 11.
 
      If you need to build with a specific compiler version, you can specify them
      using the :envvar:`CC` and :envvar:`CXX` environment variables:
 
      .. code-block:: sh
 
-         export CC=gcc-7 CXX=g++-7
+         export CC=gcc-12 CXX=g++-12
 

install/cscore.rst

@@ -38,57 +38,21 @@ the :ref:`robotpy-installer documentation <install_packages>`.
 Non-roboRIO installation
 ------------------------
 
-GNU/Linux packages
-~~~~~~~~~~~~~~~~~~
+We now distribute wheels for CSCore on pypi, so you can just use the robotpy-meta
+package to install it:
 
-If you're using Debian, Ubuntu, Fedora, or openSUSE, follow the instructions on
-https://software.opensuse.org/download.html?project=home%3Aauscompgeek%3Arobotpy&package=python3-cscore
-
-If you're using Arch Linux, you can follow the instructions at
-https://software.opensuse.org/download.html?project=home%3Aauscompgeek%3Arobotpy&package=python-cscore
-to install a precompiled package.
-
-A full list of supported platforms is available on
-https://build.opensuse.org/package/show/home:auscompgeek:robotpy/robotpy-cscore
-
-Compiling 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. Ensure a C++ compiler that supports C++17 is installed
-2. Install Python 3 (cscore is not supported on Python 2) and development headers
-3. Ensure that you have a recent version of pip3/setuptools installed (either via pip3 or using a Linux package manager)
-
-   * It has been reported that build failures may occur with certain combinations of pip/setuptools installed
-
-4. Install Numpy (either via pip3 or using a Linux package manager)
-5. Install OpenCV (either via a Linux package manager or compile from source)
+.. tab:: Windows
 
-   * If you compile from source, you **must** enable shared library support,
-     cscore cannot use a statically compiled OpenCV python module at this time
-   * If you use OpenCV 4, you must also compile with ``-DOPENCV_GENERATE_PKGCONFIG=ON``
-     and install ``pkgconfig`` via pip for robotpy-cscore to find it.
+   .. code-block:: sh
 
-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!
+      py -3 -m pip install -U robotpy[cscore]
 
-.. note::
+.. tab:: Linux/macOS
 
-   robotpy-cscore has only been lightly tested on Windows, and installation
-   of OpenCV is slightly complicated, but you may have luck using conda.  See
-   `robotpy-cscore issue #17 <https://github.com/robotpy/robotpy-cscore/issues/17>`_
-   for more details.
+   .. code-block:: sh
 
-.. note:: CSCore does not support reading USB cameras on macOS.
+      pip3 install -U robotpy[cscore]
 
-.. warning:: Currently, robotpy-cscore does not support using the OpenCV module
-             that comes with the `opencv-python <https://pypi.python.org/pypi/opencv-python>`_
-             package distributed on Pypi. Long term, I'd like to get that to
-             work, but it's going to take a bit of work. To track this issue,
-             see https://github.com/skvark/opencv-python/issues/22
 
 Next steps
 ----------

install/pynetworktables.rst

@@ -4,6 +4,9 @@
 pynetworktables install
 =======================
 
+.. warning:: This page has not been updated for 2023. We recommend using pyntcore
+             instead of pynetworktables.
+
 pynetworktables is a python package that allows FRC teams to use Python to
 communicate with their robots via NetworkTables. It should work without issues
 on your Driver Station, on a coprocessor such as a Raspberry Pi, or anywhere

install/robot.rst

@@ -23,7 +23,7 @@ Install requirements
 
 RobotPy is truly cross platform, and can be installed from Windows, most Linux
 distributions, and from Mac macOS also. To install/use the installer, you must
-have Python 3.6+ installed. You should install the installer via pip (requires
+have Python 3.7+ installed. You should install the installer via pip (requires
 internet access) by installing the core RobotPy components (see the 
 :ref:`computer installation <install_computer>` section for more details).
 
@@ -58,9 +58,9 @@ Install Python on a roboRIO
 
 .. note:: This step only needs to be done once. 
 
-As of 2021, installing Python and the RobotPy packages are separated into 
-two different steps. Once you are connected to the internet, you can run this
-to download Python for roboRIO onto your computer.
+Installing Python and the RobotPy packages are separated into two different steps.
+Once you are connected to the internet, you can run this to download Python for
+roboRIO onto your computer.
 
 .. tab:: Windows
 

troubleshooting.rst

@@ -111,6 +111,46 @@ You should either:
 
 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!
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When you find something like this here's what you can do:
+
+First, figure out where the code is crashing. Traditional debugging techniques
+apply here, but a simple way is to just delete and/or comment out things until
+it no longer fails. Then add the last thing back in and verify that the code 
+still crashes.
+
+Advanced users can compile a custom version of the robotpy libraries with
+symbols and use gdb to get a full stack trace (documentation TBD).
+
+Once you've identified where it crashes, file a bug on github and we can help
+you out.
+
+Common causes
+^^^^^^^^^^^^^
+
+Python objects are reference counted, and sometimes when you pass one directly
+to a C++ function without retaining a reference a crash can occur::
+
+    class Foo:
+        def do_something(self):
+            some_function(Thing())
+
+In this example, ``Thing`` is immediately destroyed after some_function returns
+(because there are no references to it), but some_function (or something else)
+tries to use the object after it is destroyed. This causes a segfault or memory
+access exception of some kind.
+
+These are considered bugs in RobotPy code and if you report an issue on github
+we can fix it. However, as a workaround you can retain a reference to the thing
+that you created and that often resolves the issue::
+
+    class Foo:
+        def do_something(self):
+            self.thing = Thing()
+            some_function(self.thing)
+
 .. _troubleshooting_nt:
 
 pynetworktables