RFQuack

The only RF-analysis tool that quacks!

Documentation | Research Paper

View Demo · Report Bug · Request Feature

About RFQuack

RFQuack is a versatile RF-analysis tool that allows you to sniff, analyze, and transmit data over the air.

Similarly to RFCat RFQuack has a Python-based scriptable shell that allows you to set parameters, receive, transmit, and so on.

(back to top)

Supported Radios

We porting from (and contribute back to) RadioLib. So far, we support:

• CC1101 OOK, 2-FSK, 4-FSK, MSK radio module
• nRF24L01 2.4 GHz module
• RF69 FSK, OOK radio module

Supported Arduino Platforms

In principle, RFQuack can run on any board and platform supported by PlatformIO. So far, we tested the following boards:

• ESP32 - ESP32-based boards
• Teensy - Teensy 2.x, 3.x and 4.x boards

Getting Started

This is an example of how you may give instructions on setting up RFQuack.

Prerequisites

You'll need the Protbuf Compiler, a sane Python 3.10, and PlatformIO (which itself requires some dependencies):

• Protobuf Compiler
• Python 3.10.x
• PlatformIO

For more details, please refer to the Documentation.

(back to top)

Installation

An easy way to quick start is to have an ESP32 board and a CC1101 and/or RF69 (easier to find) radio module.

git clone --recursive https://github.com/rfquack/RFQuack
cd RFQuack
pip install -r requirements.pip
vim build.env  # set your parameters and :wq
make clean build flash

For more details, please refer to the Documentation.

(back to top)

Usage

An easy way to quick start is to connect the dongle via USB and use the CLI.

$ rfq tty -P /dev/ttyUSB0
2019-04-10 18:04:31 local RFQuack[20877] INFO Transport initialized
2019-04-10 18:04:31 local RFQuack[20877] INFO Transport initialized (QoS = 2): mid = 2

...

RFQuack(/dev/ttyUSB0, 115200,8,N,1)> q.radioA.set_modem_config(modulation="OOK", carrierFreq=434.437)

result = 0
message = 2 changes applied and 0 failed.

RFQuack(/dev/ttyUSB0, 115200,8,N,1)> q.radioA.rx()

result = 0
message =
...

For more details, please refer to the Documentation.

Roadmap

• [ ] Add all relevant RadioLib modules
• [ ] Test with more than 2 radio modules
• [ ] Revisit Python CLI source code and use typed Python 3
• [ ] Integrate with URH and GNU Radio
• [ ] Make a web UI

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the proper template.

Don't forget to give the project a star! Thanks again!

1. Fork the project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Run simple integration tests (make clean build)
5. Push to the branch (git push origin feature/AmazingFeature)
6. Open a Pull Request

(back to top)

License

Distributed under the GPL 2 License. See LICENSE for more information.

(back to top)

Acknowledgments

RFQuack wouldn't exist without the inspiration, feedback, and help received from related tools and awesome humans:

• RFCat
• RadioLib
• RadioHead
• URH

(back to top)