Documentation for XRP

source/docs/xrp-robot/getting-to-know-xrp.rst

@@ -0,0 +1,136 @@
+Getting to know your XRP
+========================
+
+Booting up the XRP
+------------------
+
+Upon start up (when power is applied to the XRP either via battery or USB), the following will happen:
+
+1. The IMU will calibrate itself. This lasts approximately 3-5 seconds, and will be indicated by the green LED blinking rapidly. Ideally, the XRP should be placed on a flat surface prior to power up, and if necessary, users can hit the reset button to restart the firmware and IMU calibration process.
+
+2. The network will be configured, depending on the configuration settings. See the section on :doc:`the Web UI </docs/xrp-robot/web-ui>` for more information on how to configure the network settings. By default the XRP will broadcast its own WiFi Access Point.
+
+3. After this, the XRP is ready for use.
+
+Hardware, Sensors and GPIO
+--------------------------
+
+The XRP has the following built-in hardware/peripherals:
+
+- 2x geared drive motors with encoders
+- 2x additional geared motor connectors with encoder support (marked Motor3 and Motor4)
+- 2x Servo connectors (marked Servo1 and Servo2)
+- 1x Inertial Measurement Unit (IMU)
+- 1x LED (green)
+- 1x pushbutton (marked USER)
+- 1x Line following sensor (exposed as 2 Analog inputs)
+- 1x Ultrasonic PING style rangefinder (uses 2 digital IO pins, exposed as an analog input)
+
+Motors, Wheels, and Encoders
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The motors used on the XRP have a 48.75:1 gear reduction and a no-load output speed of 90 RPM at 4.5V.
+
+The wheels have a diameter of 60mm (2.3622"). They have a trackwidth of 155mm (6.1").
+
+The encoders are connected directly to the motor output shaft and have 12 Counts Per Revolution (CPR). With the provided gear ratio, this nets 585 counts per wheel revolution.
+
+The motor channels are listed in the table below.
+
+.. note:: We use "motor channels" here instead of "PWM channels" as the XRP requires the use of a special ``XRPMotor`` object in WPILib code to interact with the hardware.
+
++---------------+------------------------+
+| Channel       | XRP Hardware Component |
++===============+========================+
+| XRPMotor 0    | Left Motor             |
++---------------+------------------------+
+| XRPMotor 1    | Right Motor            |
++---------------+------------------------+
+| XRPMotor 2    | Motor 3                |
++---------------+------------------------+
+| XRPMotor 3    | Motor 4                |
++---------------+------------------------+
+
+.. note:: The right motor will spin in a backward direction when positive output is applied. Thus the corresponding motor controller needs to be inverted in robot code.
+
+The servo channels are listed in the table below.
+
+.. note:: We use "servo channels" here instead of "PWM channels" as the XRP requires the use of a special ``XRPServo`` object in WPILib code to interact with the hardware.
+
++---------------+------------------------+
+| Channel       | XRP Hardware Component |
++===============+========================+
+| XRPServo 4    | Servo 1                |
++---------------+------------------------+
+| XRPServo 5    | Servo 2                |
++---------------+------------------------+
+
+The encoder channels are listed in the table below.
+
++-------------+---------------------------------------+
+| Channel     | XRP Hardware Component                |
++=============+=======================================+
+| DIO 4       | Left Encoder Quadrature Channel A     |
++-------------+---------------------------------------+
+| DIO 5       | Left Encoder Quadrature Channel B     |
++-------------+---------------------------------------+
+| DIO 6       | Right Encoder Quadrature Channel A    |
++-------------+---------------------------------------+
+| DIO 7       | Right Encoder Quadrature Channel B    |
++-------------+---------------------------------------+
+| DIO 8       | Motor3 Encoder Quadrature Channel A   |
++-------------+---------------------------------------+
+| DIO 9       | Motor3 Encoder Quadrature Channel B   |
++-------------+---------------------------------------+
+| DIO 10      | Motor4 Encoder Quadrature Channel A   |
++-------------+---------------------------------------+
+| DIO 11      | Motor4 Encoder Quadrature Channel B   |
++-------------+---------------------------------------+
+
+.. note:: By default, the encoders count up when the XRP moves forward.
+
+Inertial Measurement Unit
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The XRP includes an STMicroelectronics LSM6DSOX Inertial Measurement Unit (IMU) which contains a 3-axis gyro and a 3-axis accelerometer.
+
+The XRP will calibrate the gyro and accelerometer upon each boot (the onboard LED will quickly flash for about 3-5 seconds at startup time).
+
+Onboard LED and Push Button
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The XRP has a push button (labeled USER) and a green LED onboard that are exposed as Digital IO (DIO) channels to robot code.
+
++-------------+---------------------------+
+| DIO Channel | XRP Hardware Component    |
++=============+===========================+
+| DIO 0       | USER Button               |
++-------------+---------------------------+
+| DIO 1       | Green LED                 |
++-------------+---------------------------+
+
+.. note:: DIO 2 and 3 are reserved for future system use.
+
+Line Following (Reflectance) Sensor
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When assembled according to the instructions, the XRP supports a line following sensor with 2 sensing elements. Each sensing element measures reflectance exposes these as AnalogInput channels to robot code. The returned values range from 0V (pure white) to 5V (pure black).
+
++---------------------+---------------------------+
+| AnalogInput Channel | XRP Hardware Component    |
++=====================+===========================+
+| AnalogInput 0       | Left Reflectance Sensor   |
++---------------------+---------------------------+
+| AnalogInput 1       | Right Reflectance Sensor  |
++---------------------+---------------------------+
+
+Ultrasonic Rangefinder
+^^^^^^^^^^^^^^^^^^^^^^
+
+When assembled according to the instructions, the XRP supports an ultrasonic, PING style, rangefinder. This is exposed as an AnalogInput channel to robot code. The returned values range from 0V (20mm) to 5V (4000mm).
+
++---------------------+---------------------------+
+| AnalogInput Channel | XRP Hardware Component    |
++=====================+===========================+
+| AnalogInput 2       | Ultrasonic Rangefinder    |
++---------------------+---------------------------+

source/docs/xrp-robot/hardware-and-imaging.rst

@@ -0,0 +1,69 @@
+XRP Hardware, Assembly and Imaging
+==================================
+
+To get started with the XRP, you will need to have the necessary hardware.
+
+1. `XRP Kit from SparkFun <https://www.sparkfun.com/products/22230>`__ - Available at educational discount
+2. `Micro-USB cable <https://www.amazon.com/dp/B0711PVX6Z>`__ - Ensure that this is a data cable
+3. `4 AA batteries <https://www.amazon.com/gp/product/B07TW9T8JW/>`__ - Rechargeable is best (don't forget the charger)
+
+Assembly
+--------
+
+.. note::
+
+   See the assembly instructions on the `XRP User Guide <https://xrpusersguide.readthedocs.io/en/latest/course/building.html>`_.
+
+   You should follow the instructions up to and including the point where the XRP arm is mounted to the servo.
+
+Imaging your XRP
+----------------
+
+The XRP uses a Raspberry Pi Pico W as its main processor. A special firmware will need to be installed so that the robot operates properly.
+
+Download
+^^^^^^^^
+
+The XRP firmware must be downloaded and written to the Pico W. Click on ``Assets`` at the bottom of the description to see the available image files:
+
+`XRP-WPILib Firmware <https://github.com/wpilibsuite/xrp-wpilib-firmware/releases>`__
+
+Imaging
+^^^^^^^
+
+To image the XRP, perform the following steps:
+
+1. Extract the contents of the firmware ZIP file. You should end up with a ``.uf2`` file.
+
+2. Plug the XRP into your computer with a Micro-USB cable. You should see a red power LED that lights up.
+
+3. While holding the ``BOOTSEL`` button (the white button on the green Pico W, near the USB connector), quickly press the reset button (circled below), and then release the ``BOOTSEL`` button.
+
+.. image:: images/hardware-and-imaging/xrp-reset-button.png
+   :alt: XRP Reset button
+
+4. The board will temporarily disconnect from your computer, and then reconnect as a USB storage device named ``RPI-RP2``.
+
+5. Drag the ``.uf2`` firmware file into the ``RPI-RP2`` drive, and it will automatically update the firmware.
+
+6. Once complete, the ``RPI-RP2`` USB storage device will disconnect. At this point, you can disconnect the XRP board from your computer and run it off battery power.
+
+First Boot
+^^^^^^^^^^
+
+Perform the following steps to get your XRP ready for use:
+
+1. Ensure that you have 4 AA batteries installed
+
+2. Turn the XRP on by sliding the power switch (circled below) on the XRP board to the on position. A red power LED will turn on.
+
+.. image:: images/hardware-and-imaging/xrp-power-switch.png
+   :alt: XRP Power switch
+
+3. Using your computer, connect to the XRP WiFi network using the SSID ``XRP-<IDENT>`` (where ``<IDENT>`` is based on the unique ID of the Pico W) with the WPA2 passphrase ``xrp-wpilib``.
+
+.. note:: If powering on the XRP in an environment with multiple other XRPs, the SSID can also be found by connecting the XRP to a computer, navigating to the USB storage device (``PICODISK``) that appears and opening the ``xrp-status.txt`` file.
+
+4. Open a web browser and connect to the web UI at ``http://192.168.42.1:5000``. If the page loads, you have established connectivity with the XRP.
+
+.. note:: More information about the Web UI and configuration can be found in the :doc:`Web UI section</docs/xrp-robot/web-ui>`.

source/docs/xrp-robot/hardware-support.rst

@@ -0,0 +1,42 @@
+XRP Hardware Support
+====================
+
+The XRP robot, having a different hardware architecture than a roboRIO, is compatible with a subset of commonly used FRC control system components.
+
+Compatible Hardware
+-------------------
+
+In general, the XRP is compatible with the following:
+
+- Hobby DC motors with built-in encoders (6-pin connector)
+- Standard RC-style PWM output devices (e.g. servos, PWM based motor controllers)
+- "Ping" style ultrasonic sensors (only when connected to the RANGE port)
+
+Incompatible Hardware
+---------------------
+
+Due to hardware limitations, the XRP is not compatible with the following:
+
+- Encoders other than those already integrated into hobby motors
+- Timing based sensors
+- CAN based devices
+
+Compatible Classes
+------------------
+
+All classes listed here are supported by the XRP. If a class is not listed here, assume that it is not supported and *will not* work.
+
+- ``Encoder``
+- ``AnalogInput``
+- ``DigitalInput``
+- ``DigitalOutput``
+- ``BuiltInAccelerometer``
+
+.. note:: The PWM motor controller classes (e.g. ``Spark``) and ``Servo`` are not supported. The XRP requires use of specialized ``XRPMotor`` and ``XRPServo`` classes.
+
+The following classes are provided by the XRP Vendordep (built-in to WPILib).
+
+- ``XRPGyro``
+- ``XRPMotor``
+- ``XRPServo``
+- ``XRPOnBoardIO``

source/docs/xrp-robot/index.rst

@@ -0,0 +1,18 @@
+Getting Started with XRP
+========================
+
+The XRP is a small and inexpensive robot designed for learning about programming FRC robots. All the same tools used for programming full-sized FRC robots can be used to program the XRP. The XRP comes with two drive motors with integrated wheel encoders. It also includes an IMU sensor that can be used for measuring headings and accelerations. Using it is as simple as writing a robot program, and running it on your computer. It will command the XRP to follow the steps in the program.
+
+The XRP provides a similar use case as the :doc:`Romi </docs/romi-robot/index>` with similar functionality, albeit using a lower power processor and is overall lower in cost.
+
+.. image:: images/xrp.png
+   :alt: XRP Robot
+
+.. toctree::
+   :maxdepth: 1
+
+   hardware-and-imaging
+   getting-to-know-xrp
+   hardware-support
+   web-ui
+   programming-xrp

source/docs/xrp-robot/programming-xrp.rst

@@ -0,0 +1,54 @@
+Programming the XRP
+===================
+
+Writing a program for the XRP is very similar to writing a program for a regular FRC robot. In fact, all the same tools (Visual Studio Code, Driver Station, SmartDashboard, etc) can be used with the XRP.
+
+Creating an XRP Program
+-----------------------
+
+Creating a new program for an XRP is like creating a normal FRC program, similar to the :doc:`Zero To Robot </docs/zero-to-robot/step-4/index>` programming steps.
+
+WPILib comes with two templates for XRP projects, including one based on TimedRobot, and a Command-Based project template. Additionally, an example project is provided which showcases some of the built-in functionality of the XRP, and shows how to use the vendordep exposed XRP classes. This article will walk through creating a project from this example.
+
+.. note:: In order to program the XRP using C++, a compatible C++ desktop compiler must be installed. See :ref:`Robot Simulation - Additional C++ Dependency <docs/software/wpilib-tools/robot-simulation/introduction:Additional C++ Dependency>`.
+
+Creating a New WPILib XRP Project
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Bring up the Visual Studio Code command palette with :kbd:`Ctrl+Shift+P`, and type "New project" into the prompt. Select the "Create a new project" command:
+
+.. image:: images/programming-xrp/xrp-vscode-new-project.png
+
+This will bring up the "New Project Creator Window". From here, click on "Select a project type (Example or Template)", and pick "Example" from the prompt that appears:
+
+.. image:: images/programming-xrp/xrp-vscode-select-example.png
+
+Next, a list of examples will appear. Scroll through the list to find the "XRP Reference" example:
+
+.. image:: images/programming-xrp/xrp-vscode-reference-example.png
+
+Fill out the rest of the fields in the "New Project Creator" and click "Generate Project" to create the new robot project.
+
+Running an XRP Program
+^^^^^^^^^^^^^^^^^^^^^^
+
+Once the robot project is generated, it is essentially ready to run. The project has a pre-built ``Drivetrain`` class and associated default command that lets you drive the XRP around using a joystick.
+
+One aspect where an XRP project differs from a regular FRC robot project is that the code is not deployed directly to the XRP. Instead, an XRP project runs on your development computer and leverages the WPILib simulation framework to communicate with the XRP.
+
+To run an XRP program, first, ensure that your XRP is powered on. Next, connect to ``XRP-<IDENT>`` WiFi network broadcast by the XRP. If you changed the XRP network settings (for example, to connect it to your own network), you may change the IP address that your program uses to connect to the XRP. To do this, open the ``build.gradle`` file and update the ``wpi.sim.envVar`` line to the appropriate IP address.
+
+.. rli:: https://raw.githubusercontent.com/wpilibsuite/vscode-wpilib/main/vscode-wpilib/resources/gradle/javaxrp/build.gradle
+   :language: groovy
+   :lines: 44-47
+   :linenos:
+   :lineno-start: 44
+   :emphasize-lines: 2
+
+Now to start your XRP robot code, open the WPILib Command Palette (type :kbd:`Ctrl+Shift+P`) and select "Simulate Robot Code", or press :kbd:`F5`.
+
+.. image:: images/programming-xrp/xrp-vscode-simulate.png
+
+If all goes well, you should see the simulation GUI pop up and see the gyro and accelerometer values updating.
+
+Your XRP code is now running!

source/docs/xrp-robot/web-ui.rst

@@ -0,0 +1,28 @@
+The XRP Web UI
+==============
+
+The XRP provides a simple Web UI for configuration. It is accessible at ``http://<IP Address of XRP>:5000``. By default, this is ``http://192.168.42.1:5000``.
+
+The XRP configuration is a simple JSON object that allows a user to configure the network settings of the XRP.
+
+.. image:: images/web-ui/xrp-webui-json.png
+   :alt: XRP Web UI JSON configuration
+
+Switching Network Modes
+-----------------------
+
+Box 3 in the image above shows the field that needs to be changed in order to switch the XRP from Access Point mode to/from Station mode. In Access Point (``AP``) mode, the XRP will broadcast a WiFi network. In Station (``STA``) mode, the XRP will connect to an existing WiFi network. Update the ``mode`` field with the appropriate value (``AP``/``STA``).
+
+Setting up a default Access Point (AP)
+--------------------------------------
+
+By default, the XRP will operate in Access Point mode, where it broadcasts a WiFi network. Box 1 in the image above shows which fields control the settings for the AP SSID and passphrase.
+
+If the operating mode is set to ``AP``, the access point information will be used to create the WiFi Access Point. If the mode is set to ``STA`` (station) and the XRP is unable to connect to any of the listed WiFi networks, then it will fall back to AP mode, again, using the information specified in box 1.
+
+Connecting to an existing WiFi network
+--------------------------------------
+
+Box 2 in the image above shows an example of listing a WiFi network that you want the XRP to connect to. the ``networkList`` array can be populated with as many preferred networks as you would like (following the same format as Box 2). When set to ``STA`` mode, the XRP will attempt to connect to each listed network in order. If none of the networks are available, the XRP will fallback into AP mode.
+
+.. note:: If you are unsure about what mode the XRP is operating in, or which WiFi network it is connected to, you can connect the XRP to a computer via a USB cable. A USB storage device named ``PICODISK`` will appear, and the ``xrp-status.txt`` file within it will list the appropriate network information.

source/index.rst

@@ -176,11 +176,11 @@ Community translations can be found in a variety of languages in the bottom-left
    .. grid-item-card::
       :class-header: sd-bg-info sd-text-white
 
-      **Romi Robot**
+      **Romi and XRP Robots**
 
       ^^^
 
-      The Romi Robot is a low-cost Raspberry Pi based platform for practicing WPILib programming.
+      The Romi and XRP robots are low-cost platforms for practicing WPILib programming.
 
       +++
 
@@ -191,7 +191,16 @@ Community translations can be found in a variety of languages in the bottom-left
          :expand:
          :outline:
 
-         View articles
+         View Romi articles
+
+      .. button-ref:: docs/xrp-robot/index
+         :color: primary
+         :shadow:
+         :align: center
+         :expand:
+         :outline:
+
+         View XRP articles
 
    .. grid-item-card::
       :class-header: sd-bg-info sd-text-white
@@ -389,10 +398,11 @@ Community translations can be found in a variety of languages in the bottom-left
 
 .. toctree::
    :maxdepth: 1
-   :caption: Romi Robot
+   :caption: Romi and XRP Support
    :hidden:
 
    docs/romi-robot/index
+   docs/xrp-robot/index
 
 .. toctree::
    :maxdepth: 1