Freedom Robotics

Freedom Robotics Developer Hub

Welcome to the Freedom Robotics developer hub!

You'll find comprehensive guides and documentation to help you start working with Freedom Robotics as quickly as possible, as well as support if you get stuck. Let's jump right in!

For guides to setting up a device and using Freedom's core features, choose Get Started. If you'd prefer to jump in by yourself, choose Reference for detailed interface specifications.

Get Started    API Reference

Common WebRTC Issues

See also: how WebRTC connections work

WebRTC's video and data streaming allows for direct peer connections between the robot and the browser without knowing the exact IP of each and also without being on the same networks. The result is lower latency and higher bandwidth sessions.

To accomplish this, many different technologies in the stack have to work together and sometimes making them work is not easy. WebRTC tries to automatically adjust bandwidth to recover, but may need specific tuning for your use case.

In the Freedom device settings, you can adjust settings to optimize for your specific environment:

Adjustable Settings:

  • WebRTC Max Bandwidth - This specifies the maximum bandwidth the WebRTC stack can use for compressing video. For LTE and other limited connections, we recommend lowering it from the default if you are seeing issues.
  • WebRTC Max FPS - The system defaults to 10 FPS. You can adjust down to 1 FPS or up to 15FPS. For driving a robot, many times, 5FPS is acceptable and will significantly cut necessary bandwidth.
  • Topic Bandwidth - If your topic data uploads are taking up too much bandwidth, it may starve WebRTC. Specifically, do not set your image topics higher than 1-2 FPS. The WebRTC connection will promote itself to a higher FPS independent from this.

Recommended connection:

  • 500 Kbyte/s minimum dedicated to WebRTC - This does not include other services or topic data uploads. We recommend 1.2Mbyte+/s for quality connections and browsers will try up to 3-4Mbyte/s for high quality ones.
  • Dual-sim modem - If you have a mobile robot, we recommend a dual cell card modem such as the Peplink or Cradlepoint product lines. With two sim cards (from different networks) and high-quality antennas, you will see a significant increase in the quality of your connections.

First steps in debugging WebRTC:

  • Validate if it works on a high-bandwidth network - Try it on a known quality wifi or wired network and check your maximum bandwidth. You can run sudo apt-get install speedtest-cli && speedtest-cli --bytes to see what your connection speed is. If it is greater than a few megabytes, then you should be fine.
  • Check topic bandwidth - Check your device's System Measurement tab and look at your topic bandwidth. If you are seeing a queue of messages to upload which spikes into the hundreds, then the connection is not keeping up.
  • Use Chrome Browser - Chrome has the best debugging and WebRTC support, followed by Firefox. Microsoft Edge and other platforms may not fully work.
  • Check firewalls - Try running on a different network - some corporate networks limit specific protocol's connectivity, so running on a hotspot or different network with normal connectivity may solve the issue.

Common Issues and Solutions

Below are some of the more common issues users encounter with WebRTC in general and solutions or optimizations you can do with Freedom's platform.

If your session disconnects randomly

Below are some of the reasons a session may disconnect:

  • A moving robot may have hit a dead spot in wifi - Check your wifi connectivity and signal strength.
  • IP address changes during a session - There are multiple steps in routing WebRTC packets. If the public IP of the robot changes along that route (ex: If a Verizon MIFI changes it then the WebRTC connection will be lost as data will not be routed to the new IP. You can check the public ip of a device by running curl ifconfig.me or similar, and use iwconfig and ifconfig to check for your local IPv4 settings.
  • Wifi network is changed during a session - If a computer loses a wifi network and swaps to a new SSID or base station, then the gap can disconnect it. If the IP address stays the same, then it will come back automatically. If it fully swaps networks, then you will need new routing and should click reconnect.
  • Wifi disconnection - If the network or wifi is disconnected, you will need to get it back on the network then reconnect.
  • Wifi poor signal - WebRTC needs a minimum Kbps to function. If an area exists in a network with very low quality, the WebRTC protocol may disconnect. Suggest using speedtest-cli --bytes to test connection bandwidth and also nmcli dev wifi to check wifi connection rate and signal strength (alternatively you can use iwconfig).
  • Extremely high CPU usage doesn't allow compression - we see on some machines, that a machine learning or other process can take multiple cores worth of CPU. If it is starving other processes, this can lead to the compression algorithms not having enough CPU to function. You can check this in the System Measurement tab of your device.
  • Firewall blocks the connection - see below

If you have high latency or jerky video

If you are seeing lag in your video or controls, here are a reasons and possible solutions:

  • On your robot, sometimes there are delays in sending video due to pipeline length for algorithms, delayed messages, etc. Check that you have locally fast video.
  • Try ping google.com to test your connection's overall latency. If it is > 50 msecs, then you should check out why that is happening. If you see it > 250 msecs, then your may have a very unstable WebRTC connection.
  • If you are running on a cellular modem, try running on a known-quality Wifi network to see if this resolves the issue. Many cell modems have lower quality areas where latency can be up to 1000msecs and performance is not acceptable for WebRTC.
  • In the Freedom app, press ~ while connected over WebRTC and you will see a diagnostics screen appear. Check what the latency, bandwidth and other values are. You can then run speedtest-cli --bytes to see what your connection's max speed is. You can lower the WebRTC bandwidth and FPS in the SETTINGS -> BANDWIDTH tab for your device.

If you can't connect with WebRTC at all

If the system can't create a webrtc session:

  • Check that in the advanced install settings for your device, you have selected to enable WebRTC. If it was not enabled, please enable it then re-install and try again.
  • Firewalls can stop WebRTC Connections - some corporate networks block specific ports and protocols and only whitelist certain applications. Please try on a different hotspot or tether to your phone to try it out and check firewalls and NAT settings.

The following outgoing ports need to be opened for WebRTC to work properly:

  • 80 and 443: to connect to the Freedom API
  • 3478: client port 1; needs to be outbound open for both devices.
  • 19302: client fallback port: needs to be outbound open for both devices
  • 5349: secure TURN connections

Why do I need these outbound ports open?

The freedom robotics agent needs to communicate with STUN and TURN servers in order to establish a successful WebRTC connection, and these servers are listening in these ports. Opening outbound ports simply means that an application inside your network can reach a server in these ports, but that DOES NOT mean anyone from the outside can reach your network at these ports.

Updated 3 months ago

Common WebRTC Issues


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.