Faery supports reading event streams from UDP network sources, enabling real-time distributed processing and camera streaming over networks.
5.5.1When to use UDP input¶
UDP streaming is useful for:
Real-time applications: Processing events as they arrive from cameras or other sources
Distributed systems: Receiving events from remote cameras or processing nodes
Low-latency pipelines: Minimal protocol overhead for time-critical applications
Network integration: Connecting Faery to existing UDP-based event systems
5.5.2Supported UDP formats¶
Faery supports two binary UDP formats for event transmission:
5.5.2.1t64_x16_y16_on8 (Default)¶
Timestamp: 64-bit (8 bytes)
X coordinate: 16-bit (2 bytes)
Y coordinate: 16-bit (2 bytes)
Polarity: 8-bit (1 byte)
Total: 13 bytes per event
Use case: High precision timestamps, standard coordinate resolution
5.5.2.2t32_x16_y15_on1¶
Timestamp: 32-bit (4 bytes)
X coordinate: 16-bit (2 bytes)
Y coordinate: 15-bit + 1-bit polarity (2 bytes total)
Total: 8 bytes per event
Use case: Bandwidth-constrained networks, lower timestamp precision acceptable
5.5.3Basic usage¶
5.5.3.1Command line¶
# Listen on localhost port 7777 (IPv4)
faery input udp localhost:7777 --dimensions 640x480 output file received.es
# Specify UDP format
faery input udp localhost:7777 --dimensions 640x480 --format t32_x16_y15_on1 output file received.es
# IPv6 address
faery input udp [::1]:7777 --dimensions 640x480 output file received.es
# Listen and stream to another UDP endpoint
faery input udp localhost:7777 --dimensions 640x480 output udp remote-host:88885.5.3.2Python¶
import faery
# Basic UDP input
stream = faery.events_stream_from_udp(
dimensions=(640, 480),
address=("localhost", 7777)
)
# Specify format
stream = faery.events_stream_from_udp(
dimensions=(640, 480),
address=("localhost", 7777),
format="t32_x16_y15_on1"
)
# IPv6
stream = faery.events_stream_from_udp(
dimensions=(640, 480),
address=("::1", 7777, None, None) # IPv6 format
)
# Use in processing pipeline
faery.events_stream_from_udp(
dimensions=(640, 480),
address=("localhost", 7777)
).time_slice(0 * faery.s, 10 * faery.s) \
.regularize(frequency_hz=30.0) \
.render(decay="exponential", tau="00:00:00.200000", colormap=faery.colormaps.starry_night) \
.to_file("network_stream.mp4")5.5.4Real-time processing examples¶
5.5.4.1Camera to network pipeline¶
# Send camera data over UDP
faery.events_stream_from_camera() \
.to_udp("remote-host", 7777)
# Receive and process on remote machine
faery.events_stream_from_udp(
dimensions=(640, 480),
address=("0.0.0.0", 7777) # Listen on all interfaces
).regularize(frequency_hz=60.0) \
.render(decay="exponential", tau="00:00:00.100000", colormap=faery.colormaps.starry_night) \
.to_file("remote_camera.mp4")5.5.4.2Multi-hop processing¶
# Stage 1: Basic filtering
faery.events_stream_from_udp(
dimensions=(1280, 720),
address=("localhost", 7777)
).remove_off_events() \
.to_udp(("processing-node", 8888))
# Stage 2: Advanced processing
faery.events_stream_from_udp(
dimensions=(1280, 720),
address=("0.0.0.0", 8888)
).regularize(frequency_hz=30.0) \
.render(decay="exponential", tau="00:00:00.200000", colormap=faery.colormaps.devon) \
.to_file("processed_output.mp4")5.5.4.3Event rate monitoring¶
# Monitor network event rates
faery.events_stream_from_udp(
dimensions=(640, 480),
address=("localhost", 7777)
).to_event_rate(window_duration_us=1000000) \
.to_file("network_activity.csv")5.5.5Firewall settings¶
Your firewall can sometimes block UDP traffic, so ensure that your system opens the right ports. Below are examples for Linux and Windows:
# Allow UDP input on port 7777 (Linux iptables)
sudo iptables -A INPUT -p udp --dport 7777 -j ACCEPT
# Windows Firewall (PowerShell)
New-NetFirewallRule -DisplayName "Faery UDP" -Direction Inbound -Protocol UDP -LocalPort 7777 -Action Allow5.5.6Troubleshooting¶
5.5.6.1Connection issues¶
Address already in use
OSError: [Errno 98] Address already in useCheck if another process is using the port:
netstat -ulnp | grep 7777Try a different port
No route to host
OSError: [Errno 113] No route to hostVerify network connectivity:
ping target-hostCheck firewall rules on both sender and receiver
Ensure correct IP address and port
5.5.6.2Data issues¶
No events received Either dump events to stdout or write a custom loop to check that you’re actually seeing data.
# Check if data is arriving (will block until events received)
for events in stream:
print(f"Received {len(events)} events")
break # Exit after first packetMalformed events
Verify sender and receiver use same UDP format
Check network MTU settings (large packets may be fragmented)
Ensure sender uses correct event encoding
High latency
Reduce processing complexity in pipeline
Check network latency:
ping -c 10 target-hostConsider using faster UDP format (t32_x16_y15_on1)
5.5.6.3Performance optimization¶
High CPU usage
# Add regularization to reduce processing frequency
stream = faery.events_stream_from_udp(
dimensions=(640, 480),
address=("localhost", 7777)
).regularize(frequency_hz=30.0) # Limit to 30 FPS processingMemory usage
Events are processed in streaming fashion (low memory footprint)
For finite processing, consider
.take()to limit event countMonitor with
toporhtopfor actual memory usage
Network bandwidth
# Monitor received data rate
import time
start_time = time.time()
event_count = 0
for events in stream:
event_count += len(events)
elapsed = time.time() - start_time
if elapsed > 5.0: # Report every 5 seconds
rate = event_count / elapsed
print(f"Receiving {rate:.0f} events/second")
event_count = 0
start_time = time.time()