Reporting Errors and asking questions

Please read this page before asking for help on the mailing list. It will help you get a useful response and keep the mailing list a happy place.

GNU Radio has a steep learning curve

GNU Radio is a large, complex project. Working with it requires patience and skill. The GNU Radio community are helpful people, but they expect you to try to help yourself. Questions that demonstrate that you've done your homework are more likely to elicit a response. Also, please remember that no one gets paid to answer your questions. Your question might go unanswered for days or even weeks, or even forever, even if it's a good question.

There's a lot of advice in this document. It might seem unfair to be expected to put so much work into asking questions in a specific way. However, consider this: Questions you ask on this list reach hundreds of expert engineers with decades of experience in communication, signal processing, and related fields. If you have a good question and ask it well, you are likely to get many of them to spend a lot of time thinking it through, responding, and possibly doing additional work for you, all for free. Consultants with the same levels of experience are quite expensive.

Things to try before asking questions on the mailing list

First, install a clean installation of the current GNU Radio code from git, using the exact steps given in the documentation at the following two links, and see if your issue persists. At this point, most of the people on the GNU Radio mailing list are interested in improving the state of the art, not in supporting earlier releases or debugging integration issues caused by unusual customized installations.

Next, check whether you can help yourself or someone else has had the same issue that you're dealing with.

  • Read all output carefully and look for error messages. Most likely you'll get a hint what went wrong.
  • If you've received an error message from a Python program, read it carefully from the bottom up. The last entry is where the error happens; the lines above tell you how the failing part was invoked.
  • Ask someone nearby who understands GNU Radio or communication technology in general: a friend, colleague, professor, etc. This lets you ask many questions and get many answers in a small amount of time.
  • Search the GNU Radio wiki.
  • Search the GNU Radio mailing list archive.
  • Search the Web.
  • Read the source code that you're working on.

If nothing listed above helps you address your specific question or problem, your next step is to make sure that you're generally familiar with GNU Radio and the USRP. If you ask a question from the FAQ or documentation on the mailing list, it will probably be ignored.

Finally, you should have some understanding of the components involved in GNU Radio and their theoretical underpinnings. Your problem might be that you need to learn more about the things that GNU Radio uses, rather than an issue with GNU Radio itself. If it turns out that you have a general question about Python, C++, Unix, basic signal processing, FPGA design, analog RF electronics, or some other technology, please consider asking your question in a forum dedicated to the engineering discipline that you need help with. If your question is specifically about GNU Radio, the USRP series, or closely related concepts in software-defined radio, discuss-gnuradio is probably the best forum you can ask, but try to answer your question using textbooks and the Web first. A list of reference texts is available at SuggestedReading.

Note that if you're using the USRP without GNU Radio, Ettus LLC runs it's own mailing lists for this purpose.

I've done everything above, and I still have a question. How do I ask it?

You're most likely to get a helpful response on the mailing list if you ask nicely and provide enough information for us to diagnose the problem. Read and understand How To Ask Questions The Smart Way. At the very least, we need to know:
  • How did you invoke the code that isn't working? (If you ran a program, we need to know the entire command line, and the output of "printenv" might help; if you're calling preexisting code from your own program, we need your code or at the very least the lines of code that are failing; if your problem is with a GRC flowgraph, please provide both the .grc XML file and the .py code that GRC generates for your flowgraph.)
  • What error messages did you get, if any?
  • How did the behavior of your code differ from what you expected?
  • What GNU Radio software has worked for you so far, if any? Try some of the examples, e.g. usrp_fft.py.
  • If you got abnormal output from a GUI program, save it or make a screen shot, put it on a Web or FTP server, and give us a link to it. Please don't attach large files when writing to the list.
Some GNU-Radio-specific things that we'll need to know are:
  • What operating system are you using? (Linux, BSD, Mac OS X, Windows, or other? Which distribution? Which version? 32- or 64-bit?)
  • What specific kind of computer are you running GNU Radio on? (Which CPU architecture? Single-processor or SMP?)
  • If you're using a USRP, which one? What daugherboard(s) are you using? If you're not using a USRP, what digitizer hardware are you using?
  • What analog hardware (antennas, amplifiers, filters, etc.) is connected to the inputs of your digitizer hardware?

How should I format my message?

How To Ask Questions The Smart Way has excellent guidance on this question. The following are the most commonly violated principles. These rules might differ from what you're used to at work or at school, particularly if your organization uses Outlook or PDAs. They are conventions that Unix users and Usenet have followed since at least the 1980s, and your messages are more likely to be answered if you follow them.

  • Don't send large attachments to the list. The gnu.org servers have limited bandwidth. If you need to show some big files, put them on a Web- or FTP-server.
  • Don't send entire Python scripts or block source files in your message. If you have a short, relevant snippet of code you can include it inline, but please include long blocks of code or entire source files as an attachment; or even better, post them to a public web or FTP site.
  • Don't send HTML email. Many users use text-based email readers, and it is therefore considered bad practice to use HTML formatting on mailing lists. Aggressive formating like colours will most likely get lost.
  • Don't top-post. It makes following the discussion in longer threads difficult.
  • Trim your replies. When replying to a message, remove content that is not relevant to your reply, such as signatures and questions that you don't answer.
  • Don't reply to other unrelated messages to create a new topic/thread. This creates confusion with threaded mail readers. Create a new message.
  • Conversely, when replying to a message in an existing thread, use your email program's Reply feature rather than composing a new message with the same subject. Threaded mail readers rely on the In-Reply-To header, which will be preserved by your Reply button/menu but will not be there if you create a new message.
  • If your message includes Web links to particular posts or threads on discuss-gnuradio, also include the subject lines of the posts that you're referring to. Try to link to the official gnu.org archive rather than sites like ruby-forums.org or Nabble - those site are likely to randomly disappear or change URL paths, thus making your link meaningless.
  • If you intend to participate in discussions on discuss-gnuradio, please be subscribed to the list using the format option that sends individual messages for each incoming message, not the daily digest format. Reply to individual messages, not to the digest. Send mail to the list from a real email address that you can receive replies at, not using a Web tool like ruby-forums.org.

I asked a question and I haven't gotten an answer yet. What can I do?

Questions often don't receive an answer until days after they were posted. While you are waiting, please continue to work on your problem yourself; mail the list if you find a solution. Don't re-post the same question to the list and don't ask it directly to someone whose email address you got from the list. Do not "bump" your message either.

Often the reason the question has not been answered is that it appears as if the questioner has not followed the suggestions on this page. By following the suggestions on this page, you will increase your chances of getting an answer.

If you're in a serious hurry or your question to the mailing list has gone a couple weeks without an answer and you're completely stumped, your only recourse is to hire a consultant. This will be expensive. There are quite a few communications sytem design and signal processing consultants out there; GNU Radio does not specifically endorse any of them, but at least one of the maintainers of GNU Radio is sometimes available for consulting work: Corgan Enterprises.

Sharing your Solution

If you could solve your problem, it would be more than welcome if you share it with others. Just post a closing message with your solutions. This has multiple benefits:
  • It helps others who have the same problem to find the right solution.
  • It shows all helpers that their help had some positive result and thus increases motivation to help again.
  • It gives additional information about the structure of your problems, which can be useful in other cases

Saying Thank You

Helpers need some candy from time to time. If you found some support helpful, say so. You'll get extra karma points for thanking.