MOVIShield.h

/********************************************************************
 This is a library for the Audeme MOVI Voice Control Shield
 ----> http://www.audeme.com/MOVI/
 This code is inspired and maintained by Audeme but open to change
 and organic development on GITHUB:
 ----> https://github.com/audeme/MOVIArduinoAPI
 Written by Gerald Friedland for Audeme LLC.
 Contact: fractor@audeme.com
 BSD license, all text above must be included in any redistribution.
 ********************************************************************/

#ifndef ____MOVIShield__
#define ____MOVIShield__

#if defined(ARDUINO) && ARDUINO >= 100
#include "arduino.h"
#else
#include "WProgram.h"
#endif

#include <HardwareSerial.h>


#ifndef SERIAL_BAUDRATE
#define SERIAL_BAUDRATE 9600  //  communication rate between MOVI and Arduino. 9600bps is good.
#endif

#ifndef DEBUG_SERIAL_BAUDRATE
#define DEBUG_SERIAL_BAUDRATE 115200  //  communication rate between MOVI and Arduino. 9600bps is good.
#endif




// --- MOVI events ---

#ifndef SHIELD_IDLE
#define SHIELD_IDLE 0
#endif

#ifndef BEGIN_LISTEN
#define BEGIN_LISTEN -140
#endif

#ifndef END_LISTEN
#define END_LISTEN -141
#endif

#ifndef BEGIN_SAY
#define BEGIN_SAY -150
#endif

#ifndef END_SAY
#define END_SAY -151
#endif

#ifndef CALLSIGN_DETECTED
#define CALLSIGN_DETECTED -200
#endif

#ifndef RAW_WORDS
#define RAW_WORDS -201
#endif

#ifndef PASSWORD_ACCEPT
#define PASSWORD_ACCEPT -204
#endif

#ifndef PASSWORD_REJECT
#define PASSWORD_REJECT -404
#endif

#ifndef NOISE_ALARM
#define NOISE_ALARM -530
#endif

#ifndef SILENCE
#define SILENCE -501
#endif

#ifndef UNKNOWN_SENTENCE
#define UNKNOWN_SENTENCE -502
#endif

// --- MOVI useful constants ---

#ifndef MALE_VOICE
#define MALE_VOICE false
#endif

#ifndef FEMALE_VOICE
#define FEMALE_VOICE true
#endif

#ifndef API_VERSION
#define API_VERSION 1.00f
#endif

class MOVI
{
    
public:
    
    // --- Methods that must be used in setup() ----
    
    // Construct a MOVI object with default configuration.
    MOVI();
    
    // Construct a MOVI object with optional serial monitor interaction.
    MOVI(bool debugonoff);
	
	void construct(bool debugonoff);
   
    // init waits for MOVI to be booted and resets some settings. If the recognizer had been stopped with
    // stopDialog() it is restarted.
    void init();
	
    
    // This init method only initializes the API and doesn't wait for MOVI to be ready if the parameter is false.
    void init(bool waitformovi);
    
    // This method can be used to determine if MOVI is ready to receive commands, e.g. when MOVI has been initialized with init(false).
    bool isReady();
    
    // This method adds a sentence to the training set. Sentences must not contain any punctuation or numbers.
    // Everything must be spelled out. No special characters, umlauts or accents. Uppercase or lowercase does
    // not matter.
    bool addSentence(String sentence);
    
    #ifdef F // check to see if F() macro is available
    // addsentence using Flash memory (e.g., addsentence(F("Light On");)
    bool addSentence(const __FlashStringHelper* sentence);
    #endif
    
    // This method checks if the training set contains new sentences since the last training. If so, it trains all
    // sentences added in this MOVI instance. Once training is performed, no more sentences can be added
    // and training cannot be invoked again in the same instance.
    bool train();
    
    // This method sets the callsign to the parameter given. If the callsign has previously been set to the
    // same value, nothing happens. Only one callsign can be trained per MOVI instance. The callsign can be
    // the empty string. The MOVI will react to any noise above the threshold.
    void callSign(String callsign);
    
    
    // --- Methods that are typically used in setup() but can also be used in loop() ---
    
    // Sets the output volume of the speaker.
    void setVolume(int volume);
    
    // Sets the gender of the speech synthesizer.
    void setVoiceGender(bool female);
    
    // Sets the noise threshold of the recognizer. Values vary between 2 and 95. Factory default is 5.
    void setThreshold(int threshold);
    
    // Turns the spoken responses as a result of recognition events (e.g. silence or noise) on or off.
    void responses(bool on);
    
    // Turns off the spoken welcome message indicating the call sign.
    void welcomeMessage(bool on);
    
    // Turns the recognition beeps on or off.
    void beeps(bool on);
    
    // --- Methods that are typically used in loop() ---
    
    // This method is called in loop() to get an event from the recognizer. 0 stand for no event. A postive number
    // denotes a sentence number. A negative value defines an event number. Event numbers are the negatives of
    // the numbers displayed on the serial monitor. For example: MOVIEvent[200] would return -200.
    signed int poll();
    
    // Gets the result string of an event. For example: MOVIEvent[201]: LET THERE LIGHT results in "LET THERE BE
    // LIGHT\n". The resulting string might need trimming for comparison to other strings. The resulting string
    // is uppercase and does not contain any numbers, punctuation or special characters.
    String getResult();
    
    // Makes MOVI speak the sentence given as parameter using the speech synthesizer.
    void say(String sentence);
    
    #ifdef F // check to see if F() macro is available
    // say using Flash memory (e.g., say(F("Hello World");)
    void say(const __FlashStringHelper* sentence);
    #endif
    
    // Makes MOVI speak the sentence given as first parameter and then directly listen without requiring a
    // callsign.
    void ask(String question);
    
    #ifdef F // check to see if F() macro is available
    // ask, Flash memory version (e.g., ask(F("How are you?");)
    void ask(const __FlashStringHelper* question);
    #endif
    
    // Makes MOVI speak the sentence given as first parameter. Then MOVI's password function is used to query for
    // a password. The API compares the passkey with the password and return either PASSWORD_REJECT or
    // PASSWORD_ACCEPT as an event. The passkey is not transferred to or saved on the MOVI board.
    // IMPORTANT: The passkey must consist only of words contained in the trained sentences
    // and must not contain digits or other non-letter characters except one space between the words.
    void password(String question, String passkey);
    
    #ifdef F // check to see if F() macro is available
    // password, Flash memory version (e.g., ask(F("Password please",password);)
    void password(const __FlashStringHelper* question, String passkey);
    #endif
    
    // --- Infrequently used advanced commands ---
 
    // Sends a command manually to MOVI.
    void sendCommand(String command, String parameter);
    
    #ifdef F // check to see if F() macro is available
    // Sends a command manually to MOVI. Flash memory version for AVR
    void sendCommand(const __FlashStringHelper* command, const __FlashStringHelper* parameter);
    #endif
    
    // Returns MOVI's firmware version.
    float getFirmwareVersion();
    
    // Returns MOVI's board revision.
    float getHardwareVersion();
    
    // Returns the version of this API.
    float getAPIVersion();
    
    // Stops the recognizer and synthesizer.
    void stopDialog();
    
    // Restarts the recognizer and synthesizer manually.
    void restartDialog();
    
    // Resets MOVI to factory default. This method should only be used in setup() and only if needed. All trained
    // sentences and call signs are untrained. The preferable method for a factory reset is to use the serial
    // monitor.
    void factoryDefault();
    
    // Destructs the MOVI object
    ~MOVI();
    
    // --- private methods and variables ---
private:
    float hardwareversion; // stores hardware version
    float firmwareversion; // stores firmware version
    int shieldinit;        // stores the init state of the MOVI object
    bool callsigntrainok;  // makes sure callsign is only called once
    bool debug;            // debug allows serial monitor interfacing
    bool intraining;       // determines if training is ok
    bool firstsentence;    // determines if addSentence() has been called
    void construct(int rx, int tx, bool debugonoff); // workaround for non-functioning constructor overloading
    String passstring;      // stores the passkey for a password() request

    HardwareSerial *mySerial; // serial communication line as HardwareSerial for writing and sending data to the movi shield;

    
    String response; // stores the stream of serial communication characters
    String result;   // stores the last result for getResult()
    String getShieldResponse(); // used to communicate with the shield before poll()
    bool sendCommand(String command, String parameter, String okresponse); // sends a command and listens to responses. Only works before poll().
    
    #ifdef F // check to see if F() macro is available
    // Same as above, except Flash memory version
    bool sendCommand(const __FlashStringHelper* command, const __FlashStringHelper* parameter, String okresponse);
    #endif
    
};


#endif /* defined(____MOVIShield__) */