Route Processor

Cue Wizard

An automated system for processing routes for use by the eBrevet mobile phone app, and for making paperwork (eg cue sheets and brevet cards), and much, much more, all directly and automatically from route data on Ride With GPS (RWGPS) or other systems.


The Randonneuring.org web application implements a Route Processor (aka Cue Wizard) that allows you to automatically process RWGPS routes 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. This Route Processor allows randonneuring routes to be created in RWGPS or equivalent system, but then the processor takes over -- fetching a private copy of the route into the randonneuring.org database and publishing various views and data products, including a live eBrevet interface and all subsequent paperwork automatically without involving RWGPS. Control closings are automatically calculated from the route data without needing any special notes. With the Cue Wizard Route Processor, 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 the Cue Wizard Route Processor include:

The Cue Wizard Route Processor is an independently developed system that represents 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.

The Route Processor web application is integrated into the Event Manager at the Randonneuring.Org web site. Any organizer or RBA at any RUSA club can use this system to support their events through the Randonneuring.org website free of charge. For clubs interested in integrating the route processor into their own website, source code for Cue Wizard and other Randonneuring.org tools are available under the Alfero Open Source License.

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 must add these two things to your RWGPS route:

Once you add those things to your route data, your route will process without errors and you can use eBrevet with your event and 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 Randonneuring.org 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 Randonneuring.org 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
#address=1520 E High St, Pottstown, PA 19464
#phone=(610) 718-0889

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:

#name=Name of Location.
#address=Full address with street, city, state, zip
#style=Valid styles are: staffed, overnight, merchant, open, info, photo, or postcard
#timed=no/yes (default is yes)
#question=Question to answer? (Required for info styles)
#photo=What to photograph. (Required for photo styles)
#tzname=Time Zone Name, required only if different than overall TZ
#phone=Phone number of land-line or staff at controle (optional)
#comment=Appended to note (optional)

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.

The #timed=no tag will remove the timing requirement for the control, per the new liberal ACP rule. The default is yes, which only applies the traditional randonneuring timing to open, overnight, merchant or staffed controls. This tag has no effect on photo, info, or postcard controls -- these are always untimed.

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.

Search Replace Cue Direction
(Crossing|Cross) X
Continue (straight onto|onto) B/C SO
Turn right onto R
Turn left onto L
Turn right (to stay on|to remain on|TRO) TRO R
Turn left (to stay on|to remain on|TRO) TRO L
T right onto TR
T left onto TL
T right (to stay on|to remain on|TRO) TRO TR
T left (to stay on|to remain on|TRO) TRO TL
(Bear|Slight) right onto BR
(Bear|Slight) left onto BL
(Bear|Slight) right TRO TRO BR
(Bear|Slight) left TRO TRO BL
(Immediate|Immed|Immd) left onto QL
(Immediate|Immed|Immd) right onto QR
First left onto 1st L
First right onto 1st R
First left (to stay on|to remain on|TRO) TRO 1st L
First right onto (to stay on|to remain on|TRO) TRO 1st R
Second left (to stay on|to remain on|TRO) TRO 2nd L
Second right onto (to stay on|to remain on|TRO) TRO 2nd R

Cue Abbreviations

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:

***:Easy to miss, B:Bear, B/C:Becomes, FMR:Follow Main Road, L:Left, LMR:Leave Main Road, NM:Not Marked,Q:Quick, R:Right, SO:Straight On, SS:Stop Sign, T:T Intersection, TFL:Traffic Light, TRO:To Remain On, X:Cross

Fetching Route Data

After you've added your RWGPS route, and pressed save in RWGPS, you must return to Cue Wizard and press the button "Fetch latest route from RWGPS". If you don't do that, the Randonneuring.org website will not "see" the changes you made in RWGPS. You only need to press the "Fetch" button when you've made changes to the route in the RWGPS website. Randonneuring.org 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.

For More Information

If you have questions, just ask the Randonneuring.org wizard.

For Developers

The software for the Randonneuiring.org website is written in PHP and requires the CodeIgniter 4 framework as well as the FPDF library GroceryCRUD Library, and hosting support for a MySQL database. The source code for this website is available for free download under the terms of the GNU Affero General Public License.


Copyright (C) 2023 Chris Nadovich

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

ABOUT Randonneuring.org