PA Randonneurs Cue Wizard

An automated system for making cue sheets and brevet cards directly from Ride With GPS (RWGPS) route data.

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 allow randonneuring routes to be edited and maintained only in RWGPS. With Cue Wizard, the production of brevet cards and cue sheets becomes a mechanical, automatic "one-click" process once all data is entered into RWGPS.

Features of Cue Wizard include:

Cue Wizard is similar to 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 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. You don't need any special password. You don't even have to ask permission to use it (although comments are all welcome, especially positive ones). All you need to use Cue Wizard is your RWGPS route number that you splice into a special URL. You can find the route number at the end of the RWGPS URL for viewing the route. For example, the PA Rando YARRR permanent (not the brevet) is RWGPS URL https://ridewithgps.com/routes/30586971 so the route number is 30586971

Once you know the route number, put it in a "Cue Wizard" URL like this

https://parando.org/route/id/XXXXXXXX

where you replace the X's with your 8 digit RWGPS URL

https://parando.org/route/id/30586971

That's it. If you follow that link you'll now be at a page that will allow you to make cards and cue sheets from the route. If you try the above magic route/id URL you'll see the YARRR data and it should all work fine. Of course, when you 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

Before you can use it effectively with our system, you need to add three things to your RWGPS route: 1) detailed notes on cues as required for cue sheet completeness and rider safety, 2) cues for Controles, and 3) description info for the overall route. Once you add those three 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.

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
#name=Wawa
#address=1520 E High St, Pottstown, PA 19464
#style=merchant
#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, merchant, open, info, photo, or postcard
#question=Question to answer? (Required for info styles)
#photo=What to photograph. (Required for photo styles)
#tzname=Time Zone Name, required 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".

It's only necessary to enter the timezone of a controle (using the #tzname tag) if the controle is in a differnt timezone than the overall event. See below for specifying the overall timezone.

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.

SearchReplaceCue Direction
(Crossing|Cross)X
Continue (straight onto|onto)B/C SO
Turn right ontoR
Turn left ontoL
Turn right (to stay on|to remain on|TRO)TRO R
Turn left (to stay on|to remain on|TRO)TRO L
T right ontoTR
T left ontoTL
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 ontoBR
(Bear|Slight) left ontoBL
(Bear|Slight) right TROTRO BR
(Bear|Slight) left TROTRO BL
(Immediate|Immed|Immd) left ontoQL
(Immediate|Immed|Immd) right ontoQR
First left onto1st L
First right onto1st 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

Overall Route Description #tags

There is some randonneuring specific data that must be associated with the route as a whole (Event type, official distance, etc...). If you are using this Cue Wizard system to support a PA Randonneurs event, all the rando event specific data is automatically added. You don't need to add any Route Description tags for a PA Rando brevet event. If you ignore this paragraph, and you do add Descriptive data in RWGPS for PA brevet or populaire events, it will be safely ignored.

On the other hand, if you are using this system with a permanent, or non-PA-rando brevet event, you must add #tags to the overall RWGPS route Description before the route will work with the Cue Wizard system.

When you save the route in RWGPS, a window opens up where you can name the route and enter a description. In the Description box for the overall route, you also must add #tags. For example, in the PA Rando YARRR permanent, the Description is:

#name=Yet Another River to River Ride (YARRR)
#location=Easton, PA
#type=permanent
#rusa_route_id=2519
#distance=207
#organization=PA Randonneurs
#organizer_name=Chris Nadovich
#organizer_phone=(267) 555-1212
#organizer_rusa_id=5456
#tzname=America/New_York

Paste something like that into the description when saving (replaced with your own name/phone and route data, of course).

The complete set of #tags you can put in an overall route Description are the following:
#name=Event Name (required, don't include the distance in #name!)
#type=Set to 'permanent' for all RUSA perms, 'rusa' or 'acp' for brevets
#distance=Official listed distance in km
#location=Start location (City, State) (required)
#tzname=Time zone name, see below
#organizer_name=Route owner, RBA, or Organizer name
#organizer_phone=Contact phone for emergencies
#organizer_rusa_id=Required for permanents
#rusa_route_id=Required for permanents
#time=HH:MM start time (optional)
#date=YYYY-MM-DD start date (optional)
#comment=Printed on cue sheet (optional), see below
#in_case_of_emergency=Printed on cue sheet (optional), see below
#organization=Your Club Name (optional)
#logo_url=Artwork to display instead of RUSA logo (optional)
#cue_abbreviations=List of cue abbreviatios (optional), see below
The formatting rules for these overall description tags are the same as for the controle tags.

Specifying Time Zones

Not all brevets and perms are in a single, unambiguous timezone, and some people even schedule events across daylight savings time transitions. In support of this fact, you must specify a timezone for your event. If your whole event is in a single timezone, you only enter the timezone once in the overall event description. For example, add the tag #tzname=America/New_York if your route is entirely in the US Eastern time zone. The US timezones are the following:

Eastern ........... America/New_York
Central ........... America/Chicago
Mountain .......... America/Denver
Mountain no DST ... America/Phoenix
Pacific ........... America/Los_Angeles
Alaska ............ America/Anchorage
Hawaii ............ America/Adak
Hawaii no DST ..... Pacific/Honolulu
For complete list of valid timezones worldwide, see https://www.php.net/manual/en/timezones.php

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:

***: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

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.

#cue_abbreviations = WART:Warning Another Railroad Track, TFL:Turn Freekin Left

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:

If abandoning ride or to report a problem call the organizer: {$organizer_name} ({$organizer_phone}). For Medical/Safety Emergencies Call 911 First!

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.

The event start date and time can be customized before the paperwork is generated. This is a handy feature for permanents or events that repeat. You don't need to edit the #date and #time tags in RWGPS, you can simply enter the event date and time each time you generate cards and cuesheets. It's also OK to leave the start date and time blank. If you do this, the times will be calculated based on a start on Day-0 at 00:00 AM (midnight), giving you a generic card or cue sheet that can be used at any time.

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.

PA Randonneurs Website Software
Copyright (C) 2019 Chris Nadovich https://parando.org/info/contact/webmaster

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.