Connections Troubleshooting

Connect to your Voyant sensor from the terminal, and troubleshoot network issues.

Most users don’t need this page. Setting up a connection — configuring your computer’s static IP through your OS network settings — is part of the Quick Start for your OS: Ubuntu or Windows, done before you verify the connection. Use this page only if you prefer to set up and connect from the terminal, or need to troubleshoot.

This guide explains how to set up UDP connections between a Voyant Carbon sensor and the API tools.

A Carbon sensor delivers its point cloud over UDP either by unicast (the default — the sensor replies directly to the host that connects) or by multicast (opt-in — several hosts can receive one sensor’s stream at once). See Selecting the Transport below for the command-line flags, or the Quick Start for what each option means and when to use it.

Network Setup for Sensor Connection

Before connecting to a Voyant sensor, your computer needs a static IP on the sensor’s subnet. Most users should set this up through their OS network settings — see the Quick Start for Ubuntu or Windows. The steps below are the command-line equivalent:

Identify your network interface - Use ip addr to list all network interfaces

Common interface names by platform:

Linux with classic naming: eth0, eth1, etc.
Linux with predictable naming:
- eno1 (onboard devices)
- enp0s31f6 (PCI bus/slot based)
- enx followed by MAC address (e.g., enx78e7d1ea46b2) for USB/external adapters
macOS: en0, en1, etc.
Windows: Usually identified by descriptive names in network settings

Regardless of OS, the ip addr command will return something along the lines of:

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
 link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
 inet 127.0.0.1/8 scope host lo
    valid_lft forever preferred_lft forever
 inet6 ::1/128 scope host
    valid_lft forever preferred_lft forever
3: wlp0s20f3: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
 link/ether a8:64:f1:2a:1d:e5 brd ff:ff:ff:ff:ff:ff
 inet 192.168.0.113/24 brd 192.168.0.255 scope global dynamic noprefixroute wlp0s20f3
    valid_lft 85341sec preferred_lft 85341sec
 inet6 fe80::efd1:d36:adf:b6ee/64 scope link noprefixroute
    valid_lft forever preferred_lft forever
4: docker0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc noqueue state DOWN group default
 link/ether 02:42:5a:1c:1d:ae brd ff:ff:ff:ff:ff:ff
 inet 172.17.0.1/16 brd 172.17.255.255 scope global docker0
    valid_lft forever preferred_lft forever
 inet6 fe80::42:5aff:fe1c:1dae/64 scope link
    valid_lft forever preferred_lft forever
32: enxf8e43bb23b58: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
 link/ether f8:e4:3b:b2:3b:58 brd ff:ff:ff:ff:ff:ff

In this case, the last socket (enxf8e43bb23b58), is likely the LiDAR, as the “enx” denotes an interface from an ethernet cable.

Configure the network interface with a compatible IP address - The sensor uses the 192.168.1.x subnet

Linux:
```
sudo ip addr add 192.168.1.100/24 dev <YOUR_INTERFACE_NAME>
sudo ip link set <YOUR_INTERFACE_NAME> up
```
macOS:
```
sudo ifconfig <YOUR_INTERFACE_NAME> inet 192.168.1.100 netmask 255.255.255.0
```
Replace <YOUR_INTERFACE_NAME> with your actual network interface name (e.g., eth0, eno1, en0, etc.). Following the example ip addr return above, the network interface name would be enxf8e43bb23b58.

Note for Linux users: If you ran both of the lines as one command in your terminal and the connection to the LiDAR failed or seems unstable (which you can test in the step after this one), try running the above lines as two separate commands instead.

Verify the configuration

ip addr show <YOUR_INTERFACE_NAME>  # Linux
ifconfig <YOUR_INTERFACE_NAME>      # macOS

Check connection to device

By default, Voyant LiDAR devices ship with a static IP of 192.168.1.128. Check that you can reach the sensor with:
```
ping 192.168.1.128
```
A successful connection will show ping responses with time statistics and 0% packet loss. It will look something like this:
```
PING 192.168.1.128 (192.168.1.128) 56(84) bytes of data.
--- 192.168.1.128 ping statistics ---
```
If your terminal does not show any response to your pings from the LiDAR after an extended period of time (10 seconds or so), kill the command with ctrl + c, then check if your LiDAR’s socket is still present using ip addr. If it is not, check the physical ethernet connection and try again. If it is, then try rerunning the commands in the previous step (Configure the network interface with a compatible IP address).

Selecting the Transport

You connect to a Carbon sensor the same way regardless of transport — the client always joins the multicast group, and the bind, group, and interface addresses are the same either way (detailed under For Receivers below). The group address and port are:

Group Address: 239.255.48.84
Port: 5678

The transport only changes where the sensor sends its point-cloud stream, not how you connect. For what unicast, multicast, and observer-only mean and when to use each, see Connection Transport in the Quick Start.

The CLI tools default to unicast and need no extra flags. To stream by multicast, pass --stream-transport multicast to the primary client (the one that configures the sensor); each additional host then connects with --observer-only to receive the shared stream without configuring the sensor itself.

Receiving Data from a Sensor

To receive data from a sensor using tools like voyant_carbon_client_check, use:

voyant_carbon_client_check --bind-addr 0.0.0.0:5678 --group-addr 239.255.48.84 --interface-addr 192.168.1.100

For simulation environments:

voyant_carbon_client_check --bind-addr 0.0.0.0:5678 --group-addr 239.255.48.84 --interface-addr 127.0.0.1

Configuration Options Explained

For Receivers

These parameters are the same regardless of transport — you always join the group to connect (see Selecting the Transport).

--bind-addr <BIND_ADDR>: Local address to bind to (e.g., “0.0.0.0:5678”)
- The IP address is typically “0.0.0.0” to listen on all interfaces
- The port must match the port used by the sensor (default: 5678)
--group-addr <GROUP_ADDR>: Multicast group address to join (e.g., “239.255.48.84”)
- Must be in the valid multicast range (224.0.0.0 to 239.255.255.255)
- The client always joins this group; on the default unicast transport the sensor replies directly to the client, while on multicast it streams to this group
--interface-addr <INTERFACE_ADDR>: Local interface IP address to use for the multicast group
- Set to your configured IP address (e.g., “192.168.1.100”)
- Using the specific interface ensures proper routing of multicast traffic

For the Carbon Simulator (Development Only)

The voyant_carbon_simulator tool streams synthetic frames to the group so you can exercise the API without hardware. Its send-side options are:

--bind-addr <BIND_ADDR>: Local address to bind to, default is “0.0.0.0:0”
- Using “0.0.0.0:0” binds to any interface with a random port
--group-addr <GROUP_ADDR>: Multicast group address with port (e.g., “239.255.48.84:5678”)
- This is where the synthetic frames will be sent
--ttl <TTL>: Time To Live value (default: 5)
- Controls how many network hops the packet can traverse (1-255)
- For local network, 1 is sufficient

To also serve SDL commands and host↔FPGA time-sync like the real device, add --fpga-listen-addr 127.0.0.1:1234.

Common Use Cases

Connecting to a Voyant Sensor

Configure your network interface:

Linux:
```
sudo ip addr add 192.168.1.100/24 dev <YOUR_INTERFACE_NAME>
sudo ip link set <YOUR_INTERFACE_NAME> up
```
macOS:
```
sudo ifconfig <YOUR_INTERFACE_NAME> inet 192.168.1.100 netmask 255.255.255.0
```
Example interface names by platform:
- Linux built-in Ethernet: eth0 or eno1
- Linux PCI Ethernet card: enp2s0 or similar
- Linux USB or docking station Ethernet: enx78e7d1ea46b2 (where the suffix is the MAC address)
- macOS: en0, en1, etc.
- Windows: Usually identified by descriptive names in network settings

Run a Voyant tool with receiver configuration:

voyant_carbon_client_check --bind-addr 0.0.0.0:5678 --group-addr 239.255.48.84 --interface-addr 192.168.1.100

Connecting to a Simulation Environment

For connecting to simulated Voyant sensors:

voyant_carbon_client_check --bind-addr 0.0.0.0:5678 --group-addr 239.255.48.84 --interface-addr 127.0.0.1

Testing with the Carbon Simulator (Development)

For local development without hardware, use the Carbon simulator to generate synthetic frames:

Start the simulator:
```
voyant_carbon_simulator --bind-addr 127.0.0.1:0 --group-addr 239.255.48.84:5678 --fpga-listen-addr 127.0.0.1:1234
```
--fpga-listen-addr makes the simulator serve SDL commands and host↔FPGA time-sync like a real device, so a connecting client’s Control Link and Time Sync behave as they would against hardware. Omit it if you only need the point-cloud stream.

Run a receiver tool:

voyant_carbon_client_check --bind-addr 0.0.0.0:5678 --group-addr 239.255.48.84 --interface-addr 127.0.0.1

To replay recorded raw peaks (the DSP input) instead of synthetic frames, use voyant_carbon_peaks_playback in place of the simulator in step 1 — the receiver then runs the full DSP pipeline over your recorded data:

voyant_carbon_peaks_playback --input peaks.csv --max-ramp-count 5791 --fps 10.0 --bind-addr 127.0.0.1:0 --group-addr 239.255.48.84:5678

For Simulated Data on Localhost

If you’re having trouble with multicast connections on localhost (for simulated data), you may need to add a multicast route:

sudo ip route add 239.255.48.84/32 dev lo

Recording Data from a Sensor

To record data from a connected sensor:

voyant_logger_binary --output my_recording.bin --bind-addr 0.0.0.0:5678 \
                     --group-addr 239.255.48.84 --interface-addr 192.168.1.100

Troubleshooting

USB Ethernet Adapter Not Showing in Ubuntu 22.04 Network Settings

This affects Ubuntu 22.04 with NetworkManager ≤ 1.36.x. Fixed in 24.04 (NM 1.46+).

Check your version with:

nmcli --version

Diagnose

nmcli device status

If the target ethernet interface shows unmanaged, confirm the cause:

cat /usr/lib/NetworkManager/conf.d/10-globally-managed-devices.conf

If the output contains unmanaged-devices=*,except:type:wifi,... with no except:type:ethernet, this is the cause.

Fix

sudo tee /etc/NetworkManager/conf.d/10-globally-managed-devices.conf << 'EOF'
[keyfile]
unmanaged-devices=*,except:type:wifi,except:type:gsm,except:type:cdma,except:type:ethernet
EOF

sudo systemctl restart NetworkManager

Verify

nmcli device status

The ethernet interface should show connected or disconnected instead of unmanaged. It will also now appear in Settings > Network so you can configure the adapter through the GUI.

Cannot Connect to Sensor

Verify network interface configuration:
```
ip addr show
```
Ensure your interface has the 192.168.1.x address properly configured.
Check network cables and power - Ensure the sensor is powered on and properly connected.
Verify multicast routing (only applies when using multicast; skip if you are on the default unicast transport):
```
ip route get 239.255.48.84
```
This should show the correct interface for multicast routing.
Check for firewall issues:
```
sudo iptables -L
```
Ensure your firewall isn’t blocking UDP traffic on the sensor’s port.
Verify correct port configuration:

Ensure you’re using port 5678 for real hardware devices and for simulation environments.

Multicast Routing

If you’re not receiving any data (particularly when working with Docker containers or on localhost), you may need to add a specific multicast route to your loopback interface:

sudo ip route add 239.255.48.84/32 dev lo

This step is often required when:

Working with Docker containers
Testing on localhost
Using virtual machines
Working in environments where multicast routing is not configured by default

Packet Loss or Intermittent Connectivity

If the client logs DSP sequence drop or Ramp drop warnings, or prints OS capped the UDP receive buffer at startup, the usual cause on Linux is a small kernel UDP receive buffer that overflows under load. This affects any Linux host — laptops and embedded boards alike. Raising the limit fixes it in nearly all cases (on a Raspberry Pi 5 it took a recording from occasional drops to zero drops over 10,000 frames) and is the most effective step for dropped data on Linux.

Raising the UDP receive buffer

Raise the limit persistently (survives reboot):

sudo tee /etc/sysctl.d/99-voyant-udp.conf << 'EOF'
net.core.rmem_max=26214400
net.core.rmem_default=26214400
EOF
sudo sysctl --system

To revert: sudo rm /etc/sysctl.d/99-voyant-udp.conf && sudo sysctl --system.

Restart the client afterward — the OS capped the UDP receive buffer warning should be gone and the drops should stop.

On macOS the equivalent setting is kern.ipc.maxsockbuf (sudo sysctl -w kern.ipc.maxsockbuf=26214400). Windows needs no buffer tuning.

On laptops, also make sure the host is in a performance power mode (or at least balanced), not a battery-saver mode — a throttled CPU clock is a common cause of drops. See Power mode.

If drops persist, reduce network load — make sure the link isn’t congested with other traffic.

Advanced Configuration

For persistent network interface configuration, add the following to /etc/network/interfaces:

auto <YOUR_INTERFACE_NAME>
iface <YOUR_INTERFACE_NAME> inet static
    address 192.168.1.100
    netmask 255.255.255.0

Alternatively, if using NetworkManager, create a connection profile:

nmcli con add type ethernet con-name "Voyant" ifname <YOUR_INTERFACE_NAME> ip4 192.168.1.100/24
nmcli con up "Voyant"

For Windows systems, you can set a static IP through Network Settings > Network Adapter Properties.

For macOS, use System Preferences > Network > [Your Ethernet Interface] > Configure IPv4: Manually.

Next Steps

Now that you’ve connected to your sensor:

Explore the pre-packaged tools to understand what functionality is available
Try the Python or C++ example applications to learn how to use the API
Begin developing your own applications with the Voyant API

For more advanced usage, refer to the Python or C++ API documentation.