SpeakJet.h

// SpeakJet.h
//
// Author: Mike McCauley (mikem@airspayce.com)
// Copyright (C) 2011 Mike McCauley
// $Id: SpeakJet.h,v 1.3 2012/11/26 21:01:51 mikem Exp mikem $
/// \mainpage SpeakJet library for Arduino
///
/// This is the Arduino SpeakJet library.
/// It provides an object-oriented class for driving a SpeakJet 
/// http://www.sparkfun.com/datasheets/Components/General/speakjet-usermanual.pdf speech synthesizer chip,
/// such as installed on SparkFun VoiceBox shield https://www.sparkfun.com/products/10661
///
/// It supports speaking of:
/// - raw individual phonemes
/// - arrays of phonemes
/// - words from a custom dictionary or the standard built-in dictionary
/// - sentences (sequences of words) from a custom dictionary or the standard built-in dicitonary
/// - integers from 0 to over 4 billion
/// - strings of digits or IP addresses
/// - creation and conversion of custom word-to-phonemes dictionaries
///
/// The version of the package that this documentation refers to can be downloaded 
/// from http://www.airspayce.com/mikem/arduino/SpeakJet/SpeakJet-1.5.zip
/// You can find the latest version at http://www.airspayce.com/mikem/arduino/SpeakJet
///
/// Tested with SparkFun VoiceBox on Uno, Duemilanove, Diecimila, Mega. 
/// Tested with Arduino 0021 and 1.0.2
///
/// \par Electrical connection to the SpeakJet
///
/// The connection to the SpeakJet chip requires 3 digital pins:
/// - Serial Data Tx from Arduino to the SpeakJet (RS232, using the SoftwereSerial class)
/// - Chip ready pin from the SpeakJet 'Speak' to the Arduino (low is ready)
/// - Reset from the Arduino to the SpeakJet (high is reset)
///
/// Naturally, ground and 5V are also required to supply the chip.
///
/// The SpeakJet library uses SoftwareSerial to send Serial commands at 9600 baud to the SpeakJet chip, using any of the 
/// Arduino Digital output pins. The default is pin D2. No serial data is read from the SpeakJet chip.
///
/// The SpeakJet constructor is where  you specify the Arduino digital pins to use for each of these functions. 
/// The default values work with a standard SparkFun VoideBox shield https://www.sparkfun.com/products/10661
///
/// \par Dictionaries
/// 
/// The SpeakJet library comes with a standard dictionary of approximately 1400 words, phrases and sound effects. 
/// The functions speakWord() and speakWords() speak sound effects and words from this dictionary. It is based on the 
/// PhraseALator.Dic dictionary file provided by SpeakJet, but converted to a 'C' structure 
/// for use by this SpeakJet library (see standardDict.cpp).
///
/// Alternatively you can create your own dictionary (either as a subset of the standard dictionary, 
/// or from scratch with your own words, or a combination of the two) and use speakWordfromDictionary() 
/// and speakWordsfromDictionary().
///
/// The included convertDict.pl perl script reads one or more dictionary files in the same format as 
/// PhraseALator.Dic and emits a 'C' file suitable for including in a header file or a .c or .cpp file.
///
/// Also included is a smaller dictionary (numericDict.cpp) that includes mostly only numbers, and is used to speak 
/// integers and digits with speakNumber() and speakDigits().
///
/// In SpeakJet, a Dictionary is an array of DictionaryItem structures, terminated by an empty DictionaryItem. 
/// You can build these by hand in your sketch, or you can rely on convertDict to create them from 
/// a text .dic file. In any case, it is essential that the Dictionary, and all the words and code sequences it 
/// points to are in PROGMEN. This will save you RAM.
///
/// The standard dictionary and it set of 1400 or so words occupies about 30kbytes of Flash program memory. 
/// This is far biger than some Arduinos can handle, and is quite close to the total permissable program size 
/// for say the Arduino Uno. Fortunately the standard dictionary is only linked if you use 
/// speakWord() or speakWords().
///
/// The supplied standard and numeric dicitonaries only support English, but you could contruct your own 
/// dictionaries to support other languages.
///
/// \par convertDict.pl
///
/// This support script is used to convert text dictionary files into 'C' structures suitable for including in
/// sketches or other C program files. It is used to create the numericDict.cpp and standardDict.cpp header 
/// files that are shippped with the SpeakJet library, but you can use to to create your own dictionary header files.
/// 
/// Command line arguments can be used to control the C variable name of the dictionary, 
/// so you can have several different dictionaries in your sketch. 
/// It can be used to creat a single dictionary out of one or more dictionary text files.
///
/// Caution: while the .dic file format permits words to be defined in terms of other words, this is not supported
/// by convertDict.pl. Any word defintion that is *not* in terms of basic phonemes is flagged as an error and 
/// is not added to the dictionary structure. This is mainly to avoid the fx* words int the PhraseALator.Dic file
/// being included in the standard dictionary and blowing the size out to more that 32 k.
///
/// The format of the input dictionary files is:
/// [words]
/// word=\\PH \\PH \\PH \\PH ....
/// where 'word' is the ASCII text of the word to be spoken, and \\PH \\PH ... is a sequence of standard phoneme
/// mnemonics or control codes that will be used to speak the word.
///
/// convertDict.pl will automatically append the EndOfPhrase byte required by every DictionaryEntry code array.
/// 
/// \par Examples.
///
/// A number of example sketches and a test suite illustrating the use of the public functions in SpeakJet is included.
///
/// \par Installation
///
/// Install in the usual way: unzip the distribution zip file to the libraries
/// sub-folder of your sketchbook. 
///
/// This software is Copyright (C) 2011 Mike McCauley. Use is subject to license
/// conditions. The main licensing options available are GPL V2 or Commercial:
/// 
/// \par Open Source Licensing GPL V2
///
/// This is the appropriate option if you want to share the source code of your
/// application with everyone you distribute it to, and you also want to give them
/// the right to share who uses it. If you wish to use this software under Open
/// Source Licensing, you must contribute all your source code to the open source
/// community in accordance with the GPL Version 2 when your application is
/// distributed. See http://www.gnu.org/copyleft/gpl.html
/// 
/// \par Commercial Licensing
///
/// This is the appropriate option if you are creating proprietary applications
/// and you are not prepared to distribute and share the source code of your
/// application. Contact info@airspayce.com for details.
///
/// \par Revision History
///
/// \version 1.0 Initial release
/// \version 1.1 Improve documentation
/// \version 1.3 Now Compiles amd runs with Arduino 0021. Added more documentation. 
///              Constructor invertPin argument
///              removed (not available before Arduino 1.0)
/// \version 1.4 Updated author and distribution location details to airspayce.com
/// \version 1.5 2024-10-16 fixes to allow compilation uner modern Arduino IDE 2.3.2
///
 
#ifndef SPEAKJET_h
#define SPEAKJET_h
 
#if ARDUINO >= 100
#include <Arduino.h>
#else
#include <wiring.h>
#include <avr/pgmspace.h>
// These defs cause trouble on some versions of Arduino
#undef abs
#undef double
#undef round
#endif
 
#include <SoftwareSerial.h>
 
/////////////////////////////////////////////////////////////////////
/// \class SpeakJet SpeakJet.h <SpeakJet.h>
/// \brief Driver object for SpeakJet chips such as on SparkFun 
/// VoiceBox shield https://www.sparkfun.com/products/10661
///
/// Uses SoftwareSerial class to send command codes to the SpeakJet chip.
/// Supports a wide range of funcitons for speaking words, phrases, numbers and strings of digits.
///
class SpeakJet : public SoftwareSerial
{
public:
 
    /// \brief Structure for translating text words into SpeakJet codes.
    ///
    /// word is a pointer to the ASCII text of the word to be pronounced.
    /// codes is an array of SpeakJet phoneme codes that will be used to speak the word. 
    /// It must end with EndOfPhrase (0xff).
    /// The entire dictionary must also be in PROGMEM.
    /// See the included dicitonary files standardDict.cpp and numericDict.cpp for examples on
    /// how to achieve this.
    /// Alternatively use convertDict.pl to create correctly structured Dictionary from a .dic text file.
    typedef struct
    {
        const char*   word;   ///< ASCII text of word to speak (must be in PROGMEM)
        const uint8_t*  codes;  ///< Array of speakjet control codes. End with EndOfPhrase (0xff) (must be in PROGMEM)
    } DictionaryEntry;
 
    /// Command codes for SpeakJet chip.
    /// These can be passed to speakCode().
    /// Arrays of them can be passed to speakCodes(), with an EndOfPhrase at the end.
    /// Based on http://www.sparkfun.com/datasheets/Components/General/speakjet-usermanual.pdf
    typedef enum
    {
        Pause0        = 0,                     ///< Pause 0ms
        Pause1        = 1,                     ///< Pause 100ms
        Pause2        = 2,                     ///< Pause 200ms
        Pause3        = 3,                     ///< Pause 700ms
        Pause4        = 4,                     ///< Pause 30ms
        Pause5        = 5,                     ///< Pause 60ms
        Pause6        = 6,                     ///< Pause 90ms
        Fast          = 7,                     ///< Next phoneme at 0.5 speed
        Slow          = 8,                     ///< Next phoneme at 1.5 speed
        Stress        = 14,                    ///< Next phoneme with some stress
        Relax         = 15,                    ///< Next phoneme with relaxation
        Wait          = 16,                    ///< Stops and waits for a Start (see manual)
        Soft          = 18,                    ///< Stops and waits for a Start (see manual)
        Volume        = 20,                    ///< Next octet is volume 0 to 127. Default 96
        Speed         = 21,                    ///< Next octet is speed 0 to 127. Default 114
        Pitch         = 22,                    ///< Next octet is pitch in Hz = to 255
        Bend          = 23,                    ///< Next octet is frequency bend  to 15. Default is 5
        PortCtr       = 24,                    ///< Next octet is port control value. See manual. Default is 7
        Port          = 25,                    ///< Next octet is Port Output Value. See manual. Default is 0
        Repeat        = 26,                    ///< Next octet is repeat count. 0 to 255
        CallPhrase    = 28,                    ///< Next octet is EEPROM phrase to play and return. See manual.
        GotoPhrase    = 29,                    ///< Next octet is EEPROM phgrase to go to. See manual.
        Delay         = 30,                    ///< Next octet is delay in multiples of 10ms. 0 to 255.
        Reset         = 31,                    ///< Reset Volume Speed, Pitch, Bend to defaults.
 
        // 32 to 127 reserved
 
        // 128 to 254 Sound codes
        // Phonemes, standard names
        Phoneme_IY    = 128,                   ///< 70ms Voiced Long Vowel
        Phoneme_IH    = 129,                   ///< 70ms Voiced Long Vowel
        Phoneme_EY    = 130,                   ///< 70ms Voiced Long Vowel
        Phoneme_EH    = 131,                   ///< 70ms Voiced Long Vowel
        Phoneme_AY    = 132,                   ///< 70ms Voiced Long Vowel
        Phoneme_AX    = 133,                   ///< 70ms Voiced Long Vowel
        Phoneme_UX    = 134,                   ///< 70ms Voiced Long Vowel
        Phoneme_OH    = 135,                   ///< 70ms Voiced Long Vowel
        Phoneme_AW    = 136,                   ///< 70ms Voiced Long Vowel
        Phoneme_OW    = 137,                   ///< 70ms Voiced Long Vowel
        Phoneme_UH    = 138,                   ///< 70ms Voiced Long Vowel
        Phoneme_UW    = 139,                   ///< 70ms Voiced Long Vowel
        Phoneme_MM    = 140,                   ///< 70ms Voiced Nasal
        Phoneme_NE    = 141,                   ///< 70ms Voiced Nasal
        Phoneme_NO    = 142,                   ///< 70ms Voiced Nasal
        Phoneme_NGE   = 143,                   ///< 70ms Voiced Nasal
        Phoneme_NGO   = 144,                   ///< 70ms Voiced Nasal
        Phoneme_LE    = 145,                   ///< 70ms Voiced Resonate
        Phoneme_LO    = 146,                   ///< 70ms Voiced Resonate
        Phoneme_WW    = 147,                   ///< 70ms Voiced Resonate
        Phoneme_RR    = 149,                   ///< 70ms Voiced Resonate
        Phoneme_IYRR  = 149,                   ///< 200ms Voiced R Color Vowel
        Phoneme_EYRR  = 150,                   ///< 200ms Voiced R Color Vowel
        Phoneme_AXRR  = 151,                   ///< 190ms Voiced R Color Vowel
        Phoneme_AWRR  = 152,                   ///< 200ms Voiced R Color Vowel
        Phoneme_OWRR  = 153,                   ///< 185ms Voiced R Color Vowel
        Phoneme_EYIY  = 154,                   ///< 165ms Voiced Diphthong
        Phoneme_OHIY  = 155,                   ///< 200ms Voiced Diphthong
        Phoneme_OWIY  = 156,                   ///< 225ms Voiced Diphthong
        Phoneme_OHIH  = 157,                   ///< 185ms Voiced Diphthong
        Phoneme_IYEH  = 158,                   ///< 170ms Voiced Diphthong
        Phoneme_EHLE  = 159,                   ///< 140ms Voiced Diphthong
        Phoneme_IYUW  = 160,                   ///< 180ms Voiced Diphthong
        Phoneme_AXUW  = 161,                   ///< 170ms Voiced Diphthong
        Phoneme_IHWW  = 162,                   ///< 170ms Voiced Diphthong
        Phoneme_AYWW  = 163,                   ///< 200ms Voiced Diphthong
        Phoneme_OWWW  = 164,                   ///< 131ms Voiced Diphthong
        Phoneme_JH    = 165,                   ///< 70ms Voiced Affricate
        Phoneme_VV    = 166,                   ///< 70ms Voiced Fricative
        Phoneme_ZZ    = 167,                   ///< 70ms Voiced Fricative 
        Phoneme_ZH    = 168,                   ///< 70ms Voiced Fricative
        Phoneme_DH    = 169,                   ///< 70ms Voiced Fricative
        Phoneme_BE    = 170,                   ///< 45ms Voiced Stop
        Phoneme_BO    = 171,                   ///< 45ms Voiced Stop
        Phoneme_EB    = 172,                   ///< 10ms Voiced Stop
        Phoneme_OB    = 173,                   ///< 10ms Voiced Stop
        Phoneme_DE    = 174,                   ///< 45ms Voiced Stop
        Phoneme_DO    = 174,                   ///< 45ms Voiced Stop
        Phoneme_ED    = 176,                   ///< 10ms Voiced Stop
        Phoneme_OD    = 177,                   ///< 10ms Voiced Stop
        Phoneme_GE    = 178,                   ///< 55ms Voiced Stop
        Phoneme_GO    = 179,                   ///< 55ms Voiced Stop
        Phoneme_EG    = 180,                   ///< 55ms Voiced Stop
        Phoneme_OG    = 181,                   ///< 55ms Voiced Stop
        Phoneme_CH    = 182,                   ///< 70ms Voiceless Affricate
        Phoneme_HE    = 183,                   ///< 70ms Voiceless Fricative
        Phoneme_HO    = 184,                   ///< 70ms Voiceless Fricative
        Phoneme_WH    = 185,                   ///< 70ms Voiceless Fricative
        Phoneme_FF    = 186,                   ///< 70ms Voiceless Fricative
        Phoneme_SE    = 187,                   ///< 40ms Voiceless Fricative
        Phoneme_SO    = 188,                   ///< 40ms Voiceless Fricative
        Phoneme_SH    = 189,                   ///< 50ms Voiceless Fricative
        Phoneme_TH    = 190,                   ///< 40ms Voiceless Fricative
        Phoneme_TT    = 191,                   ///< 50ms Voiceless Stop
        Phoneme_TU    = 192,                   ///< 70ms Voiceless Stop
        Phoneme_TS    = 193,                   ///< 170ms Voiceless Stop
        Phoneme_KE    = 194,                   ///< 55ms Voiceless Stop
        Phoneme_KO    = 195,                   ///< 55ms Voiceless Stop
        Phoneme_EK    = 196,                   ///< 55ms Voiceless Stop
        Phoneme_OK    = 197,                   ///< 45ms Voiceless Stop
        Phoneme_PE    = 198,                   ///< 99ms Voiceless Stop
        Phoneme_PO    = 199,                   ///< 99ms Voiceless Stop
        // Robot sound
        Sound_R0      = 200,                   ///< 80ms Robot
        Sound_R1      = 201,                   ///< 80ms Robot
        Sound_R2      = 202,                   ///< 80ms Robot
        Sound_R3      = 203,                   ///< 80ms Robot
        Sound_R4      = 204,                   ///< 80ms Robot
        Sound_R5      = 205,                   ///< 80ms Robot
        Sound_R6      = 206,                   ///< 80ms Robot
        Sound_R7      = 207,                   ///< 80ms Robot
        Sound_R8      = 208,                   ///< 80ms Robot
        Sound_R9      = 209,                   ///< 80ms Robot
        // Alarm sound
        Sound_A0      = 210,                   ///< 300ms Alarm
        Sound_A1      = 211,                   ///< 101ms Alarm
        Sound_A2      = 212,                   ///< 102ms Alarm
        Sound_A3      = 213,                   ///< 540ms Alarm
        Sound_A4      = 214,                   ///< 530ms Alarm
        Sound_A5      = 215,                   ///< 500ms Alarm
        Sound_A6      = 216,                   ///< 135ms Alarm
        Sound_A7      = 217,                   ///< 600ms Alarm
        Sound_A8      = 218,                   ///< 300ms Alarm
        Sound_A9      = 219,                   ///< 250ms Alarm
        // Beeps
        Sound_B0      = 220,                   ///< 200ms Beep
        Sound_B1      = 221,                   ///< 270ms Beep
        Sound_B2      = 222,                   ///< 280ms Beep
        Sound_B3      = 223,                   ///< 260ms Beep
        Sound_B4      = 224,                   ///< 300ms Beep
        Sound_B5      = 225,                   ///< 100ms Beep
        Sound_B6      = 226,                   ///< 104ms Beep
        Sound_B7      = 227,                   ///< 100ms Beep
        Sound_B8      = 228,                   ///< 270ms Beep
        Sound_B9      = 229,                   ///< 262ms Beep
        // Biological
        Sound_C0      = 230,                   ///< 160ms Biological
        Sound_C1      = 231,                   ///< 300ms Biological
        Sound_C2      = 232,                   ///< 182ms Biological
        Sound_C3      = 233,                   ///< 120ms Biological
        Sound_C4      = 234,                   ///< 175ms Biological
        Sound_C5      = 235,                   ///< 350ms Biological
        Sound_C6      = 236,                   ///< 160ms Biological
        Sound_C7      = 237,                   ///< 260ms Biological
        Sound_C8      = 238,                   ///< 95ms Biological
        Sound_C9      = 239,                   ///< 75ms Biological
        // DTMF 
        DTMF_0        = 240,                   ///< DTMF 0 95ms
        DTMF_1        = 241,                   ///< DTMF 1 95ms
        DTMF_2        = 242,                   ///< DTMF 2 95ms
        DTMF_3        = 243,                   ///< DTMF 3 95ms
        DTMF_4        = 244,                   ///< DTMF 4 95ms
        DTMF_5        = 245,                   ///< DTMF 5 95ms
        DTMF_6        = 246,                   ///< DTMF 6 95ms
        DTMF_7        = 247,                   ///< DTMF 7 95ms
        DTMF_8        = 248,                   ///< DTMF 8 95ms
        DTMF_9        = 249,                   ///< DTMF 9 95ms
        DTMF_STAR     = 250,                   ///< DTMF * 95ms
        DTMF_HASH     = 251,                   ///< DTMF # 95ms
        // Miscellaneous
        Sound_M0      = 252,                   ///< Sonar ping 125ms
        Sound_M1      = 253,                   ///< Pistol shot 250ms
        Sound_M2      = 254,                   ///< WOW 530ms
 
        EndOfPhrase   = 255,                   ///< End of phrase marker. Required at end of code arrays
 
    } CommandCodes;
 
 
    /// Constructor.
    /// Specifies the Arduino digital pins to use to communicate with the SpeakJet chip.
    /// The default values of the arguments are suitable for use with the standard SparkFun VoiceBox shield.
    /// You can have multiple instances to talk to different SpeakJet chips, provided they use
    /// interface pins.
    /// \param[in] txPin Digital pin to use to send command codes to the SpeakJet. Defaults to 2.
    /// \param[in] resetPin Digital pin to use to force a reset of the SpeakJet. Defaults to 3.
    /// \param[in] readyPin Digital pin to use to read if the SpeakJet is ready for another code. 
    ///            Defaults to 4, the SPK pin output from the SpeakJet chip.
    SpeakJet(uint8_t txPin = 2, uint8_t resetPin = 3, uint8_t readyPin = 4);
 
    /// Object initialiser.
    /// This causes the digital interface pins in the constructor to be set for input or output as the case may be
    /// The SoftwareSerial interface is initialised to 9600 baud, and the SpeakJet is reset by 
    /// forcing the Reset pin high for 100ms.
    /// \return true if the reset succeeded.
    bool    init();
 
    /// Reset the SpeakJet chip.
    /// Forces the Reset pin high for 100ms.
    bool    reset();
 
    /// Check if the SpeakJet chip is ready 
    /// to receive another code. Reads the state of the readyPin configured in the constructor. Low is ready.
    /// \return true if it is ready.
    bool    isReady();
 
    /// Wait until the SpeakJet chip is ready.
    /// Blocks until isReady() return true.
    void    waitReady();
 
    /// Speak a single phoneme code.
    /// Waits until the SpeakJet chip is ready, then sends a single code (one of the CommandCodes enum entries)
    /// This is the basic function used to send all codes to the chip.
    /// Can also be used to sen control codes like Pause, Volume Speed etc to control the enunciation of following
    /// Phonemes.
    /// Returns after the code has been sent.
    /// \param[in] code One of the CommandCodes enum entries or a raw code number
    void    speakCode(uint8_t code);
 
    /// Speak a an array of phoneme codes.
    /// Waits until the SpeakJet chip is ready, then sends a single code (one of the CommandCodes enum entries)
    /// This is the basic function used to send all codes to the chip.
    /// Returns after the code has been sent.
    /// \param[in] codes Array of command codes, terminated by EndOfPhrase (255)
    void    speakCodes(uint8_t *codes);
 
    /// Speaks a single dictionary entry
    /// This low level function sends the code array of a DictionaryEntry to the SpeakJet chip.
    /// You can call it from your own sketches, but it probably rarely necessary.
    /// \param[in] dict Pointer to a DictionaryEntry in PROGMEM
    /// \return true if successful.
    bool    speakDictionaryEntry(const DictionaryEntry* dict);
 
    /// Speaks a single word from a Dictionary.
    /// Searches a Dictionary for an exactly matching word and then sends the corresponding codes
    /// to the SpeakJet chip.
    /// Caution: A linear search is currently used.
    /// \param[in] word The word to speak in the dictionary
    /// \param[in] dict Pointer to the first of a set of DictionaryEntry structures, one for each word in the Dictionary.
    /// \return true if successful. False if the word is not present in the dictionary.
    bool    speakWordFromDictionary(const char* word, const DictionaryEntry* dict);
 
    /// Speak a sequence of words from a Dictionary.
    /// The sequnce of words is spit by whitespace and the individual words are spoken one after another,
    /// with a Pause1 between each word.
    /// \param[in] words String of space separated words
    /// \param[in] dict Pointer to the first of a set of DictionaryEntry structures, one for each word in the Dictionary.
    /// \return true if successful.
    bool    speakWordsFromDictionary(char* words, const DictionaryEntry* dict);
 
    /// Speak a word from the standard Dictionary.
    /// If the word is present in the standard dictionary, the codes will be sent to the SpeakJet chip.
    /// \param[in] word The word to speak in the dictionary
    /// \return true if successful.
    bool    speakWord(const char* word);
 
    /// Speak a sequence of words from a standard Dictionary.
    /// \param[in] words String of space separated words
    /// \return true if successful.
    bool    speakWords(char* words);
 
    /// Speak the digits in a string.
    /// Each digit (and some punctuation) is spoken one charavcter at a time. Suported are:
    /// - Digits 0 through 9 
    /// - '-' (sp0ken as "plus")
    /// - '+' (spoken as "minus")
    /// - '.' (spoken as "dot")
    /// Other characters are ignored
    /// \param[in] digits String of digits to be spoken, one at a time
    /// \return true if successful.
    bool    speakDigits(const char* digits);
 
    /// Speaks an integer number from 0 to 99
    /// This low level function is used internally, and you probably would not need to call it from your sketch. 
    /// See instead speakNumber()
    /// \param[in] n Integer from 0 to 99. Returns false if the number exceeds 99.
    /// \return true if successful.
    bool    speakNumber99(uint8_t n);
 
    /// Speaks an integer number from 0 to 999
    /// This low level function is used internally, and you probably would not need to call it from your sketch. 
    /// See instead speakNumber()
    /// \param[in] n Integer from 0 to 99. Returns false if the number exceeds 999.
    /// \return true if successful.
    bool    speakNumber999(uint16_t n);
 
    /// Speaks an integer number from 0 to (2^32 -1)
    /// Converts the integer into an conventional English phrase for saying he number out loud such as:
    /// 0 -> "zero"
    /// 9 -> "nine"
    /// 10 -> "ten"
    /// 999 -> "nine hundred and ninety nine"
    /// 1000 -> "one thousand"
    /// 1001 -> "one thousand and one"
    /// 65377 -> "sixty five thousand three hundred and seventy seven"
    /// \param[in] n integer number from 0 to (2^32 -1)
    /// \return true if successful.
    bool    speakNumber(uint32_t n);
 
 
private:
 
    /// The digital out pin used to issue a reset to the SpeakJet chip
    uint8_t _resetPin;
 
    /// The digital input pin used to check whether the SpeakJet chip is ready for another code.
    uint8_t _readyPin;
 
};
 
 
/// @example test.pde
/// Test suite sketch.
/// Tests all the SpeakJet library calls, and shows how to call them.
/// Demonstrates the use of custom and standard dictionaries, and the numeric dicitonary
/// for digits and numbers.
/// Uses the standard dictionary and therefore links to about 32K in size
/// which will not fit in some Arduinos.
/// Tested on Arduino Uno.
#endif