diff --git a/README.md b/README.md index 4bbf4fe..9472063 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,8 @@ become increasingly more difficult to introduce all of the pieces to new users. This is the foundation for a unified documentation site for all RobotPy projects, in hopes of reducing that confusion. +Now that Python is an officialy supported language, this site still aims to unify the various API documentation for RobotPy projects. However, much of our documentation has been moved to the [WPILib documentation](https://docs.wpilib.org). + All of our documentation is built using Sphinx, and is hosted at http://robotpy.readthedocs.io/ diff --git a/conf.py b/conf.py index 655c2ee..4dbc3d1 100644 --- a/conf.py +++ b/conf.py @@ -93,21 +93,34 @@ } redirects = { + "getting_started": f"{frc_docs}/docs/zero-to-robot/introduction.html", "2020_notes": "upgrade_notes.html", "install/pynetworktables": "pyntcore.html", - "frameworks/command": f"{frc_docs}/docs/software/commandbased/index", + "frameworks/command": f"{frc_docs}/docs/software/commandbased/", + "guide/anatomy": f"{frc_docs}/docs/zero-to-robot/step-4/creating-test-drivetrain-program-cpp-java-python.html", + "guide/index": f"{frc_docs}/docs/software/python/", + "guide/deploy": f"{frc_docs}/docs/software/python/subcommands/deploy.html", "guide/examples": "https://github.com/robotpy/examples", + "guide/guidelines": "guidelines", "guide/nt": f"{frc_docs}/docs/software/networktables/index.html", + "guide/running": f"{frc_docs}/docs/software/python/subcommands/index.html", + "guide/python": "https://docs.python-guide.org/en/latest/intro/learning/", + "guide/simulator": f"{frc_docs}/docs/software/wpilib-tools/robot-simulation/introduction.html", + "guide/testing": "testing", "hw": f"{frc_docs}/docs/hardware/hardware-basics/index.html", - "install/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", + "install/computer": f"{frc_docs}/docs/zero-to-robot/step-2/python-setup.html", + "install/components": f"{frc_docs}/docs/zero-to-robot/step-2/python-setup.html", + "install/packages": f"{frc_docs}/docs/zero-to-robot/step-2/python-setup.html", + "install/robot": f"{frc_docs}/docs/zero-to-robot/step-2/python-setup.html", + "install/commands": f"{frc_docs}/docs/software/vscode-overview/3rd-party-libraries.html", + "install/cscore": f"{frc_docs}/docs/zero-to-robot/step-2/python-setup.html", + "install/ctre": f"{frc_docs}/docs/software/vscode-overview/3rd-party-libraries.html", + "install/navx": f"{frc_docs}/docs/software/vscode-overview/3rd-party-libraries.html", + "install/pathplannerlib": f"{frc_docs}/docs/software/vscode-overview/3rd-party-libraries.html", + "install/pwfusion": f"{frc_docs}/docs/software/vscode-overview/3rd-party-libraries.html", + "install/pyfrc": f"{frc_docs}/docs/zero-to-robot/step-2/python-setup.html", + "install/pyntcore": f"{frc_docs}/docs/zero-to-robot/step-2/python-setup.html", + "install/rev": f"{frc_docs}/docs/software/vscode-overview/3rd-party-libraries.html", "vision/code": f"{frc_docs}/docs/software/vision-processing/index.html", "vision/index": f"{frc_docs}/docs/software/vision-processing/index.html", "vision/other": f"{frc_docs}/docs/software/vision-processing/index.html", @@ -184,7 +197,7 @@ epub_title = "RobotPy" epub_author = "RobotPy development team" epub_publisher = "RobotPy development team" -epub_copyright = "2014-2022, RobotPy development team" +epub_copyright = "2014-2024, RobotPy development team" # A list of files that should not be packed into the epub file. epub_exclude_files = ["search.html"] diff --git a/dev/deploy.rst b/dev/deploy.rst index 38c760a..06be79e 100644 --- a/dev/deploy.rst +++ b/dev/deploy.rst @@ -4,21 +4,26 @@ Deploy process details ====================== -When the code is uploaded to the robot, the following steps occur: +TODO -* SSH/sftp operations are performed as the ``lvuser`` user (this is REALLY important, don't use the ``admin`` user!) -* pyfrc does some checks to make sure the environment is setup properly -* The directory containing ``robot.py`` is recursively copied to the the directory ``/home/lvuser/py`` -* The files ``robotCommand`` and ``robotDebugCommand`` are created -* ``/usr/local/frc/bin/frcKillRobot.sh -t -r`` is called, which causes any existing robot code to be killed, and the new code is launched +.. + This is mostly the same, but has a lot of additional steps as of 2024 -If you wish for the code to be started up when the roboRIO boots up, you need to -make sure that "Disable RT Startup App" is **not** checked in the roboRIO's web -configuration. + When the code is uploaded to the robot, the following steps occur: -These steps are compatible with what C++/Java does when deployed by GradleRIO, -so you should be able to seamlessly switch between python and other FRC -languages! + * SSH/sftp operations are performed as the ``lvuser`` user (this is REALLY important, don't use the ``admin`` user!) + * robotpy-installer does some checks to make sure the environment is setup properly + * The directory containing ``robot.py`` is recursively copied to the the directory ``/home/lvuser/py`` + * The files ``robotCommand`` and ``robotDebugCommand`` are created + * ``/usr/local/frc/bin/frcKillRobot.sh -t -r`` is called, which causes any existing robot code to be killed, and the new code is launched + + If you wish for the code to be started up when the roboRIO boots up, you need to + make sure that "Disable RT Startup App" is **not** checked in the roboRIO's web + configuration. + + These steps are compatible with what C++/Java does when deployed by GradleRIO, + so you should be able to seamlessly switch between python and other FRC + languages! .. _manual_code_deploy: @@ -67,16 +72,12 @@ Example code: print(data) - if __name__ == "__main__": - wpilib.run(MyRobot) - - How to manually run code ------------------------ .. note:: Generally, you shouldn't need to use this process. -If you don't have (or don't want) to install pyfrc, running code manually is +If you don't have (or don't want) to install robotpy-installer, running code manually is pretty simple too. 1. Make sure you have RobotPy installed on the robot @@ -92,4 +93,4 @@ Your driver station should be able to connect to your code, and it will be able to operate your robot! .. note:: This is good for running experimental code, but it won't start the - code when the robot starts up. Use pyfrc to do that. + code when the robot starts up. Use robotpy-installer to do that. diff --git a/dev/design.rst b/dev/design.rst index 46d6edb..0d3b2d3 100644 --- a/dev/design.rst +++ b/dev/design.rst @@ -3,52 +3,7 @@ Design .. _robotpy_extension_options: -Adding options to robot.py --------------------------- +Adding options to the ``robotpy`` command +----------------------------------------- -When :func:`wpilib.run` is called, that function determines available commands -that can be run, and parses command line arguments to pass to the commands. -Examples of commands include: - -* Running the robot code -* Running the robot code, connected to a simulator -* Running unit tests on the robot code -* And lots more! - -python setuptools has a feature that allows you to extend the commands available -to robot.py without needing to modify WPILib's code. To add your own command, -do the following: - -* Define a setuptools entrypoint in your package's setup.py (see below) -* The entrypoint name is the command to add -* The entrypoint must point at an object that has the following properties: - * Must have a docstring (shown when ``--help`` is given) - * Constructor must take a single argument (it is an argparse parser which options can be added to) - * Must have a 'run' function which takes two arguments: options, and robot_class. It must - also take arbitrary keyword arguments via the ``**kwargs`` mechanism. If it receives arguments - that it does not recognize, the entry point must ignore any such options. - -If your command's run function is called, it is your command's responsibility -to execute the robot code (if that is desired). This sample command -demonstrates how to do this:: - - class SampleCommand: - '''Help text shown to user''' - - def __init__(self, parser): - pass - - def run(self, options, robot_class, **static_options): - # runs the robot code main loop - robot_class.main(robot_class) - -To register your command as a robotpy extension, you must add the following -to your setup.py setup() invocation:: - - from setuptools import setup - - setup( - ... - entry_points={'robotpy': ['name_of_command = package.module:CommandClassName']}, - ... - ) +As of 2024 the ``robotpy`` command (also accessed via ``python -m robotpy``) is located in the `robotpy-cli `__ package. Instructions for adding custom subcommands is located in the README file. diff --git a/faq.rst b/faq.rst index 6685a3a..813d944 100644 --- a/faq.rst +++ b/faq.rst @@ -27,7 +27,7 @@ Installing and Running RobotPy How do I install RobotPy? ~~~~~~~~~~~~~~~~~~~~~~~~~ -See our :ref:`getting started guide `. +RobotPy installation documentation is now at :doc:`frc-docs `. What version of Python do RobotPy projects use? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -83,6 +83,8 @@ you are a vendor, please reach out to our team and we'd be happy to assist. The RobotPy project also provides unofficial wrappers for vendor libraries that don't take a lot of effort to create and maintain. +.. seealso:: :doc:`frc:docs/software/vscode-overview/3rd-party-libraries` + Competition ----------- @@ -103,10 +105,7 @@ using RobotPy since 2010, and the maintainer of RobotPy is a member of the WPILib team. Much of the time when bugs are found, they are found in the underlying WPILib, instead of RobotPy itself. -One caveat to this is that because RobotPy doesn't have a beta period like -WPILib does, bugs tend to be found during the first half of competition season. -However, by the time build season ends, RobotPy is just as stable as any of -the officially suported languages. +One caveat to this is that because RobotPy is not yet widely adopted, bugs tend to be found during the first half of competition season. However, by the time build season ends, RobotPy is just as stable. How often does RobotPy get updated? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -148,8 +147,17 @@ Ross Light, FRC Team 973. Peter is a member of the FIRST WPILib team, and also created the `ntcore `_ and `cscore `_ libraries. -The current RobotPy maintainer is `Dustin -Spicuzza `_, also a member of the FIRST WPILib team. +How is RobotPy different from WPILib? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All current RobotPy developers are members of the FIRST WPILib team, so in some sense RobotPy is a subgroup of WPILib. However, RobotPy is still separate from WPILib in many ways and has it's own shiny logo, but as time goes on we are aiming to integrate more into the greater WPILib whole. + +One thing that makes RobotPy different from WPILib is that we also maintain separate libraries for interacting with various 3rd party vendors, but we expect as Python gets more traction in FRC that vendors will develop and maintain their own libraries. + +Who develops RobotPy? +--------------------- + +The current RobotPy maintainer is `Dustin Spicuzza `_. Current RobotPy developers include: @@ -164,6 +172,7 @@ RobotPy is an open project that all members of the FIRST community can easily and quickly contribute to. If you find a bug, or have an idea that you think others can use: +- Add Python documentation to :doc:`the official WPILib documentation ` - Test and report any issues you find. - Port and test a useful library. - Write a Python module and share it with others (and contribute it to diff --git a/frameworks/magicbot.rst b/frameworks/magicbot.rst index fb373ed..f901003 100644 --- a/frameworks/magicbot.rst +++ b/frameworks/magicbot.rst @@ -32,11 +32,6 @@ class as your base robot class. You'll note that it's similar to '''Called when teleop starts; optional''' def teleopPeriodic(self): - '''Called on each iteration of the control loop''' - - if __name__ == '__main__': - wpilib.run(MyRobot) - A robot control program can be divided into several logical parts (think drivetrain, forklift, elevator, etc). We refer to these parts as diff --git a/getting_started.rst b/getting_started.rst deleted file mode 100644 index c877bbc..0000000 --- a/getting_started.rst +++ /dev/null @@ -1,21 +0,0 @@ - -.. _getting_started: - -Getting Started -=============== - -RobotPy WPILib is a set of libraries that are used on your roboRIO to -enable you to use Python as your main programming language for FIRST Robotics -robot development. It includes support for almost all components that are -supported by WPILib's C++ implementation. - -You can run RobotPy-based programs either on your computer or on a robot. There -are a lot of different ways you can get started with RobotPy, but we recommend -the following steps: - -* :ref:`Install RobotPy on your computer ` -* Learn how to write Python-based robot code via :ref:`anatomy` and the various - sections of the :ref:`programmer's guide ` - -Once you've played around with some code in simulation, then you should -:ref:`install RobotPy on your robot `. diff --git a/guide/anatomy.rst b/guide/anatomy.rst deleted file mode 100644 index eb37c47..0000000 --- a/guide/anatomy.rst +++ /dev/null @@ -1,260 +0,0 @@ -.. _anatomy: - -Anatomy of a robot -================== - -.. note:: The following assumes you have some familiarity with python, and - is meant as a primer to creating robot code using the python version - of wpilib. See our :ref:`python primer ` for a brief - introduction to the python programming language. - -This tutorial will go over the things necessary for very basic robot -code that can run on an FRC robot using the python version of WPILib. -Code that is written for RobotPy can be ran on your PC using various -simulation tools that are available. - -Create your Robot code ----------------------- - -Your robot code must start within a file called ``robot.py``. Your code -can do anything a normal python program can, such as importing other -python modules & packages. Here are the basic things you need to know to -get your robot code working! - -Importing necessary modules ---------------------------- - -All of the code that actually interacts with your robot's hardware is -contained in a library called WPILib. This library was originally implemented -in C++ and Java. Your robot code must import this library module, and create -various objects that can be used to interface with the robot hardware. - -To import wpilib, it's just as simple as this:: - - import wpilib - -.. note:: Because RobotPy implements the same WPILib as C++/Java, you can learn - a lot about how to write robot code from the many C++/Java focused - WPILib resources that already exist, including FIRST's official - documentation. Just translate the code into python. - -Robot object ------------- - -Every valid robot program must define a robot object that inherits from -:class:`wpilib.IterativeRobot` or :class:`wpilib.TimedRobot`. -These classes define a number of functions that you need to override, -which get called at various times. - -* :class:`wpilib.IterativeRobot` functions -* :class:`wpilib.TimedRobot` functions - -.. note:: It is recommended that inexperienced programmers use the - TimedRobot class, which is what this guide will discuss. - -An incomplete version of your robot object might look like this:: - - class MyRobot(wpilib.TimedRobot): - - def robotInit(self): - self.motor = wpilib.Jaguar(1) - -The ``robotInit`` function is where you initialize data that needs to be -initialized when your robot first starts. Examples of this data includes: - -* Variables that are used in multiple functions -* Creating various wpilib objects for devices and sensors -* Creating instances of other objects for your robot - -In python, the constructor for an object is the ``__init__`` function. Instead -of defining a constructor for your main robot object, you can override -robotInit instead. If you do decide that you want to override ``__init__``, then -you must call ``super().__init__()`` in your ``__init__`` method, or an -exception will be thrown. - -Adding motors and sensors -------------------------- - -Everything that interacts with the robot hardware directly must use the wpilib -library to do so. Starting in 2015, full documentation for the python version -of WPILib is published online. Check out the API documentation (:external+robotpy:doc:`wpilib`) -for details on all the objects available in WPILib. - -.. note:: - You should *only* create instances of your motors and other WPILib hardware - devices (Gyros, Joysticks, Sensors, etc) either during or after robotInit is - called on your main robot object. If you don't, there are a lot of things - that will fail. - -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+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 -following python code in your `robotInit` method:: - - self.motor = wpilib.Jaguar(4) - -Looking through the documentation some more, you would notice that to set -the PWM value of the motor, you need to call the :meth:`.Jaguar.set` function. The docs -say that the value needs to be between -1.0 and 1.0, so to set the motor -full speed forward you could do this:: - - self.motor.set(1) - -Other motors and sensors have similar conventions. - -Robot drivetrain control -~~~~~~~~~~~~~~~~~~~~~~~~ - -For standard types of drivetrains (2 or 4 wheel, mecanum, kiwi), you'll want to -use the various included class to control the motors instead of writing -your own code to do it. For most standard drivetrains, you'll want to use one -of three classes: - -* :class:`wpilib.drive.DifferentialDrive` for differential drive/skid-steer drive platforms such as 2 or 4 wheel platforms, the Kit of Parts drive base, "tank drive", or West Coast Drive. -* :class:`wpilib.drive.KilloughDrive` for Killough (Kiwi) triangular drive platforms. -* :class:`wpilib.drive.MecanumDrive` for mecanum drive platforms. - -For example, when you create a :class:`wpilib.drive.DifferentialDrive` object, you can -pass in motor controller instances:: - - l_motor = wpilib.Talon(0) - r_motor = wpilib.Talon(1) - self.robot_drive = wpilib.drive.DifferentialDrive(l_motor, r_motor) - -Or you can pass in motor controller groups to use more than one controller per side:: - - self.frontLeft = wpilib.Spark(1) - self.rearLeft = wpilib.Spark(2) - self.left = wpilib.SpeedControllerGroup(self.frontLeft, self.rearLeft) - - self.frontRight = wpilib.Spark(3) - self.rearRight = wpilib.Spark(4) - self.right = wpilib.SpeedControllerGroup(self.frontRight, self.rearRight) - - self.drive = wpilib.drive.DifferentialDrive(self.left, self.right) - -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+robotpy:doc:`wpilib.drive`, and the FIRST WPILib Programming Guide. - -Robot Operating Modes (TimedRobot) --------------------------------------- - -During a competition, the robot transitions into various modes depending on -the state of the game. During each mode, functions on your robot class -are called. The name of the function varies based on which mode the robot is -in: - -* ``disabledXXX`` - Called when robot is disabled -* ``autonomousXXX`` - Called when robot is in autonomous mode -* ``teleopXXX`` - Called when the robot is in teleoperated mode -* ``testXXX`` - Called when the robot is in test mode - -Each mode has two functions associated with it. xxxInit is called when the -robot first switches over to the mode, and xxxPeriodic is called 50 times -a second (approximately -- it's actually called as packets are received -from the driver station). - -For example, a simple robot that just drives the robot using a single -joystick might have a teleopPeriodic function that looks like this:: - - def teleopPeriodic(self): - self.robot_drive.arcadeDrive(self.stick) - -This function gets called over and over again (about 50 times per second) -while the robot remains in teleoperated mode. - -.. warning:: When using the TimedRobot as your Robot class, you should - avoid doing the following operations in the xxxPeriodic functions - or functions that have xxxPeriodic in the call stack: - - * Never use ``time.sleep()`` as you will momentarily lose - control of your robot during the delay, and it will not be - as responsive. - * Avoid using loops, as unexpected conditions may cause you to - lose control of your robot. - -Main block ----------- - -Languages such as Java require you to define a 'static main' function. In -python, because every .py file is usable from other python programs, you -need to `define a code block which checks for __main__ `_. -Inside your main block, you tell WPILib to launch your robot's code using -the following invocation:: - - if __name__ == '__main__': - wpilib.run(MyRobot) - -This simple invocation is sufficient for launching your robot code on the -robot, and also provides access to various RobotPy-enabled extensions that -may be available for testing your robot code, such as pyfrc and robotpy-frcsim. - -Putting it all together ------------------------ - -If you combine all the pieces above, you end up with something like this -below, taken from one of the samples in our github repository:: - - #!/usr/bin/env python3 - """ - This is a good foundation to build your robot code on - """ - - import wpilib - import wpilib.drive - - - class MyRobot(wpilib.TimedRobot): - - def robotInit(self): - """ - This function is called upon program startup and - should be used for any initialization code. - """ - self.left_motor = wpilib.Spark(0) - self.right_motor = wpilib.Spark(1) - self.drive = wpilib.drive.DifferentialDrive(self.left_motor, self.right_motor) - self.stick = wpilib.Joystick(1) - self.timer = wpilib.Timer() - - def autonomousInit(self): - """This function is run once each time the robot enters autonomous mode.""" - self.timer.reset() - self.timer.start() - - def autonomousPeriodic(self): - """This function is called periodically during autonomous.""" - - # Drive for two seconds - if self.timer.get() < 2.0: - self.drive.arcadeDrive(-0.5, 0) # Drive forwards at half speed - else: - self.drive.arcadeDrive(0, 0) # Stop robot - - def teleopPeriodic(self): - """This function is called periodically during operator control.""" - self.drive.arcadeDrive(self.stick.getY(), self.stick.getX()) - - - if __name__ == "__main__": - wpilib.run(MyRobot) - -There are a few different python-based robot samples available, and you -can find them in `our github examples repository `_. - -.. seealso:: RobotPy comes with various frameworks that make it easier to create - your robot code. See the page on :ref:`frameworks`. - -Next Steps ----------- - -This is a good foundation for building your robot, next you will probably want -to know about :ref:`running_robot_code`. diff --git a/guide/deploy.rst b/guide/deploy.rst deleted file mode 100644 index 30bfd5d..0000000 --- a/guide/deploy.rst +++ /dev/null @@ -1,98 +0,0 @@ - -.. _deploy: - -Deploying to the robot ----------------------- - -.. contents:: :local: - -The easiest way to install code on the robot is to use the deploy command -provided by pyfrc. This command will first run any unit tests on your robot -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 `) 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 -m robotpy deploy - -.. tab:: Linux/macOS - - .. code-block:: sh - - 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 `_. -You can use netconsole and the normal FRC tools to interact with the running -robot code. - -If you're having problems deploying code to the robot, check out the -:ref:`troubleshooting section ` - -Immediate feedback via Netconsole -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Note that when you run the deploy command like that, you won't get any feedback -from the robot whether your code actually worked or not. If you want to see the -feedback from your robot without launching a separate NetConsole window, a -really useful option is ``--nc``. This will cause the deploy command to show -your program's console output, by launching a netconsole listener. - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy deploy --nc - -.. tab:: Linux/macOS - - .. code-block:: sh - - python3 -m robotpy deploy --nc - -.. note:: This requires the driver station software to be connected to your robot - -Skipping Tests -~~~~~~~~~~~~~~ - -Now perhaps your tests are failing, but you really need to upload the code, and -don't care about the tests. That's OK, you can still upload code to the robot: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy deploy --skip-tests - -.. tab:: Linux/macOS - - .. code-block:: sh - - python3 -m robotpy deploy --skip-tests - -Starting deployed code at boot -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you wish for the deployed code to be started up when the roboRIO boots up, -you need to make sure that "Disable RT Startup App" is **not** checked in the -roboRIO's web configuration. See the -:doc:`FIRST documentation ` -for more information. - -Manually deploying code -~~~~~~~~~~~~~~~~~~~~~~~ - -Generally, you you just use the steps above. However, if you really want to, -then see :ref:`manual_code_deploy`. - -Next Steps -~~~~~~~~~~ - -Let's talk about :ref:`the robot simulator ` next. - diff --git a/guide/index.rst b/guide/index.rst deleted file mode 100644 index 50d63a8..0000000 --- a/guide/index.rst +++ /dev/null @@ -1,21 +0,0 @@ - -.. _programmers_guide: - -Programmer's Guide ------------------- - -* If you don't know python very well (or at all), start with :ref:`python_primer` -* Otherwise, start with :ref:`anatomy` - - -.. toctree:: - :maxdepth: 2 - - python - anatomy - running - deploy - simulator - testing - guidelines - nt \ No newline at end of file diff --git a/guide/nt.rst b/guide/nt.rst deleted file mode 100644 index 4adad3a..0000000 --- a/guide/nt.rst +++ /dev/null @@ -1,42 +0,0 @@ - -.. _networktables_guide: - -Using NetworkTables -=================== - -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 -clients can be on the driver station, a coprocessor, or anything else on the -robot’s local control network. - -.. contents:: :local: - -Robot Configuration -------------------- - -.. note:: These notes apply to all languages that use NetworkTables, not just Python - -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 NetworkTables on the field, we strongly -encourage teams to `ensure every device has a static IP address`. - -- Static IPs are ``10.XX.XX.2`` -- mDNS Hostnames are ``roborio-XXXX-frc.local`` (don't use these!) - -For example, if your team number was 1234, then the static IP to connect to -would be ``10.12.34.2``. - -For information on configuring your RoboRIO and other devices to use static IPs, see the -:doc:`WPILib documentation `. - -Resources ---------- - -- :doc:`Networktables concepts and documentation ` - -- :ref:`NTCore API Reference ` - -- :ref:`NetworkTables troubleshooting ` diff --git a/guide/python.rst b/guide/python.rst deleted file mode 100644 index 83b3264..0000000 --- a/guide/python.rst +++ /dev/null @@ -1,328 +0,0 @@ - -.. _python_primer: - -Introduction to Python -====================== - -.. note:: This is intended to be a *very* brief overview/reference of the various - topics you need to master in order to program Python. This is not an - exhaustive guide to programming with python. We recommend other - resources to really learn that in-depth: - - * `List of various guides to learn Python `_ - * `CodeAcademy `_ - * `Python 3.5 Tutorial `_ - - If you want to practice some of these concepts, try out - `pybasictraining `_! - -Language elements ------------------ - -Comments -~~~~~~~~ - -Comments are not functional and do not do anything. They are intended to -be human readable things that help others understand what the code is -doing. Comments should be indented at the same level as surrounding code - -:: - - # This is a comment. It starts with a '#' character - -Indentation -~~~~~~~~~~~ - -All code should be indented in multiples of 4 spaces. Tab characters -should be avoided. Anytime you see a ``:`` character at the end of a -line, the next line(s) should have another level of indentation. This is -a visual indicator to show that the following lines are part of a block -of code associated with the previous line. For example: - -:: - - # this is good - if x == True: - do_something() - - # this is bad and will not work - if x == True: - do_something() - -Pass -~~~~ - -pass is a null operation — when it is executed, nothing happens. It is -useful as a placeholder when a statement is required syntactically, but -no code needs to be executed. **Most finished code will not use pass for -anything.** - -:: - - if False: - pass - -Numbers -~~~~~~~ - -You can use numbers in Python, and perform computations on them. - -:: - - # A number - 1 - - # Multiplying two numbers - 2*2 - -Strings -~~~~~~~ - -Strings are groups of words that you can use as variables, and the program can -manipulate them and pass them around. - -:: - - "This is a string" - 'This is also a string' - '''This is a string that can - be extended to multiple lines''' - """This is also - a multiline string""" - -Booleans -~~~~~~~~ - -Boolean values are those that are True or False. In python, True and False always -have the first letter capitalized. - -Variables ---------- - -Variables are used to store some information (strings, numbers, objects, etc). -They can be assigned values, and referred to later on. - -:: - - x = 1 - x = 'some value' - -Control Flow ------------- - -If -~~ - -If statements allow you to control the flow of the program and make decisions -about what the program should do next, based on information retrieved -previously. Note that the body of the if statement is indented:: - - if statement is True: - # do_something here - elif other_statement is True: - # do something lese here - else: - # otherwise do this - -Also see the `python -documentation `_. - -Operations ----------- - -Python supports various types of operations on variables and constants: - -:: - - # Addition - 1 + 2 - x + 1 - - # Multiplication - 1 * 2 - x * 2 - - # Equality operator (evaluated to True or False) - 1 == 1 - x == 1 - - # Less than - x < 2 - - # Lots more! - -Functions ---------- - -Functions are blocks of code that can be reused and are useful for grouping -code. They can return a value to the caller. The code that is contained inside -of a function is not executed until you call the function. - -Defintion -~~~~~~~~~ - -To define a function, you start with the word ``def``, followed by the name -of the function, and a set of parentheses:: - - def function_name(): - '''String that describes what the function does''' - pass - -Functions can accept input from their callers, allowing them to be reused for -many purposes. You place the names of the parameters inside the parentheses:: - - def function_name(parameter1, parameter2): - pass - -After computing a result, you can return it to the caller. You can also return -constants or variables:: - - def function_returns_computation(parameter1, parameter2): - return parameter1 + parameter2 - - def function_returns_a_variable(): - x = 1 - return x - - def function_returns_a_value(): - return True - -Calling a function -~~~~~~~~~~~~~~~~~~ - -The code that is contained inside of a function is not executed until -you call the function. You call it by specifying the name of the function, -followed by parentheses:: - - # Calling a function that takes no parameters - function_name() - -If you wish to pass data to the function, you place the variable names (or constants) -inside of the parentheses:: - - # Calling a function with two constant parameters - return_value = function_name(1, 2) - - # Calling a function with two variables - return_value = function_name(x, y) - -Classes -------- - -A collection of functions (also called methods) and variables can be put into a -logical group called a 'class'. - -Definition -~~~~~~~~~~ - -A class named ``Foo``:: - - class Foo(object): - '''String that describes the class''' - - def __init__(self): - '''Constructor -- this function gets called when an instance is created''' - - # store a variable in the class for use later - self.variable = 1 - - def method(self, parameter1, optional_parameter=None): - '''A function that belongs to the Foo class. It takes - two arguments, but you can specify only one if you desire''' - pass - -A class named ``Bar`` - -:: - - class Bar(Foo): - '''This class inherits from the Foo class, so anything in - Foo is transfered (and accessible) here''' - - def __init__(self, parameter1): - pass - -Creating an instance -~~~~~~~~~~~~~~~~~~~~ - -To actually use a class, you must create an instance of the class. Each instance -of a class is unique, and usually operations on the class instances do not -affect other instances of the same class. - -:: - - foo = Foo() - - # These are two separate instances of the Bar class, and operations on one - # do not affect the other - bar1 = Bar(1) - bar2 = Bar(1) - -Accessing variables stored in a class instance -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - x = Foo() # creates an instance of Foo - y = x.variable # get the value from the instance - x.variable = 1 # set the value in the instance - -Calling functions (methods) on a class instance -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - x = Foo() # this creates an instance of Foo - x.method() # this calls the function - - -Loops ------ - -for -~~~ - -:: - - for i in a_list_of_things: - print(i) - -while -~~~~~ - -:: - - while statement is True: - do_this_until_statement_is_not_true() - -Exceptions ----------- - -:: - - try: - do_something_that_might_cause_an_exception() - if bad_thing is True: - raise SomeException() - except ExceptionType as e: - # this code is only executed if an ExceptionType exception is raised - print("Error: " + e) - finally: - # This is always executed - clean_up() - - try: - import wpilib - except ImportError: - import fake_wpilib as wpilib - -Future topics -------------- - -- Lists, dictionaries, tuples -- Scope - -Next Steps ----------- - -Learn about the basic structure of Robot code at :ref:`anatomy`. diff --git a/guide/running.rst b/guide/running.rst deleted file mode 100644 index 0eccd45..0000000 --- a/guide/running.rst +++ /dev/null @@ -1,69 +0,0 @@ - -.. _running_robot_code: - -Running robot code -================== - -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. - -How to execute the script -------------------------- - -.. tab:: Windows - - On Windows, you will typically execute your robot code by opening up the - command prompt (cmd), changing directories to where your robot code is, - and then running this: - - .. code-block:: sh - - py -3 -m robotpy - -.. tab:: Linux/macOS - - On Linux/macOS, you will typically execute your robot code by opening up the - Terminal program, changing directories to where your robot code is, and - then running this: - - .. code-block:: sh - - python3 -m robotpy - -Commands --------- - -When you run your code without additional arguments, you'll see an error message -saying something like ``robot.py: error: the following arguments are required: -command``. RobotPy tools install various commands that you can run from your -robot code. To discover the various features that are installed, you can use the -``--help`` command: - -.. tab:: Windows - - .. code-block:: batch - - py -3 -m robotpy --help - -.. tab:: Linux/macOS - - .. code-block:: sh - - python3 -m robotpy --help - -.. note:: RobotPy supports an extension mechanism that allows advanced users the - ability to create their own custom ``robotpy`` commandline options. - For more information, see :ref:`robotpy_extension_options` - -Next steps ----------- - -There are two ways you can run the code: on the robot, and on the simulator: - -* :ref:`deploy` -* :ref:`simulator` - -.. note:: If you're just starting out with RobotPy, you'll probably find it faster - (and more instructive) to start playing with your code in the simulator - before you actually deploy it to a robot. diff --git a/guide/simulator.rst b/guide/simulator.rst deleted file mode 100644 index acbe798..0000000 --- a/guide/simulator.rst +++ /dev/null @@ -1,100 +0,0 @@ - -.. _simulator: - -Robot Simulator -=============== - -An important (but often neglected) part of developing your robot code is to -test it! Because we feel strongly about testing and simulation, the RobotPy -project provides tools to make those types of things easier through the -`pyfrc `_ project. From 2014-2019, RobotPy -provided its own simulation GUI. Starting in 2020, RobotPy uses the -WPILib simulation GUI instead. - -Running the simulator ---------------------- - -To run the GUI simulator, run your robot.py with the following arguments: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy sim - -.. tab:: Linux/macOS - - .. code-block:: sh - - python3 -m robotpy sim - -User interface --------------- - -See the :doc:`WPILib Simulation User Interface ` -documentation for more details. - -2D Field Widget and Physics ---------------------------- - -The WPILib Simulation GUI has a 2D field available, just like the original -PyFRC simulator had. This allows you to drive your robot around on a -virtual field -- in particular, it's very useful for testing the logic of -autonomous mode movements. - -.. note:: To enable the field view, go to the "NetworkTables" > "SmartDashboard" - menu, and select "Field". - -For the robot to move across the field, you must implement a physics module -(it's a lot easier than it sounds!). Helper functions are provided to -calculate robot position for common drivetrain types. - -We have a variety of examples and documentation available: - -* :ref:`PyFRC API docs ` -* :external+robotpy:doc:`wpilib.simulation` -* `RobotPy Examples Repository `_ - -.. _smartdashboard: - -Communicating via NetworkTables -------------------------------- - -The simulator launches a NetworkTables server (just as the robot does), so it -can be communicated with via standard NetworkTables tools (such as OutlineViewer, -Shuffleboard, or SmartDashboard). - -For this to work, you need to tell the client to connect to the IP address that -your simulator is listening on (this will be ``localhost`` or ``127.0.0.1``). - -pynetworktables2js -~~~~~~~~~~~~~~~~~~ - -pynetworktables2js will automatically connect to ``localhost`` if no arguments -are given. - -OutlineViewer -~~~~~~~~~~~~~ - -You can type an address in when OutlineViewer launches, then tell it to start in -client mode. - -Shuffleboard -~~~~~~~~~~~~ - -Shuffleboard can be configured to connect to localhost in the preferences. - -SmartDashboard -~~~~~~~~~~~~~~ - -Using SmartDashboard, you need to launch the jar using the following command: - -.. code-block:: sh - - $ java -jar SmartDashboard.jar ip 127.0.0.1 - - -Next Steps ----------- - -The next section discusses a very important part of writing robot code -- :ref:`unit_tests`. diff --git a/guide/guidelines.rst b/guidelines.rst similarity index 87% rename from guide/guidelines.rst rename to guidelines.rst index ba26d16..52de45b 100644 --- a/guide/guidelines.rst +++ b/guidelines.rst @@ -3,9 +3,7 @@ Best Practices ============== -This section has a selection of things that other teams have found to be good -things to keep in mind to build robot code that works consistently, and to -eliminate possible failures. +This section has a selection of Python-specific things that other teams have found to be good things to keep in mind to build robot code that works consistently, and to eliminate possible failures. .. contents:: :local: @@ -132,14 +130,3 @@ With these thoughts in mind, here's an example of what I mean:: robot's drive function is in it's own exception handler, so even if everything else in the robot dies, at least you can still drive around. - -Consider using a robot framework --------------------------------- - -If you're creating anything more than a simple robot, you may find it easier to -use a robot framework to help you organize your code and take care of some of -the boring details for you. While frameworks sometimes have a learning curve -associated with them, once you learn how they work you will find that they can -save you a lot of effort and prevent you from making certain kinds of mistakes. - -See our documentation on :ref:`frameworks` diff --git a/index.rst b/index.rst index c4e5e85..b308e0b 100644 --- a/index.rst +++ b/index.rst @@ -9,17 +9,15 @@ 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 +As of 2024 Python is an officially supported language for programming robots in FRC, and we have moved much of our installation and usage documentation over to :doc:`a section of the WPILib documentation `. -Please read our :ref:`Upgrade Notes` page for things that have -changed this season that you should be aware of. +.. note:: Please read our :ref:`Upgrade Notes` page for things that have changed this season that you should be aware of. -.. note:: RobotPy is a community project and the tools we create are not - officially supported by FIRST. Please see the - :ref:`FAQ ` for more information. +Getting Started +--------------- - 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. +* The best place to start is the :doc:`zero-to-robot documentation `. +* Also see :doc:`frc:docs/software/python/index` Projects -------- @@ -27,42 +25,34 @@ Projects The primary reason RobotPy exists is to support teams that want to write their 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 +* `mostrobotpy `_: provides the ability to use the core WPILib libraries from Python +* `pyfrc `_: provides unit testing and realtime robot simulation * `robotpy-wpilib-utilities `_: Community focused extensions for WPILib Additionally, RobotPy is home to several projects that are useful for all teams, even if they aren’t writing their robot code in python: -* `pyntcore `_: python bindings for NetworkTables that you can use to communicate with a dashboard and/or your robot. +* :ref:`pyntcore `: python bindings for NetworkTables that you can use to communicate with a dashboard and/or your robot. * `pynetworktables `_: legacy NetworkTables implementation that you can use to communcate with SmartDashboard and/or your robot. -* `pynetconsole `_: A simple netconsole implementation in python -* `robotpy-cscore `_: Python bindings for cscore, a powerful camera/streaming library -* `robotpy-apriltag `_: Python bindings for the WPILib apriltag library +* :ref:`robotpy-cscore `: Python bindings for cscore, a powerful camera/streaming library +* :ref:`robotpy-apriltag `: Python bindings for the WPILib apriltag library * `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. -We welcome contributions from all members of the FIRST community! +We are in the process of migrating much of our documentation to the :doc:`WPILib documentation site `. .. 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 - + guidelines + testing troubleshooting support faq + +.. include:: _sidebar.rst.inc .. toctree:: :caption: RobotPy Developers diff --git a/install/components.rst b/install/components.rst deleted file mode 100644 index 3b17139..0000000 --- a/install/components.rst +++ /dev/null @@ -1,91 +0,0 @@ -.. _robotpy_components: - -RobotPy Components -================== - -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 --------------------------- - -If you install just the ``robotpy`` package via pip, then all of the core -RobotPy wrappers around WPILib will be installed. However there are several -groups of optional components that you can install. -Vendor categories: - -* ``navx`` - Kauai Labs NavX MXP Robotics Navigation -* ``pathplannerlib`` - PathPlannerLib path planning 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 v2 (2020+) -* ``cscore`` - WPILib cscore library -* ``romi`` - Romi robot specific components -* ``sim`` - WPILib extra simulation support - -Install all vendors and WPILib optional components: - -* ``all`` - -Using components ----------------- - -Component categories are represented as 'extra requirements' for the RobotPy -package. Pip allows you to install extra requirements by putting the names -of the categories in brackets. - -Let's say that you wanted to install the latest version of the NavX software -along with command based programming. You would do this - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m pip install -U robotpy[navx,commands] - -.. tab:: Linux/macOS - - .. code-block:: sh - - 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 - - .. code-block:: sh - - py -3 -m pip install -U robotpy[all] - -.. tab:: Linux/macOS - - .. code-block:: sh - - 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. diff --git a/install/computer.rst b/install/computer.rst deleted file mode 100644 index baa7805..0000000 --- a/install/computer.rst +++ /dev/null @@ -1,172 +0,0 @@ - -.. _install_computer: - -Computer Installation -===================== - -.. note:: installation via pip typically requires internet access - -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 except on ARM coprocessors, you -must have a 64-bit python installed. - -* `Python for Windows `_ -* `Python for macOS `_ - -Once you have installed Python, you can use pip to install RobotPy. While it is -possible to install without pip, due to the large number of dependencies this is -not recommended nor is it supported. - -.. tab:: Windows - - .. warning:: On Windows, the `Visual Studio 2019 redistributable `_ - package is required to be installed. - - - Run the following command from cmd or Powershell to install the core RobotPy - packages: - - .. code-block:: sh - - py -3 -m pip install robotpy - - .. seealso:: This command only installs the core RobotPy packages. See additional - details for installing :ref:`optional/vendor components - ` - - To upgrade, you can run this: - - .. code-block:: sh - - py -3 -m pip install --upgrade robotpy - - 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 - - py -3 -m pip install --user robotpy - - -.. tab:: macOS - - On a macOS system that has pip installed, just run the following command from the - Terminal application (may require admin rights): - - .. code-block:: sh - - pip3 install robotpy - - .. seealso:: This command only installs the core RobotPy packages. See additional - details for installing :ref:`optional/vendor components - ` - - To upgrade, you can run this: - - .. code-block:: sh - - pip3 install --upgrade robotpy - - If you don't have administrative rights on your computer, either use - `virtualenv/virtualenvwrapper `_, or - or you can install to the user site-packages directory: - - .. code-block:: sh - - pip3 install --user robotpy - -.. tab:: Linux - - .. _install_linux: - - Since 2021, RobotPy distributes manylinux binary wheels on PyPI. However, - 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: - - .. code-block:: sh - - pip3 --version - - If you need to upgrade your version of pip, it is highly recommended to use a - `virtual environment `_. - - If you have a compatible version of pip, you can simply run: - - .. code-block:: sh - - pip3 install robotpy - - .. seealso:: This command only installs the core RobotPy packages. See additional - details for installing :ref:`optional/vendor components - ` - - To upgrade, you can run this: - - .. code-block:: sh - - pip3 install --upgrade robotpy - - The following Linux distributions are known to work, but this list is not - necessarily comprehensive: - - * Ubuntu 22.04+ - * Fedora 36+ - * Arch Linux - - If you manage to install the packages and get the following error or - something similar, your system is most likely not compatible with RobotPy:: - - OSError: /usr/lib/x86_64-linux-gnu/libstdc++.so.6: version `GLIBCXX_3.4.22' not found (required by /usr/local/lib/python3.7/dist-packages/wpiutil/lib/libwpiutil.so) - - **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 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-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/index.rst b/install/index.rst deleted file mode 100644 index 40e213e..0000000 --- a/install/index.rst +++ /dev/null @@ -1,37 +0,0 @@ - -.. _installation: - -Installation -============ - -Writing Robot code in Python: - -* If you wish to deploy code or use the Robot Simulator, see the :ref:`computer - Installation documentation `. - -* To install RobotPy on your robot, see the :ref:`RobotPy installation - documentation `. - -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 `. - -Using cscore from Python: - -* See the :ref:`robotpy-cscore installation documentation `. - -Installing extra software packages on the RoboRIO: - -* You can install third party packages such as OpenCV, NumPy, robotpy-cscore, - robotpy-ctre, and other python packages on your RoboRIO using the :ref:`RobotPy - Installer `. - -.. toctree:: - :hidden: - - components - computer - packages - robot diff --git a/install/packages.rst b/install/packages.rst deleted file mode 100644 index 03addf4..0000000 --- a/install/packages.rst +++ /dev/null @@ -1,210 +0,0 @@ - -.. _install_packages: - -RoboRIO Package Installer -========================= - -.. note:: This is not the RobotPy installation guide, see :ref:`install_robotpy` - if you're looking for that! - -Most FRC robots are not placed on networks that have access to the internet, -particularly at competition arenas. The RobotPy installer is designed for -this type of 'two-phase' operation -- with individual steps for downloading -and installing packages separately. - -The RobotPy installer supports downloading external packages from the python -package repository (pypi) via pip, and installing those packages onto the robot. -We cannot make any guarantees about the quality of external packages, so use -them at your own risk. - -.. note:: If your robot is on a network that has internet access, then you - can manually install packages via opkg or pip. However, if you use - the RobotPy installer to install packages, then you can easily - reinstall them on your robot in the case you need to reimage it. - - If you choose to install packages manually via pip, keep in mind that - when powered off, your roboRIO does not keep track of the correct - date, and as a result pip may fail with an SSL related error message. - To set the date, you can either: - - * Set the date via the web interface - * You can login to your roboRIO via SSH, and set the date via the - date command:: - - date -s "2015-01-03 00:00:00" - -Each of the commands supports various options, which you can read about by -invoking the --help command. - -Installing/Executing the installer ----------------------------------- - -.. note:: The installer is included when you install the RobotPy meta package, - so if you installed that then you likely already have it - -To install/use the installer, you must have Python 3.6+ installed. You should install -the installer via pip. - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m pip install robotpy-installer - -.. tab:: Linux/macOS - - .. code-block:: sh - - pip3 install robotpy-installer - -To upgrade the installed version of the installer, you need to add the ``-U`` -flag to pip. - -Executing the installer -~~~~~~~~~~~~~~~~~~~~~~~ - -Once you have the installer program installed, to execute the installer do: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy_installer [command..] - -.. tab:: Linux/macOS - - .. code-block:: sh - - robotpy-installer [command..] - -Python ------- - -These commands allow you to install/upgrade Python on your roboRIO. Once Python -is installed, it's likely that you won't need to upgrade it. - -download-python -~~~~~~~~~~~~~~~~ - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy_installer download-python - -.. tab:: Linux/macOS - - .. code-block:: sh - - robotpy-installer download-python - -This will update the cached Python package to the newest versions available. - -install-python -~~~~~~~~~~~~~~~ - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy_installer install-python - -.. tab:: Linux/macOS - - .. code-block:: sh - - robotpy-installer install-python - -.. note:: You must already have Python downloaded (via ``download-python``), or - this command will fail. - -Python Packages ---------------- - -If you want to use a python package hosted on Pypi in your robot code, these -commands allow you to easily download and install those packages. - -.. note:: If you need Python packages that require compilation, the RobotPy - project distributes some commonly used packages. See the - `roborio-wheels `_ - project for more details. - -download -~~~~~~~~ - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy_installer download PACKAGE [PACKAGE ..] - -.. tab:: Linux/macOS - - .. code-block:: sh - - robotpy-installer download PACKAGE [PACKAGE ..] - -Specify python package(s) to download, similar to what you would pass the -'pip install' command. This command does not install files on the robot, and -must be executed from a computer with internet access. - -You can run this command multiple times, and files will not be removed from -the download cache. - -You can also use a `requirements.txt` file to specify which packages should -be downloaded. - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy_installer download -r requirements.txt - -.. tab:: Linux/macOS - - .. code-block:: sh - - robotpy-installer download -r requirements.txt - -install -~~~~~~~ - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy_installer install PACKAGE [PACKAGE ..] - -.. tab:: Linux/macOS - - .. code-block:: sh - - robotpy-installer install PACKAGE [PACKAGE ..] - -Copies python packages over to the roboRIO, and installs them. If the -package already has been installed, it will be reinstalled. - -You can also use a `requirements.txt` file to specify which packages should -be downloaded. - - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy_installer install -r requirements.txt - -.. tab:: Linux/macOS - - .. code-block:: sh - - robotpy-installer install -r requirements.txt - -.. warning:: The 'install' command will only install packages that have been - downloaded using the 'download' command, or packages that are - on the robot's pypi cache. - -.. warning:: If your robot does not have a python3 interpeter installed, this - command will fail. Run the `install-python` command first. - - diff --git a/install/robot.rst b/install/robot.rst deleted file mode 100644 index 6514ca2..0000000 --- a/install/robot.rst +++ /dev/null @@ -1,140 +0,0 @@ - -.. _install_robotpy: - -Robot Installation -================== - -These instructions will help you get RobotPy installed on your RoboRIO, which will -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. - -Install requirements --------------------- - -.. warning:: This guide assumes that your RoboRIO has the current legal RoboRIO - image installed. If you haven't done this yet, see :doc:`the WPILib - documentation ` - for imaging instructions. To image the RoboRIO for RobotPy, you - only need to have the latest FRC Game Tools installed. - -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.7+ installed. You should install the installer via pip (requires -internet access) by installing the core RobotPy components (see the -:ref:`computer installation ` section for more details). - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m pip install robotpy - -.. tab:: Linux/macOS - - .. code-block:: sh - - pip3 install robotpy - -Install process ---------------- - -The RoboRIO robot controller is typically not connected to a network that has -internet access, so there are two stages to installing RobotPy. - -* First, you need to connect your computer to the internet and use the installer - to download the packages to your computer. -* Second, disconnect from the internet and connect to the network that the RoboRIO - is on - -The details for each stage will be discussed below. You can run the installer via -python. This is slightly different on Windows/macOS/Linux. - -Install Python on a roboRIO -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: This step only needs to be done once. - -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 - - .. code-block:: sh - - py -3 -m robotpy_installer download-python - -.. tab:: Linux/macOS - - .. code-block:: sh - - robotpy-installer download-python - -Once everything has downloaded, you can switch to your Robot's network, and -use the following commands to install. - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy_installer install-python - -.. tab:: Linux/macOS - - .. code-block:: sh - - robotpy-installer install-python - -It will ask you a few questions, and copy the right files over to your robot -and set things up for you. - -Installing RobotPy on a roboRIO -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The RobotPy installer supports downloading wheels from PyPI and the RobotPy -website and installing them on the roboRIO. The ``download`` and ``install`` -commands behave similar to the ``pip`` command, including allowing use of -a 'requirements.txt' file if desired. - -As mentioned above, installation needs to be done in two steps (download then -install). Once you are connected to the internet: - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy_installer download robotpy - -.. tab:: Linux/macOS - - .. code-block:: sh - - robotpy-installer download robotpy - -.. seealso:: This command only downloads the core RobotPy packages. See additional - details for installing :ref:`optional/vendor components - ` - -Once everything has downloaded, you can switch to your Robot's network, and -use the following commands to install. - -.. tab:: Windows - - .. code-block:: sh - - py -3 -m robotpy_installer install robotpy - -.. tab:: Linux/macOS - - .. code-block:: sh - - robotpy-installer install robotpy - -The robotpy installer uses pip to download and install packages, so you can -replace ``robotpy`` above with the name of a pure python package as published -on PyPI. - -.. note:: If you need Python packages that require compilation, the RobotPy - project distributes some commonly used packages. See the - `roborio-wheels `_ - project for more details. diff --git a/guide/testing.rst b/testing.rst similarity index 97% rename from guide/testing.rst rename to testing.rst index bcda3fe..867a44b 100644 --- a/guide/testing.rst +++ b/testing.rst @@ -138,7 +138,3 @@ be reported as covered. tool, the output is buffered until the process exits. This does not happen under pytest, however. It's not clear why this occurs. -Next Steps ----------- - -Learn more about some :ref:`best_practices` when creating robot code. diff --git a/troubleshooting.rst b/troubleshooting.rst index 1167dea..d26900a 100644 --- a/troubleshooting.rst +++ b/troubleshooting.rst @@ -9,61 +9,10 @@ Troubleshooting Robot Code ---------- -Problem: I can't run code on the robot! -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -There are lots of things that can go wrong here. It is very important to have -the latest versions of the FIRST robot software installed: - -* Robot Image -* Driver Station + Tools - -The `FIRST WPILib documentation `_ -contains information on what the current versions are, and how to go about -updating the software. - -You should also have the latest version of the RobotPy software packages: - -* Do you have the latest version of pyfrc? - -.. warning:: Make sure that the version of WPILib on your computer matches the - version installed on the robot! You can check what version you have locally - by running - - .. tab:: Windows - - .. code-block:: sh - - py -3 -m pip list - - .. tab:: Linux/macOS - - .. code-block:: sh - - pip3 list - -1. Did you run the deploy command to put the code on the robot? -2. Make sure you have the latest version of pyfrc! Older versions **won't** work. -3. Read any error messages that pyfrc might give you. They might be useful. :) - -Problem: no module named 'wpilib' -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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: no module named ... -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you're using a non-WPILib vendor library, it must be installed separately. - -* :ref:`robotpy_components` - - -If you're on your local computer, did you :ref:`install robotpy via pip `? +.. + Problem: I can't run code on the robot! + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you're on the roboRIO, did you :ref:`install RobotPy `? Problem: deploy cannot connect to the robot, or appears to hang ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -169,7 +118,7 @@ Don't know what the right hostname is? That's what the next section is for... Use static IPs when using NetworkTables ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. seealso:: :ref:`networktables_guide` +.. seealso:: :doc:`frc:docs/networking/networking-introduction/ip-configurations` Problem: I can't determine if NetworkTables has connected