new doc split

LimelightVision · Jun 4, 2023 · 679cc1d · 679cc1d
1 parent ea97328
commit 679cc1d
Show file tree

Hide file tree

Showing 8 changed files with 319 additions and 4 deletions.
diff --git a/docs/getting_started_imaging.rst b/docs/getting_started_imaging.rst
@@ -0,0 +1,54 @@
+Imaging
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Follow this guide to update your Limelight Smart Camera to the latest version of LimelightOS.
+
+
+.. _Downloads: https://limelightvision.io/pages/downloads
+.. tabs::
+
+	.. tab:: Limelight 3
+
+		* Power-off your limelight.
+		* Download the latest drivers, image and Balena Flash tool from from the Downloads_ Page.
+		* Run a USB-USB-C cable from your laptop to your limelight. Your limelight wiill power on automatically
+		* Run "Balena Etcher" as an administrator.
+		* It may take up to 20 seconds for your machine to recognize the camera.
+		* Select the latest .zip image in your downloads folder
+		* Select a "Compute Module" device in the "Drives" menu
+		* Click "Flash"
+		* Once flashing is complete, remove the usb cable from your limelight.
+
+	.. tab:: Limelight 2
+
+		* Power off your Limelight.
+		* Download the latest drivers, image and Balena Flash tool from from the Downloads_ Page.
+		* Run a USB-MicroUSB cable from your laptop to your limelight. Your limelight will power on automatically.
+		* Run "Balena Etcher" as an administrator.
+		* It may take up to 20 seconds for your machine to recognize the camera.
+		* Select the latest .zip image in your downloads folder
+		* Select a "Compute Module" device in the "Drives" menu
+		* Click "Flash"
+		* Once flashing is complete, remove the usb cable from your limelight.
+
+	.. tab:: Limelight 1
+
+		.. image:: img/esd-susceptibility-symbol.gif
+			:align: center
+			:width: 64
+			:height: 64
+
+		.. warning:: Some versions of Limelight 1 are electrostatically sensitive around the micro-usb port.  To prevent damaging the port, ground yourself to something metal before you connect to the micro usb port.  This will ensure your personal static charge has been discharged.
+
+		* Power off your Limelight.
+		* Download the latest drivers, image and Balena Flash tool from from the Downloads_ Page.
+		* Run a USB-MicroUSB cable from your laptop to your limelight.
+		* Turn-on to your limelight.
+		* Run "Balena Etcher" as an administrator.
+		* It may take up to 20 seconds for your machine to recognize the camera.
+		* Select the latest .zip image in your downloads folder
+		* Select a "Compute Module" device in the "Drives" menu
+		* Click "Flash"
+		* Once flashing is complete, remove power from your limelight
+
+.. warning:: Only connect the microUSB cable while imaging. Limelight enters a special flash mode while the microUSB cable is connected. You will not be able to access the web interface while Limelight is in flash mode.
diff --git a/docs/getting_started_mounting.rst b/docs/getting_started_mounting.rst
@@ -0,0 +1,33 @@
+Mounting
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. tabs::
+
+	.. tab:: Limelight 3
+
+		Use four 1 1/2" 10-32 screws and nylock nuts to mount your Limelight.
+
+		.. image:: img/LL3DrawingSmall.png
+
+		.. note:: Q. What is the purpose of the status LEDs? 
+
+			A. The green LED will blink quickly when a target has been acquired. 
+			The yellow LED will blink if the camera is set to use a dynamic IP address, and will stay solid if the camera is using a static IP address.
+
+	.. tab:: Limelight 2
+
+		Use four 1 1/2" 10-32 screws and nylock nuts to mount your Limelight.
+
+		.. image:: img/LL2DrawingSmall.png
+
+		.. note:: Q. What is the purpose of the status LEDs? 
+
+			A. The green LED will blink quickly when a target has been acquired. 
+			The yellow LED will blink if the camera is set to use a dynamic IP address, and will stay solid if the camera is using a static IP address.
+
+	.. tab:: Limelight 1
+
+		Use four 1 1/4" 10-32 screws and nylock nuts to mount your Limelight.
+
+		.. image:: img/LL1DrawingSmall.png
+
diff --git a/docs/getting_started_networking.rst b/docs/getting_started_networking.rst
@@ -0,0 +1,70 @@
+Networking Setup
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+We highly recommend following the static IP instructions for reliability during events.
+
+Follow these steps before starting:
+
+* Go to add/remove programs in windows, and search for "bonjour"
+* How many items do you see?
+	* If there are two (2) items with "bonjour" in their names, uninstall "bonjour print services"
+	* If there are no (0) items with "bonjour" in their names, install bonjour from our Downloads_ page.
+* Reboot your robot and computer.
+* Download the  `Limelight Finder Tool <https://limelightvision.io/pages/downloads/>`_
+* Follow the steps listed below.
+
+.. tabs::
+
+	.. tab:: Static IP Address (Recommended)
+
+		* Follow the bonjour-related instructions above.
+		* Power-up your robot, and connect your laptop to your robot's network.
+		* After your Limelight flashes its LED array, open the Limelight Finder Tool and search for your Limelight or navigate to http://limelight.local:5801. This is the configuration panel.
+		* Navigate to the "Settings" tab on the left side of the interface.
+		* Enter your team number and press the "Update Team Number" button.
+		* Change your "IP Assignment" to "Static".
+		* Set your Limelight's IP address to "10.TE.AM.11".
+		* NOTE: Teams with zeros need to pay special attention:
+		* Team 916 uses 10.9.16.xx,
+		* Team 9106 uses 10.91.6.xx
+		* Team 9016 uses 10.90.16.xx
+		* Set the Netmask to "255.255.255.0".
+		* Set the Gateway to "10.TE.AM.1".
+		* Click the "Update" button.
+		* Give your roboRIO the following static IP address: "10.TE.AM.2"
+		* Power-cycle your robot.
+		* You will now be access your config panel at http://10.TE.AM.11:5801, and your camera stream at http://10.TE.AM.11:5800
+
+	.. tab:: Dynamic IP Address (Not recommended)
+
+		* Follow the bonjour-related instructions above.
+		* Power-up your robot, and connect your laptop to your robot's network.
+		* After your Limelight flashes its LED array, open the Limelight Finder Tool and search for your Limelight or navigate to http://limelight.local:5801. This is the configuration panel.
+		* Navigate to the "Settings" tab on the left side of the interface.
+		* Enter your team number and press the "Update Team Number" button.
+		* Change your "IP Assignment" to "Automatic".
+		* Click the "Update" button.
+		* Power-cycle your robot.
+		* You can continue be access your config panel at http://limelight.local:5801, and your camera stream at http://limelight.local:5800
+
+.. This is a comment. Mutli-line notes, warnings, admonitions in general need indented lines after the first line
+.. note:: Q. Why do we recommend a static IP? 
+
+	A. First, it shaves multiple seconds off Limelight's boot time. Second, teams have historically had issues with DHCP assignment and mDNS responders on actual FRC fields and with event radio firmware.  
+
+	We recommend setting static IP addresses on your robo-rio and driverstation as well.  The networking settings to use 
+	on all of these devices can be found near the bottom half of this web page:
+	https://docs.wpilib.org/en/stable/docs/networking/networking-introduction/ip-configurations.html
+
+
+.. note:: Q. How do I reset the IP address? 
+
+	A. After your Limelight has booted, hold the config button on the front face of the camera until the LEDs start blinking. Power-cycle your robot, and your Limelight will have an automatically-assigned IP address.
+
+	.. image:: img/limelight_reset.png
+			:align: center
+			:height: 180
+
+
+* If the above steps do not fix the problem, install Angry IP scanner and find the address for your limelight.
+* Go to <limelightaddress>:5801, and give your limelight a .11 static IP.
+* From this point onward, you can rely on the static IP to access the page.
diff --git a/docs/getting_started_programming.rst b/docs/getting_started_programming.rst
@@ -0,0 +1,121 @@
+Basic Programming
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+For now, we just need to get data from the camera to your robot. Limelight posts targeting data to Network Tables at 100hz. The default update rate for NetworkTables is 10hz, but Limelight automatically overwrites it to allow for more frequent data transfer.
+
+To get started, we recommend reading four values from the "limelight" Network Table as frequently as possible. Our code samples will show you exactly how to do this. The offsets to your target (in degrees) are sent as "tx" and "ty". These can be used to turn your robot, turn a turret, etc. The target's area, sent as "ta", may be used a rough indicator of distance to your target. Area is a value between 0 and 100, where 0 means that your target's hull area is 0% of the total image area, and 100 means that your target's hull fills the entire image. The rotation or "skew" of your target is returned as "ts". If all values are equal to zero, no targets exist.
+
+In addition, you may control certain features by setting values in NetworkTables. See the complete NT API here: :doc:`networktables_api`
+
+Read the following from the "limelight" table
+
+=========== =====================================================================================
+tv		Whether the limelight has any valid targets (0 or 1)
+----------- -------------------------------------------------------------------------------------
+tx	 	Horizontal Offset From Crosshair To Target (-27 degrees to 27 degrees)
+----------- -------------------------------------------------------------------------------------
+ty 		Vertical Offset From Crosshair To Target (-20.5 degrees to 20.5 degrees)
+----------- -------------------------------------------------------------------------------------
+ta 		Target Area (0% of image to 100% of image)
+=========== =====================================================================================
+
+-------------------------------------------------
+
+Write the following to the "limelight" table
+
+=========== =====================================================================================
+ledMode		Sets limelight's LED state
+----------- -------------------------------------------------------------------------------------
+0	 	use the LED Mode set in the current pipeline
+----------- -------------------------------------------------------------------------------------
+1 		force off
+----------- -------------------------------------------------------------------------------------
+2 		force blink
+----------- -------------------------------------------------------------------------------------
+3 		force on
+=========== =====================================================================================
+
+=========== =====================================================================================
+camMode		Sets limelight's operation mode
+----------- -------------------------------------------------------------------------------------
+0	 	Vision processor
+----------- -------------------------------------------------------------------------------------
+1 		Driver Camera (Increases exposure, disables vision processing)
+=========== =====================================================================================
+
+
+=========== =====================================================================================
+pipeline	Sets limelight's current pipeline
+----------- -------------------------------------------------------------------------------------
+0 .. 9		Select pipeline 0..9
+=========== =====================================================================================
+
+
+.. tabs::
+
+	.. tab:: Java
+
+		Don't forget to add these imports:
+
+		.. code-block:: java
+
+			import edu.wpi.first.wpilibj.smartdashboard.SmartDashboard;
+			import edu.wpi.first.networktables.NetworkTable;
+			import edu.wpi.first.networktables.NetworkTableEntry;
+			import edu.wpi.first.networktables.NetworkTableInstance;
+
+
+		.. code-block:: java
+
+			NetworkTable table = NetworkTableInstance.getDefault().getTable("limelight");
+			NetworkTableEntry tx = table.getEntry("tx");
+			NetworkTableEntry ty = table.getEntry("ty");
+			NetworkTableEntry ta = table.getEntry("ta");
+			
+			//read values periodically
+			double x = tx.getDouble(0.0);
+			double y = ty.getDouble(0.0);
+			double area = ta.getDouble(0.0);
+
+			//post to smart dashboard periodically
+			SmartDashboard.putNumber("LimelightX", x);
+			SmartDashboard.putNumber("LimelightY", y);
+			SmartDashboard.putNumber("LimelightArea", area);
+
+		
+	.. tab:: LabView
+
+		.. image:: img/Labview_10.png
+
+	.. tab:: C++
+
+		Don't forget to add these #include directives:
+
+		.. code-block:: c++
+
+			#include "frc/smartdashboard/Smartdashboard.h"
+			#include "networktables/NetworkTable.h"
+			#include "networktables/NetworkTableInstance.h"
+			#include "networktables/NetworkTableEntry.h"
+			#include "networktables/NetworkTableValue.h"
+			#include "wpi/span.h"
+
+		.. code-block:: c++
+
+			std::shared_ptr<nt::NetworkTable> table = nt::NetworkTableInstance::GetDefault().GetTable("limelight");  
+			double targetOffsetAngle_Horizontal = table->GetNumber("tx",0.0);
+			double targetOffsetAngle_Vertical = table->GetNumber("ty",0.0);
+			double targetArea = table->GetNumber("ta",0.0);
+			double targetSkew = table->GetNumber("ts",0.0); 
+
+
+	.. tab:: Python
+
+		.. code-block:: python
+
+		    from networktables import NetworkTables
+		    
+		    table = NetworkTables.getTable("limelight")
+		    tx = table.getNumber('tx',None)
+		    ty = table.getNumber('ty',None)
+		    ta = table.getNumber('ta',None)
+		    ts = table.getNumber('ts',None) 
diff --git a/docs/getting_started_wiring.rst b/docs/getting_started_wiring.rst
@@ -0,0 +1,33 @@
+
+Wiring
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Limelight takes a 12V input, but is built to function down to 4.5V. Its LEDs have a constant brightness down to 7V.
+
+.. warning:: Do not use the REV radio power module to power your Limelight
+
+.. image:: img/wiring.jpg
+		:align: center
+		:width: 100%
+Credit - Christian Femia
+
+
+.. tabs::
+
+	.. tab:: Standard Wiring
+
+		* Do not run wires to your VRM.
+		* Run two wires from your limelight to a slot on your PDP (NOT your VRM).
+		* Add any breaker (5A, 10A, 20A, etc.) to the same slot on your PDP.
+		* Run an ethernet cable from your Limelight to your robot radio.
+
+	.. tab:: Power-over-Ethernet (PoE) Wiring
+
+		PoE allows you to add both power and network connectivity to your Limelight via an Ethernet cable.
+
+		.. warning:: This is not standard  IEEE 802.3 (44V-48V) PoE - this is why you must use a passive injector with 12V.
+
+		* (LIMELIGHT 1 ONLY) Ensure that your Limelight's power jumper is set to the "E" position.
+		* Connect a passive `Passive PoE Injector <http://www.revrobotics.com/rev-11-1210/>`_ to your PDP (NOT your VRM).
+		* Add any breaker (5A, 10A, 20A, etc.) to the same slot on your PDP.
+		* Run an ethernet cable from your Limelight to your passive POE injector.
diff --git a/docs/index.rst b/docs/index.rst
@@ -14,7 +14,11 @@ Limelight is an easy-to-use smart camera for FRC.
    :maxdepth: 2
    :caption: Getting Started
 
-   getting_started
+   getting_started_mounting
+   getting_started_wiring
+   getting_started_imaging
+   getting_started_networking
+   getting_started_programming
    crosshair_calibration
    status_lights
    using_multiple_pipelines

diff --git a/docs/neural_network_pipelines.rst b/docs/neural_network_pipelines.rst
@@ -53,7 +53,7 @@ Change the crop window to easily ignore objects outside of the desired detection
 
 
 Nerual Classifier Pipeline
-~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ----------
 

diff --git a/docs/vision_pipeline_tuning.rst b/docs/vision_pipeline_tuning.rst
@@ -77,7 +77,7 @@ Increasing the black level offset can significantly darken your camera stream. T
 	:width: 100%
 
 Red Balance, Blue Balance
----------------------
+------------------------------------------
 Controls the intensity of Red and Blue color components in your image. These collecively control your Limelight's white balance. We recommend leaving these at their default values of
 
 
@@ -311,7 +311,7 @@ Force Convex
 Use this option to select only the "outermost" corners of a target for SolvePnP.
 
 Contour Simplification
--------------------
+--------------------------------------
 Use this option to remove small, noisy edges from the target.
 
 Acceptable Error