diff --git a/docs_versioned_docs/version-ros2humble/components/networking/_ros2_networking_overview.mdx b/docs_versioned_docs/version-ros2humble/components/networking/_ros2_networking_overview.mdx index 8a542586..b020a508 100644 --- a/docs_versioned_docs/version-ros2humble/components/networking/_ros2_networking_overview.mdx +++ b/docs_versioned_docs/version-ros2humble/components/networking/_ros2_networking_overview.mdx @@ -1,14 +1,12 @@ -ROS 2 networking uses an abstracted middleware referred to as the "RMW Implementation". The Clearpath robot packages support -eProsima Fast DDS as the middleware implementation. This middleware has two supported options for ROS 2 node discovery, Simple -Discovery and Discovery Server. Each of these discovery mechanisms has their own use case: +The Clearpath robot packages currently support eProsima Fast DDS as the ROS Middleware (RMW) Implementation. This middleware has two supported options for ROS 2 node discovery, Simple Discovery and Discovery Server. Each of these discovery mechanisms has their own use case: **Simple Discovery** - Default, does not require manual setup - Generally operates on the basis that any ROS 2 devices on the network should be discoverable and connect automatically - Requires multicasting on the network (may be restricted on school or corporate networks) -- Good for simple systems (small number of robots on a dedicated local network) +- Good for simple systems (small number of nodes on a dedicated local network) **Discovery Server** -- Requires manual configuration in the robot.yaml -- Generally operates on the basis that ROS 2 networks should be controlled and can only discover other devices as directed +- Requires manual configuration in the `robot.yaml` +- Generally operates on the basis that ROS 2 networks should be controlled and should only discover other nodes as needed - Does not require multicasting (more likely to work on school or corporate networks) \ No newline at end of file diff --git a/docs_versioned_docs/version-ros2humble/components/networking/_standard_clearpath_bridge_setup.mdx b/docs_versioned_docs/version-ros2humble/components/networking/_standard_clearpath_bridge_setup.mdx index a760e3bf..24e8bb9c 100644 --- a/docs_versioned_docs/version-ros2humble/components/networking/_standard_clearpath_bridge_setup.mdx +++ b/docs_versioned_docs/version-ros2humble/components/networking/_standard_clearpath_bridge_setup.mdx @@ -1,8 +1,8 @@ The default networking configuration for a robot's computer is to bridge all Ethernet interfaces and assign the computer -the IP address `192.168.131.1`. See [Network IP Addresses](../../ros/networking/network_ip_addresses.mdx) for a detailed list of IP ranges. +the IP address `192.168.131.1`. See [Standard IP Addresses](../../ros/networking/standard_ip_addresses.mdx) for a detailed list of IP ranges. To configure the default bridge: -1. Run `sudo clearpath-computer-setup` +1. Run `sudo clearpath-computer-setup` 2. Navigate to **Netplan Setup** -> **Pre-set Configurations**. 3. Select **Standard Clearpath Bridge** and generate the configuration by following the instructions. 4. Return to the **Netplan Setup** menu and select **Apply Configuration Changes**. diff --git a/docs_versioned_docs/version-ros2humble/robots/accessories/add-ons/base_station.mdx b/docs_versioned_docs/version-ros2humble/robots/accessories/add-ons/base_station.mdx index 704525ce..0ec2e6f9 100644 --- a/docs_versioned_docs/version-ros2humble/robots/accessories/add-ons/base_station.mdx +++ b/docs_versioned_docs/version-ros2humble/robots/accessories/add-ons/base_station.mdx @@ -37,6 +37,6 @@ Clearpath uses this RTK correction in its OutdoorNav autonomy software, but we d :::note -Refer to the [Network IP Addresses page](../../../ros/networking/network_ip_addresses.mdx) for the commonly used device IP addresses. +Refer to the [Standard IP Addresses page](../../../ros/networking/standard_ip_addresses.mdx) for the commonly used device IP addresses. ::: diff --git a/docs_versioned_docs/version-ros2humble/robots/indoor_robots/ridgeback/user_manual_ridgeback.mdx b/docs_versioned_docs/version-ros2humble/robots/indoor_robots/ridgeback/user_manual_ridgeback.mdx index d730c998..f16d32df 100644 --- a/docs_versioned_docs/version-ros2humble/robots/indoor_robots/ridgeback/user_manual_ridgeback.mdx +++ b/docs_versioned_docs/version-ros2humble/robots/indoor_robots/ridgeback/user_manual_ridgeback.mdx @@ -109,7 +109,7 @@ this cannot be changed since the MCU is statically set to 192.168.131.2 and expe | 192.168.131.20 | Front-facing LIDAR | | 192.168.131.21 | Rear-facing LIDAR (if present) | -See [Network IP Addresses](../../../ros/networking/network_ip_addresses.mdx) for a full list of common IP addresses. +See [Standard IP Addresses](../../../ros/networking/standard_ip_addresses.mdx) for a full list of common IP addresses. #### Payload Integration Plate diff --git a/docs_versioned_docs/version-ros2humble/robots/outdoor_robots/warthog/tutorials_warthog.mdx b/docs_versioned_docs/version-ros2humble/robots/outdoor_robots/warthog/tutorials_warthog.mdx index 962d9dd6..adf4e941 100644 --- a/docs_versioned_docs/version-ros2humble/robots/outdoor_robots/warthog/tutorials_warthog.mdx +++ b/docs_versioned_docs/version-ros2humble/robots/outdoor_robots/warthog/tutorials_warthog.mdx @@ -16,11 +16,9 @@ import Support from "/components/support.mdx"; Clearpath Robotics Warthog is a rugged, all-terrain unmanned ground vehicle. -The Warthog is currently only supported in [ROS 1](/docs_versioned_docs/version-ros1noetic/robots/outdoor_robots/warthog/tutorials_warthog.mdx). - For more information or to receive a quote, please [visit us online](http://clearpathrobotics.com/warthog). - + --- diff --git a/docs_versioned_docs/version-ros2humble/ros/config/camera_compression.mdx b/docs_versioned_docs/version-ros2humble/ros/config/camera_compression.mdx index 136ed810..715ac083 100644 --- a/docs_versioned_docs/version-ros2humble/ros/config/camera_compression.mdx +++ b/docs_versioned_docs/version-ros2humble/ros/config/camera_compression.mdx @@ -6,7 +6,7 @@ toc_min_heading_level: 2 toc_max_heading_level: 4 --- -Using the [`image_transport`](https://github.com/ros-perception/image_common), [`image_transport_plugins`](https://github.com/ros-perception/image_transport_plugins) and [`ffmpeg_image_transport`](https://github.com/ros-misc-utilities/ffmpeg_image_transport) packages, it is possible to compress and stream images/video using ROS messages. This is important in order to enable the transmission of large images or video streams over wireless networks with limited bandwidth. For a walkthrough of a case study see [Video over WiFi](../tutorials/video_over_wifi.mdx). The supported compression methods are outlined below: +Using the [`image_transport`](https://github.com/ros-perception/image_common), [`image_transport_plugins`](https://github.com/ros-perception/image_transport_plugins) and [`ffmpeg_image_transport`](https://github.com/ros-misc-utilities/ffmpeg_image_transport) packages, it is possible to compress and stream images/video using ROS messages. This is important in order to enable the transmission of large images or video streams over wireless networks with limited bandwidth. For a walkthrough of a case study see [Video over Wi-Fi](../tutorials/video_over_wifi.mdx). The supported compression methods are outlined below: | Image Transport Name | Topic Name | Compression Method | Purpose | Comments | | :------------------- | :---------------- | :--------------------- |:------------------ |:--------- | diff --git a/docs_versioned_docs/version-ros2humble/ros/config/yaml/sensors/cameras.mdx b/docs_versioned_docs/version-ros2humble/ros/config/yaml/sensors/cameras.mdx index 223137f4..0fbdc371 100644 --- a/docs_versioned_docs/version-ros2humble/ros/config/yaml/sensors/cameras.mdx +++ b/docs_versioned_docs/version-ros2humble/ros/config/yaml/sensors/cameras.mdx @@ -5,6 +5,7 @@ sidebar_position: 2 toc_min_heading_level: 2 toc_max_heading_level: 5 --- +import AxisCamera from "/docs_versioned_docs/version-ros2humble/components/yaml/sensors/axis_camera.mdx"; import FlirBlackfly from "/docs_versioned_docs/version-ros2humble/components/yaml/sensors/flir_blackfly.mdx"; import IntelRealsense from "/docs_versioned_docs/version-ros2humble/components/yaml/sensors/intel_realsense.mdx"; import StereolabsZed from "/docs_versioned_docs/version-ros2humble/components/yaml/sensors/stereolabs_zed.mdx"; @@ -19,6 +20,9 @@ For further details on how to work with large camera data, see [Camera Data Comp ## Supported Cameras +### Axis Camera + + ### Intel Realsense diff --git a/docs_versioned_docs/version-ros2humble/ros/config/yaml/system.mdx b/docs_versioned_docs/version-ros2humble/ros/config/yaml/system.mdx index 0b2efc29..24f233af 100644 --- a/docs_versioned_docs/version-ros2humble/ros/config/yaml/system.mdx +++ b/docs_versioned_docs/version-ros2humble/ros/config/yaml/system.mdx @@ -16,7 +16,7 @@ services must be reinstalled as directed in the [software installation instructi The **hosts** section serves as a way to match hostnames to IP addresses. By default, Clearpath robots use the serial number as the hostname and have a default IP of `192.168.131.1`. This section must define ip addresses for all hostnames that appear in -the remainder of the `robot.yaml` file. +the remainder of the `robot.yaml` file. For example: @@ -55,7 +55,7 @@ ros2: ### Middleware The **middleware** section defines the which RMW Implementation to use and any related settings. To choose -which implementation and discovery method is right for your project see [networking](../../networking/ros2-networking.mdx). +which implementation and discovery method is right for your project see [ROS 2 Discovery Configuration](../../networking/ros2_discovery_config.mdx). | Key | Value / Datatype | Description | |:---:| :--------------: | ----------- | diff --git a/docs_versioned_docs/version-ros2humble/ros/installation/offboard_pc.mdx b/docs_versioned_docs/version-ros2humble/ros/installation/offboard_pc.mdx index c776422d..ab9e04f3 100644 --- a/docs_versioned_docs/version-ros2humble/ros/installation/offboard_pc.mdx +++ b/docs_versioned_docs/version-ros2humble/ros/installation/offboard_pc.mdx @@ -74,4 +74,4 @@ Add the following line to your `~/.bashrc` file to automatically source the gene source ~/clearpath/setup.bash ``` -4. If you are using Fast DDS Discovery Server, follow the instructions on the [ROS 2 networking page](../networking/ros2-networking.mdx#offboard-pc). \ No newline at end of file +4. If you are using Fast DDS Discovery Server, follow the instructions on [ROS 2 Discovery Configuration](../networking/ros2_discovery_config.mdx#offboard-pc). \ No newline at end of file diff --git a/docs_versioned_docs/version-ros2humble/ros/networking/img/radiation-pattern-1.png b/docs_versioned_docs/version-ros2humble/ros/networking/img/radiation-pattern-1.png new file mode 100644 index 00000000..f6a91b3d Binary files /dev/null and b/docs_versioned_docs/version-ros2humble/ros/networking/img/radiation-pattern-1.png differ diff --git a/docs_versioned_docs/version-ros2humble/ros/networking/img/radiation-pattern-2.png b/docs_versioned_docs/version-ros2humble/ros/networking/img/radiation-pattern-2.png new file mode 100644 index 00000000..a225f79c Binary files /dev/null and b/docs_versioned_docs/version-ros2humble/ros/networking/img/radiation-pattern-2.png differ diff --git a/docs_versioned_docs/version-ros2humble/ros/networking/img/wireshark-io-graph.png b/docs_versioned_docs/version-ros2humble/ros/networking/img/wireshark-io-graph.png new file mode 100644 index 00000000..366f660b Binary files /dev/null and b/docs_versioned_docs/version-ros2humble/ros/networking/img/wireshark-io-graph.png differ diff --git a/docs_versioned_docs/version-ros2humble/ros/networking/network_troubleshooting.mdx b/docs_versioned_docs/version-ros2humble/ros/networking/network_troubleshooting.mdx deleted file mode 100644 index e339f4a3..00000000 --- a/docs_versioned_docs/version-ros2humble/ros/networking/network_troubleshooting.mdx +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Network Troubleshooting -sidebar_position: 6 ---- - -The following troubleshooting flowcharts cover many of the most common troubleshooting issues with network integrity and ROS 2 communication using FastDDS. - -### Network Integrity - -The first step to troubleshooting your system networking is to verify the network integrity. Click on the image below to open in a new tab and explore the troubleshooting steps. - -
- -
- -
- -
- -### ROS 2 Communication - -Once network integrity is confirmed, the next step is to troubleshoot being able to publish and subscribe to ROS topics. The following flowchart covers the most common networking errors in Fast DDS. Many of these concepts are transferrable to other DDS implementations. Click on the image below to open in a new tab and explore the troubleshooting steps. - -
- -
- -
- -
diff --git a/docs_versioned_docs/version-ros2humble/ros/networking/network_troubleshooting/_category_.json b/docs_versioned_docs/version-ros2humble/ros/networking/network_troubleshooting/_category_.json new file mode 100644 index 00000000..a884158c --- /dev/null +++ b/docs_versioned_docs/version-ros2humble/ros/networking/network_troubleshooting/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Network Troubleshooting", + "position": 9 +} diff --git a/docs_versioned_docs/version-ros2humble/ros/networking/network_troubleshooting/intermittent_connectivity.mdx b/docs_versioned_docs/version-ros2humble/ros/networking/network_troubleshooting/intermittent_connectivity.mdx new file mode 100644 index 00000000..08250687 --- /dev/null +++ b/docs_versioned_docs/version-ros2humble/ros/networking/network_troubleshooting/intermittent_connectivity.mdx @@ -0,0 +1,175 @@ +--- +title: Intermittent Connectivity +sidebar_position: 4 +--- + +Intermittent connectivity, where communication drops in and out or slows down, can be challenging to diagnose. Unlike issues that entirely block communication, inconsistent communication arises from transient or situational factors, which often involve complex interactions between multiple factors. This page reviews several common causes and how to address them. + +## Wi-Fi Interference or Low Signal Strength {#weak-wi-fi} +Wireless networks can be significantly impacted by many factors such as interference or weak signal, resulting in packet loss and fluctuating bandwidth. Within the context of ROS, this can manifest as lost messages, delayed messages or nodes disappearing intermittently as a few examples. + +There are two ways to approach this issue. The first is to improve the network capacity so that it can support more data transmission. This should be considered as the first approach to fixing the issue as there can often be some quick fixes that provide measurable improvement. Secondary to that, the amount of data being transmitted should be reduced as is necessary to bring it into alignment with the abilities of the network. This second part is covered under the [Insufficient Bandwidth](#insufficient-bandwidth) section. + +To evaluate the network, it is best to start by stopping all ROS 2 systems on the network and then using [iperf3](network_troubleshooting_tools.mdx#iperf3) to verify the network bandwidth. This should be done with the robot in several locations, particularly any location where the instability issues occur. In general, as a rule of thumb, if the bandwidth is less than 40 Mbps then it is a low bandwidth network and it must be very carefully managed to support a ROS 2 system. + +If the network bandwidth is consistently lower than expected across the system then consider that there may be a [Hardware Problem](#hardware-problems), or that the networking infrastructure is not appropriate for the terrain or use case. This could mean for example that the wrong Wi-Fi frequency was chosen, antennas are mounted incorrectly, antennas have too high or too low of gain, or that there is too much interference. If the network bandwidth is lower than expected in certain regions then it is more likely that there is a local obstruction or interference issue. Review the [Wi-Fi Fundamentals](../wifi_fundamentals.mdx) and [Wi-Fi Hardware](../wifi_hardware.mdx) pages to understand why this might be and how to address it. + +## Insufficient Bandwidth + +#### Understanding the problem {#bandwidth-problem} + +Bandwidth is a measure of data throughput on a network. The overall available bandwidth on a wired network is generally fairly consistent while the available bandwidth on a wireless network is incredibly variable and is affected by many different factors. Attempting to transmit more data than the available bandwidth can cause a variety of different symptoms including unsuccessful transmissions, devices losing connection and delayed messages. + +#### Verification {#bandwidth-verification} + +To determine if this problem is effecting a given system, an estimate needs to be made for how much bandwidth is available over the network vs how much bandwidth is being used. This process is easiest if the router is accessible and has a bandwidth monitoring interface. If no such interface is available then a similar measure can be achieved by using [bmon](network_troubleshooting_tools.mdx#bmon) to measure the rate of transmitted data on each device and adding it up. With the full system operating, record how much bandwidth is being used on the network and note this measurement for later. + +Next, all of the communications over the network should be stopped and the network bandwidth should be measured again. Any systems running on the same network will effect the results so it is important to consider not only all ROS systems but also other systems that are running on the network. Verify that there is no bandwidth being used on the network. If there still is, identify which devices and processes are still using the network and address them or record the value to add it to the bandwidth measurement results of the next step. + +Then use [iperf3](network_troubleshooting_tools.mdx#iperf3) to evaluate the available bandwidth on the network. This test should be repeated as necessary to characterize the network and network environment. In the case of wireless networks, it is important to evaluate the bandwidth in problematic areas or locations where problems have been seen in the past. Repeat the test for all different types of messages that are transmitted (such as TCP, UDP small packets and UDP large packets). These network bandwidth measurements should be recorded for reference later, and attention should be given to the lower readings and the readings that match the type of the majority of the traffic. + +If the overall available bandwidth is lower than expected, see the [Wi-Fi Interference or Low Signal Strength](#weak-wi-fi) section. + +If the bandwidth used by the full system operating exceeds 80% of the available bandwidth capacity of the network, then this should be addressed in order to provide reliable performance in the regions tested. Ideally, basic operation should not exceed 50% of the full bandwidth of the network, allowing for unexpected interference, routing inefficiencies and general overhead. See the [Video over Wi-Fi](../../tutorials/video_over_wifi.mdx) tutorial for an example on how to evaluate what is realistic for a network. + +#### Solutions {#bandwidth-solutions} + +The first step is to determine if the ROS 2 system is actually the problem. With the rest of the systems running but the ROS 2 system disabled, check the network bandwidth. If most of the bandwidth is being used by other processes, consider having a dedicated network for the ROS 2 system or address why those other systems are using that much of the bandwidth. + +If the ROS 2 system is responsible for most of the bandwidth then it is important to calculate the expected bandwidth usage of the ROS 2 system. Calculate the bandwidth required for each of the main topics that are being transmitted (largest sizes and highest frequency) to establish an estimate of the bandwidth required for the ROS 2 system operation. This can be calculated for each topic using `message size * frequency * number of subscriptions over the network`. For an example of this calculation for two computers, see the [Video over Wi-Fi](../../tutorials/video_over_wifi.mdx) tutorial. Compare this expected value with the measured value of how much bandwidth is being used by the ROS 2 system. If the actual bandwidth usage is double or higher than the expected bandwidth then consider that the system may be having the problem of [Duplicate Messages](#duplicate-messages). + +If the required bandwidth for the system exceeds the available bandwidth then changes must be made. The first thing to consider is if the data is being transmitted in the most concise or dense format. Refer to the discussion on the [ROS 2 Communication](../ros2_communication.mdx#optimizing-sensor-data-for-transmission) page. Once the data is being transmitted using the most efficient message types, consider the frequency of the largest messages. Decreasing the frequency of messages directly reduces how much data needs to be processed and how much bandwidth is needed. + +## Duplicate Messages in Fast DDS {#duplicate-messages} + +Due to the low level mechanisms of how the DDS middleware messaging works, it is possible for messages to be sent in duplicate or multiplicate (3x or more). This section details how it occurs in Fast DDS. It may be possible for this to occur in other RMW Implementations through a similar mechanism. + +#### Why Does This Happen? {#duplicate-message-why} +Consider a robot with a lidar and an offboard computer that is trying to subscribe to the lidar scan from the terminal. The `ros2 topic echo` process on the offboard computer will create a subscription to the topic. This subscription involves the subscriber contacting the publisher to request the data and to tell the publisher where to send the data. The subscriber will self report the list of IP addresses where it is listening for messages along with port information, also known as its "locator list". In Fast DDS, by default, this locator list is initialized with all of the IP addresses that the computer had assigned at the time when the node was started. In the example being discussed, assume that the offboard computer had two IP addresses, one from a wired connection to the robot and one from a Wi-Fi connection to the internet. Since both of those IP addresses were present when the node was started, the locator list would have both IP addresses and the subscription would share both of these addresses with the publisher. Whenever the publisher publishes a new message, it will send the message to both IP addresses and then it is up to the operating system to route those messages through the most appropriate network. + +If there is only one network available on the robot across which to send the messages then all messages will be sent across that network irrelevant of whether the IP subnet matches. Within the context of this example, that would mean that two copies of every message would get sent across the wired connection to the offboard computer, one addressed to the offboard computer's wired IP address, and one addressed to the offboard computer's Wi-Fi address. For large messages, this can be very problematic as it consumes the network bandwidth. + +If there is more than one network available on the robot, then the messages will be sorted based on the IP subnet and then based on route metric. Within the context of this example, assume that the robot had another separate network with a higher route metric meaning that the second copy of the message would be sent out over that separate network. This would mean that although the robot is sending out two copies of the message, only one is making it back to the offboard computer while the second copy is sent on an incorrect network. In this case the wired connection between the robot and the offboard computer is only carrying one copy of each message and the offboard computer is only receiving one copy of the message. However, the robot computer is constantly switching between interfaces, sending one message on each. For large messages this can cause a bottleneck in the robot computer's onboard networking or CPU usage which could then impact its ability to keep up with the expected rates. + +This example was explained within the context of the subscriber reporting 2 IP addresses in the locator list but it can happen with 3 or more IP addresses and therefore could result in many copies being sent of each message. This issue is of highest concern for large messages and where the expected bandwidth usage is over half of the network capacity. However, it can also be a problem when there are excessive numbers of small messages being sent, such as with Simple Discovery with many nodes. + +#### Verification {#duplicate-verification} +The following steps can be used to verify if this issue is present: +1. Record a [tshark](network_troubleshooting_tools.mdx#tshark) capture on the robot capturing all network interfaces. Ensure that the discovery process and the subscription to the message are both captured. +2. Either analyze this directly in the terminal or save the capture and open it in [Wireshark](network_troubleshooting_tools.mdx#wireshark) to analyze it. When analyzing it, filter for the topic and verify how many different IP addresses the messages are being sent to, and which ones. + +#### Solutions {#duplicate-solutions} + +1. The first solution is to ensure that the subscribing computer only ever connects to one network at a time and that it only has one IP address. This works well for initial testing and for situations where the networking configuration needs to change often. However, it must be monitored and managed every time the system is used. While this section refers to "the subscribing computer" this should be applied to every computer in the system that subscribes to any substantially sized data. + 1. Ensure that the subscribing computer is only connected to one network and therefore has only one IP address. In the example this would be the offboard computer. + 2. Stop and restart all ROS nodes on the subscribing computer including the [ROS 2 Daemon](../ros2_communication.mdx#ros-2-daemon) and any Discovery Servers on the offboard computer. + 3. Confirm using the same [verification steps](#duplicate-verification) to ensure that the problem has been resolved. + +2. The second solution is more involved initially but can be set and forgotten. This solution works for systems where the networks are well defined and rarely change. As a reminder, the implementation details for this solution are specific to Fast DDS. The modification is to set a Fast DDS profile on the computer that restricts the locator list to a specific network interface using the IP address to identify the interface. This profile must be applied for all nodes as well as for the terminals. + 1. On the subscribing computer, create a new file called `fastdds_network_profile.xml` with the following contents, replacing the IP address with the IP address for the network interface that should be used for ROS 2 communications: + +```xml + + + + + CustomUdpTransport + UDPv4 + +
192.168.131.1
+ + 1400 + + + + + + + CustomUdpTransport + + false + + + +``` + +:::note + +The Max Message Size is set in this profile example because it is set by default by the Clearpath packages and is recommended to address the fragmentation problems described in [Large Data Fragmentation](#large-data-fragmentation). + +::: + + 2. Choose the correct option for your setup: + 1. If setting this on a Clearpath robot computer or a computer that is using the `clearpath_desktop` packages, set the profile parameter [profile](../../config/yaml/system.mdx#middleware) in the `robot.yaml` as the full path to the XML file. On the robot this will automatically update the appropriate files and relaunch the default services. You will still need to source the `/etc/clearpath/setup.bash` file in any open terminals to update them and restart the ROS 2 Daemon. On the offboard computer, follow the [instructions](../../installation/offboard_pc.mdx#setup-folder) for regenerating your `setup.bash` based on the updated `robot.yaml` file, and source this `setup.bash` file again in all of your terminals. + 2. If not using this in combination with the Clearpath packages, set the `FASTDDS_DEFAULT_PROFILES_FILE` environment variable to contain the full path to the XML file. This must be set in every environment where nodes are launched (including the ROS 2 Daemon and any services). This line can be added to the `.bashrc` file to be applied each time that a new terminal is opened. If the `.bashrc` was modified, ensure that it is sourced again in every open terminal window. + + ```bash + export FASTDDS_DEFAULT_PROFILES_FILE=/path/to/file/fastdds_network_profile.xml + ``` + + 3. Stop and restart all ROS nodes on the subscribing computer including the [ROS 2 Daemon](../ros2_communication.mdx#ros-2-daemon) and any Discovery Servers on the offboard computer. + 3. Confirm using the same [verification steps](#duplicate-verification) to ensure that the problem has been resolved. + + +## Large Data Fragmentation + +Large messages are fragmented into small packets in order to be transmitted across a network. This fragmentation can happen on the DDS level or on the operating system level (as part of the IPv4 protocol). For large UDP messages, this can be a problem because if any one fragment is dropped or corrupted then the message cannot be assembled and the entire message must be discarded. This issue has been addressed by default in the Clearpath software packages so they should not be a problem on devices with `clearpath_common` installed. + +If the fragmentation is occurring on the operating system (IPv4) level, then these fragments are stored in an IPv4 fragmentation buffer. By default, in Ubuntu Server, this fragmentation buffer is roughly 4 MB in size and has a timeout of 30 seconds. If a 4 MB image is being transferred, it does not take many missed packets for the buffer to be filled and no more fragments can successfully received until the existing fragments time out. One way to address this issue is to increase the buffer size and decrease the timeout such that the buffer is large enough to contain all of the data from the largest topics that would be received within the timeout given their respective frequencies. By default, the Clearpath packages override the default settings with the timeout set to 3 seconds and the buffer size to 128 MB. This would accommodate a 4 MB message being transmitted at 10 Hz. + +Another way that the fragmentation can become a problem is that when the messages are routed through certain interfaces or firewalls, the fragments may need to be assembled and refragmented. Some routers or other routing devices such as managed switches may be limited in how quickly these messages can be routed and fail to successfully assemble the messages. To avoid having to modify any buffers on these additional devices, the DDS settings can be modified to reduce the message size on the DDS level to lower than the Maximum Transmission Unit (MTU) so that the messages are not fragmented at the IPv4 level. This does cause a small increase in overhead to manage the fragmentation at the DDS level but this generally not significant. + +In Fast DDS this is done by applying the following XML profile. See the [Duplicate Messages](#duplicate-solutions) section for instructions on applying a custom XML profile. This profile is assigned by default when using the Clearpath packages and the `setup.bash` generated by Clearpath software. + +```xml + + + + + CustomUdpTransport + UDPv4 + 1400 + + + + + + + CustomUdpTransport + + false + + + +``` + +## Incorrect ROS 2 Quality of Service Settings {#qos} + +Subscriber quality of service settings such as reliability policy of *Reliable* or a large depth value can increase the network traffic and cause message backlogs in low bandwidth networks where some packets are lost. For more details, refer to the discussion on the [ROS 2 Communication](../ros2_communication.mdx#qos) page. + +## Insufficient Computing Resources + +If the CPU usage on the robot or on the offboard computer are close to maximum, then it can result in low message frequency, increased latency and many other networking issues. This could be because all of the CPU cores are entirely maxed out, or it could be a single node getting slowed down if it is using up a full core with a thread that cannot be divided into multiple cores. To evaluate this, monitor the CPU usage on all of the computers during operation. Additionally, monitor to see if the expected frequencies are able to be achieved on the computer where the data is being published. If the computer cannot handle publishing locally at the full expected frequency then it is not a network issue. To address this, either the processes must be modified to be less computationally heavy, or hardware needs to be upgraded to be able to run the processes. Certain processes are better suited to GPUs, and image/video/data compression processes can be tuned to reduce CPU usage. Some nodes can be optimized by writing them in C++ instead of Python, or by combining nodes into a composable node to take advantage of zero-copy data transfer. + +Resource restrictions can also be encountered on network devices such as routers or managed switches. Any routing system has a limit of how many messages can be routed in a certain amount of time. These systems may take longer to route large messages that are fragmented as part of the IPv4 protocol. To avoid this, fragmentation can be shifted to the DDS level as described in the [Large Data Fragmentation](#large-data-fragmentation) section. + +## Hardware Problems + +Inconsistent connectivity can be caused by unreliable or insufficient networking hardware. For Wi-Fi systems this could include the wrong antenna selection, outdated Wi-Fi technology, or bad antenna cables with excessive loss. Review the [Wi-Fi Fundamentals](../wifi_fundamentals.mdx) and [Wi-Fi Hardware](../wifi_hardware.mdx) pages to understand why this might be and how to address it. For the wired components, ensure that the ethernet cables are at least Cat5e (Cat6 recommended), and that the ethernet ports are rated for 1 Gbps at minimum. If there are any routing hardware on the network, ensure that they are rated for sufficient throughput (1 Gbps minimum recommended). Additionally, all hardware and cable assemblies should have the appropriate vibration, temperature and moisture ratings to ensure operational reliability. + +Assuming that the hardware selection and placement is appropriate for the application, the physical quality of the hardware should be verified. All cables and components should be fully intact, connectors and ports secured, and have no visible damage. Where possible, tests should be done to verify bandwidth across isolated sections of the network (for example, from the robot computer to an onboard router). If possible, replace components with known working modules or cables to verify performance. + +The following are some advanced networking issues that can occur on the hardware level: + +#### Electromagnetic Interference (EMI) +Electromagnetic interference generally comes from proximity to motors, motor drivers or power supplies without sufficient shielding. This can result in unpredictable behavior, brownouts, corrupted data or damage to components. In the context of networking, the primary concern is interference on the power going to the computer, power going to an onboard router, and data lines connecting to an onboard router, computer or antennas. Several steps can be taken to reduce electromagnetic interference: +- Route high power lines (to motors and actuators) away from wires going to sensitive electronics (such as computers, routers, sensors or antennas). +- Shield both data lines and noisy cables separately. +- Twist noisy power cables to lower EMI emissions. +- Apply common mode chokes or ferrite cores to the noisy cables (ensure that they are properly rated for the power). + +#### Insufficient or Unstable Power Supply +If too much current is being drawn from a power supply, it can experience transient drops in voltage that are hard to detect but can cause unpredictable behavior and brownouts. This can also be seen if the power supply is damaged. Verify that the power supply is rated for the current draw, including any surge current requirements, and is functioning properly. + +#### Damaged Components +Vibration can cause components such as capacitors and other bulky components on PCBs to fail, particularly if the devices are not vibration rated. Similarly moisture and heat can cause damage to components in a manner that may not be visible. Be aware that the temperature within enclosures without adequate ventilation can be dramatically higher than ambient temperatures outside and should be monitored. \ No newline at end of file diff --git a/docs_versioned_docs/version-ros2humble/ros/networking/network_troubleshooting/network_integrity.mdx b/docs_versioned_docs/version-ros2humble/ros/networking/network_troubleshooting/network_integrity.mdx new file mode 100644 index 00000000..4e9c339b --- /dev/null +++ b/docs_versioned_docs/version-ros2humble/ros/networking/network_troubleshooting/network_integrity.mdx @@ -0,0 +1,19 @@ +--- +title: Network Integrity +sidebar_position: 2 +--- + +The first step to troubleshooting your system networking is to verify the network integrity. Click on the image below to open in a new tab and explore the troubleshooting steps. + +
+ +
+ +
+ +
+ +Once network integrity is confirmed, the next troubleshooting step is to investigate [ROS 2 Connectivity](ros2_connectivity.mdx). \ No newline at end of file diff --git a/docs_versioned_docs/version-ros2humble/ros/networking/network_troubleshooting/network_troubleshooting_tools.mdx b/docs_versioned_docs/version-ros2humble/ros/networking/network_troubleshooting/network_troubleshooting_tools.mdx new file mode 100644 index 00000000..7cbe5d6d --- /dev/null +++ b/docs_versioned_docs/version-ros2humble/ros/networking/network_troubleshooting/network_troubleshooting_tools.mdx @@ -0,0 +1,246 @@ +--- +title: Network Troubleshooting Tools +sidebar_label: Troubleshooting Tools +sidebar_position: 5 +--- + +The following are useful troubleshooting tools for analyzing and understanding network traffic. + +## ROS 2 CLI +The ROS 2 Command Line Interface (CLI) is a very useful initial set of commands for troubleshooting ROS 2 systems. The following are some of the commonly used commands: + +- `ros2 node list` - Check that the nodes are discovered and running +- `ros2 topic list` - Check that the topics are discovered and have at least one publisher or subscriber (does not need to be both) +- `ros2 topic echo ` - Subscribe to a topic and see what is being published +- `ros2 topic info --verbose` - See the identity of each publisher and subscriber +- `ros2 topic hz ` - Check the frequency of messages received on a topic +- `ros2 topic bw ` - Check the bandwidth being used for a topic (given the current topic frequency) +- `ros2 topic delay ` - Calculates the message delay using timestamps (is only as accurate as the time sync between the computers) + +## iPerf3 + +[iPerf3](https://iperf.fr/) is an open source tool designed to measure the available bandwidth between two devices on a network. It can test both TCP and UDP communications. This is useful for evaluating network quality, and determining if the network is capable of supporting the traffic required for a given system. This tool can also be used to evaluate the impact of distances and obstacles on wireless network connection strength. + +iPerf3 uses a server-client model: +- Server: Runs on a computer and listens for connections. +- Client: Runs on the other computer, initiates the test and specifies the details of the test. + +:::warning + +It is not advised to use iPerf3 over metered networks (such as cellular or satellite networks) because the test works by transferring large amounts of data. + +::: + +#### Installation {#iperf3-installation} +```bash +sudo apt update +sudo apt install iperf3 +``` + +#### Usage {#iperf3-usage} +1. Before beginning the test, identify the network that is being tested and ensure that the two computers are connected on that network and only on that network. Take note of any other traffic happening on the network that may impact the results. + +2. Start the server on one computer + +```bash +iperf3 -s +``` + +3. On the other computer, launch the client and direct it to the server with the options set for a given test. + + For a simple test of how much bandwidth is available run: + ```bash + iperf3 -c + ``` + + Where `` is replaced with the IP address of the computer running the server. + + This test sends the maximum possible amount of data from the client to the server using TCP. The `-R` option can be used to reverse the traffic and test data flow from the server back to the client. + + Given that most ROS RMW Implementations use UDP messages, it can be useful to run this test using UDP as well: + ```bash + iperf3 -c -u -l -b + ``` + + Where `` is replaced with the IP address of the computer running the server, `` is replaced with the desired UDP packet size in bytes, and `` is replaced with the target bandwidth to test for in bits/sec. The size of the UDP packets can be adjusted to emulate traffic consisting of different ROS 2 message sizes. Around 100-200 bytes is a small UDP packet and around 1400 bytes is a large UDP packet: + + There are many other options documented in the (iPerf manual)[https://iperf.fr/iperf-doc.php]. + +4. The most significant result to look at is the bitrate which indicated the available bandwidth. For UDP, it is also useful to look at the percentage of lost packets. + +5. Repeat the test multiple times with any possible variations in the system. Many things impact bandwidth including interference from other wireless networks, physical distance, and obstacles relative to antennas. + +## bmon + +bmon or Bandwidth Monitor is a command-line tool for monitoring current bandwidth usage. While iPerf3 tests the maximum possible bandwidth, bmon is used to monitor an active system to analyze traffic generated through operation. + +#### Installation {#bmon-installation} + +```bash +sudo apt update +sudo apt install bmon +``` + +#### Usage {#bmon-usage} + +To start bmon run + +```bash +bmon +``` + +The `Interfaces` section lists all of the network interfaces and the traffic being transmitted (`TX`) and received (`RX`) on each. The traffic is shown in `bps` (bits per second) and in `pps` (packets per second). The lower section shows a graphical representation of the bandwidth usage over time for the selected network. Finally, pressing `d` opens a detailed statistics section including error rates and dropped packets. + +## Wireshark + +[Wireshark](https://wiki.wireshark.org/) is a powerful network protocol analyzer that captures and inspects packets on a network in real-time. It can be used to analyze ROS 2 communication to identify problems and optimize data flow. This can involve identifying the ports in use, analyzing the number of packets or bandwidth being used for different types of messages or investigating individual messages that are not successfully transmitted. + +#### Installation {#wireshark-installation} + +```bash +sudo apt update +sudo apt install wireshark +``` + +During installation, it may prompt you to allow non-root users to capture packets. You can accept this option for convenience. You may need to log out and log back in for the change to apply. + +#### Usage {#wireshark-usage} + +1. Open Wireshark and select the network interface(s) connected to the ROS 2 system. If you did not give permissions to non-root users then you will need to launch with sudo. +2. Start traffic capture by clicking the `Start` button. All of the traffic will be displayed in real-time. +3. Optionally save or export the data. + +To maximize utility, make sure to capture the ROS 2 discovery process. This allows Wireshark to interpret DDS (RTPS) messages and makes more information such as topics names available for use in filters and for analysis. In Simple Discovery the discovery process will be captured in the background. For Discovery Server, ensure that the ROS 2 daemon is restarted at the beginning of the capture on the computer where the capture is being taken, to record the discovery process. + +#### Features + +##### Display Filters +Filters can be used to isolate specific types of traffic. + +Filtering for ROS DDS messages only (assumes no other RTPS systems on the network): + +``` +rtps +``` + +Filtering for ROS 2 DDS messages to or from a particular device (for example, a device with IP address 192.168.186.131): + +``` +rtps && ip.addr == 192.168.186.131 +``` + +Filtering for ROS 2 DDS messages based on topic name or message type (for this to work, the discovery process must have been recorded in the same Wireshark capture). Replace the topic string and/or message type as necessary: + +``` +rtps && rtps.param.topicName contains "ffmpeg" +``` + +or + +``` +rtps && rtps.param.typeName == "ffmpeg_image_transport_msgs::msg::dds_::FFMPEGPacket_" +``` + +Do note that this will not accurately filter and reflect messages that were fragmented using the IP protocol. Only the message where the IP fragments are reassembled will show up using this filter. + +These types of filters can be combined into complex and specific filters to effectively isolate messages of interest. + +##### Statistics + +One very useful view for analyzing traffic over time or for optimizing systems is the `I/O Graphs` view. This is found under the `Statistics` dropdown menu. The `I/O Graphs` view allows lines to be added to the graph using different display filters. + + +
+
+ +
Wireshark I/O Graphs Example
+
+
+ +In addition to the display filters, take note of the y-axis (bits vs packets) to determine what data is graphed. The `Interval` setting at the bottom of the window (not shown) controls the timeframe over which each datapoint is calculated. + +Additional statistics views that can be useful include `Source and Destination Addresses` to see which devices have sent/received how many packets and identify outliers (accessed through `Statistics` -> `IPv4 Statistics` -> `Source and Destination Addresses`). Similarly, `Destination and Ports` can be used to identify which ports are being used on each device (accessed through `Statistics` -> `IPv4 Statistics` -> `Destination and Ports`). These are not the only useful views, but are a good place to start. + +## tshark + +[tshark](https://www.wireshark.org/docs/man-pages/tshark.html) is the command line version of Wireshark. This is useful for Ubuntu server based systems, to be able to enable the use of Wireshark functionality without requiring a display for capture. + +#### Installation {#tshark-installation} + +```bash +sudo apt update +sudo apt install tshark +``` + +During installation, it may prompt you to allow non-root users to capture packets. You can accept this option for convenience. You may need to log out and log back in for the change to apply. + +#### Usage {#tshark-usage} + +To capture packets on a specific network interface, use: + +```bash +tshark -i +``` + +Replace `` with your network interface (such as `eth0` or `wlan0`). The `-i` option can be repeated multiple times to capture from more than one interface simultaneously. Use the `-D` option to list the available interfaces: + +```bash +tshark -D +``` + +The captured data can be analyzed in the command line, or it can be saved to a file using `-W` for later analysis in Wireshark: + +```bash +tshark -i -w capture.pcap +``` + +Capture filters can be used to reduce the log sizes if necessary or when analyzing directly in the command line. + +## Nmap + +Nmap (Network Mapper) is a command line tool for network exploration and management. It can be used to identify connected devices and open ports among other uses. + +#### Installation {#nmap-installation} + +```bash +sudo apt update +sudo apt install nmap +``` + +#### Usage {#nmap-usage} + +A small selection of functionality is discussed here, for full documentation see the [Nmap manual](https://nmap.org/book/man.html). + +To detect the other hosts on your network, run a ping scan as follows but replace the IP address with one on the network that is to be scanned: + +```bash +nmap -sn 10.27.0.1/24 +``` +This will return a list of IP addresses where hosts were found that responded to the ping and the associated ping latency. + +To do a port scan run: + +```bash +nmap -p +``` + +Where `` is replaced by the port number(s) or range to be checked and `` is replaced with the target IP address of the device to be checked. This will give a report of the status of all of the ports requested. + +To do a host scan run: + +```bash +nmap +``` + +Where `` is replaced with the target IP address to be inspected. This will give summary information about a particular device on the network including the currently open ports. + +Finally, to try and identify what operating system is running at a particular IP address, run: + +```bash +nmap -O +``` + +Where `` is replaced with the target IP address to be inspected. \ No newline at end of file diff --git a/docs_versioned_docs/version-ros2humble/ros/networking/network_troubleshooting/ros2_connectivity.mdx b/docs_versioned_docs/version-ros2humble/ros/networking/network_troubleshooting/ros2_connectivity.mdx new file mode 100644 index 00000000..8ebdc00e --- /dev/null +++ b/docs_versioned_docs/version-ros2humble/ros/networking/network_troubleshooting/ros2_connectivity.mdx @@ -0,0 +1,21 @@ +--- +title: ROS 2 Connectivity +sidebar_position: 3 +--- + +The first step for troubleshooting ROS 2 connectivity between two computers is to investigate [Network Integrity](network_integrity.mdx). Once network integrity is confirmed, the next step is to troubleshoot being able to publish and subscribe to ROS topics. The following flowchart covers the most common networking errors in Fast DDS. Many of these concepts are transferrable to other DDS implementations. Click on the image below to open in a new tab and explore the troubleshooting steps. + +When using the troubleshooting flowchart in combination with the Clearpath software packages, be aware that most environment variables are controlled by the `robot.yaml` and should be updated by modifying the robot.yaml. The networking settings are controlled in the [system section](../../config/yaml/system.mdx#ros-2-environment). When troubleshooting the offboard computer connection, ensure that the `robot.yaml` file on the computer is also updated and that the `setup.bash` is [regenerated](../../installation/offboard_pc.mdx#setup-folder) every time the settings are changed. + +
+ +
+ +
+ +
+ +If the system is able to communicate and passes all of these tests but is unreliable in operation, see the page about [intermittent connectivity](intermittent_connectivity.mdx). \ No newline at end of file diff --git a/docs_versioned_docs/version-ros2humble/ros/networking/network_troubleshooting/troubleshooting_overview.mdx b/docs_versioned_docs/version-ros2humble/ros/networking/network_troubleshooting/troubleshooting_overview.mdx new file mode 100644 index 00000000..241789d2 --- /dev/null +++ b/docs_versioned_docs/version-ros2humble/ros/networking/network_troubleshooting/troubleshooting_overview.mdx @@ -0,0 +1,10 @@ +--- +title: Overview +sidebar_position: 1 +--- + +Networking is a topic that can be intimidating to approach due to the many overlapping and interacting concepts involved. Any one symptom can have a myriad of different causes. In order to facilitate learning about common networking issues, and to empower individuals to troubleshoot their networking systems, the following information and tools have been curated: + +- For how to get ROS 2 communication working between two computers, start with the [Network Integrity Flowchart](network_integrity.mdx) and then the [ROS 2 Connectivity Flowchart](ros2_connectivity.mdx). +- For issues where communication is inconsistent, see [Intermittent Connectivity](intermittent_connectivity.mdx). +- For tool recommendations when troubleshooting networking issues and guidance on how to use them, see [Network Troubleshooting Tools](network_troubleshooting_tools.mdx). \ No newline at end of file diff --git a/docs_versioned_docs/version-ros2humble/ros/networking/ntp.mdx b/docs_versioned_docs/version-ros2humble/ros/networking/ntp.mdx index 156a6eec..b0231f80 100644 --- a/docs_versioned_docs/version-ros2humble/ros/networking/ntp.mdx +++ b/docs_versioned_docs/version-ros2humble/ros/networking/ntp.mdx @@ -1,6 +1,6 @@ --- title: Configuring NTP -sidebar_position: 5 +sidebar_position: 8 --- Network Time Protocol, or NTP, is a network protocol that allows computers on a network to synchronize their clocks diff --git a/docs_versioned_docs/version-ros2humble/ros/networking/overview.mdx b/docs_versioned_docs/version-ros2humble/ros/networking/overview.mdx index bd3abd8a..ae682cfd 100644 --- a/docs_versioned_docs/version-ros2humble/ros/networking/overview.mdx +++ b/docs_versioned_docs/version-ros2humble/ros/networking/overview.mdx @@ -5,12 +5,34 @@ sidebar_position: 1 import Ros2NetworkingOverview from "/docs_versioned_docs/version-ros2humble/components/networking/_ros2_networking_overview.mdx"; +This section covers general information about how ROS 2 networking works, how to configure ROS 2 networking, general Wi-Fi information and detailed troubleshooting guides. + ### SSH and SFTP Clearpath robots ship with an SSH server operating on port 22 for remote login. This server also supports sftp for file-transfer to/from the robot if needed. By default you can log in using the default username and password for the robot. +### ROS 2 Networking {#ros2-networking} + +There are many nuances to working with ROS 2 nodes and ensuring that all components are communicating properly. The most important of these concepts are reviewed in the [ROS 2 Communication](ros2_communication.mdx) page. + +:::tip + +For the best chance of success, use a high speed, high bandwidth network and monitor the network usage. + +::: + +#### ROS 2 Discovery Configuration + + + +Further information on [ROS 2 Discovery Configuration](ros2_discovery_config.mdx). + +### Wi-Fi Fundamentals and Hardware + +ROS 2 communication can be demanding on networks, particularly wireless networks. At times, difficulties with ROS 2 communication can actually stem from core Wi-Fi stability and reliability issues. The [Wi-Fi Fundamentals](wifi_fundamentals.mdx) and [Wi-Fi Hardware](wifi_hardware.mdx) pages discuss important concepts useful for optimizing Wi-Fi networks for use with ROS 2 mobile robots. + ### Wired LAN IP Addresses {#ip-addresses} All Clearpath robots use the `192.168.131.0/24` subnet for any permanently-installed network hardware. This includes, @@ -25,19 +47,7 @@ but may not be limited to The `192.168.131.0/24` subnet is statically configured; all devices are configured to use a static IP address, and there is normally not a DHCP server operating on this subnet. -For a list of standard payload IP addresses, please see [network IP addresses](network_ip_addresses.mdx). - -### ROS 2 Networking {#ros2-networking} - - - -Further information on [ROS 2 Networking](ros2-networking.mdx). - -:::tip - -For the best chance of success, use a high speed, high bandwidth network and monitor the network usage. - -::: +For a list of standard payload IP addresses, please see [Standard IP Addresses](standard_ip_addresses.mdx). ### Clock Synchronization @@ -47,8 +57,6 @@ primary computer being the authoritative source for the others. For details on configuring `chrony`, please see [configuring NTP](ntp.mdx). -:::note - -Contact our Support team at if you have any questions. +### Network Troubleshooting -::: \ No newline at end of file +There are many things that can go wrong when setting up ROS 2 networking. To aid in this process, a [troubleshooting section](./network_troubleshooting/troubleshooting_overview.mdx) is available with flowcharts to guide the process of troubleshooting two computers that are not communicating properly as well as discussion of common issues that can cause intermittent or unreliable communication. A list and description of troubleshooting tools is also available to assist in the troubleshooting process. \ No newline at end of file diff --git a/docs_versioned_docs/version-ros2humble/ros/networking/ros2_communication.mdx b/docs_versioned_docs/version-ros2humble/ros/networking/ros2_communication.mdx new file mode 100644 index 00000000..359d5e71 --- /dev/null +++ b/docs_versioned_docs/version-ros2humble/ros/networking/ros2_communication.mdx @@ -0,0 +1,71 @@ +--- +title: ROS 2 Communication +sidebar_position: 3 +--- + +This page reviews information that is useful to understand for working with ROS 2 DDS based communication. + +## RMW Implementations +ROS 2 uses an abstracted [ROS Middleware](https://docs.ros.org/en/humble/Concepts/Intermediate/About-Different-Middleware-Vendors.html) (RMW) to manage the networking and communication. There are several RMW Implementations to choose from, and each operates somewhat differently. Most RMW Implementations are based on the [DDS](https://docs.ros.org/en/humble/Installation/DDS-Implementations.html) (Data Distribution Service) standard which is built on the RTPS (Real-time Publish Subscribe) protocol. In the DDS standard, the ROS 2 nodes act as participants that can publish and subscribe. In most cases, DDS uses UDP messages for the underlying communication over the network. Each RMW implementation has many ways that it can be configured to achieve different goals such as simplicity, redundancy or robustness. The DDS system is decentralized, meaning that the participants are not managed by any one entity. Instead the system works peer to peer, allowing nodes to find each other. This process is referred to as the discovery process. + +The Clearpath robot packages currently support the eProsima Fast DDS as the RMW Implementation. There are still several decisions that have to be made in configuring the Clearpath robot networking. The most significant decision is choosing the discovery method. In Fast DDS, there is the default `Simple Discovery` and the more managed `Discovery Server` option. These two options are discussed in detail in the [ROS 2 Discovery Config](ros2_discovery_config.mdx) page. Instructions on switching the discovery method are available on that page, as well as the specific parameters are documented in the [System section](../config/yaml/system.mdx#middleware) of `robot.yaml`. + +## DDS Settings +There are a variety of settings that are set through the `robot.yaml` that control how the DDS layer operates. For example, the [Domain ID](https://docs.ros.org/en/humble/Concepts/Intermediate/About-Domain-ID.html) is used in the calculation of which ports each node communicates on. In order for the DDS communication to be successful, the network needs to allow unrestricted data flow between the devices on these ports. + +If not using the `robot.yaml` or the accompanying generated `setup.bash` file, then these settings must be set using environment variables. See [this page](https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.html) for how to configure the ROS 2 environment, and see [this page](https://fast-dds.docs.eprosima.com/en/2.6.x/fastdds/env_vars/env_vars.html) for additional information about Fast DDS environment variables. There are some nuances to how and when these settings are adopted. Please see the [ROS 2 Daemon](#ros-2-daemon) and [Adapting to Network Changes](#adapting-to-network-changes) sections below for more details. + +## ROS 2 Daemon +The ROS 2 daemon is a service that runs in the background and participates in the discovery process as a node. The daemon keeps track of the ROS 2 participants that have been discovered on the network and makes that information available to the ROS 2 introspection tools over the command line interface (CLI). Using the daemon allows for faster and more accurate results from commands such as `ros2 topic list`, `ros2 node list` and `ros2 topic echo`. + +This daemon is started automatically by any command line interface (CLI) command that needs it. However, the daemon collects discovery information from the network over time so it may take anywhere from a few seconds to a few minutes for the daemon to gain a complete list of all ROS 2 participants, depending on the size of the system. Therefore, the results of the command that starts the daemon may be incomplete. If the daemon is stopped and then a command is run that restarts the daemon, wait and then run the command again to get a complete response. + +When the daemon starts, it adopts the ROS 2 communication settings at that time from the terminal where it was started. This includes settings like the RMW Implementation, Fast DDS Simple Discovery vs Discovery Server, ROS Domain ID, and others. These settings do not update in the daemon once started. This means that changing the ROS Domain ID in the terminal does not change the ROS Domain ID of the daemon and therefore does not change the behavior of the ROS 2 CLI commands such as `ros2 topic list`. To have the CLI results update, the daemon must be stopped and restarted (`ros2 daemon stop` followed by `ros2 daemon start` or a command that auto-starts the daemon). This also means that if there are two different terminals active with different settings, the ROS 2 CLI can only work with one of them at a time, and the daemon must be stopped and restarted in the appropriate terminal before being used. There are `no-daemon` options that can be used with some CLI commands, however they are less reliable and do not always give complete results since they are only able to report on information captured during the delay between the request of the command and the results being displayed. + +When working with Fast DDS Discovery Server, the daemon must be started with super client privileges (`ROS_SUPER_CLIENT=True`). Super client means that the client will have access to all of the information from the discovery server(s), not just the information that it needs. This is necessary to support the functionality of the ROS 2 CLI Introspection commands. This is set automatically in the Clearpath setup.bash files. + +### Key Takeaways + +Important considerations when working with the ROS 2 Daemon: +1. Each computer has only one daemon with one set of ROS 2 communication settings. +2. The daemon automatically starts when certain ROS 2 Command Line Interface (CLI) commands such as `ros2 topic list` or `ros2 node list` are run. +3. The daemon only adopts the communication settings from the terminal where it was started and these do not update. To use it with any updated or different settings, it must be stopped and then restarted with the new settings. +4. After the daemon starts, it takes a few seconds or minutes to complete the discovery process, and may give incomplete results until then. This often just means running `ros2 topic list` twice (or more until the full list shows up) whenever starting to use the CLI tools. +5. When in doubt, restart the daemon. + +## Adapting to Network Changes + +### Changing Network Settings +Like with the ROS 2 Daemon, the ROS 2 settings for any given ROS 2 node are adopted at start and do not update while the node is running. If the ROS 2 networking settings (such as Domain ID, Automatic Discovery Range and Discovery Servers) are changed, then the nodes need to be stopped and restarted. For the convenience of users, any such settings that are modified in the Clearpath `robot.yaml` file on the robot will automatically trigger a restart of all of the nodes that are started by the Clearpath services. Any nodes that were manually launched must be manually restarted. + +On the offboard computer, the `robot.yaml` must be updated, just like on the robot, however, the `setup.bash` must be manually [regenerated](../installation/offboard_pc.mdx#setup-folder) and sourced again in all terminals, and then all of the nodes must be manually restarted. + +### Changing IP Addresses and Node Locator List +In Fast DDS, the locator list for each node is the list of IP addresses and ports where that node is listening for messages. This list is initialized once when the node starts with the list of IP addresses that the computer had active at the time when the node started and is never updated. This list is used in the discovery process to establish connections. This means that if the computer were to change IP addresses (as can happen with DHCP or when connecting to a new network) then the node would not be available at the new IP address. To prevent this from happening, it is recommended to use static IPs for all devices in the ROS 2 network. The IP addresses should be reserved on the router(s) in the system to avoid conflicts, or at least not be included in the DHCP range. + +### Network Wait Online Service +As a continuation of the previous issue, because the locator list never updates, it means that the nodes are not available over any new IP addresses that become active after the nodes start. For that reason, starting any nodes should wait until the network interfaces are all online. For services on Ubuntu Server, this is done by creating a dependency on `systemd-networkd-wait-online.service`. This is taken care of for the Clearpath services as part of the Clearpath software install process. However, for this process to work properly, the netplan file must be configured correctly. Any network connection that is being used for ROS communication should not be labelled as optional. + +This also means that the offboard network infrastructure, such as routers and switches, should be booted up first before turning on the ROS systems so that all networks are ready to connect. + +### Key Takeaways + +1. Nodes must be restarted to adopt updated networking settings including new or updated IP addresses. +2. Use static IP addresses for all devices and reserve them on the network(s). +3. Ensure that all networks are active and connected prior to launching ROS nodes. + +## Optimizing Sensor Data for Transmission +It is important to identify what data is appropriate to be transmitted over a given network. Data being transmitted wirelessly should be in the most concise or information dense message type. However, when working with large data types, this must be considered even for high-bandwidth wired networks. + +As a general rule, image data should always be compressed using one of the standard [image transports](../config/camera_compression.mdx). Even on lower resource systems, compression can be used to reduce bandwidth significantly. If working with a camera video stream, using the FFMPEG H.264 compression offers much more significant compression than the standard JPEG compression. For a detailed example of sizing a video stream for a wireless network, see the [Video Over Wi-Fi tutorial](../tutorials/video_over_wifi.mdx). + +Similarly, depth data is often transmitted in inefficient formats. Depth data can be stored efficiently as lidar scan packets, or depth images (depending on the sensor used). However, once the data is expanded out into a PointCloud message type, the data is much sparser. It takes a lot more bandwidth to transmit the same data in a PointCloud format, sometimes upwards of 15 times the bandwidth. The scan packets or depth images should only be transformed into the PointCloud format on the computer that needs to consume the PointCloud, and preferably as part of a [composable node](https://docs.ros.org/en/humble/Concepts/Intermediate/About-Composition.html) where the data is also being consumed. + +## ROS 2 Quality of Service {#qos} +ROS 2 Quality of Service (QoS) describes a group of settings, called *Policies*, that dictate how a message is transmitted. Both the publisher and subscriber will have a QoS declared. The QoS of the publisher defines the highest level policy available for each setting. The subscriber QoS defines the policies that will be used for that particular subscription. If the subscriber needs a higher level of policy than the publisher offers then the subscription will fail. There are many policies that can be controlled as part of the QoS. Two of particular interest are reliability and history depth. + +The reliability policy can be set to *Reliable* or *Best Effort*. Under *Best Effort*, the publisher will publish the message once and the computer will attempt to deliver it over the network but it will not check to ensure it arrives. With *Reliable*, the publisher will retry sending the message repeatedly if it is not successfully delivered. *Best Effort* should be used whenever it is more important to receive the latest data and it doesn't matter if a historic message is missing. This is typical for sensor data. The reliability setting is very important to consider with larger messages. If the transmission of a large message fails, it is a much greater burden on the network to continue retrying to send the message. Using the ROS 2 CLI to echo a topic by default uses a *Reliable* QoS. + +The history and depth policy are important for a similar reason. These two policies together control how many historic messages are stored and would be resent. The history policy should be set to *Keep Last* while depth is the integer that controls the size of this queue. If the reliability is set to *Reliable* then the queue size is the number of historic messages which will continue to be resent until they are successfully received. This queue length should be kept as low as possible while still supporting the needed functionality. For example, for sensor data where the latest message is the only important message, then the subscriber should have depth of 1. + +For more details on quality of service, see the [Clearpath Robot API](../api/overview.mdx#qos-profiles) and the [ROS 2 documentation](https://docs.ros.org/en/humble/Concepts/Intermediate/About-Quality-of-Service-Settings.html). \ No newline at end of file diff --git a/docs_versioned_docs/version-ros2humble/ros/networking/ros2-networking.mdx b/docs_versioned_docs/version-ros2humble/ros/networking/ros2_discovery_config.mdx similarity index 93% rename from docs_versioned_docs/version-ros2humble/ros/networking/ros2-networking.mdx rename to docs_versioned_docs/version-ros2humble/ros/networking/ros2_discovery_config.mdx index 1ad3286f..08d714b2 100644 --- a/docs_versioned_docs/version-ros2humble/ros/networking/ros2-networking.mdx +++ b/docs_versioned_docs/version-ros2humble/ros/networking/ros2_discovery_config.mdx @@ -1,6 +1,6 @@ --- -title: ROS 2 Networking -sidebar_position: 3 +title: ROS 2 Discovery Configuration +sidebar_position: 4 --- ## Overview @@ -14,7 +14,7 @@ import Ros2NetworkingOverview from "/docs_versioned_docs/version-ros2humble/comp ### Simple Discovery Participants (nodes) send periodic multicast announcement messages over the network with their unicast addresses, and -then all participants share discovery information (such as topics, and action servers.) with all other participants. +then all participants share discovery information (such as topics and services) with all other participants. This means that all participants get information about all other participants irrelevant of whether or not they need that information. @@ -34,15 +34,15 @@ combination of Clearpath robots. For more detailed information regarding Fast DDS or simple discovery, visit the [eProsima Fast DDS documentation](https://fast-dds.docs.eprosima.com/en/latest/fastdds/ros2/ros2.html). -Additional details on how to select simple disocvery in the `robot.yaml` config file are available in the +Additional details on how to select simple discovery in the `robot.yaml` config file are available in the [Middleware section of Robot Configuration](../config/yaml/system.mdx#middleware). ### Discovery Server A discovery server is a process running on a computer that serves to record and report ROS discovery information. A server can be thought of as a look up table for ROS discovery information. When a participant (node) starts, it -checks in with the servers to share its discovery information and request what information it is looking for. -In this way, particpants only get discovery information and establish communication as necessary. A participant +checks in with the servers to share its discovery information and request what information it needs. +In this way, participants only get discovery information and establish communication as necessary. A participant does not know all of the information that is available, only where to find the fellow participants that it needs. There can be multiple servers in a given system. These can be used for redundancy or to segregate information. @@ -98,7 +98,7 @@ There are multiple different ways to configure discovery server depending on whi This section will go over some basic configurations and is generalized for use as an introduction. It does not describe all possible configurations. The `ROS_DISCOVERY_SERVER` environment variable, shown in the various diagrams, indicates which discovery servers a given robot is connected to. Additionally, communication will be referred to -in terms of seeing ROS 2 topics although this is representative of all nodes, topics, action servers, and so on. +in terms of seeing ROS 2 topics although this is representative of all nodes, topics, action servers, and so on. :::note @@ -109,7 +109,7 @@ packages. ::: -### 1. Fully Connected {#fully-connected} +### Fully Connected {#fully-connected} This configuration is the simplest to set up using the `robot.yaml` config. It allows all robots to operate independently but also allows any ROS 2 device in the system to see all of the topics from all of the @@ -146,7 +146,7 @@ middleware: Additional details on the available fields for the `robot.yaml` config file are available in the [Middleware section of Robot Configuration](../config/yaml/system.mdx#middleware). -### 2. Command Center {#command-center} +### Command Center {#command-center} In this configuration you have many robots that each operate independently and an offboard computer that checks in and communicates with each of the robots. Each of the robots will have and refer to their own local @@ -219,14 +219,14 @@ middleware: Additional details on the available fields for the `robot.yaml` config file are available in the [Middleware section of Robot Configuration](../config/yaml/system.mdx#middleware). -## Offboard Computer Setup {#offboard-pc} +### Offboard Computer Setup for Discovery Server {#offboard-pc} Use the `robot.yaml` from one of the robots in order to set up the offboard computer. The `servers` list must include all of the discovery servers and all of the ones that the offboard computer should be connecting with must not be disabled. 1. Regenerate the `setup.bash` every time the `servers` list changes in any way (as per [offboard computer install instructions](../installation/offboard_pc.mdx#setup-folder)) -2. If a discovery server is intended to be run on the offboard computer then generate and run the discovery-server-start launch file. +2. If a discovery server is intended to be run on the offboard computer then generate and run the `discovery-server-start` launch script. To generate the launch script: @@ -238,5 +238,5 @@ ros2 run clearpath_generator_common generate_discovery_server -s ~/clearpath To launch the server ``` -bash -e ~/clearpath/discovery-server-start +bash -e ~/clearpath/discovery-server-start ``` diff --git a/docs_versioned_docs/version-ros2humble/ros/networking/network_ip_addresses.mdx b/docs_versioned_docs/version-ros2humble/ros/networking/standard_ip_addresses.mdx similarity index 99% rename from docs_versioned_docs/version-ros2humble/ros/networking/network_ip_addresses.mdx rename to docs_versioned_docs/version-ros2humble/ros/networking/standard_ip_addresses.mdx index 0292a290..131f646a 100644 --- a/docs_versioned_docs/version-ros2humble/ros/networking/network_ip_addresses.mdx +++ b/docs_versioned_docs/version-ros2humble/ros/networking/standard_ip_addresses.mdx @@ -1,6 +1,6 @@ --- -title: Network IP Addresses -sidebar_position: 4 +title: Standard IP Addresses +sidebar_position: 7 --- These are the standard addresses that Clearpath uses for custom robot configurations. diff --git a/docs_versioned_docs/version-ros2humble/ros/networking/wifi_fundamentals.mdx b/docs_versioned_docs/version-ros2humble/ros/networking/wifi_fundamentals.mdx new file mode 100644 index 00000000..1f2f03a8 --- /dev/null +++ b/docs_versioned_docs/version-ros2humble/ros/networking/wifi_fundamentals.mdx @@ -0,0 +1,102 @@ +--- +title: Wi-Fi Fundamentals +sidebar_position: 5 +--- + +Reliable wireless communication is crucial for operating mobile robots. This page covers essential Wi-Fi concepts including frequency bands, obstructions, interference and regulations. Understanding these concepts builds the foundation for making educated decisions about networking hardware and network design. Note that the recommendations discussed in this section are for optimizing the performance of a few robots on a dedicated Wi-Fi network, and may run counter to recommendations for configuring enterprise networks. + +## Wi-Fi Technology {#wifi-tech} + +### Wi-Fi Standards {#wifi-standards} +Wi-Fi standards are defined in IEEE 802.11 to ensure that all Wi-Fi devices are interoperable and offer a standard set of features. The Wi-Fi generations are often referred to by numbers or by the section of the standard, such as: + +| Wi-Fi Generation | Wi-Fi Standard | Frequency Bands Involved | +|------------------|----------------|--------------------------| +| Wi-Fi 4 | 802.11n | 2.4 GHz, 5 GHz | +| Wi-Fi 5 | 802.11ac | 5 GHz | +| Wi-Fi 6 | 802.11ax | 2.4 GHz, 5 GHz | +| Wi-Fi 6E | 802.11ax | 2.4 GHz, 5 GHz, 6 GHz | +| Wi-Fi 7 | 802.11be | 2.4 GHz, 5 GHz, 6 GHz | + +Using a newer Wi-Fi generation allows the system to take advantage of newer features, however both the router and the client must support this same newer generation and the antenna must support the frequency used. + +### Wireless Frequency and Wi-Fi Bands +The frequency of wireless communication impacts range, speed, and susceptibility to interference. Most commonly, ROS 2 robots are operated on the Wi-Fi bands of 2.4, 5 or 6 GHz. However, it is also possible to use other frequencies such as 900 MHz (802.11ah) depending on regional regulations and specific application requirements. It is important to make sure that the antennas used are suitable for the frequency bands used. Some routers have dedicated antennas for each band while others use multi-band antennas. + +It can be beneficial to get a system that allows for 2.4 GHz to be used as a backup to 5 GHz when 5 GHz signal strength is too low, and thus taking advantage of both frequencies. + +#### 2.4 GHz Band +This band has slightly longer range than 5 or 6 GHz for the same transmit power and antenna gain. However, this increase in range generally does not give better performance with clear line of sight because it starts off with much lower max data rates and is susceptible to interference from common devices such as Bluetooth, microwaves and other wireless systems. However, 2.4 GHz tends to operate better through obstructions. Wi-Fi 6 (802.11ax) offers benefits in data throughput over older Wi-Fi technology in this band. + +If choosing to use 2.4 GHz, efforts will generally need to be made to keep the system running on low bandwidth such as using Fast DDS Discovery Server and being strategic with which information is transmitted and in which format. + +#### 5 GHz Band +This band has a slightly shorter range compared to 2.4 GHz due to being a higher frequency. However, it provides significantly higher data throughput and thus by using a slightly higher gain antenna, it can perform much better than 2.4 GHz for the same range with clear line of sight. The higher frequency is more easily blocked or reflected by obstructions. The 5 GHz band tends to be less crowded because there are less devices operating on this band and there are more channel options. This is generally the best option for applications requiring high bandwidth such as video streaming, applications with clear line of sight at a distance and/or environments with multiple Wi-Fi networks. + +Within the context of ROS 2 and data heavy systems, it is possible to have a system that requires the throughput available only in 5 GHz or higher frequencies. When choosing which frequency band, it is important to consider how much bandwidth is required. Similarly it is important to try and limit how much data has to be transmitted wirelessly. + +#### 6 GHz Band +This is a newer band, only supported by Wi-Fi 6E and newer devices. Due to how new it is, it is sparsely populated. It has the least interference and highest speed. + +### Wi-Fi Channels, Channel Width and Interference {#channels} +Each Wi-Fi band has a series of channels. Each channel is centred at a designated frequency and each network will communicate over a particular channel or group of channels. Using a wider channel width means that the system is using several adjacent channels. Wider channel widths offer higher throughput but also greater chance of interference. Interference is based on how much other wireless traffic is also sharing the same or overlapping channels, and results in lower bandwidth, dropped connections and increased latency. + +It is important to understand that on the 2.4 GHz band, adjacent channels are overlapping. If operating with a 20 MHz channel width, then there are 3 possible channels that do not overlap (1, 6 and 11), while operating with a 40 MHz channel width means that there are only 2 options and they will always overlap and interfere with each other. At 5 GHz, only channels that do not overlap at 20 MHz are considered. There are 25+ channels available that do not overlap at 20 MHz channel width (depending on regional regulations). When using higher channel widths, communication will still span over many channels and increase the likelihood of interference between networks. That being said, there are 5+ non-overlapping channels available at 80 MHz channel width (depending on on regional regulations). This gives a lot more options than on the 2.4 GHz network. 6 GHz has even more channels available with more opportunities for channel widths as high as 320 MHz. + +The choice of channels and channel widths depends very much on the type of network being designed. The recommendations discussed in this section are for specific robot configurations and may run counter to recommendations for configuring enterprise networks. This is because the goals, restrictions and priorities of these systems are different. Do note that if the router is using the same Wi-Fi radio to broadcast a network and to connect to another Wi-Fi network as a client (for Wi-Fi as WAN), then both networks must use the same channel and channel width. + +In an outdoor system where there is one access point servicing a small number of robots (<10) and relatively little interference, the focus is on throughput. To maximize this throughput the channel should be chosen for the lowest interference and the channel width should be wide (80 MHz on 5 GHz and 40 MHz on 2.4 GHz). Functionally, it is often best to allow the router to automatically choose the channel and channel width. It will evaluate the best options based on evaluating interference in the immediate area. If the router does not support dynamic channel selection, then interference can be evaluated using a Wi-Fi analyzer phone app and an available channel with the least interference can be selected. This method will not catch non-Wi-Fi devices that share the same frequencies, however it is a good guide, particularly at 5 GHz. It is valuable to note that some devices have to decrease the transmit power to support larger channel widths. Whether this is a problem is something that should be evaluated by testing empirically with the devices in the operating area. + +In a system where there needs to be multiple access points to service many robots in the same area, it is important to select channels and channel widths so that the different access points are not causing interference for each other. In this case, automatic channel selection and channel width selection would be undesirable. + +In an indoor system where there is a lot of interference, it is important to work with the IT team that maintains the building Wi-Fi infrastructure. Likely this would result in using 20 MHz channel widths and setting the system to a particular channel to prevent interference with the building infrastructure. + +#### Additional Sources of Interference +It is important to note that interference comes not only from competing Wi-Fi networks but also other wireless devices that may share the same frequencies (such as Bluetooth) as well as electromagnetic noise from motors and similar devices. This electromagnetic noise is of a greater concern when communicating at lower frequencies such as 900 MHz, where the magnitude of the noise harmonics are greater. + +### Multi-Input Multi-Output (MIMO) {#mimo} +With modern Wi-Fi technology, it is possible to establish more than one simultaneous stream of data to increase throughput. A given router or Wi-Fi card supports a set number of spatial streams, also referred to as chains. Each chain generally requires its own antenna. For this to be most effective, the router should have the same number or more spatial streams as the robot. The theoretical maximum bandwidth between two robots will be limited by the device with the least spatial streams, although additional transmitting antennas can improve signal quality. In a multi-robot configuration, the router can use additional spatial streams to communicate with additional robots. In Wi-Fi 6E and later, this communication works in both directions, but with older Wi-Fi technology this benefit is only when transmitting data from the router to the robot and not both ways. + +### Data Rate vs Bandwidth +It is common for routers to quote very high data rates however it is important to understand the difference between these theoretical maximum data rates and actual possible bandwidth. The maximum possible rate is often used as a sales tactic and there are several large caveats to the advertised rates. First off, if a router can simultaneously communicate on multiple frequency bands, the maximum theoretical data rate at each of these bands is often summed together to calculate the advertised rate. Assuming that a system is exclusively on one frequency band, the maximum possible data rate is already much lower. For example, a router may be capable of 600 Mbps across 2 spatial streams at 2.4 GHz, 2400 Mbps across 2 spatial streams at 5 GHz and 2400 Mbps across 2 spatial streams at 6 GHz. This would get quoted as a 5400 Mbps router. However, if one device with two spatial streams were connected at 5 GHz the theoretical max speed would be 2400 Mbps or if it had only one spatial stream the theoretical max speed would be 1200 Mbps. + +The theoretical max data rate determined for a specific frequency band is still a theoretical maximum and does not reflect a reasonable bandwidth. This theoretical speed would be true assuming no interference, no obstructions, essentially no overhead to the protocols and essentially a no loss environment. In reality, there are many factors that contribute to lower speeds. A good rule of thumb is to expect no more than half of the theoretical maximum. If the interference is bad or the signal is weak (such as at long distances from the router) the actual bandwidth will be much lower. + +Additionally, the maximum data rate is not the only limiting factor. The bandwidth available to a particular device on a network may be much lower if there are an excessive number of clients or if the packets being sent are incredibly small. In these cases the overhead of routing packets and switching clients become the limiting factors and actual data rates are nowhere near the theoretical maximums. In these cases, the system needs more access points, not higher bandwidth access points. + +### Signal Strength +The strength of a Wi-Fi connection is referred to as RSSI (Received Signal Strength Indicator). There is an RSSI value for how well the client can receive from the router and one for how well the router can receive from the client. This value is measured as a negative dBm value and a higher number (closer to 0) is better. How this number is evaluated varies between devices but generally anything over -67 dBm is a good signal while anything under -75 dBm is not good. The required signal strength in order for a given system to work will depend on how much data throughput the system needs and how robust it is to dropped packets. + +Having physical objects near the antennas, between the receiving and transmitting antennas, or even too close to the direct path between the two antennas will result in lower signal strength. Obstacles that the signal would have to travel through significantly impede Wi-Fi signal, particularly at higher frequency bands. Different materials do impact signals differently, such as metal generally reflects Wi-Fi signals while materials such as glass and wood allow more penetration although the signal is still significantly attenuated. For indoor applications, walls that are brick or concrete will be much more detrimental to signal strength in comparison to drywall. If obstacle penetration is a concern then it may be beneficial to use a 2.4 GHz network. Antenna placement is discussed more in [Wi-Fi Hardware](wifi_hardware.mdx#placing-antennas). + +## Wi-Fi Regulations {#wifi-regulations} + +Wireless communication is regulated by government bodies, such as: + +- **ISED (Innovation, Science and Economic Development):** Canada +- **FCC (Federal Communications Commission):** United States + +It is important to understand the various types and significance of regulations that exist for wireless devices. Certain Wi-Fi channels are reserved for specific usage and are not available for everyone to use. Similarly, there are differences in power limits for different Wi-Fi channels. These regulations vary greatly between regions. The information below are examples of the types of regulations that may be in place and are not a reference for what is legal in any given region. It is your responsibility to check that your system complies with your local regulations. + +To assist in making your system compliant, ensure that the router(s) in the system have the correct regulatory approvals for the country where the system is operating. Some routers have different hardware versions for different countries, while others need the region set in the software. + +### DFS Channels +DFS (Dynamic Frequency Selection) channels are a section of channels that are used by weather and radar systems. To use these channels, a router must check that no radar systems are using these channels within range. During operation, if a radar message is detected then the router must switch channels. DFS channels are not commonly used and thus can be very useful for avoiding interference. However, if choosing to use DFS channels then the system must be equipped to handle a temporary break in communication if the system were to need to switch channels unexpectedly. Not all routers support DFS channels. + +### Transmit Power and EIRP +The conducted transmit power is the strength at which a Wi-Fi device transmits its signal, not including the gain from the antenna. At its core, a higher transmit power increases the range of the signal. This relates directly to the range in which the network is usable but also the range in which the network will cause interference. Due to the potential for interference, transmit power is limited on all channels, although not all channels have the same limits. Routers generally quote the transmit power for all chains combined, although it is important to verify this in the datasheet. When comparing routers with different numbers of chains, note that the transmit power is divided per chain. So for 2 routers that each have a total transmit power of 26 dBm, one with 2 chains and one with 3 chains, the 3 chain router will have higher throughput at close range due to the additional spatial stream but the router with 2 chains will have a further range due to the higher effective transmit power per chain. + +The effective transmit power across the complete transmission system is referred to as the EIRP (Equivalent or Effective Isotropically Radiated Power). It is calculated by taking the conducted transmit power (in dBm) and adding it to the gain from the antenna (in dBi) minus the loss from the antenna connectors and cables. Many regions have separate limits on conducted transmit power and EIRP on different bands. To ensure compliance with regulations it is important to look up the particular channels that are being used and to determine the maximum allowable transmit power and EIRP. + +While transmit power is critical to long distance and outdoor applications, it is important to understand that double the power does not result in double the range. The power density at a particular distance is proportional to the inverse square of the distance. In theory this means that a 6 dBm increase in power should double the range of the network however due to other factors such as interference and obstacles, this is rarely the case. Do note that unnecessarily high transmit power indoors can result in excessive reflections and excessive interference. To provide coverage for a large region indoors (with many surfaces to reflect signals), it is best to set up multiple access points as a mesh network, and utilize a lower transmit power. + +## Key Takeaways +- Newer Wi-Fi technology offers increased speeds and better connectivity (recommended to use Wi-Fi 6 or newer). +- Lower frequencies penetrate objects better, higher frequencies give much more bandwidth with clear line of sight. +- Choose channels with the least interference. +- Multi Input Multi Output (MIMO) generally increases throughput. +- Actual bandwidth is much lower than theoretical data rate. +- Antennas should be mounted away from any other object or surface (nothing beside them or behind them etc.). +- Ensure that your system complies with local regulations, especially in regards to allowable channels, conducted transmit power and EIRP. + +To continue building on this knowledge, read through the [Wi-Fi Hardware](wifi_hardware.mdx) page. \ No newline at end of file diff --git a/docs_versioned_docs/version-ros2humble/ros/networking/wifi_hardware.mdx b/docs_versioned_docs/version-ros2humble/ros/networking/wifi_hardware.mdx new file mode 100644 index 00000000..ed81926d --- /dev/null +++ b/docs_versioned_docs/version-ros2humble/ros/networking/wifi_hardware.mdx @@ -0,0 +1,172 @@ +--- +title: Wi-Fi Hardware +sidebar_position: 6 +--- + +Choosing the correct Wi-Fi hardware for a given application is very important to the quality of the network. Primarily this involves the selection of routers, antennas and cables, as well as the placement of each of these components. The following sections also contain several tips to get the most out of a Wi-Fi network. + +## Routers +When choosing a router, start by ensuring that the router supports the desired features mentioned in the [Wi-Fi Fundamentals](wifi_fundamentals.mdx) page. This includes: + +- Wi-Fi generation (recommended 6 or higher) +- Desired frequency bands +- Desired channels and channel widths (specifically DFS channels if desired) +- Auto channel and channel width selection if desired +- Desired number of spatial streams (at minimum match the number of streams supported by the clients) +- Appropriate certification for the region of operation +- Sufficient transmit power given the use case and antennas (may involve reducing the transmit power to stay within legal limits or for indoor usage) +- Consider a router with removable antennas for use cases that may require higher gain or directional antennas +- Advanced networking features (port forwarding, NAT, SSH, firewall, routing rules and more) +- The number of ethernet ports needed and that supports the desired data throughput +- Environmental compatibility (temperature, humidity and vibration ratings) +- Compatible power requirements (voltage and current) + +## Antennas +Antenna selection is incredibly important for system performance. It is very specific to the needs of a given project including the specific terrain where the system is operating, and the relative location and orientation of the antennas. Antennas are generally described using the following properties: + +- **Frequency Band**: Antennas are designed to work at particular frequencies. It is possible to get antennas that cover 2.4, 5 and 6 GHz bands in one antenna or individual antennas that are tuned for just a single band. +- **Gain**: This is the maximum gain value in the direction of highest gain. It is important to note that this peak gain could be only in one direction, see the radiation patterns to gain a better understanding of the overall gain in the region of interest at the frequency of interest. Higher gain does not mean higher power as a whole. Higher gain antennas focus all of the energy into a particular area, removing it from other areas. +- **Beam Width**: Beam width defines the angle where most of the antenna's power is directed, that is the angle where the network signal will be strongest. It is defined for both the horizontal and vertical planes. The beam width is the angle measured on the main lobe of the radiation pattern between the two points where the power is less than half of the maximum (-3 dBi). It is once again important to note, that this beam width may not be radially symmetric even on omni-directional antennas. It is important to look at the radiation pattern from different angles to identify any possible gaps in coverage. +- **Polarization**: Polarization of antennas indicates the direction of oscillation of the electric field in the waves emitted. It is important to match the polarization of the transmitting and receiving antennas, particularly outdoors where there are less reflective surfaces. Most common are linear vertical and linear horizontal polarizations but circular polarizations also exist. It is generally recommended to use vertically polarized antennas for most scenarios if there is enough space to mount them sufficiently far apart. +- **Impedance**: Typically this should be 50 Ohms for all Wi-Fi devices, and must match between the antennas, connectors, cables and radio. +- **VSWR (Voltage Standing Wave Ratio)**: VSWR is essentially a measure of efficiency for the antenna. More specifically, it is a measure of how well the antenna impedance is matched and how much power is transmitted vs being reflected back to the radio. The measure ranges from 1 to infinity with 1 being a perfect system. Realistically, anything less than 2 is good and anything under 2.5 is acceptable for Wi-Fi applications. +- **Max Input Power**: This is the power rating of the antenna where it will perform as specified. Generally the maximum allowable power for any WiFi channel is 30 dB or 1 Watt, so anything higher is acceptable. This is not generally a concern. +- **Multi in One**: Some antennas will be marketed as having multiple antennas in one body. These offer benefits of easy installation and not requiring as much space. However, they generally always have worse radiation patterns (with weak spots) and involve orthogonal polarization (discussed further in [Antenna Orientation](#orientation)). If maximizing connectivity is the priority then these should generally be avoided. +- **Radiation Patterns**: The radiation pattern is a description of how the power transmitted by the antenna is directed into the surrounding space. These can often be referred to in one word descriptions such as spherical omnidirectional (similar gain in all directions), donut omnidirectional (similar gain in all directions on the horizontal plane and low gain up and down) or directional (all energy focused in a single direction). This is only a rough description of what the radiation pattern is. The radiation pattern should always be evaluated using at minimum radiation pattern diagrams on the horizontal and vertical planes at each frequency, or at best with a full 3D model of the radiation pattern at each frequency. This information is generally provided in the datasheets of good antennas. For more information see [Radiation Patterns](#radiation-patterns). + +It is important to choose the correct antenna type for your application: +- For a stationary base station antenna servicing a large outdoor operating area, look for an omnidirectional antenna with a donut shape radiation pattern. This will have strong connection in all directions out from the antenna but not waste energy going down into the ground or up into the sky. This antenna should be mounted near the centre of the operating area to maximize range. If the antenna must be mounted at one edge of the region, consider a directional antenna although the total area serviced will be less than if the antenna were able to be mounted in the centre of the area. +- For a mobile application where the robot may be traversing hills or where there will be a significant height difference, consider an omnidirectional antenna with a more spherical shape radiation pattern. This will make the connection more robust to changes in angle and height of the robot. +- For a mobile application where the robot will be staying on a level surface and the antenna is a similar height to the base station antenna(s) consider a higher gain donut shape pattern. This will help maximize range and bandwidth. + +### Terrain and Vertical Beam Width + +It is important to match the vertical beam width of the antennas with the terrain, antenna heights and range. Especially at higher gains, the vertical beam width tends to be narrow and the signal strength outside of this beam width drops off more rapidly. The vertical beam width is reported as an angle. Using the [radiation pattern](#radiation-patterns), the location of this beam width relative to the horizontal plane can be determined. Knowing the desired mounting height of the antennas, simple geometry can be used to project the beam and determine which areas are within the beam width. For properly selected antennas, all communicating antennas should fall within or very close to each others' beams at all times. + +Consider an application with a central base station and a robot traveling around it. If the base station antenna is mounted high in the air with a narrow vertical beam width and the robot is low to the ground, also with a narrow beam width then it is possible that both antennas can never receive high signal strength from the other. Both beams go out mostly horizontal, passing by each other. In order for the region of highest gain to coincide with the opposite antenna, the robots would have to be very far away. This would be okay if the application were only for the robot to operate while being far away but signal strength would be low at long distance for any antenna mounted low to the ground. Therefore, raising the robot antenna to more closely match the height of the base station antenna would be ideal. + +In almost any case where there is a height difference between antennas, there will be a region when the antennas are close to each other, where there will not be good signal strength. An increase in antenna gain (resulting in a narrower vertical beam width) or increase in height disparity will make this region larger. Matching the antenna height addresses this, however this is before considering the impact of terrain that is not flat. + +If the terrain is not flat, then a larger vertical beam width on a stationary antenna may be used to add coverage for some lower or higher elevations, however any valleys beyond a hill would have a low signal strength. For a robot antenna, larger vertical beam width accommodates for the robot being on an angle when traversing hills and slopes. It is important to note that for good long distance communication, both this and the [Fresnel zone](#mounting-height) clearance should be satisfied. + +### Radiation Patterns +Radiation patterns are incredibly important and it is not recommended to buy an antenna without analyzing the radiation pattern. Antennas have different gain in different directions and the patterns will never be perfect. Well made antennas will have closer to ideal properties, with consistent gains and smooth shapes. Looking at peak gain or beam widths alone can give a false sense of security. For a peak gain to be accurate, it needs only to exist in one single direction from the antenna. There are omnidirectional antennas that will quote a good peak gain, however the radiation pattern shows that most of the directions have a gain that is -3 dB lower than the peak gain. This is not a good omnidirectional antenna. Similarly, the vertical beam width can be quoted for the best position on the main lobe while the opposite side has a much smaller beam width. This is why it is so important to inspect the radiation pattern directly. A big part of reviewing radiation patterns is to evaluate how balanced and well-formed the shape is, and then how well that shape matches the application. + +#### Evaluating Radiation Patterns +First it is important to understand that radiation patterns are plotted on a logarithmic graph. This means that the axis going out from the center of the circle is measured in decibels (dB). There are several ways that this axis can be labelled but common methods are: +1. The point of peak gain is 0 dB and all other gains are measured in negative decibels relative to that peak gain +2. The peak gain is marked as the quoted peak gain of the antenna in dBi and 0 dB is actually 0 dBi gain in reference to the input signal. + +Remember that in logarithmic graphs, -3 dB is half power and -6 dB indicates a drop to less than half of the distance to get the same signal strength. A signal may look like it drops off gently in the side view radiation pattern, but in fact it has dropped to -6 dB in only 5 degrees. This means that if the robot position is 5 degrees lower in relation to the base station antenna, then the range of the signal drops significantly. This has different levels of impact depending on the terrain, range and overall gain of the antenna. + +There are two 2-dimensional views of the radiation pattern that should be available in the datasheet for any good antenna. +1. The horizontal plane, or top down view. +2. The vertical / elevation plane, or side view +Sometimes two orthogonal vertical views will be shown, and sometimes a 3-dimensional render will be shown. More information is better in this case because it makes it easier to evaluate the antenna. Sometimes the 2-dimensional views may be superimposed on top of each other in the same graph or they may be presented separately, or they may be separate with superimposed lines for different frequencies. + +Antenna properties are very sensitive to the frequency being used. As a result, separate radiation patterns should be shown for each section of a frequency band. Generally higher frequencies will result in more narrow lobes. Review all of the following points with the radiation pattern diagrams for each frequency that is being used. + +For an antenna with an omnidirectional or donut shaped pattern: +- Is the peak gain located on or close to the horizon + - If the peak gain is in a direction that would not be used in normal operation then it is not a very accurate measure of the effective gain that will be seen in operation. Use the radiation pattern to estimate an average gain for the directions that will be used in operation + - Example: Some antennas have the strongest gain slightly above the horizon. This is good for robots that are low to the ground. Some antennas have the strongest gain slightly below the horizon. This is good for base stations that are mounted high to service a large range. +- How rotationally symmetric is the horizontal plane? (ideal case it would be a perfect circle centered on the antenna) + - If a significant portion of the horizontal plane is -3 dB from the peak then that indicates that a significant area will not have the expected gain or signal strength + - If there are directions in which the gain drops lower than -3 dB from the peak, then there will be weaker signal in those specific directions. It is important to determine if those are directions that matter. Some discretion needs to be made on how sharply signal drops in these directions and the potential impact. +- Is the quoted vertical beam width accurate for each direction on each frequency. Sometimes the vertical beam width is only measured on the main lobe in the best direction so it is recommended to estimate the worst case and the average vertical beam width yourself. + +For directional antennas the process is very similar but instead of evaluating for circular symmetry on the horizontal plane, the vertical plane considerations are used instead. The horizontal plane is also judged for beam width and lobe shape. + +**Example 1** + +The datasheet for this antenna quoted an 8 dBi gain, 20 degree vertical beam width and 360 degree horizontal beam width. This information may be true for certain frequencies and certain directions but it does not tell the whole story. + +
+
+ +
+
+ +In this case the side view or elevation plane is shown in red, and the top view or horizontal plane is shown in black. The outer ring of the circle is measured as 0 dB and indicates the peak gain of the antenna. The blue dotted line is the -3 dB line, marking the point of half power which is used to measure beam width. Additional lines are marked to indicate every 10 dB with the scale labelled within the circle + +Starting with the horizontal plane (black line), the radiation pattern is not very rotationally symmetric. In fact, from -45 degrees clockwise to 150 degrees the gain is less than the dotted blue line and therefore less than half power. As a result, the horizontal beam width is not actually 360 degrees. From roughly 55 degrees to 65 degrees the gain is at -6 dB which will result in half of the range. A similar pattern is visible in the vertical plane (red lines). In one direction, the vertical beam width of 20 degrees is plausible, however in the opposite direction the gain never passes -3 dB. This slice of the radiation pattern is not even at the worst position or else that measurement would have been -6 dB as was seen in the horizontal plane. These patterns suggest that this antenna is not a good omnidirectional antenna and will not provide consistent performance. + +**Example 2** + +The datasheet for this antenna quoted a 7 dBi gain and did not list the beam widths. + +
+
+ +
+
+ +In this case the horizontal plane is shown on the left and the vertical plane is shown on the right, with all frequencies overlapped on each diagram. The gain is measured in dBi so 0 on the graph is 0 dB gain relative to the input signal and the peak gain should match the peak gain quoted for the antenna. The scale for the rings of each circle is shown on the far left. Each ring is 2.5 dB from its neighbor and the colors alternate. It can be helpful to print these diagrams out to analyze them. + +Starting with the horizontal plane, the radiation pattern is relatively rotationally symmetric and centered around the antenna. The shape is slightly elongated with the peak gain at 90 degrees and 270 degrees. The shape is not bad though because the gain only drops by roughly -2.5 dB from the peak and largely affects 60 degrees on each side. The vertical plane also shows a symmetric shape, and relatively consistent patterns over different frequencies. Most of the energy is focused outwards, not up or down. The vertical beam width can be measured as roughly 15 degrees centred on the horizon. This is good for relatively flat terrain. + +### Placing Antennas + +#### Obstructions + +Consider Wi-Fi signals similarly to visible light. The waves are always impacted by objects. There are materials that the waves are blocked by, materials that the waves can pass through but where they become much weaker, and materials that they can pass through more freely. Any object or wall will interfere with Wi-Fi signals. Metals tend to be the worst as the signals are largely reflected, but any obstruction affects Wi-Fi signals. + +There should ideally not be any obstructions between the transmitting and receiving antennas. For this discussion, consider the application of antennas on an outdoor robot controlled from a base station. At any given time, the base station antennas could be in any direction around the robot within an angle of the horizontal plane that can be calculated based on the terrain. This means that when looking at the robot from any such angle, there should be a clear view of all of the antennas. If an antennas is obstructed (not clearly visible) then the signal to or from that antenna will be poorer. + +Do note that while visible light is a good parallel to use to understand Wi-Fi signal obstruction, see-through or perforated surfaces still attenuate Wi-Fi signals and should be considered moderate obstructions. + +#### Spacing + +Antennas must be placed a minimum of half a wavelength apart. For 2.4 GHz that is 6.5 cm (or 2.6 inches) and for 5 GHz that is 3.0 cm (or 1.2 inches). This minimum distance is to reduce the coupling between the antennas, a phenomenon that degrades performance. However, additional distance between antennas continues to improve performance. + +#### Orientation + +Antenna orientation matters for two main reasons: + +**Signal Polarization** + +The emitted signals have a polarization, and two antennas are isolated from each other if they have perfectly orthogonal polarization. That means that if two antennas with the same linear polarization were mounted one vertically and one horizontally, they would have very poor signal strength even at close range. In contrast, the strongest signal is obtained if the two antennas are mounted perfectly parallel to each other. That way no power is lost due to any difference in polarization. Most commonly antennas have linear vertical polarization, but it is important to check the datasheet to confirm, particularly when multiple different types of antennas are being used together in the same wireless network. + +It is possible to use orthogonally polarized antenna pairs. In other words, there could be one horizontally polarized and one vertically polarized antenna on each of the robots and on the base station. This is less than ideal because it now means that each antenna on the robot can only communicate with one of the antennas on the base station. If the antennas were all aligned such that a mismatched pair is closest and obstructing the matching antennas then the performance would be worse than if all antennas had the same polarization. That being said, orthogonally polarized antenna pairs can still be useful when there is not enough space to mount the antennas at the required spacing on the robot. In that case it is important to then match the polarization on the base station, mounting both a horizontal and vertical polarized antenna on the base station as well. + +**Radiation Pattern** + +The radiation pattern is relative to the orientation of the antenna. For donut shaped radiation patterns, this means that if the antenna is on an angle, then one side of the donut goes down into the ground and the opposite side goes up into the air. Neither of these are generally useful for ground robots. If the antenna is pointed up, perpendicular to the overall terrain, then that will maximize the useable range of the signal. + +#### Mounting Height and the Fresnel Zone {#mounting-height} + +When trying to establish long distance wireless connectivity (over 100 m), it is important to understand the concept of a Fresnel zone. The Fresnel zone is an ellipsoidal region enveloping both the transmitting and receiving antennas that must be unobstructed for best signal transmission. This is due to the behavior of how wireless signals reflect off of surfaces, sometimes resulting in destructive interference, essentially cancelling out the original transmission. Keeping the primary Fresnel zone clear significantly decreases interference caused by this phenomenon. It is important to understand that this zone also extends below and behind the antenna as reflections from this region can also cause interference. + +The size of the Fresnel zone is calculated based on the signal frequency and communication distance. There are many Fresnel zone calculators available online. The Fresnel zone indicates how high the antennas must be mounted above the highest obstruction. The rule of thumb is that the primary Fresnel zone should ideally be at least 80% unobstructed, but not worse that 60% obstructed. It is possible to run systems at higher levels of obstruction but significant consideration must be made to how poor the connectivity will be and how low the data rate will be. + +For example, in a system where the robot is operating up to 300 m away from the base station, the Fresnel zone has a maximum diameter of 2.1 m (7.0 ft) for 5 GHz communication or 3.0 m (10.0 ft) for 2.4 GHz. Assuming there are no obstructions other than the ground, both the robot and base station antennas would need to be mounted at that height for a fully unobstructed Fresnel zone. If one antenna could not be mounted that high then the Fresnel zone ellipsoid could be angled and the appropriate heights could still be calculated. However, the radiation patterns of the antennas must be considered, to ensure the antennas are appropriate given the terrain. + +## Antenna Cables and Connectors {#cables} + +Antenna cables are not all the same. Wi-Fi signals can be attenuated greatly by inferior cables. Irrelevant of cable quality, it is advantageous to make the cables as short as possible, ultimately placing the antennas and router or network interface card as close together as is reasonable. + +To evaluate the impact of a given cable, estimate the signal loss from the connectors and the cabling. It is a rule of thumb to assume a loss of 1 dB for every connector pair in the path, essentially for every additional cable used. That being said, the quality and type of connector impacts the actual loss. The datasheet for the cable should state the loss for a given frequency and length. If buying a prebuilt cable assembly, the datasheet or drawing may only indicate the type of cable, and the cable datasheet must then be referenced. + +Consider connecting a router and antenna with a 3 m (10 ft) cable made of LMR 195 equivalent cabling to communicate at 5 GHz. LMR 195 cable has an attenuation of 98.1 dB/100 m (29.9 dB/100 ft) and one single cable with a connector at each end is an assumed loss of 1 dB. This would have the following estimated loss calculation: +``` +estimated loss = 3 m * 98.1 dB/100 m + 1 dB +estimated loss = 3.9 dB +``` + +This loss is moderate. Recall that a loss of 3 dB is a loss of half power and that a loss of 6 dB is equivalent to losing half of the range or dropping to only 25% power. If range or bandwidth is the priority, then this application would be recommended to get a higher quality cable or shorter cable. If LMR 240 equivalent cable was used, it would be an estimated loss of 3 dB. Both of these example cables are acceptable cables for use at 5 GHz, however, there are many cables available that are only suitable for very short distances or low frequencies. Try to keep antenna cables as short as possible, use as few connectors as is reasonable and use the distance to calculate what quality of cable is needed to keep the loss acceptable. + +## Key Takeaways +- When choosing a router, consider all of the desired features. +- Higher antenna gain means that the signal will get focused more in certain regions: better signal in one region always means worse signal in a different region. +- Antenna selection is application specific and involves considering the range, direction and terrain. +- Always evaluate the radiation pattern of an antenna before choosing it. +- Never obstruct antennas and ensure that they are mounted at least 6.5 cm (or 2.6 inches) apart for 2.4 GHz. +- Be mindful of antenna orientation and polarization. +- When transmitting long distances (over 100 m), consider the Fresnel zone when choosing mounting height. +- Keep antenna cables short with fewest possible connectors, and use high quality cables to reduce loss. \ No newline at end of file diff --git a/docs_versioned_docs/version-ros2humble/ros/tutorials/video_over_wifi.mdx b/docs_versioned_docs/version-ros2humble/ros/tutorials/video_over_wifi.mdx index 9ba33b6a..695f0359 100644 --- a/docs_versioned_docs/version-ros2humble/ros/tutorials/video_over_wifi.mdx +++ b/docs_versioned_docs/version-ros2humble/ros/tutorials/video_over_wifi.mdx @@ -1,28 +1,28 @@ --- -title: Video over WiFi -sidebar_label: Video over WiFi +title: Video over Wi-Fi +sidebar_label: Video over Wi-Fi sidebar_position: 6 toc_min_heading_level: 2 toc_max_heading_level: 4 --- -Cameras can be challenging to work with as they produce large amounts of data which can overwhelm networks. They must be configured for a particular use case and networking configuration. This tutorial will go over the process of configuring a system with a 6 megapixel camera for use in teleoperating the robot over a WiFi network. However, the same concepts can be applied to any camera and any use case. +Cameras can be challenging to work with as they produce large amounts of data which can overwhelm networks. They must be configured for a particular use case and networking configuration. This tutorial will go over the process of configuring a system with a 6 megapixel camera for use in teleoperating the robot over a Wi-Fi network. However, the same concepts can be applied to any camera and any use case. ## Getting to Know the System ### The Robot -In this example, the robot computer is running the Clearpath ROS 2 packages and is directly connected to a 6.3 MP FLIR Blackfly camera via USB. The camera has been properly configured in the `robot.yaml` as per [YAML Camera Configuration](../config/camera_compression.mdx). The robot networking has been configured as FastDDS Discovery server and is configured in the `robot.yaml` as per [YAML System Configuration](../config/yaml/system.mdx). The robot computer has then been connected to the local area WiFi network. +In this example, the robot computer is running the Clearpath ROS 2 packages and is directly connected to a 6.3 MP FLIR Blackfly camera via USB. The camera has been properly configured in the `robot.yaml` as per [YAML Camera Configuration](../config/camera_compression.mdx). The robot networking has been configured as FastDDS Discovery server and is configured in the `robot.yaml` as per [YAML System Configuration](../config/yaml/system.mdx). The robot computer has then been connected to the local area Wi-Fi network. ### The Offboard Computer -The offboard computer, from which the user will be teleoperating the robot, has been set up using the [Offboard Computer Setup Instructions](../installation/offboard_pc.mdx). The offboard computer is also connected to the same WiFi network as the robot. +The offboard computer, from which the user will be teleoperating the robot, has been set up using the [Offboard Computer Setup Instructions](../installation/offboard_pc.mdx). The offboard computer is also connected to the same Wi-Fi network as the robot. Full ROS 2 communication has been tested between the offboard computer and the robot computer, and the operator is able to control the robot using [Keyboard Teleoperation](driving.mdx#keyboard-teleoperation). -### The WiFi Network +### The Wi-Fi Network -It is important to understand the capabilities of a given network and to have realistic expectations of what data can be transmitted over the network. A router is advertised with a theoretical maximum bandwidth, however, that is in optimal conditions and may involve summing maximum theoretical bandwidths across multiple frequency bands. This is not representative of how much bandwidth will realistically be available to a single device on a particular frequency channel. Instead, network bandwidth should be tested empirically for a given set of hardware in a given environment. Many variables impact the available bandwidth including interference from other networks, obstacles such as walls or trees, and the WiFi hardware itself. A tool such as [iperf3](https://iperf.fr/) can be used to evaluate the usable bandwidth of a WiFi network. +It is important to understand the capabilities of a given network and to have realistic expectations of what data can be transmitted over the network. A router is advertised with a theoretical maximum bandwidth, however, that is in optimal conditions and may involve summing maximum theoretical bandwidths across multiple frequency bands. This is not representative of how much bandwidth will realistically be available to a single device on a particular frequency channel. Instead, network bandwidth should be tested empirically for a given set of hardware in a given environment. Many variables impact the available bandwidth including interference from other networks, obstacles such as walls or trees, and the Wi-Fi hardware itself. A tool such as [iPerf3](../networking/network_troubleshooting/network_troubleshooting_tools.mdx#iperf3) can be used to evaluate the usable bandwidth of a Wi-Fi network. To directly test the available bandwidth and simulate the robot sending large amounts of data to the offboard computer, the `iperf3` server was run on the offboard computer and the `iperf3` client was run on the robot. This test was run for both TCP and UDP messages to understand the capacity for different types of communication, although by default FastDDS communicates only using UDP. This test was repeated with the robot in different locations all around the operation space, including the furthest and most obscured areas. A system should be designed to be fully functional in all areas of the operational field. If the connection is insufficient in those furthest regions then the network must be improved. @@ -54,7 +54,7 @@ In conclusion, something must be done if this camera is to be used for teleopera ### Binning -One option for reducing the size of the image is to use binning. There are several different mechanisms by which this can be done depending on the camera and driver, but ultimately it increases the size of the pixels and reduces the resolution. Enabling binning with the Blackfly camera reduces the processing required for debayering and ultimately reduces the load on the computer. Setting binning in x and y both to 2 reduces the overall image size to a quarter. The resultant image is 1536x1024 pixels, or 4.7 MB per image, which is more than the resolution requirement of 1280x720. At this reduced resolution, it would take 570 Mbps to transmit at 15 FPS. This is somewhat reasonable to transmit over 1 Gbps ethernet connections but is still too large to transmit over WiFi. +One option for reducing the size of the image is to use binning. There are several different mechanisms by which this can be done depending on the camera and driver, but ultimately it increases the size of the pixels and reduces the resolution. Enabling binning with the Blackfly camera reduces the processing required for debayering and ultimately reduces the load on the computer. Setting binning in x and y both to 2 reduces the overall image size to a quarter. The resultant image is 1536x1024 pixels, or 4.7 MB per image, which is more than the resolution requirement of 1280x720. At this reduced resolution, it would take 570 Mbps to transmit at 15 FPS. This is somewhat reasonable to transmit over 1 Gbps ethernet connections but is still too large to transmit over Wi-Fi. ### Compression Method Selection