ReportingErrors

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.

Remember: You are talking to people and asking for their time

When asking questions on the mailing list, you are asking other people for a huge favour: You are asking for them to give up some of their time and help you solve your problems. No one gets paid to help you. You will only get useful responses if you respect our mailing list's etiquette. Most importantly, remember these two things: Stay polite, and make sure you've done everything you can to make it easier for other's to help you.

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.

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.

Checklist: Before asking questions on the mailing list

Often, going through this checklist will solve the problem for you:

1. Check if the problem was already solved by someone else:
   • Search the GNU Radio wiki.
   • Search the GNU Radio mailing list archive.
   • Search the Web.
   • Read the GNU Radio FAQ
   • 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.
2. Rule out common sources for problems
   • Update and/or reinstall your GNU Radio version
   • Try and create the smallest possible program/flow graph that exhibits your issue
3. Check whether you can help yourself:
   • Read the source code that you're working on. Use grep or similar tools to find source files that pertain to your problem.
   • Read all output carefully and look for error messages.
   • 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.
   • Check examples to see if there's something similar to what you need
   • Run common apps such as uhd_fft to try and rule out sources of error

If none of this solves your problem, consider this:

• Is this a question for the GNU Radio mailing list?
  • If it's specific to USRPs, you might want to consider the usrp-users mailing list.
  • General SDR- and radio-related questions can be asked on the mailing list, but often there are better-suited places to ask
• Is this a 'textbook' question?
  • There are a lot of good textbooks explaining the basics of SDR, digital communications, analog hardware etc.

Once you've gone through this list and are still pulling a blank, you should ask on the mailing list.

Checklist: Asking a question on the mailing list

• Read and follow the advice of How To Ask Questions The Smart Way
• Include the following information:
  • How did you invoke the code that isn't working? (E.g., post the entire command line)
  • What error messages did you get, if any?
  • If your 'error message' was abnormal output from a GUI widget, post a link to a screenshot
  • How did the behavior of your code differ from what you expected?
  • Version of GR, Version of underlying libraries (e.g. UHD if applicable), OS version and type, CPU information
  • If applicable: Which SDR hardware you're using (USRP model, daughterboards etc.)
  • If applicable: Which external hardware you're using (antennas, amps, filters etc.)
• Provide the failing code, this includes:
  • A stripped-down version of the C++ or Python codes
  • If it's a failing GRC flowgraph, a good way is to attach the .grc and post a link to a screenshot of the flow graph
  • Use your judgment of how much code to include; too much and people will be discouraged to read it, too little and the relevant portion may not be in there.

Writing good emails in this fashion is often a large portion of finding the answer.

Checklist: Formatting

Good formatting makes emails easier to read and is less discouraging for people to help.
Also, formatting guidelines may differ from what you're used to for other communications, e.g. at your work place.

• Remember you're talking to another human being. Stay polite.
• Follow the advice on How To Ask Questions The Smart Way
• Don't send large attachments to the list. The gnu.org servers have limited bandwidth. Prefer uploading them somewhere and linking to them.
• Crop to relevent portions of code.
• Prefer simple formatting over flashy HTML emails. Funky formatting often gets lost. Ideally, send plain-text emails instead of HTML.
• 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.
• Prefer inline responses over top-posts. This makes is much easier to follow or enter an ongoing conversation and will make it more likely for people to help that are late to the party.
• Stick the same topic/thread when discussing a question, and start a new thread for new questions. This makes reading easier in threaded mail readers and the archives.
• Don't answer to digests. If you plan to post on discuss-gnuradio, subscribe in normal way (individual messages).
• 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.
• 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. Prefer the official gnu.org archive rather than sites like Nabble, as those links are more stable.

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.