Route Processor

Cue Wizard

Introduction

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:

• Free and available online for any rando club for use.
• Supports eBrevet mobile phone app with real time rider checkin tracking displayed online.
• 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 controle time calculations based on verified algorithms.
• Support for untimed controls.
• Mass start event date/time, or free start
• Worldwide time-zone and "daylight savings time" support
• Download links for GPX, and JSON route files
• Automatic distance segment calculations
• Route maps and elevation profiles
• Automatic search/replace cue note simplification
• Distinctive formatting of Controle cues (staffed, merchant, info...)
• Support for "photo" and "info" controles
• Custom brevet card logo
• Rider roster and finish results support
• Custom club logo and other club specific configuration
• Source code freely available

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:

• Cues for Controls — These cues must be marked as 'control' type. This step is already required by RUSA to submit routes to their route library.
• Control Note Attributes — Cue Wizard requires that each control is fully described with a set of hashtag #name=value pairs typed in the cue 'notes'. At a minimum the #name, #address, and #style of the cue must be specified. For #style=info cues, the control #question must be specified. For #style=photo controls, the #photo must be specified. If you would like this control to be un-timed per the new liberal ACP rule, add the #timed=no attribute.

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

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.

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.

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:

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.