PA Randonneurs Cue Wizard

Introduction

The PA Rando Cue Wizard allows you to generate a cue sheet and brevet card directly from a RWGPS route with minimal input and user interaction. The goal of this system is to eliminate the burden of generating traditional randonneuring paperwork -- to make the RBA and Organizer's life as easy as possible. Cue Wizard allows randonneuring routes to be created in RWGPS or equivalent system, but then Cue Wizard takes over -- keeping a private copy of the route and generating all subsequent paperwork automatically without involving RWGPS. Control closings are automatically calculated from the route data without needing any special notes. With Cue Wizard, the production of brevet cards and cue sheets becomes a mechanical, automatic "one-click" process once all data is entered. Should something change -- a last minute route adjustment because the pre-ride discovers that a bridge is out -- don't panic. One click and Presto! All the paperwork and web resources are completely and instantly updated to reflect the change.

Features of Cue Wizard include:

• Free and available online for any rando club for use.
• One click PDF Cue sheet generation in either Portrait or Landscape
• One click PDF Brevet card generation, 1 or 2 fold cards, inside and outside.
• Automatically generated event web page with links to cue sheets, maps, and routes
• All route data can be entered and maintained in RWGPS or other compatible system.
• Local cache of route data, independent of any third party.
• Automatic RUSA/ACP/Perm controle time calculations based on published algorithms.
• Custom event date/time, or generic start
• Worldwide time-zone and "daylight savings time" support
• Download links for GPX, TCX, and JSON route files
• Automatic distance segment calculations
• Route maps and elevation profiles
• Route statistics
• Automatic search/replace cue note simplification
• Distinctive formatting of Controle cues (staffed, merchant, info...)
• Support for "photo" EPP controles
• Support for QR Code controle check-in sheets
• Custom brevet card logo
• Rider roster and finish results support
• Brevet card barcode support
• Custom club logo and other club specific configuration
• Source code freely available

Cue Wizard is an expansion/enhancement of other systems that produce cards and cue sheets, such as Card-O-Matic from New England Randonneurs, and Rando Route Sheet from Seattle International Randonneurs. The main thing that distinguishes Cue Wizard from these other systems is that Cue Wizard has a very austere web interface and attempts to provide "one click" production of cards and cuesheets based on options and attributes associated with the route and event that are pre-stored in the route data (eg on RWGPS) as simple #name=value tags.

Access

Cue wizard is part of the Pennsylvania Randonneurs web site, and has special features that directly support PA Rando events, but anyone at any club can use Cue Wizard to support any event or permanent under terms of our website license.

To use cue wizard, you need to log in to the PA Rando website with your RUSA ID or last name. If you've previously registered for aa PA Rando event, you will already have a login. There is a link to recover/create your login password if you don't know it. If you have never ridden an event with PA Rando, you can contact the RBA to have an account created for you.

After you log in, you'll see a list of existing events associated with you as organizer. You can also create a new event. Events define the basic parameters of a brevet like ACP vs RUSA sanction, offical distance, start time (for brevets), etc... so the system knows how to create cards, cue sheets, and calculate control closings.

When your event is created with all the details set (especially the link URL to the route!), you should click the special Cue Wizard icon that looks like this: . You'll now be at a page that will allow you to make cards and cue sheets from the route, assuming the route is properly set up. Of course, when you first try with your own route you'll likely see some errors given in red. No worries. That's normal. You haven't added controles or a route description yet. Read the errors, and the text below in this document. They'll help guide you toward what you need to add to your RWGPS route in order to make it work with the Cue Wizard.

Preparing RWGPS routes for use with Cue Wizard

Most of you will use RWGPS to capture route data. Before you can use it effectively with our system, you need to add two things to your RWGPS route: 1) detailed notes on cues as required for cue sheet completeness and rider safety, 2) cues for Controles. Once you add those two things to your route data, you can create quality randonneuring cue sheets (landscape or portrait) and brevet cards for an event with just one click, as well as many other kinds of paperwork.

Adding Notes to Direction Cues

Once your have your route designed, RWGPS generates servicable cue notes for most ordinary left/right turn cues automatically from the map input, but there will always be something missing. RWGPS can never automatically generate the detailed turn cue notes discriminating randonneurs expect in a cue sheet (and conscientious RBAs, Organizers, and Route Owners like to provide). Nor can RWGPS automatically generate controle cues. These things must be entered manually.

The RWGPS system has a nice "Add to Cue sheet" mode in the route editor for customizing the default cues. As you scan down the auto-generated cues in RWGPS, many can be left unchanged. You might be tempted to abbreviate some of them, but you shouln't bother as the Cue Wizard system will do quite a bit of automatic search/replace abbreviating, as described below.

What you should focus on when reviewing cue notes is adding spotting notes to make turns easier to spot. Some riders navigate only with a cue sheet (yes they still exist). At PA Rando we will usually add things like (SS) for a stop sign, (TFL) for traffic signal, and so on. We also add an easy to see "Straight" non-turn cue immediately before an easy to miss turn. Also, for all rider (even those blindly guided by GPS), we suggest adding cue notes warning about road hazards. These warnings will go on the cue sheet and will be output by a GPS unit. Finally, consider adding cue notes (and entire cues) identifying places to find water, food, and other things tired randonneurs seek. Note: it's best to add all these extra bits of info at the end of each Note so they don't interfere with the direction text. Leave the direction text at the beginning of the note.

Adding Controle Cues

For each controle, we like to make a total of three cues manually. The cue triplet should be all placed on the map very near the controle, but RWGPS will force some distance between them. . You can study some of our recent RWGPS routes for PA Rando to see how it's done.

1. The first cue in the "Controle Triplet" will be a direction cue, usually type Left or Right, sometimes Straight, and have a Note that says something like "Enter Wawa controle on the left", or whatever you want the voice in your phone to say (or GPS display to show). The voice in the phone reads the Notes as you get to the controle. No description #tags are needed on the first cue.
2. The middle cue will be the actual controle, cue type "Control" (RWGPS spells the Controle "Type" without the final "e"). The middle controle cue should have a Note like all cues, but it also needs special #tags in the Description.
3. Then the third cue in the triplet is another ordinary turn cue for departure. Again, this is a direction type, Left or Right, with note Something like "Leave Wawa by turning left (same direction)". As with the entering cue, description #tags are not needed on the final cue of the triplet.

Start and Finish

All intermediate controles should have this "triplet" of cues, but the start and finish cues are special cases that only need two cues. There must always be at least two control cues defined: a START control in the first km of the route, and a FINISH control in the last km of the route. Put a cue with Type set to Control in the first or last km and it will be automatically recognized as the START or FINISH. For these terminal controles, it's OK to just have two cues in the triplet. You can omit the "entrance" cue for the START, and the exit cue for the FINISH.

Controle Description #tags

As mentioned above, the middle of the controle cue triplet is the one where the Type needs to be set to "Control". For Note on this cue, you can put a note like "Welcome to the Blah Blah Control", or whatever you want the app to say or GPS to display. But under the Description of the control-type cue, you must add #tags of the form #tag=data to describe the cue. For example, the Pottstown controle in our YARRR route has the Description tags

You'll need to paste #tags in a description like this for all your cues that are set to type Control. If you don't, the system will nag you with red errors until you do.

At a minimum, every control-type cue should have a Description that includes #name, #style, and an #address. The complete set of #tags you can put in a cue Description are the following:

The #tags should be entered as all lowercase, one per line. If setting a value, follow the tag with an equal sign and the value. Tags can be listed in any order. There's generous forgiveness of whitespace, so you don't have to worry too much about leaving (or not leaving) a blank space anywhere. The system will ignore everything before the first #tag, so if you want to enter stuff in the Description that is not to be seen by Cue Wizard, you can do it before the first "hashtag".

If the control #style=info then you must include a #question tag defining whot question the rider needs to answer at the controle. If the controle #style=photo, then you must include a #photo tag defining what the rider needs to photograph.

Automatic Search/Replace

The automatically generated cue note from RWGPS is a lot more verbose than the note on a typical randonneur cue sheet. The RWGPS note will be "Turn right onto Main Street" whereas a typically printed rando cuesheet would have only the austere "R Main St". On the other hand, when spoken by the RWGPS app using the voice in your phone, the verbose text sounds just fine. For this reason, Cue Wizard contains a set of search/replace rules for transforming verbose RWGPS cue notes into terse rando cues. That way, the voice in the phone can still say the verbose text, while the cue sheet shows only a terse cue text.

You don't have to do anything to your RWGPS data to enable these search/replace rules. It will happen to your cue notes automatically. In fact, the less you do to the automatically generated notes, the better, as the system works best with the original note formats. The printed cues will say "R" not "Right" and verbosity like "Turn onto" will be deleted. Review the automatic changes before doing a lot of work simplifying cues. You can always make small tweeks to the cue notes manually, and these will be generally respected.

The following is a list of some of the search/replace transformations performed.

Cue Abbreviations

At PA Randonneurs we use some common abbreviations in cue notes, and by default a glossary of these is printed at the start of a cuesheet. The standard list is:

If you'd like add, remove, or change some of these cue abbreviations in the glossary that's printed, add a #cue_abbreviations tag to the description, with a list of abbreviations you want to alter. Each abbreviation should have the abbreviation first, then a colon ':', followed by the definition. Multiple abbreviations should be separated by commas. For example, if you want to add the abbreviation 'WART' for 'Warning Another Railroad Track', and redefine 'TFL' to now be defined as 'Turn Freekin Left', you would add the following tag to the route description in RWGPS.

All the default abbreviations will still be printed along with your additions. If you want to remove an abbrevation, give the abbreviation with a colon and don't put anything for the definition. If you don't want any abbreviations printed at all, use #cue_abbreviations=NONE.

Comments and In Case of Emergency

Above the cue abbreviations, a box is always printed with text in italics inditating what to do in an emergency. The default text is:

You can change this default text to something else by using the #in_case_of_emergency tag.

Normally, immediately below the Cue Abbreviations the cues will begin, but if you want to print one last commont, there is a #comment tag that allows you to specify a general text comment that will appear below the Cue Abbreviations but above the first cue.

In both of these texts, magic template variables such as {$organizer_name} and {$organizer_phone} are automatically replaced by values for these specified for the event. There is a long list of available variables that can be used in these texts, including most of the description tags.

Downloading Route Data

After you've added your RWGPS route, and pressed save in RWGPS, you must return to Cue Wizard and press the button "Re-download route from RWGPS". If you don't do that, the PA Rando website will not "see" the changes you made in RWGPS. You only need to press the "Re-Download" button when you've made changes to the route in the RWGPS website. PA Rando keeps a cached copy of the RWGPS route data and uses this copy for cue and card generation. The copy is refreshed when you press this button.

Generating Cues and Cards

If you entered all your #tags correctly, saved in RWGPS, and re-downloaded in Cue Wizard, you'll see your errors disappear. If you still see errors, fix them. Save. Re-download. Eventually you should see no errors and the buttons to generate cues and cards for the route will appear.

By default, brevet cards are printed with a blank area where a rider's name and address can be written, on attached with a sticker. If the list of riders is available as a CSV file, this roster can be uploaded and the card backs will be filled out with the rider names, addresses, and a bar code containing the rider name and RUSA number.

The CSV roster file format is similar to that accepted by Card-O-Matic. The CSV file must have a header containing column names containing strings from this list: RUSA, FIRST, LAST, STREET, ADDRESS, CITY, STATE, and ZIP. All columns are optional except either "RUSA" or "LAST". The column names are case insensitive. Longer names that contain these strings are accepted (eg FIRST_NAME is accepted as FIRST). Column names that don't match the strings listed are ignored.

If rider names are available, a Code 128 barcode is printed on the card. The barcode contains the RUSA ID number, last name, and first initial of the rider, concatinated without blanks. Any of these are not available (eg non-RUSA rider) it is omitted. The barcode is useful for "quick check-in" at controles by means of a cell phone barcode scanning app.

For More Information

If you have questions, just ask the PA Rando webmaster.

License and Source Code

Cue Wizard is written in PHP and requires the CodeIgniter framework as well as the FPDF library. The source code for this website is available for free download under the terms of the GNU Affero General Public License.