Connections Guide

This guide explains how to set up UDP connections between Voyant LiDAR sensors and API tools. Voyant sensors and tools communicate using multicast UDP connections.

Note: Voyant sensors currently only support multicast UDP transmission.

Multicast is the primary connection method for Voyant sensors. This allows multiple receivers to simultaneously connect to a single sensor’s data stream, which is ideal for development, debugging, and production deployments.

Network Setup for Sensor Connection

Before connecting to a Voyant sensor, you need to configure your network interface:

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 alongs 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.20.x subnet

Linux:
```
sudo ip addr add 192.168.20.100/24 dev <YOUR_INTERFACE_NAME>
sudo ip link set <YOUR_INTERFACE_NAME> up
```
macOS:
```
sudo ifconfig <YOUR_INTERFACE_NAME> inet 192.168.20.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.20.20. Check that you can reach the sensor with:
```
ping 192.168.20.20
```
A successful connection will show ping responses with time statistics and 0% packet loss. It will look something like this:
```
PING 192.168.20.20 (192.168.20.20) 56(84) bytes of data.
--- 192.168.20.20 ping statistics ---
9 packets transmitted, 9 received, 0% packet loss, time 8010ms
rtt min/avg/max/mdev = 1.873/1.904/1.925/0.014 ms
```
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).

Multicast Connection Parameters

Voyant sensors come pre-configured to send data to the following multicast address:

Group Address: 224.0.0.0
Port: 4444

Receiving Data from a Sensor

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

voyant_foxglove_bridge --bind-addr 0.0.0.0:4444 --group-addr 224.0.0.0 --interface-addr 192.168.20.100

For simulation environments:

voyant_foxglove_bridge --bind-addr 0.0.0.0:4444 --group-addr 224.0.0.0 --interface-addr 127.0.0.1

Configuration Options Explained (multicast)

For Multicast Receivers

--bind-addr <BIND_ADDR>: Local address to bind to (e.g., “0.0.0.0:4444”)
- 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: 4444)
--group-addr <GROUP_ADDR>: Multicast group address to join (e.g., “224.0.0.0”)
- Must be in the valid multicast range (224.0.0.0 to 239.255.255.255)
- This is the address the sensor sends data to
--interface-addr <INTERFACE_ADDR>: Local interface IP address to use for the multicast group
- Set to your configured IP address (e.g., “192.168.20.100”)
- Using the specific interface ensures proper routing of multicast traffic

For Multicast Senders (Development Only)

--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., “224.0.0.0:4444”)
- This is where the data 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

Common Use Cases

Connecting to a Voyant Sensor

Configure your network interface:

Linux:
```
sudo ip addr add 192.168.20.100/24 dev <YOUR_INTERFACE_NAME>
sudo ip link set <YOUR_INTERFACE_NAME> up
```
macOS:
```
sudo ifconfig <YOUR_INTERFACE_NAME> inet 192.168.20.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 multicast receiver configuration:

voyant_foxglove_bridge --bind-addr 0.0.0.0:4444 --group-addr 224.0.0.0 --interface-addr 192.168.20.100

Connecting to a Simulation Environment

For connecting to simulated Voyant sensors:

voyant_foxglove_bridge --bind-addr 0.0.0.0:4444 --group-addr 224.0.0.0 --interface-addr 127.0.0.1

Testing with Mock Data (Development)

For local development using the mock data generator:

Start the mock data sender:

voyant_points_mock_stream --bind-addr 127.0.0.1:0 --group-addr 224.0.0.0:4444

Run a receiver tool:

voyant_foxglove_bridge --bind-addr 0.0.0.0:4444 --group-addr 224.0.0.0 --interface-addr 127.0.0.1

For Mock Data on Localhost

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

sudo ip route add 224.0.0.0/24 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:4444 \
                     --group-addr 224.0.0.0 --interface-addr 192.168.20.100

Troubleshooting

Cannot Connect to Sensor

Verify network interface configuration:
```
ip addr show
```
Ensure your interface has the 192.168.20.x address properly configured.
Check network cables and power - Ensure the sensor is powered on and properly connected.
Verify multicast routing:
```
ip route get 224.0.0.0
```
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 4444 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 224.0.0.0/24 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

Check buffer sizes:

sysctl net.core.rmem_max
sysctl net.core.rmem_default

Consider increasing UDP receive buffer sizes:

sudo sysctl -w net.core.rmem_max=26214400
sudo sysctl -w net.core.rmem_default=26214400

Reduce network load - Ensure your network 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.20.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.20.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 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 API documentation.