diff --git a/conf.py b/conf.py index 51b7bb2..1cdf463 100644 --- a/conf.py +++ b/conf.py @@ -107,7 +107,8 @@ } redirects = { - "2020_notes": "upgrade_notes.html" + "2020_notes": "upgrade_notes.html", + "install/pynetworktables": "pyntcore.html" } # The version info for the project you're documenting, acts as replacement for diff --git a/dev/deploy.rst b/dev/deploy.rst index 96e3ab6..a2a9c36 100644 --- a/dev/deploy.rst +++ b/dev/deploy.rst @@ -16,7 +16,7 @@ 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 eclipse, +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! diff --git a/getting_started.rst b/getting_started.rst index 8b84e3f..150ace7 100644 --- a/getting_started.rst +++ b/getting_started.rst @@ -20,6 +20,6 @@ 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 pynetworktables on the driver station or on a -coprocessor, then check out the :ref:`pynetworktables install docs `. +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/nt.rst b/guide/nt.rst index c9ccae0..612bc10 100644 --- a/guide/nt.rst +++ b/guide/nt.rst @@ -4,8 +4,6 @@ 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 @@ -22,7 +20,7 @@ Robot Configuration FIRST introduced the mDNS based addressing for the RoboRIO in 2015, and generally teams that use additional devices have found that while it works at home and sometimes in the pits, it tends to not work correctly on the field at -events. For this reason, if you use pynetworktables on the field, we strongly +events. For this reason, if you use NetworkTables on the field, we strongly encourage teams to `ensure every device has a static IP address`. * Static IPs are ``10.XX.XX.2`` @@ -34,121 +32,17 @@ would be ``10.12.34.2``. For information on configuring your RoboRIO and other devices to use static IPs, see the :doc:`WPILib documentation `. -Server initialization (Robot) ------------------------------ - -WPILib automatically starts NetworkTables for you, and no additional -configuration should need to be done. - -Client initialization (Driver Station/Coprocessor) --------------------------------------------------- - -.. note:: For install instructions, see - :ref:`pynetworktables installation instructions ` - -As of 2017, this is very easy to do. Here's the code:: - - from networktables import NetworkTables - - NetworkTables.initialize(server='10.xx.xx.2') - -The key is specifying the correct server hostname. See the above section on -robot configuration for this. - -.. warning:: NetworkTables does not connect instantly! If you write a script - that calls ``initialize`` and immediately tries to read from - NetworkTables, you will almost certainly not be able to read - any data. - - To write a script that waits for the connection, you can use the - following code:: - - import threading - from networktables import NetworkTables - - cond = threading.Condition() - notified = [False] +Resources +--------- - def connectionListener(connected, info): - print(info, '; Connected=%s' % connected) - with cond: - notified[0] = True - cond.notify() +Installation: - NetworkTables.initialize(server='10.xx.xx.2') - NetworkTables.addConnectionListener(connectionListener, immediateNotify=True) +.. seealso:: :ref:`pyntcore installation ` - with cond: - print("Waiting") - if not notified[0]: - cond.wait() - - # Insert your processing code here - print("Connected!") - -Theory of operation -------------------- - -In its most abstract form, NetworkTables can be thought of as a dictionary that -is shared across multiple computers across the network. As you change the value -of a table on one computer, the value is transmitted to the other side and can -be retrieved there. - -The keys of this dictionary **must** be strings, but the values can be numbers, -strings, booleans, various array types, or raw binary. Strictly speaking, the -keys can be any string value, but they are typically path-like values such as -``/SmartDashboard/foo``. - -When you call :meth:`NetworkTablesInstance.getTable `, -this retrieves a :class:`NetworkTable ` instance -that allows you to perform operations on a specified path:: - - table = NetworkTablesInstance.getTable('SmartDashboard') - - # This retrieves a boolean at /SmartDashboard/foo - foo = table.getBoolean('foo', True) - -There is also an concept of subtables:: - - subtable = table.getSubTable('bar') - - # This retrieves /SmartDashboard/bar/baz - baz = table.getNumber('baz', 1) - -As you may have guessed from the above example, once you obtain a NetworkTable -instance, there are very simple functions you can call to send and receive -NetworkTables data. - -* To retrieve values, call ``table.getXXX(name, default)`` -* To send values, call ``table.putXXX(name, value)`` - -NetworkTables can also be told to call a function when a particular key in the -table is updated. - -Code Samples -~~~~~~~~~~~~ +API: .. seealso:: :ref:`NTCore API Reference ` -Troubleshooting -~~~~~~~~~~~~~~~ - -.. seealso:: :ref:`pynetworktables troubleshooting ` - -External tools --------------- - -WPILib's OutlineViewer (requires Java) is a great tool for connecting to -networktables and seeing what's being transmitted. - -* `Download OutlineViewer `_ - -WPILib's Shuffleboard (requires Java) is the new (as of 2018) tool to replace -SmartDashboard for creating custom NetworkTables-enabled dashboards. - -* `Download Shuffleboard `_ - -WPILib's SmartDashboard (requires Java) is an older tool used by teams to connect -to NetworkTables and used as a dashboard. +Troubleshooting: -* `Download SmartDashboard `_ +.. seealso:: :ref:`NetworkTables troubleshooting ` diff --git a/install/components.rst b/install/components.rst index 2868f2a..c7f62fe 100644 --- a/install/components.rst +++ b/install/components.rst @@ -57,6 +57,12 @@ along with command based programming. You would do this pip3 install -U robotpy[navx,commands] +.. tab:: Linux ARM Coprocessor + + .. code-block:: sh + + pip3 install --find-links=https://tortall.net/~robotpy/wheels/2023/raspbian/ -U robotpy[navx,commands] + Or if you wanted to install everything: .. tab:: Windows @@ -71,19 +77,15 @@ Or if you wanted to install everything: pip3 install -U robotpy[all] +.. tab:: Linux ARM Coprocessor + + .. code-block:: sh + + pip3 install --find-links=https://tortall.net/~robotpy/wheels/2023/raspbian/ -U robotpy[all] + RoboRIO vs Computer ------------------- The RobotPy meta package is used for installation on both the RoboRIO and on your computer. - -Coprocessor installation ------------------------- - -Building RobotPy components can take a really long time, so its best if you -use the pre-built wheels that we publish for ARM32 and AARCH64 systems. - -.. code-block:: sh - - pip3 install --find-links=https://tortall.net/~robotpy/wheels/2023/raspbian/ -U robotpy diff --git a/install/computer.rst b/install/computer.rst index 4cad43f..baa7805 100644 --- a/install/computer.rst +++ b/install/computer.rst @@ -122,7 +122,7 @@ not recommended nor is it supported. **source install** - Alternatively, if you have a C++17 compiler installed, you may be able + Alternatively, if you have a C++20 compiler installed, you may be able to use pip to install RobotPy from source. .. warning:: It may take a very long time to install! @@ -141,3 +141,32 @@ not recommended nor is it supported. export CC=gcc-12 CXX=g++-12 +.. tab:: Linux ARM Coprocessor + + We now publish prebuilt wheels at https://tortall.net/~robotpy/wheels/2023/raspbian/, which can be downloaded by giving the ``--find-links`` option to + pip: + + .. code-block:: sh + + pip3 install --find-links=https://tortall.net/~robotpy/wheels/2023/raspbian/ robotpy + + **source install** + + Alternatively, if you have a C++20 compiler installed, you may be able + to use pip to install RobotPy from source. + + .. warning:: It may take a very long time to install! + + .. warning:: + + Mixing our pre-built wheels with source installs may cause runtime errors. + This is due to internal ABI incompatibility between compiler versions. + + Our ARM wheels are built on Ubuntu 22.04 with GCC 10. + + 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-12 CXX=g++-12 \ No newline at end of file diff --git a/install/cscore.rst b/install/cscore.rst index d941396..ca7fbdc 100644 --- a/install/cscore.rst +++ b/install/cscore.rst @@ -4,8 +4,6 @@ robotpy-cscore install ====================== -.. note:: cscore is not installed when you ``pip install robotpy`` - RoboRIO installation -------------------- @@ -17,20 +15,20 @@ is very simple: .. code-block:: sh # While connected to the internet - py -3 -m robotpy_installer download robotpy-cscore + 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 + py -3 -m robotpy_installer install robotpy[cscore] .. tab:: Linux/macOS .. code-block:: sh # While connected to the internet - robotpy-installer download robotpy-cscore + robotpy-installer download robotpy[cscore] # While connected to the network with a RoboRIO on it - robotpy-installer install robotpy-cscore + robotpy-installer install robotpy[cscore] For additional details about running robotpy-installer on your computer, see the :ref:`robotpy-installer documentation `. @@ -38,8 +36,7 @@ the :ref:`robotpy-installer documentation `. Non-roboRIO installation ------------------------ -We now distribute wheels for CSCore on pypi, so you can just use the robotpy-meta -package to install it: +We now distribute pre-built wheels for CSCore, so you can just use pip to install it: .. tab:: Windows @@ -53,6 +50,12 @@ package to install it: 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 ---------- diff --git a/install/index.rst b/install/index.rst index 395905e..4e0b1fd 100644 --- a/install/index.rst +++ b/install/index.rst @@ -14,9 +14,9 @@ Writing Robot code in Python: Using NetworkTables from Python: -* To install pynetworktables on a system that does not have RobotPy +* 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:`pynetworktables installation documentation `. + :ref:`pyntcore installation documentation `. Using cscore from Python: @@ -45,7 +45,7 @@ Notes specific to individual packages :maxdepth: 1 pyfrc - pynetworktables + pyntcore commands ctre navx diff --git a/install/pynetworktables.rst b/install/pynetworktables.rst deleted file mode 100644 index af64f5a..0000000 --- a/install/pynetworktables.rst +++ /dev/null @@ -1,93 +0,0 @@ - -.. _install_pynetworktables: - -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 -else that you might install Python. - -pynetworktables requires Python 2.7 or 3.3 or greater to be installed on the -system that you'll be using it on. - -.. note:: You only need to install pynetworktables separately if you're using - it on a system that doesn't already have pyfrc or RobotPy installed - on it (such as a coprocessor) - -Install via pip on Windows --------------------------- - -The latest versions of Python on Windows come with pip, but you may need to -install it by hand if you're using an older version. Once pip is installed, -run the following command from the command line: - -.. code-block:: sh - - Python 2.7: py -2 -m pip install pynetworktables - Python 3.x: py -3 -m pip install pynetworktables - -To upgrade, you can run this: - -.. code-block:: sh - - Python 2.7: py -2 -m pip install --upgrade pynetworktables - Python 3.x: py -3 -m pip install --upgrade pynetworktables - -If you don't have administrative rights on your computer, either use -`virtualenv/virtualenvwrapper-win `_, or -or you can install to the user site-packages directory: - -.. code-block:: sh - - Python 2.7: py -2 -m pip install --user pynetworktables - Python 3.x: py -3 -m pip install --user pynetworktables - -Install via pip on macOS/Linux ------------------------------- - -On a Linux or macOS system that has pip installed, just run the following command -from the Terminal application (may require admin rights): - -.. code-block:: sh - - Python 2.7: pip install pynetworktables - Python 3.x: pip3 install pynetworktables - -To upgrade, you can run this: - -.. code-block:: sh - - Python 2.7: pip install --upgrade pynetworktables - Python 3.x: pip3 install --upgrade pynetworktables - -If you don't have administrative rights on your computer, either use -`virtualenv/virtualenvwrapper-win `_, or -or you can install to the user site-packages directory: - -.. code-block:: sh - - Python 2.7: pip -m pip install --user pynetworktables - Python 3.x: pip3 -m pip install --user pynetworktables - -Manual install (without pip) ----------------------------- - -.. note:: It is highly recommended to use pip for installation when possible - -You can download the source code, extract it, and run this:: - - python setup.py install - -If you are using Python 2.7, you will need to also install the -`monotonic package from pypi `_ - -Getting Started ---------------- - -See the :ref:`NetworkTables guide ` to learn more about -using pynetworktables to communicate with your robot. diff --git a/install/robot.rst b/install/robot.rst index 6fcc166..6514ca2 100644 --- a/install/robot.rst +++ b/install/robot.rst @@ -8,10 +8,6 @@ These instructions will help you get RobotPy installed on your RoboRIO, which wi allow you to write robot code using Python. If you install RobotPy on your RoboRIO, you are still able to deploy C++ and Java programs without any conflicts. -.. note:: If you're looking for instructions to use NetworkTables from Python, - you probably want the :ref:`pynetworktables installation documentation - `. - Install requirements -------------------- diff --git a/troubleshooting.rst b/troubleshooting.rst index 57fc10c..af58bee 100644 --- a/troubleshooting.rst +++ b/troubleshooting.rst @@ -153,8 +153,8 @@ that you created and that often resolves the issue:: .. _troubleshooting_nt: -pynetworktables ---------------- +pyntcore +-------- isConnected() returns False! ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -167,30 +167,42 @@ will fail. Ensure you're using the correct mode ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you're running pynetworktables as part of a RobotPy robot -- relax, -pynetworktables is setup as a server automatically for you, just like in +If you're running NetworkTables as part of a RobotPy robot -- relax, +NetworkTables is setup as a server automatically for you, just like in WPILib! If you're trying to connect to the robot from a coprocessor (such as a Raspberry Pi) or from the driver station, then you will need to ensure that -you initialize pynetworktables correctly. +you initialize NetworkTables correctly. The following shows how to initialize +pyntcore correctly as a client. -Thankfully, this is super easy as of 2017. Here's the code:: +.. code-block:: python - from networktables import NetworkTables + import ntcore - # replace your team number below - NetworkTables.startClientTeam(1234) + inst = ntcore.NetworkTableInstance.getDefault() + + # start a NT4 client + inst.startClient4("example client") + + # connect to a roboRIO with team number TEAM + inst.setServerTeam(TEAM) + + # starting a DS client will try to get the roboRIO address from the DS application + inst.startDSClient() + + # connect to a specific host/port + inst.setServer("host", ntcore.NetworkTableInstance.kDefaultPort4) Don't know what the right hostname is? That's what the next section is for... -Use static IPs when using pynetworktables -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Use static IPs when using NetworkTables +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. seealso:: :ref:`networktables_guide` -Problem: I can't determine if networktables has connected +Problem: I can't determine if NetworkTables has connected ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Make sure that you have enabled python logging (it's not enabled by default):: @@ -205,8 +217,8 @@ Once you've enabled logging, look for messages that look like this:: If you see a message like this, it means that your client has connected to the robot successfully. If you don't see it, that means there's still a problem. -Usually the problem is that you set the hostname incorrectly in your call to -``NetworkTables.initialize``. +Much of the time this occurs when not using a static IP for your robot, and is +fixed when you start using a static IP for your robot. .. _troubleshooting_cscore: diff --git a/upgrade_notes.rst b/upgrade_notes.rst index cf6d26b..432fbf7 100644 --- a/upgrade_notes.rst +++ b/upgrade_notes.rst @@ -20,7 +20,6 @@ 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 -------------------- diff --git a/vision/roborio.rst b/vision/roborio.rst index 66b2147..8f74801 100644 --- a/vision/roborio.rst +++ b/vision/roborio.rst @@ -98,7 +98,7 @@ Important notes ~~~~~~~~~~~~~~~ * Your image processing code will be launched via a stub that will setup logging - and initialize pynetworktables to talk to your robot code + 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,