Skip to content

Commit

Permalink
Update README and github workflows
Browse files Browse the repository at this point in the history
  • Loading branch information
@svpcom
svpcom committed Aug 9, 2024
1 parent 2ae2503 commit 7083c94
Show file tree
Hide file tree
Showing 4 changed files with 55 additions and 64 deletions.
6 changes: 3 additions & 3 deletions .github/workflows/build_debian.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,19 +9,19 @@ on:

jobs:
build_and_test:
runs-on: ubuntu-24.04
runs-on: ubuntu-22.04
strategy:
fail-fast: false
matrix:
version: [11, 12]
arch: [ "arm32v7", "arm64v8", "amd64", "mips64le" ]
arch: [ "arm32v7", "arm64v8", "amd64", "mips64le", "s390x", "ppc64le"]

steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: build package
run: |
curl -s -L https://github.com/svpcom/wfb-ng/releases/download/wifibroadcast-17.10/qemu-7.2.0-fixed.tar.gz | sudo tar xzv -C /
curl -s -L https://github.com/svpcom/wfb-ng/releases/download/wifibroadcast-17.10/qemu-7.2.13-fixed.tar.gz | sudo tar xzv -C /
make deb_docker DOCKER_SRC_IMAGE=${{ matrix.arch }}/debian:${{ matrix.version }}
- name: Archive production artifacts
uses: actions/upload-artifact@v4
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/build_pi.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ on:

jobs:
build_and_test:
runs-on: ubuntu-24.04
runs-on: ubuntu-22.04
strategy:
fail-fast: false
matrix:
Expand All @@ -24,7 +24,7 @@ jobs:
uses: actions/checkout@v4
- name: build package
run: |
curl -s -L https://github.com/svpcom/wfb-ng/releases/download/wifibroadcast-17.10/qemu-7.2.0-fixed.tar.gz | sudo tar xzv -C /
curl -s -L https://github.com/svpcom/wfb-ng/releases/download/wifibroadcast-17.10/qemu-7.2.13-fixed.tar.gz | sudo tar xzv -C /
make deb_docker DOCKER_SRC_IMAGE=p2ptech/cross-build:${{ matrix.docker-images }}
- name: Archive production artifacts
uses: actions/upload-artifact@v4
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/build_ubuntu.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ on:

jobs:
build_and_test:
runs-on: ubuntu-24.04
runs-on: ubuntu-22.04
strategy:
fail-fast: false
matrix:
Expand All @@ -21,7 +21,7 @@ jobs:
uses: actions/checkout@v4
- name: build package
run: |
curl -s -L https://github.com/svpcom/wfb-ng/releases/download/wifibroadcast-17.10/qemu-7.2.0-fixed.tar.gz | sudo tar xzv -C /
curl -s -L https://github.com/svpcom/wfb-ng/releases/download/wifibroadcast-17.10/qemu-7.2.13-fixed.tar.gz | sudo tar xzv -C /
make deb_docker DOCKER_SRC_IMAGE=${{ matrix.arch }}/ubuntu:${{ matrix.version }}
- name: Archive production artifacts
uses: actions/upload-artifact@v4
Expand Down
105 changes: 48 additions & 57 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,20 +1,23 @@
![WFB-NG](doc/logo-big.png)
![WFB-ng](doc/logo-big.png)

This is the next generation of long-range **packet** radio link based on **raw WiFi radio**

Main features:
--------------
- 1:1 map of RTP to IEEE80211 packets for minimum latency (doesn't serialize to byte stream)
- Smart FEC support (immediately yield packet to video decoder if FEC pipeline without gaps)
- **1:1 map of RTP to IEEE80211 packets for minimum latency** (doesn't serialize to byte stream)
- **Smart FEC support** (there are many FEC improvements which allow to reduce latency in case of packet loss)
- [Bidirectional mavlink telemetry](https://github.com/svpcom/wfb-ng/wiki/Setup-HOWTO). You can use it for mavlink up/down and video down link.
- IP-over-WFB tunnel support. You can transmit ordinary ip packets over WFB link. Note, don't use ip tunnel for high-bandwidth transfers like video or mavlink. It uses less efficient FEC coding and doesn't aggregate small packets.
- Automatic TX diversity (select TX card based on RX RSSI)
- Stream encryption and authentication ([libsodium](https://download.libsodium.org/doc/))
- Distributed operation. It can gather data from cards on different hosts. So you don't limited to bandwidth of single USB bus.
- Aggregation of mavlink packets. Doesn't send wifi packet for every mavlink packet.
- **IPv4 tunnel for generic usage.** You can transmit ordinary ip packets over WFB link. Note, don't use ip tunnel for high-bandwidth transfers like video or mavlink because it has more overhead than raw udp streams.
- **Automatic TX diversity** (select TX card based on RX RSSI)
- **Stream encryption and authentication** ([libsodium](https://download.libsodium.org/doc/))
- **Distributed operation.** It can gather data from cards on different hosts. So you don't limited to bandwidth of single USB bus.
- **Aggregation of mavlink and tunnel packets.** Doesn't send wifi packet for every mavlink or tunnel packet.
- **Dynamic FEC and radio modulation.** You can change channel capacity/reliability without link interruption.
- **Full channel state logging including mavlink parser.** You can log all telemetry and link state for future offline debug.
- **Support for traffic shaper**. You can use standard linux traffic shapers to priority different channels and/or data/fec packets.
- Enhanced [OSD](https://github.com/svpcom/wfb-ng-osd) for Raspberry PI (consume 10% CPU on PI Zero) or any other system which
supports gstreamer (Linux X11, etc). Compatible with any screen resolution. Supports aspect correction for PAL to HD scaling.
- Provides IPv4 tunnel for generic usage
supports gstreamer and OpenGL (Linux X11/Wayland, etc). Compatible with any screen resolution.
- Supported CPU architectues: **arm32v7, arm64v8, amd64, mips64le, s390x, ppc64le, i386**. I.e. any linux with kernel >= 4.x and usb port.

> :warning: **Warranty/Disclaimer** <br />
> This is free software and comes with no warranty, as stated in parts 15 and 16 of the GPLv3 license. The creators and contributors of the software are not responsible for how it is used.
Expand All @@ -26,9 +29,20 @@ If you like WFB-ng you can support author via:
- https://boosty.to/svpcom/donate
- `bitcoin:bc1qfvlsvr0ea7tzzydngq5cflf4yypemlacgt6t05`

## Wiki:
See https://github.com/svpcom/wfb-ng/wiki for additional info

## Community support:
Telegram group: (**wfb-ng support**) https://t.me/wfb_ng
Please note, that it is only one official group.

## Supported WiFi hardware:
- **RTL8812au**. (stable) 802.11ac capable. [**Requires external patched driver!**](https://github.com/svpcom/rtl8812au) System was tested with ALPHA AWUS036ACH on both sides in 5GHz mode.
- **RTL8812eu**. (stable) 802.11ac capable. [**Requires external patched driver!**](https://github.com/svpcom/rtl8812eu) System was tested with [LB-LINK's BL-M8812EU2 module](https://www.lb-link.com/product_36_183.html)

## Getting Started

For detailed instructions on how to get started read through
For detailed instructions on how to get started read through
[PX4-Guide](https://docs.px4.io/main/en/companion_computer/video_streaming_wfb_ng_wifi.html)
and follow the [Setup HowTo](https://github.com/svpcom/wfb-ng/wiki/Setup-HOWTO)

Expand Down Expand Up @@ -64,24 +78,25 @@ sudo reboot
wfb-cli gs
```

### Quick start using Ubuntu Ground Station
### Quick start using Debian or Ubuntu Ground Station

- Install patched `RTL8812AU`driver:
- Install patched `RTL8812AU` or `RTL8812EU` driver:
```
sudo apt-get install dkms
# For 8812au:
git clone -b v5.2.20 https://github.com/svpcom/rtl8812au.git
cd rtl8812au/
# For 8812eu:
git clone -b v5.2.20 https://github.com/svpcom/rtl8812eu.git
cd rtl8812eu/
# For both:
sudo ./dkms-install.sh
```
- Make sure the driver is correctly installed by running the following command. You should see the WiFi card in an `unmanaged` state.
```
nmcli
```
- Get the name of the WiFi card by running:
```
ifconfig
```
- You should see output similar to:
- You should see output similar to:
```
wlan0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 2312
ether 0c:91:60:0a:5a:8b txqueuelen 1000 (Ethernet)
Expand All @@ -90,12 +105,13 @@ wlan0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 2312
TX packets 0 bytes 0 (0.0 B)
TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
```
- Copy the name of the RTL8812AU WiFi card.
- Install wfb-ng. Replace `wifi0`with the previously copied name of the WiFi card.
- Run `$ ethtool -i wlan0` and ensure that it show right driver: `rtl88xxau_wfb` or `rtl8812eu`
- Copy the name of the RTL8812AU/EU WiFi card.
- Install wfb-ng. Replace `wlan0` with the previously copied name of the WiFi card.
```
git clone -b stable https://github.com/svpcom/wfb-ng.git
cd wfb-ng
sudo ./scripts/install_gs.sh wifi0
sudo ./scripts/install_gs.sh wlan0
```
- Done! To monitor the link use the following command on the ground station:
```
Expand All @@ -105,48 +121,37 @@ wfb-cli gs

**Failing to get connection?**

Make sure the WiFi channel on the ground and on the drone are the same. To check, use:
```
head /etc/wifibroadcast.cfg
```

You should see output similar to:
```
[common]
wifi_channel = 161 # 161 -- radio channel @5825 MHz, range: 5815–5835 MHz, width 20MHz
# 1 -- radio channel @2412 Mhz,
# see https://en.wikipedia.org/wiki/List_of_WLAN_channels for reference
```
Ensure the WiFi channel selected is the same on the ground and on the drone.
1. Check WFB-ng GS logs with `sudo journalctl -xu wifibroadcast@gs`. If there is any errors then try to resolve it.
2. If there are any encryption errors then ensure that `drone.key` and `gs.key` on drone and gs corresponds each other.
2. Make sure the WiFi channel and link domain on the ground and on the drone are the same. To check, see `/etc/wifibroadcast.cfg` and ensure that `[common] wifi_channel` and `[drone] link_domain` / `[gs] link domain` is the same on the ground and on the drone.

---


## FAQ
**Q: What type of data can be transmitted using WFB-NG?**
**Q: What type of data can be transmitted using WFB-ng?**

**A:** Any UDP with packet size <= 1445. For example x264 inside RTP or Mavlink.
**A:** Any UDP with packet size <= 3993. For example x264/265 inside of RTP, Mavlink or generic IPv4 via tunnel.

**Q: What are transmission guarantees?**

**A:** Wifibrodcast uses FEC (forward error correction) which can recover 4 lost packets from 12 packets block with default settings. You can tune it (both TX and RX simultaneously!) to fit your needs.
**A:** WFB-ng uses FEC (forward error correction) which can recover 4 lost packets from 12 packets block with default settings. You can tune it to fit your needs.

**Q: Is only Raspberry PI supported?**

**A:** WFB-NG is not tied to any GPU - it operates with UDP packets. But to get RTP stream you need a video encoder (which encodes raw data from camera to x264 stream). In my case RPI is only used for video encoding (because RPI Zero is too slow to do anything else) and all other tasks (including WFB-NG) are done by other board (NanoPI NEO2).
**A:** WFB-ng is not tied to any GPU - it operates with UDP packets. But to get RTP stream you need a video encoder (which encodes raw data from camera to x264 stream). In my case RPI is only used for video encoding (because RPI Zero is too slow to do anything else) and all other tasks (including WFB-ng) are done by other board (NanoPI NEO2).

**Q: What is a difference from original wifibroadcast?**

**A:** Original version of wifibroadcast uses a byte-stream as input and splits it to packets of fixed size (1024 by default). If radio packets were lost and this is not corrected by FEC you'll get a hole at random (unexpected) place of stream. This is especially bad if data protocol is not resistant to (was not desired for) such random erasures. So i've rewritten it to use UDP as data source and pack one source UDP packet into one radio packet. Radio packets now have variable size depending on payload size. This reduces video latency a lot.

## Theory
WFB-NG puts the wifi cards into monitor mode. This mode allows to send and receive arbitrary packets without association and waiting for ACK packets.
WFB-ng puts the wifi cards into monitor mode. This mode allows to send and receive arbitrary packets without association and waiting for ACK packets.
- [WFB-ng design and protocol description](https://github.com/svpcom/wfb-ng/blob/master/doc/wfb-ng-std-draft.md)
- [Analysis of Injection Capabilities and Media Access of IEEE 802.11 Hardware in Monitor Mode](https://github.com/svpcom/wfb-ng/blob/master/doc/Analysis%20of%20Injection%20Capabilities%20and%20Media%20Access%20of%20IEEE%20802.11%20Hardware%20in%20Monitor%20Mode.pdf)
- [802.11 timings](https://github.com/ewa/802.11-data)

Sample usage chain:
-------------------
## Sample usage chain:
```
Camera -> gstreamer --[RTP stream (UDP)]--> wfb_tx --//--[ RADIO ]--//--> wfb_rx --[RTP stream (UDP)]--> gstreamer --> Display
```
Expand All @@ -169,8 +174,8 @@ To decode:
! rtph264depay ! avdec_h264 ! clockoverlay valignment=bottom ! autovideosink fps-update-interval=1000 sync=false
```

HOWTO build:
----------------------
## HOWTO build:

For development (inline build)
```
make
Expand Down Expand Up @@ -200,17 +205,3 @@ wfb_keygen
```
Leave them in place for development build or copy to `/etc` for binary install.
Put `drone.key` to drone and `gs.key` to gs.

Supported WiFi hardware:
------------------------
- **RTL8812au**. (stable) 802.11ac capable. [**Requires external patched driver!**](https://github.com/svpcom/rtl8812au) System was tested with ALPHA AWUS036ACH on both sides in 5GHz mode.
- **RTL8812eu**. (beta) 802.11ac capable. [**Requires external patched driver!**](https://github.com/svpcom/rtl8812eu) System was tested with [LB-LINK's BL-M8812EU2 module](https://www.lb-link.com/product_36_183.html)

Wiki:
-----
See https://github.com/svpcom/wfb-ng/wiki for additional info

Community support:
---------------
Telegram group: (**wfb-ng support**) https://t.me/wfb_ng
Please note, that it is only one official group.

0 comments on commit 7083c94

Please sign in to comment.