Skip to content

Quickstart

v3xctrl is an open-source system for controlling RC vehicles and streaming live video over 4G/LTE networks. It consists of a streamer (Raspberry Pi-based) that captures video and receives control inputs, and a viewer application (Windows, Linux, Android) that displays the video feed and sends your commands.

This guide is meant to get you up and running as quickly as possible. It is structured in such a way that you can set things up step by step, validating correct functionality in each step.

1. RPi Setup

Prerequisites

  • A Raspberry Pi Zero 2 W - without soldered pins
  • A good quality SD card - preferably 32GB, Class 10, U3
  • Power supply to power the Raspberry Pi

Follow the Streamer installation guide.

Validation

You can connect to the web interface at http://v3xctrl.local in your browser.

2. Viewer Setup

Prerequisites

  • A computer (Windows or Linux) on the same network as the streamer
  • The following ports open on the machine running the viewer (you might need to forward them through your router):
    • 16384: UDP for receiving video (UDP & TCP for running self-tests)
    • 16386: UDP for receiving UDP messages

The Viewer is where the video feed will be displayed and your inputs connect to, basically the UI you will use to control your streamer.

Download, extract and run the GUI for your operating system from the releases section.

Take note of the internal IP address of the machine you are running the viewer on. It has to be in the same network that you set your streamer up to connect with in step 1.

Validation

The viewer application starts and shows a window waiting for a connection.

3. Initial configuration

Prerequisites

  • Completed step 1 and step 2
  • The viewer is running
  • You know the internal IP address of your viewer machine

While keeping the viewer running, open the streamers web interface: http://v3xctrl.local. In the server section make sure "Connection Mode" is set to "direct". In the Host field, set the internal IP address of your viewer machine which you have established in step 2. Scroll to the bottom and click "Save".

Now switch to the "Services" tab, find the v3xctrl-control service and click the "Start" button.

On the viewer open the menu by pressing Esc, switch to the "Streamer" tab and click the "Start Video" button, click "Back" on the bottom right and after a couple of seconds you should see a test image in the viewer.

Congratulations - you have established your first connection!

In the web interface you can now set the control service to autostart on boot. Click the "Config Editor" tab, scroll down to "Autostart" and check "control". Scroll to the bottom and click "Save".

Validation

  • In the viewer the "Latency" and "Data" fields are changing
  • The "No control signal" message has disappeared
  • A test image is visible in the viewer

4. Camera configuration

Prerequisites

  • A Raspberry Pi Zero 2 W compatible camera
  • Some cameras may need additional setup. You can check out the Hardware section of the wiki for instructions.

Shut down your streamer via web interface and attach your Raspberry Pi Zero 2 W compatible camera. Double-check the polarity of the CSI connector. Once attached, power it up and wait for the web interface to be available.

With the viewer running, you will have an indication once the control service autostarts and connects to the viewer. Now open the web interface, scroll down to the "Video" section and expand it. Scroll down to the "Test image" checkbox and uncheck it. Scroll to the bottom and click "Save".

On the viewer, open the menu by pressing Esc, switch to the "Streamer" tab and click the "Start Video" button, click "Back" on the bottom right and after a couple of seconds you should see the camera image in the viewer.

Validation

The camera image is visible in the viewer instead of the test image.

5. Peripherals

Following the pinout guide, connect your hardware. You can attach everything at once, or do it step by step for easier debugging. Attaching things step by step will make your life easier since you will only ever have one thing to debug before progressing to the next step, being confident that what you just set up is actually working.

5.a Servo and ESC

Prerequisites

  • ESC
  • Servo

ESC should be connected to GND and PWM1, Servo should be connected to GND and PWM2.

Warning

Before powering up the streamer, make sure that your vehicle is in a safe position. Depending on your ESC, your motor might start to spin if calibration is not yet done.

Make sure ESC has power and the servo is being powered from the ESC too. Start the streamer.

Servo

If the servo is moving in the wrong direction, go to the "Controls" section, expand it, scroll down to "Steering" and check the "invert Steering" checkbox.

You can go through the full Calibration step now, or leave it for after you are done with the base configuration.

Validation

Once connected to the viewer, use W, S, A, D to test that ESC and Servo are reacting to inputs.

5.b Power supply

Prerequisites

  • 5V power supply, preferably a high-quality 5V buck converter powered from a Lipo battery

Before connecting the 5V power supply, make sure the Raspberry Pi is no longer powered via power brick. Connect the 5V power supply to 5V and GND. Double-check polarity.

Validation

The streamer boots from your power source and the web interface is accessible.

5.c Voltage sensor

Prerequisites

  • INA231 or INA226

Voltage sensor is not mandatory, but highly recommended if you want to get the most out of your batteries. Connect the INA of your choosing to 3.3V, GND, SDA and SCL. Finally connect the VBUS pin of your INA to the battery positive plug.

Note

The INA by default uses the I2C address of 0x40 and will be automatically picked up on boot if attached.

Validation

Attach your power source, wait for the streamer to boot up and verify with the viewer that voltage telemetry is being transmitted.

6. Modem Setup

Prerequisites

Now that everything has been tested on the local network, the last step is to add the modem. Follow the steps in the SIM card documentation to prepare your SIM card. Insert the SIM card into your modem and attach the modem to the streamer.

Boot up the streamer, use the web interface http://v3xctrl.local and go to the "Modem" tab.

Note

For the "Modem" tab to show details, you have to make sure that the control service is not running, you can stop it from the "Services" tab

Confirm the following details:

  • "SIM Status" shows OK
  • "Carrier" is not null
  • "Context 1" is set to IP xxx.xxx.xxx.xxx (yyy)

If those above points are true, then you are ready to stream over your mobile network.

Go to the "Config Editor" tab, in the Server section enter the external IP address of your viewer (you can use whatismyipaddress.com to find it, if you don't know it), scroll down to "Network", expand, scroll to "routing" and select "RNDIS". Further down in the Modem section, select the "Model" of your modem. Scroll to the bottom and click "Save".

Warning

After changing routing type you will have to restart the streamer.

Validation

  • The OSD in the viewer shows Latency and Modem details in the upper right corner
  • To make absolutely sure the modem is being used to transmit data you can connect to the streamer via ssh and use nload to verify the network device being used. If you see traffic on eth0, that is the modem.

7. Next steps

Congratulations, now that the base setup is completed, there are a couple of things you can do next:

This guide covers direct connections. For relay and spectator modes, see Connection Types.