Emergency Excuse Generator
      Main           Schematics & Code           Construction           Customize It!           Try It!      Other Projects  
  





   




Although this project is labeled Emergency Excuse Generator, it doesn't mean you can use it only for this purpose. In fact, it is quite easy to replace the "excuse" part and turn the device into something very different (for example a really fancy Magic 8 Ball that has thousands answers, not just a few).

If you write your own generator, I would appreciate if you can share it. If you send it to me I can post it on this page - with full credits and with a link to your website, of course.

Defining the Generating Rules
To create your own generator, you need to write a file that describes the rules according to which the text is produced. Using the form at the bottom of this page you can compile this rule data and generate an include file to use in place of the default excuse.inc. Upload this to your Excuse Generator and you will have a Magic 8 Ball instead. Or anything that strikes your fancy.

A rule file is a list of replacement rules that describe how the output text is going to be generated. Each row in this file corresponds to one rule in the following format: 
  rule_id:replacement text
The rule_id is a string, composed of numbers, letters, and the underscore character, such as rule_number_1. Other than a few specially used rule_id-s, it can be anything that will make you remember what the rule is for. There can be more than one rule with the same ID - those rules are considered interchangeable.

The replacement can be anything. It can contain just plain text but also can have references to other rules. Rule references are surrounded with < and >, for example <rule_number_2> is a reference to rule_number_2.

OK, this so far may look quite abstract and complicated, but I believe a small example will clear up everything. Take a look at the following rule file snippet: 
  opinion:you are a <adjective> <noun>
  adjective:good
  adjective:bad
  noun:manager
  noun:programmer
Let start from the opinion rule. This rule will generate an opinion in the form you are a something. The something is a text composed by invoking an adjective and noun rule. But note that we have two adjective and two noun rules. Which one of them will be invoked depends purely on chance. So, once you will see 
  you are a good manager
and other time 
  you are a bad programmer
Rules can be cascaded at several levels. Let say we want to generate more complex text, so we will add add two more rules to our file: 
  express_opinion:I think <opinion>
  express_opinion:<opinion>, I believe
Now, when the express_opinion rule is invoked, it will produce text like 
  I think you are a good programmer
  you are a bad manager, I believe
Because in the context we are using them believe and think are pretty much interchangeable, we can increase the flexibility even more by assigning those two to a new rule. Here are all rules put together: 
  express_opinion:I <think_or_believe> <opinion>
  express_opinion:<opinion>, I <think_or_believe>
  opinion:you are a <adjective> <noun>
  adjective:good
  adjective:bad
  noun:manager
  noun:programmer
  think_or_believe:think
  think_or_believe:believe
All in all, this very simple file can already generate 32 possible sentences (not very creative, I admit, but this is not the point).

Special Rules
Maybe at you are already wondering how we can specify which rule is the "main" one. How does the microcontroller know that it has to start with the express_opinion rule, and not from noun? The order of the rules is not important. This order may not be even preserved when the file is processed later. Instead, the rules are distinguished by their IDs - special rules have IDs that consist of numbers only.

In the current version of the code, only three special rules are recognized: 0, 1, and 2:

The 0 rule is invoked when a the button on the generator is pressed. This will be the main rule from where you will reference all other rules.

The 1 and 2 rules must result in strings of 16 characters each. Those are used to display some welcome text when the device is powered up. In the default Excuse Generator table, they are just showing the version info and the Generator's web page address: 
  1:EEG Version 1.00
  2:avtanski.net/eeg
So, a valid rule file (for a mindless chatty generator) may look something like this: 
  1:EEG Version 1.00
  2:avtanski.net/eeg
  0:<express_opinion>
  0:<say_something_rude>
  0:<say_something_nice>
  0:<ask_something_personal>
  ... and so on, and so on, followed by
      the definitions of all those rules ...
You must have the 0, 1, and 2 rules in your rule file - the code expect those to be in place, and will not compile if they are missing. You are free to change the text as you see fit, however.

Other Considerations
Finally, there are a few tips and tricks that I couldn't fit anywhere else:
  • Automatic Capitalization. The generator code is written to automatically switch the first letter of each displayed statement to uppercase. This may save you a lot of trouble in the rule file. If you don't want this automatic capitalization, you can take out the relevant routine in eeg.asm.
  • Mapping spaces. When the rule file is compiled, trailing and starting spaces are removed from the text of each rule. This makes a lot of sense in most cases, but sometimes you may want to keep that space. If so, use the underscore symbol in place of the space. For example rule1:the_ will generate the text "the ", with a trailing space.
  • Recursive Rule References. It is generally a good idea to avoid recursive references - situations when a rule refers to itself either directly, through his own replacement text, or indirectly, by referring a rule that somewhere down the chain refers back to the original rule. The problem is that you don't have a guarantee that the text generation will ever complete - you may also get a stack overflow or two. Recursive references may be used with the proper care - try to avoid them, but sometimes a recursion can save you a lot of time.
  • More Special Rules. In case you need to refer to more special rules, use rule IDs that consists of numbers only. For every such ID a pair of #define-s will be generated in the include file. You can take a look at excuse.inc and eeg.asm to see those defines and how are they used.


Rule Compiler
Use the form below to test and compile your rules. Paste the rule file text into the text area. Pressing the Generate Sample button will execute your rules, will let you know if there are any problems, and will generate a list of sample statements.

The End Address box specifies where in the program memory you want your data table to terminate. The default value is 0x0FFF, which means that for PIC16F690 the data table will be pushed to the very end of the program memory, leaving the maximum possible space for modifications to the main code. When testing your rules, keep monitoring the Start Address field to ensure that there is enough room for the main program. Try to avoid tables starting below 0x200.

Pressing the Generate Include File button will compile your rules and will produce an include file. Modify eeg.asm to refer to this file instead of excuse.inc.


  
      Main           Schematics & Code           Construction           Customize It!           Try It!      Other Projects