The EasyVR library implements the serial communication protocol to manage the EasyVR module and the EasyVR Shield from Arduino boards and compatible controllers and it enables a quick access to all the EasyVR features.
Installation
To install the EasyVR library on your Arduino IDE use the menu Sketch > Include Library > Add .ZIP Library and open the release archive.
You can also use Sketch > Include Library > Manage Libraries… and look for “EasyVR” to download and install the latest release.
Examples
You can easily open the example sketches included with the EasyVR library from inside the Arduino IDE, using the menu File > Examples > EasyVR and choosing one of the available sketches.
EasyVR library settings
Macros
- #define EASYVR_RX_TIMEOUT
- #define EASYVR_STORAGE_TIMEOUT
- #define EASYVR_WAKE_TIMEOUT
- #define EASYVR_PLAY_TIMEOUT
- #define EASYVR_TOKEN_TIMEOUT
Detailed Description
By assigning new values to these symbols you can alter the default settings used by the library implementation.
These settings are available for completeness. The default values should be appropriate for normal use cases.
Macro Definition Documentation
#define EASYVR_RX_TIMEOUT
Receive timeout (in ms). The maximum time that is spent waiting for a reply from the EasyVR module.
#define EASYVR_STORAGE_TIMEOUT
Reply timeout for storage operations (in ms). The maximum time that is spent waiting for a reply after a command that involves write access to the EasyVR internal storage.
#define EASYVR_WAKE_TIMEOUT
Wakeup maximum delay (in ms). The maximum time that the EasyVR module can spend for waking up from idle states.
#define EASYVR_PLAY_TIMEOUT
Playback maximum duration (in ms). The maximum time that is spent waiting for a synchronous playback operation to complete. Asynchronous playback is not affected.
#define EASYVR_TOKEN_TIMEOUT
Token maximum duration (in ms). The maximum time that is spent by the EasyVR module for sending a SonicNet token and reply.
EasyVR Class Reference
Public Types
- enum ModuleId { VRBOT, EASYVR, EASYVR2, EASYVR2_3, EASYVR3, EASYVR3_1, EASYVR3_2,
EASYVR3_3, EASYVR3_4, EASYVR3_5, EASYVR3PLUS }
- enum Language { ENGLISH, ITALIAN, JAPANESE, GERMAN, SPANISH, FRENCH }
- enum Group { TRIGGER, PASSWORD }
- enum Wordset { TRIGGER_SET, ACTION_SET, DIRECTION_SET, NUMBER_SET }
- enum Distance { HEADSET, ARMS_LENGTH, FAR_MIC }
- enum Knob { LOOSER, LOOSE, TYPICAL, STRICT, STRICTER }
- enum Level { EASY, NORMAL, HARD, HARDER, HARDEST }
- enum TrailingSilence { TRAILING_MIN, TRAILING_DEF, TRAILING_MAX, TRAILING_100MS,
TRAILING_200MS, TRAILING_300MS, TRAILING_400MS, TRAILING_500MS, TRAILING_600MS,
TRAILING_700MS, TRAILING_800MS }
- enum CommandLatency { MODE_NORMAL, MODE_FAST }
- enum Baudrate { B115200, B57600, B38400, B19200, B9600 }
- enum WakeMode { WAKE_ON_CHAR, WAKE_ON_WHISTLE, WAKE_ON_LOUDSOUND, WAKE_ON_2CLAPS,
WAKE_ON_3CLAPS }
- enum ClapSense { CLAP_SENSE_LOW, CLAP_SENSE_MID, CLAP_SENSE_HIGH }
- enum PinConfig { OUTPUT_LOW, OUTPUT_HIGH, INPUT_HIZ, INPUT_STRONG, INPUT_WEAK }
- enum PinNumber { IO1, IO2, IO3, IO4, IO5, IO6 }
- enum SoundVolume { VOL_MIN, VOL_HALF, VOL_FULL, VOL_DOUBLE }
- enum SoundIndex { BEEP }
- enum GrammarFlag { GF_TRIGGER }
- enum RejectionLevel { REJECTION_MIN, REJECTION_AVG, REJECTION_MAX }
- enum MessageSpeed { SPEED_NORMAL, SPEED_FASTER }
- enum MessageAttenuation { ATTEN_NONE, ATTEN_2DB2, ATTEN_4DB5, ATTEN_6DB7 }
- enum MessageType { MSG_EMPTY, MSG_8BIT }
- enum LipsyncThreshold { RTLS_THRESHOLD_DEF, RTLS_THRESHOLD_MAX }
- enum ErrorCode { ERR_DATACOL_TOO_LONG, ERR_DATACOL_TOO_NOISY, ERR_DATACOL_TOO_SOFT,
ERR_DATACOL_TOO_LOUD, ERR_DATACOL_TOO_SOON, ERR_DATACOL_TOO_CHOPPY,
ERR_DATACOL_BAD_WEIGHTS, ERR_DATACOL_BAD_SETUP, ERR_RECOG_FAIL, ERR_RECOG_LOW_CONF,
ERR_RECOG_MID_CONF, ERR_RECOG_BAD_TEMPLATE, ERR_RECOG_BAD_WEIGHTS,
ERR_RECOG_DURATION, ERR_T2SI_EXCESS_STATES, ERR_T2SI_BAD_VERSION, ERR_T2SI_OUT_OF_RAM,
ERR_T2SI_UNEXPECTED, ERR_T2SI_OVERFLOW, ERR_T2SI_PARAMETER, ERR_T2SI_NN_TOO_BIG,
ERR_T2SI_NN_BAD_VERSION, ERR_T2SI_NN_NOT_READY, ERR_T2SI_NN_BAD_LAYERS,
ERR_T2SI_TRIG_OOV, ERR_T2SI_TOO_SHORT, ERR_RP_BAD_LEVEL, ERR_RP_NO_MSG,
ERR_RP_MSG_EXISTS, ERR_SYNTH_BAD_VERSION, ERR_SYNTH_ID_NOT_SET,
ERR_SYNTH_TOO_MANY_TABLES, ERR_SYNTH_BAD_SEN, ERR_SYNTH_BAD_MSG, ERR_CUSTOM_NOTA,
ERR_CUSTOM_INVALID, ERR_SW_STACK_OVERFLOW, ERR_INTERNAL_T2SI_BAD_SETUP }
- enum BridgeMode { BRIDGE_NONE, BRIDGE_NORMAL, BRIDGE_BOOT, BRIDGE_ESCAPE_CHAR }
Public Member Functions
- EasyVR (Stream &s)
- bool detect ()
- bool stop ()
- int8_t getID ()
- bool setLanguage (int8_t lang)
- bool setTimeout (int8_t seconds)
- bool setMicDistance (int8_t dist)
- bool setKnob (int8_t knob)
- bool setTrailingSilence (int8_t dur)
- bool setLevel (int8_t level)
- bool setCommandLatency (int8_t mode)
- bool setDelay (uint16_t millis)
- bool changeBaudrate (int8_t baud)
- bool sleep (int8_t mode)
· bool addCommand (int8_t group, int8_t index) - bool removeCommand (int8_t group, int8_t index)
- bool setCommandLabel (int8_t group, int8_t index, const char *name)
- bool eraseCommand (int8_t group, int8_t index)
- bool getGroupMask (uint32_t &mask)
- int8_t getCommandCount (int8_t group)
- bool dumpCommand (int8_t group, int8_t index, char *name, uint8_t &training)
- int8_t getGrammarsCount (void)
- bool dumpGrammar (int8_t grammar, uint8_t &flags, uint8_t &count)
- bool getNextWordLabel (char *name)
- void trainCommand (int8_t group, int8_t index)
- void recognizeCommand (int8_t group)
- void recognizeWord (int8_t wordset)
- bool hasFinished ()
- int8_t getCommand ()
- int8_t getWord ()
- int16_t getToken ()
- int16_t getError ()
- bool isTimeout ()
- bool isAwakened ()
- bool isConflict ()
- bool isMemoryFull ()
- bool isInvalid ()
- bool setPinOutput (int8_t pin, int8_t config)
- int8_t getPinInput (int8_t pin, int8_t config)
- void detectToken (int8_t bits, int8_t rejection, uint16_t timeout)
- void sendTokenAsync (int8_t bits, uint8_t token)
- bool sendToken (int8_t bits, uint8_t token)
- bool embedToken (int8_t bits, uint8_t token, uint16_t delay)
- void playSoundAsync (int16_t index, int8_t volume)
- bool playSound (int16_t index, int8_t volume)
- bool dumpSoundTable (char *name, int16_t &count)
- bool playPhoneTone (int8_t tone, uint8_t duration)
- bool resetAll (bool wait=true)
- bool resetCommands (bool wait=true)
- bool resetMessages (bool wait=true)
- bool checkMessages ()
- bool fixMessages (bool wait=true)
- void recordMessageAsync (int8_t index, int8_t bits, int8_t timeout)
- void playMessageAsync (int8_t index, int8_t speed, int8_t atten)
- void eraseMessageAsync (int8_t index)
- bool dumpMessage (int8_t index, int8_t &type, int32_t &length)
- bool realtimeLipsync (int16_t threshold, uint8_t timeout)
- bool fetchMouthPosition (int8_t &value)
- bool exportCommand (int8_t group, int8_t index, uint8_t *data)
- bool importCommand (int8_t group, int8_t index, const uint8_t *data)
- void verifyCommand (int8_t group, int8_t index)
- int bridgeRequested (Stream &port)
- void bridgeLoop (Stream &port)
Detailed Description
An implementation of the EasyVR communication protocol.
Member Enumeration Documentation
enum ModuleId
Module identification number (firmware version)
Enumerator
VRBOT Identifies a VRbot module
EASYVR Identifies an EasyVR module
EASYVR2 Identifies an EasyVR module version 2
EASYVR2_3 Identifies an EasyVR module version 2, firmware revision 3
EASYVR3 Identifies an EasyVR module version 3, firmware revision 0
EASYVR3_1 Identifies an EasyVR module version 3, firmware revision 1
EASYVR3_2 Identifies an EasyVR module version 3, firmware revision 2
EASYVR3_3 Identifies an EasyVR module version 3, firmware revision 3
EASYVR3_4 Identifies an EasyVR module version 3, firmware revision 4
EASYVR3_5 Identifies an EasyVR module version 3, firmware revision 5
EASYVR3PLUS Identifies an EasyVR module version 3+, firmware revision 0
enum Language
Language to use for recognition of built-in words
Enumerator
ENGLISH Uses the US English word sets
ITALIAN Uses the Italian word sets
JAPANESE Uses the Japanese word sets
GERMAN Uses the German word sets
SPANISH Uses the Spanish word sets
FRENCH Uses the French word sets
enum Group
Special group numbers for recognition of custom commands
Enumerator
TRIGGER The trigger group (shared with built-in trigger word)
PASSWORD The password group (uses speaker verification technology)
enum Wordset
Index of built-in word sets
Enumerator
TRIGGER_SET The built-in trigger word set
ACTION_SET The built-in action word set
DIRECTION_SET The built-in direction word set
NUMBER_SET The built-in number word set
enum Distance
Microphone distance from the user’s mouth, used by all recognition technologies
Enumerator
HEADSET Nearest range (around 5cm)
ARMS_LENGTH Medium range (from about 50cm to 1m)
FAR_MIC Farthest range (up to 3m)
enum Knob
Confidence thresholds for the knob settings, used for recognition of built-in words or custom
grammars (not used for the mixed trigger group)
Enumerator
LOOSER Lowest threshold, most results reported
LOOSE Lower threshold, more results reported
TYPICAL Typical threshold (default)
STRICT Higher threshold, fewer results reported
STRICTER Highest threshold, fewest results reported
enum Level
Strictness values for the level settings, used for recognition of custom commands (not used for the
mixed trigger group)
Enumerator
EASY Lowest value, most results reported
NORMAL Typical value (default)
HARD Slightly higher value, fewer results reported
HARDER Higher value, fewer results reported
HARDEST Highest value, fewest results reported
enum TrailingSilence
Trailing silence settings used for recognition of built-in words or custom grammars (including the
mixed trigger group), in a range from 100ms to 875ms in steps of 25ms.
Enumerator
TRAILING_MIN Lowest value (100ms), minimum latency
TRAILING_DEF Default value (400ms) after power on or reset
TRAILING_MAX Highest value (875ms), maximum latency
TRAILING_100MS Silence duration is 100ms
TRAILING_200MS Silence duration is 200ms
TRAILING_300MS Silence duration is 300ms
TRAILING_400MS Silence duration is 400ms
TRAILING_500MS Silence duration is 500ms
TRAILING_600MS Silence duration is 600ms
TRAILING_700MS Silence duration is 700ms
TRAILING_800MS Silence duration is 800ms
enum CommandLatency
Latency settings used for recognition of custom commands or passwords (excluding the mixed trigger
group)
Enumerator
MODE_NORMAL Normal settings (default), higher latency
MODE_FAST Fast settings, better response time
enum Baudrate
Constants to use for baudrate settings
Enumerator
B115200 115200 bps
B57600 57600 bps
B38400 38400 bps
B19200 19200 bps
B9600 9600 bps (default)
enum WakeMode
Constants for choosing wake-up method in sleep mode
Enumerator
WAKE_ON_CHAR Wake up on any character received
WAKE_ON_WHISTLE Wake up on whistle or any character received
WAKE_ON_LOUDSOUND Wake up on a loud sound or any character received
WAKE_ON_2CLAPS Wake up on double hands-clap or any character received
WAKE_ON_3CLAPS Wake up on triple hands-clap or any character received
enum ClapSense
Hands-clap sensitivity for wakeup from sleep mode. Use in combination with WAKE_ON_2CLAPS or
WAKE_ON_3CLAPS
Enumerator
CLAP_SENSE_LOW Lowest threshold
CLAP_SENSE_MID Typical threshold
CLAP_SENSE_HIGH Highest threshold
enum PinConfig
Pin configuration options for the extra I/O connector
Enumerator
OUTPUT_LOW Pin is an output at low level (0V)
OUTPUT_HIGH Pin is an output at high level (3V)
INPUT_HIZ Pin is an high impedance input
INPUT_STRONG Pin is an input with strong pull-up (~10K)
INPUT_WEAK Pin is an input with weak pull-up (~200K)
enum PinNumber
Available pin numbers on the extra I/O connector
Enumerator
IO1 Identifier of pin IO1
IO2 Identifier of pin IO2
IO3 Identifier of pin IO3
IO4 Identifier of pin IO4 [only EasyVR3]
IO5 Identifier of pin IO5 [only EasyVR3]
IO6 Identifier of pin IO6 [only EasyVR3]
enum SoundVolume
Some quick volume settings for the sound playback functions (any value in the range 0-31 can be used)
Enumerator
VOL_MIN Lowest volume (almost mute)
VOL_HALF Half scale volume (softer)
VOL_FULL Full scale volume (normal)
VOL_DOUBLE Double gain volume (louder)
enum SoundIndex
Special sound index values, always available even when no soundtable is present
Enumerator
BEEP Beep sound
enum GrammarFlag
Flags used by custom grammars
Enumerator
GF_TRIGGER A bit mask that indicate grammar is a trigger (opposed to commands)
enum RejectionLevel
Noise rejection level for SonicNet token detection (higher value, fewer results)
Enumerator
REJECTION_MIN Lowest noise rejection, highest sensitivity
REJECTION_AVG Medium noise rejection, medium sensitivity
REJECTION_MAX Highest noise rejection, lowest sensitivity
enum MessageSpeed
Playback speed for recorded messages
Enumerator
SPEED_NORMAL Normal playback speed
SPEED_FASTER Faster playback speed
enum MessageAttenuation
Playback attenuation for recorded messages
Enumerator
ATTEN_NONE No attenuation (normalized volume)
ATTEN_2DB2 Attenuation of -2.2dB
ATTEN_4DB5 Attenuation of -4.5dB
ATTEN_6DB7 Attenuation of -6.7dB
enum MessageType
Type of recorded message
Enumerator
MSG_EMPTY Empty message slot
MSG_8BIT Message recorded with 8-bits PCM
enum LipsyncThreshold
Threshold for real-time lip-sync
Enumerator
RTLS_THRESHOLD_DEF Default threshold
RTLS_THRESHOLD_MAX Maximum threshold
enum ErrorCode
Error codes used by various functions
Enumerator
ERR_DATACOL_TOO_LONG too long (memory overflow)
ERR_DATACOL_TOO_NOISY too noisy
ERR_DATACOL_TOO_SOFT spoke too soft
ERR_DATACOL_TOO_LOUD spoke too loud
ERR_DATACOL_TOO_SOON spoke too soon
ERR_DATACOL_TOO_CHOPPY too many segments/too complex
ERR_DATACOL_BAD_WEIGHTS invalid SI weights
ERR_DATACOL_BAD_SETUP invalid setup
ERR_RECOG_FAIL recognition failed
ERR_RECOG_LOW_CONF recognition result doubtful
ERR_RECOG_MID_CONF recognition result maybe
ERR_RECOG_BAD_TEMPLATE invalid SD/SV template
ERR_RECOG_BAD_WEIGHTS invalid SI weights
ERR_RECOG_DURATION incompatible pattern durations
ERR_T2SI_EXCESS_STATES state structure is too big
ERR_T2SI_BAD_VERSION RSC code version/Grammar ROM dont match
ERR_T2SI_OUT_OF_RAM reached limit of available RAM
ERR_T2SI_UNEXPECTED an unexpected error occurred
ERR_T2SI_OVERFLOW ran out of time to process
ERR_T2SI_PARAMETER bad macro or grammar parameter
ERR_T2SI_NN_TOO_BIG layer size out of limits
ERR_T2SI_NN_BAD_VERSION net structure incompatibility
ERR_T2SI_NN_NOT_READY initialization not complete
ERR_T2SI_NN_BAD_LAYERS not correct number of layers
ERR_T2SI_TRIG_OOV trigger recognized Out Of Vocabulary
ERR_T2SI_TOO_SHORT utterance was too short
ERR_RP_BAD_LEVEL play – illegal compression level
ERR_RP_NO_MSG play, erase, copy – msg doesn’t exist
ERR_RP_MSG_EXISTS rec, copy – msg already exists
ERR_SYNTH_BAD_VERSION bad release number in speech file
ERR_SYNTH_ID_NOT_SET (obsolete) bad sentence structure
ERR_SYNTH_TOO_MANY_TABLES (obsolete) too many talk tables
ERR_SYNTH_BAD_SEN (obsolete) bad sentence number
ERR_SYNTH_BAD_MSG bad message data or SX technology files missing
ERR_CUSTOM_NOTA none of the above (out of grammar)
ERR_CUSTOM_INVALID invalid data (for memory check)
ERR_SW_STACK_OVERFLOW no room left in software stack
ERR_INTERNAL_T2SI_BAD_SETUP T2SI test mode error
enum BridgeMode
Type of Bridge mode requested
Enumerator
BRIDGE_NONE Bridge mode has not been requested
BRIDGE_NORMAL Normal bridge mode (EasyVR baudrate 9600)
BRIDGE_BOOT Bridge mode for EasyVR bootloader (baudrate 115200)
BRIDGE_ESCAPE_CHAR Special character to enter/exit Bridge mode
Constructor & Destructor Documentation
EasyVR (Stream & s)
Creates an EasyVR object, using a communication object implementing the #Stream interface (such as
#HardwareSerial, or the modified #SoftwareSerial and #NewSoftSerial).
Parameters:
| s | the Stream object to use for communication with the EasyVR module |
Member Function Documentation
bool detect ()
Detects an EasyVR module, waking it from sleep mode and checking it responds correctly.
Return values:
| true | if a compatible module has been found |
bool stop ()
Interrupts pending recognition or playback operations.
Return values:
| true | if the request is satisfied and the module is back to ready |
int8_t getID ()
Gets the module identification number (firmware version).
Return values:
| integer | is one of the values in ModuleId |
bool setLanguage (int8_t lang)
Sets the language to use for recognition of built-in words.
Parameters:
| lang | (0-5) is one of values in Language |
Return values:
| true | if the operation is successful |
bool setTimeout (int8_t seconds)
Sets the timeout to use for any recognition task.
Parameters:
| seconds | (0-31) is the maximum time the module keep listening for a word or a command |
Return values:
| true | if the operation is successful |
bool setMicDistance (int8_t dist)
Sets the operating distance of the microphone. This setting represents the distance between the
microphone and the user’s mouth, in one of three possible configurations.
Parameters:
| dist | (1-3) is one of values in Distance |
Parameters:
| true | if the operation is successful |
bool setKnob (int8_t knob)
Sets the confidence threshold to use for recognition of built-in words or custom grammars.
Parameters:
| knob | (0-4) is one of values in Knob |
Return values:
| true | if the operation is successful |
bool setTrailingSilence (int8_t dur)
Sets the trailing silence duration for recognition of built-in words or custom grammars.
Parameters:
| dur | (0-31) is the silence duration as defined in TrailingSilence |
Return values:
| true | if the operation is successful |
bool setLevel (int8_t level)
Sets the strictness level to use for recognition of custom commands.
Parameters:
| level | (1-5) is one of values in Level |
Return values:
| true | if the operation is successful |
bool setCommandLatency (int8_t mode)
Enables or disables fast recognition for custom commands and passwords. Fast SD/SV recognition can
improve response time.
Parameters:
| mode | (0-1) is one of the values in CommandLatency |
Return values:
| true | if the operation is successful |
bool setDelay (uint16_t millis)
Sets the delay before any reply of the module.
Parameters:
| millis | (0-1000) is the delay duration in milliseconds, rounded to 10 units in range 10-100 and to 100 units in range 100-1000. |
Return values:
| true | if the operation is successful |
bool changeBaudrate (int8_t baud)
Sets the new communication speed. You need to modify the baudrate of the underlying Stream object
accordingly, after the function returns successfully.
Parameters:
| baud | is one of values in Baudrate |
Return values:
| true | if the operation is successful |
bool sleep (int8_t mode)
Puts the module in sleep mode.
Parameters:
| mode | is one of values in WakeMode, optionally combined with one of the values in ClapSense |
Return values:
| true | if the operation is successful |
bool addCommand (int8_t group, int8_t index)
Adds a new custom command to a group.
Parameters:
| group | (0-16) is the target group, or one of the values in #Groups |
| index | (0-31) is the index of the command within the selected group |
Return values:
| true | if the operation is successful |
bool removeCommand (int8_t group, int8_t index)
Removes a custom command from a group.
Parameters:
| group | (0-16) is the target group, or one of the values in #Groups |
| index | (0-31) is the index of the command within the selected group |
Return values:
| true | if the operation is successful |
bool setCommandLabel (int8_t group, int8_t index, const char * name)
Sets the name of a custom command.
Parameters:
| group | (0-16) is the target group, or one of the values in #Groups |
| index | (0-31) is the index of the command within the selected group |
| name | is a string containing the label to be assigned to the specified command |
Return values:
| true | if the operation is successful |
bool eraseCommand (int8_t group, int8_t index)
Erases the training data of a custom command.
Parameters:
| group | (0-16) is the target group, or one of the values in #Groups |
| index | (0-31) is the index of the command within the selected group |
Return values:
| true | if the operation is successful |
bool getGroupMask (uint32_t & mask)
Gets a bit mask of groups that contain at least one command.
Parameters:
| mask | is a variable to hold the group mask when the function returns |
Return values:
| true | if the operation is successful |
int8_t getCommandCount (int8_t group)
Gets the number of commands in the specified group.
Parameters:
| group | (0-16) is the target group, or one of the values in #Groups |
Return values:
| integer | is the count of commands (negative in case of errors) |
bool dumpCommand (int8_t group, int8_t index, char * name, uint8_t & training)
Retrieves the name and training data of a custom command.
Parameters:
| group | (0-16) is the target group, or one of the values in #Groups |
| index | (0-31) is the index of the command within the selected group |
| name | points to an array of at least 32 characters that holds the command label when the function returns |
| training | is a variable that holds the training count when the function returns. Additional information about training is available through the functions isConflict() and getWord() or getCommand() |
Return values:
| true | if the operation is successful |
int8_t getGrammarsCount (void )
Gets the total number of grammars available, including built-in and custom.
Return values:
| integer | is the count of grammars (negative in case of errors) |
bool dumpGrammar (int8_t grammar, uint8_t & flags, uint8_t & count)
Retrieves the contents of a built-in or a custom grammar. Command labels contained in the grammar
can be obtained by calling getNextWordLabel()
Parameters:
| grammar | (0-31) is the target grammar, or one of the values in Wordset |
| flags | is a variable that holds some grammar flags when the function returns. See GrammarFlag |
| count | is a variable that holds the number of words in the grammar when the function returns. |
Return values:
| true | if the operation is successful |
bool getNextWordLabel (char * name)
Retrieves the name of a command contained in a custom grammar. It must be called after
dumpGrammar()
Parameters:
| name | points to an array of at least 32 characters that holds the command label when the function returns |
Return values:
| true | if the operation is successful |
void trainCommand (int8_t group, int8_t index)
Starts training of a custom command. Results are available after hasFinished() returns true.
Parameters:
| group | (0-16) is the target group, or one of the values in #Groups |
| index | (0-31) is the index of the command within the selected group |
Note:
The module is busy until training completes and it cannot accept other commands. You can interrupt training with stop().
void recognizeCommand (int8_t group)
Starts recognition of a custom command. Results are available after hasFinished() returns true.
Parameters:
| group | (0-16) is the target group, or one of the values in #Groups |
Note:
The module is busy until recognition completes and it cannot accept other commands. You can interrupt recognition with stop().
void recognizeWord (int8_t wordset)
Starts recognition of a built-in word. Results are available after hasFinished() returns true.
Parameters:
| wordset | (0-3) is the target word set, or one of the values in Wordset, (4-31) is the target custom grammar, if present |
Note:
The module is busy until recognition completes and it cannot accept other commands. You can interrupt recognition with stop().
bool hasFinished ()
Polls the status of on-going recognition, training or asynchronous playback tasks.
Return values:
| true | if the operation has completed |
int8_t getCommand ()
Gets the recognised command index if any.
Return values:
| (0-31) | is the command index if recognition is successful, (-1) if no command has been recognized or an error occurred |
int8_t getWord ()
Gets the recognised word index if any, from built-in sets or custom grammars.
Return values:
| (0-31) | is the command index if recognition is successful, (-1) if no built-in word has been recognized or an error occurred |
int16_t getToken ()
Gets the index of the received SonicNet token if any.
Return values:
| integer | is the index of the received SonicNet token (0-255 for 8-bit tokens or 0-15 for 4-bit tokens) if detection was successful, (-1) if no token has been received or an error occurred |
int16_t getError ()
Gets the last error code if any.
Return values:
| (0-255) | is the error code, (-1) if no error occurred |
bool isTimeout ()
Retrieves the timeout indicator.
Return values:
| true | if a timeout occurred |
bool isAwakened ()
Retrieves the wake-up indicator (only valid after hasFinished() has been called).
Return values:
| true | if the module has been awakened from sleep mode |
bool isConflict ()
Retrieves the conflict indicator.
Return values:
| true | is a conflict occurred during training. To know what caused the conflict, use getCommand() and getWord() (only valid for triggers) |
bool isMemoryFull ()
Retrieves the memory full indicator (only valid after addCommand() returned false).
Return values:
| true | if a command could not be added because of memory size constaints (up to 32 custom commands can be created) |
bool isInvalid ()
Retrieves the invalid protocol indicator.
Return values:
| true | if an invalid sequence has been detected in the communication protocol |
bool setPinOutput (int8_t pin, int8_t config)
Configures an I/O pin as an output and sets its value
Parameters:
| pin | (1-3) is one of the values in PinNumber |
| config | (0-1,5-6) is one of the output values in PinConfig (OUTPUT_LOW, OUTPUT_HIGH) or Arduino style HIGH and LOW macros |
Return values:
| true | if the operation is successful |
int8_t getPinInput (int8_t pin, int8_t config)
Configures an I/O pin as an input with optional pull-up and return its value
Parameters:
| pin | (1-3) is one of the values in PinNumber |
| config | (2-4) is one of the input values in PinConfig (INPUT_HIZ, INPUT_STRONG, INPUT_WEAK) |
Return values:
| integer | is the logical value of the pin |
void detectToken (int8_t bits, int8_t rejection, uint16_t timeout)
Starts listening for a SonicNet token. Manually check for completion with hasFinished().
Parameters:
| bits | (4 or 8) specifies the length of received tokens |
| rejection | (0-2) specifies the noise rejection level, it can be one of the values in RejectionLevel |
| timeout | (1-28090) is the maximum time in milliseconds to keep listening for a valid token or (0) to listen without time limits. |
Note:
The module is busy until token detection completes and it cannot accept other commands. You
can interrupt listening with stop().
void sendTokenAsync (int8_t bits, uint8_t token)
Starts immediate playback of a SonicNet token. Manually check for completion with hasFinished().
Parameters:
| bits | (4 or 8) specifies the length of trasmitted token |
| token | is the index of the SonicNet token to play (0-255 for 8-bit tokens or 0-15 for 4-bit tokens) |
Note:
The module is busy until playback completes and it cannot accept other commands. You can
interrupt playback with stop().
bool sendToken (int8_t bits, uint8_t token)
Plays a SonicNet token and waits for completion.
Parameters:
| bits | (4 or 8) specifies the length of trasmitted token |
| token | is the index of the SonicNet token to play (0-255 for 8-bit tokens or 0-15 for 4-bit tokens) |
Return values:
| true | if the operation is successful |
bool embedToken (int8_t bits, uint8_t token, uint16_t delay)
Schedules playback of a SonicNet token after the next sound starts playing.
Parameters:
Return values:
| bits | (4 or 8) specifies the length of trasmitted token |
| token | is the index of the SonicNet token to play (0-255 for 8-bit tokens or 0-15 for 4-bit tokens) |
| delay | (1-28090) is the time in milliseconds at which to send the token, since the beginning of the next sound playback |
| true | if the operation is successful |
Note:
The scheduled token remains valid for one operation only, so you have to call playSound() or
playSoundAsync() immediately after this function.
void playSoundAsync (int16_t index, int8_t volume)
Starts playback of a sound from the sound table. Manually check for completion with hasFinished().
Parameters:
| index | is the index of the target sound in the sound table |
| volume | (0-31) may be one of the values in SoundVolume |
Note:
The module is busy until playback completes and it cannot accept other commands. You can
interrupt playback with stop().
bool playSound (int16_t index, int8_t volume)
Plays a sound from the sound table and waits for completion
Parameters:
| index | is the index of the target sound in the sound table |
| volume | (0-31) may be one of the values in SoundVolume |
Return values:
| true | if the operation is successful |
Note:
To alter the maximum time for the wait, define the EASYVR_PLAY_TIMEOUT macro before
including the EasyVR library.
bool dumpSoundTable (char * name, int16_t & count)
Retrieves the name of the sound table and the number of sounds it contains
Parameters:
| name | points to an array of at least 32 characters that holds the sound table label when the function returns |
| count | is a variable that holds the number of sounds when the function returns |
Return values:
| true | if the operation is successful |
bool playPhoneTone (int8_t tone, uint8_t duration)
Plays a phone tone and waits for completion
Parameters:
| tone | is the index of the tone (0-9 for digits, 10 for ‘*’ key, 11 for ‘#’ key and 12-15 for extra keys ‘A’ to ‘D’, -1 for the dial tone) |
| duration | (1-32) is the tone duration in 40 milliseconds units, or in seconds for the dial tone |
Return values:
| true | if the operation is successful |
bool resetAll (bool wait = true)
Empties internal memory for custom commands/groups and messages.
Parameters:
| wait | specifies whether to wait until the operation is complete (or times out) |
Return values:
| true | if the operation is successful |
Note:
It will take some time for the whole process to complete (EasyVR3 is faster) and it cannot be interrupted. During this time the module cannot accept any other command. The sound table and custom grammars data is not affected.
bool resetCommands (bool wait = true)
Empties internal memory for custom commands/groups only. Messages are not affected.
Parameters:
| wait | specifies whether to wait until the operation is complete (or times out) |
Return values:
| true | if the operation is successful |
Note:
It will take some time for the whole process to complete (EasyVR3 is faster) and it cannot be
interrupted. During this time the module cannot accept any other command. The sound table and
custom grammars data is not affected.
bool resetMessages (bool wait = true)
Empties internal memory used for messages only. Commands/groups are not affected.
Parameters:
| wait | specifies whether to wait until the operation is complete (or times out) |
Return values:
| true | if the operation is successful |
Note:
It will take some time for the whole process to complete (EasyVR3 is faster) and it cannot be
interrupted. During this time the module cannot accept any other command. The sound table and
custom grammars data is not affected.
bool checkMessages ()
Performs a memory check for consistency.
Return values:
| true | if the operation is successful |
Note:
If a memory write or erase operation does not complete due to unexpected conditions, like power
losses, the memory contents may be corrupted. When the check fails getError() returns
ERR_CUSTOM_INVALID.
bool fixMessages (bool wait = true)
Performs a memory check and attempt recovery if necessary. Incomplete data will be erased. Custom
commands/groups are not affected.
Parameters:
| wait | specifies whether to wait until the operation is complete (or times out) |
Return values:
| true | if the operation is successful |
Note:
It will take some time for the whole process to complete (several seconds) and it cannot be interrupted. During this time the module cannot accept any other command. The sound table and custom grammars data is not affected.
void recordMessageAsync (int8_t index, int8_t bits, int8_t timeout)
Starts recording a message. Manually check for completion with hasFinished().
Parameters:
| index | (0-31) is the index of the target message slot |
| bits | (8) specifies the audio format (see MessageType) |
| timeout | (0-31) is the maximum recording time (0=infinite) |
Note:
The module is busy until recording times out or the end of memory is reached. You can interrupt
an ongoing recording with stop().
void playMessageAsync (int8_t index, int8_t speed, int8_t atten)
Starts playback of a recorded message. Manually check for completion with hasFinished().
Parameters:
| index | (0-31) is the index of the target message slot |
| speed | (0-1) may be one of the values in MessageSpeed |
| atten | (0-3) may be one of the values in MessageAttenuation |
Note:
The module is busy until playback completes and it cannot accept other commands. You can
interrupt playback with stop().
void eraseMessageAsync (int8_t index)
Erases a recorded message. Manually check for completion with hasFinished().
Parameters:
| index | (0-31) is the index of the target message slot |
bool dumpMessage (int8_t index, int8_t & type, int32_t & length)
Retrieves the type and length of a recorded message
Parameters:
| index | (0-31) is the index of the target message slot |
| type | (0,8) is a variable that holds the message format when the function returns (see MessageType) |
| length | is a variable that holds the message length in bytes when the function returns |
Return values:
| true | if the operation is successful |
Note:
The specified message may have errors. Use getError() when the function fails, to know the reason of the failure.
bool realtimeLipsync (int16_t threshold, uint8_t timeout)
Starts real-time lip-sync on the input voice signal. Retrieve output values with fetchMouthPosition() or
abort with stop().
Parameters:
| threshold | (0-1023) is a measure of the strength of the input signal below which the mouth is considered to be closed (see LipsyncThreshold, adjust based on microphone settings, distance and background noise) |
| timeout | (0-255) is the maximum duration of the function in seconds, 0 means infinite |
Return values:
| true | if the operation is successfully started |
bool fetchMouthPosition (int8_t & value)
Retrieves the current mouth position during lip-sync.
Parameters:
| value | (0-31) is filled in with the current mouth opening position |
Return values:
| true | if the operation is successful, false if lip-sync has finished |
bool exportCommand (int8_t group, int8_t index, uint8_t * data)
Retrieves all internal data associated to a custom command.
Parameters:
| group | (0-16) is the target group, or one of the values in #Groups |
| index | (0-31) is the index of the command within the selected group |
| data | points to an array of at least 258 bytes that holds the command raw data |
Return values:
| true | if the operation is successful |
bool importCommand (int8_t group, int8_t index, const uint8_t * data)
Overwrites all internal data associated to a custom command. When commands are imported this way,
their training should be tested again with verifyCommand()
Parameters:
| group | (0-16) is the target group, or one of the values in #Groups |
| index | (0-31) is the index of the command within the selected group |
| data | points to an array of at least 258 bytes that holds the command raw data |
Return values:
| true | if the operation is successful |
void verifyCommand (int8_t group, int8_t index)
Verifies training of a custom command (useful after import). Similarly to trainCommand(), you should
check results after hasFinished() returns true
Parameters:
| group | (0-16) is the target group, or one of the values in #Groups |
| index | (0-31) is the index of the command within the selected group |
int bridgeRequested (Stream & port)
Tests if bridge mode has been requested on the specified port
Parameters:
| port | is the target serial port (usually the PC serial port) |
Return values:
non zero if bridge mode should be started
Note:
The EasyVR Commander software can request bridge mode when connected to the specified serial port, with a special handshake sequence.
void bridgeLoop (Stream & port)
Performs bridge mode between the EasyVR serial port and the specified port in a continuous loop. It
can be aborted by sending a question mark (‘?’) on the target port.
Parameters:
| port | is the target serial port (usually the PC serial port) |