How to Add an Example Flowgraph to a Block Doc

Why?

Part of the value of our Block Doc pages is having an Example Flowgraph to show how that block can be used. In a recent review of our 555 current blocks, 214 of them do not have an Example Flowgraph!

To which pages?

Look at Pages with no Example Flowgraph and Documentation Stubs for the lists of pages in need of Example Flowgraphs.

This document describes the process to add an Example Flowgraph to an existing Block Doc; you'll find all of them in the Category Block Docs.

How?

Sign in or work as guest

If you have a Wiki account, sign in, but if you don't, you still can edit the Wiki. Your changes will be placed in a queue to be reviewed before acceptance.

Overview

The following steps use Complex_To_Float as a specific example.

1. Find or create a flowgraph containing the subject block.
2. Load and execute the flowgraph to test that it works!
3. Make a screen capture (see below)
4. Go to Special:Upload, Choose File, and open it.
5. Save the file name and pixel dimensions in your notes.
   e.g. File:SSB_rcv_weaver_fg.png 1,552 × 623 pixels
6. Open the subject block doc and select the 'Edit' tab next to the 'Read' tab.
7. Below the == Example Flowgraph == line, if there is any placeholder text, delete it and enter the flowgraph file information in the following format: [[File:SSB_rcv_weaver_fg.png|800px]]
   where File:SSB_rcv_weaver_fg.png is your screenshot, and the 800px is the width to display.
   Note: if the original pixel width dimension is less than 800, use that value instead of the 800 in the example.
8. Find the line which contains [[Category:Pages with no Example Flowgraph]] and delete it.
9. In the Summary entry box, enter "add Example Flowgraph"
10. Click "Show preview" to examine what you have done.
11. In addition to checking the Example Flowgraph, scroll to the bottem of the page and check that the only Category shown is "Block Docs".
12. Make any corrections needed and then click "Save page".

Individual Steps

Finding an existing flowgraph

If you're using the Qt version of GRC, you fill find the Examples… menu point in the File menu. This is not available in the default (Gtk) GRC.

You can check the installed examples that came with GNU Radio for an existing flow graph. You'll find them in the installation prefix, i.e., in the directory that running gnuradio-config-info --prefix outputs, under ${prefix}/share/gnuradio/examples.

If you prefer working on the source code, you can check the grc/ directory in the module that the block comes from – in the case of Complex to Float that would be gnuradio/gr-blocks/grc; you can find that on the GNU Radio source code repository.

Capturing an image of the Flowgraph

TODO: Explain in morer & gooder words

• In the View Menu, activate Show parameter expressions in block (TODO: That's GTK-GRC, check how it is in Qt-GRC)
• Make sure the flow graph is still tidy (see below on creating one)
• File menu: Screen capture.
• Make sure "PNG Files" is selected as file type.
• Save flowgraph in a directory you'll find it again; name it name of your flowgraph_fg.png (e.g. SSB_rcv_weaver_fg.png).

---

Barry's original wording:

• In GRC, select File -> Screen Capture
• Change the filename to "<your file>_fg.png" (e.g. SSB_rcv_weaver_fg.png)
• Change the folder to '~/Pictures/Screenshots'

---

Creating a new Example Flowgraph

TODO: When to do this?

What makes a good Example Flowgraph?

• TODO: Full sentences
• TODO: Illustrations

---

• Illustrates for what the block is usually used for
  • Not just "Null Source -> Block -> Null Sink", that doesn't help
• Is limited in scope
  • If you want to illustrate Multiplication with a Constant, don't do it by showing a 50-Block flowgraph that implements a complicated transceiver system
• If the block has parameters, shows how the relate to the context of the Flowgraph
• Is tidy
  • No upside-down blocks,
  • no disabled blocks,
  • connections as straight as feasible,
  • no overlapping blocks, and
  • no "ratsnests" of confusing connections (maybe use Virtual Sink / Virtual Source?)
• Uses the "Comment" field (in the "Advanced" tab in the Block properties) on all blocks that are not self-explanatory