EasyVR Library  1.3
Public Types | Public Member Functions
EasyVR Class Reference

Public Types

enum  ModuleId {
  VRBOT,
  EASYVR,
  EASYVR2
}
enum  Language {
  ENGLISH,
  ITALIAN,
  JAPANESE,
  GERMAN,
  SPANISH,
  FRENCH
}
enum  Group {
  TRIGGER,
  PASSWORD
}
enum  Wordset {
  TRIGGER_SET,
  ACTION_SET,
  DIRECTION_SET,
  NUMBER_SET
}
enum  Knob {
  LOOSER,
  LOOSE,
  TYPICAL,
  STRICT,
  STRICTER
}
enum  Level {
  EASY,
  NORMAL,
  HARD,
  HARDER,
  HARDEST
}
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
}
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  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_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_SW_STACK_OVERFLOW,
  ERR_INTERNAL_T2SI_BAD_SETUP
}

Public Member Functions

 EasyVR (Stream &s)
bool detect ()
bool stop ()
int8_t getID ()
bool setLanguage (int8_t lang)
bool setTimeout (int8_t seconds)
bool setKnob (int8_t knob)
bool setLevel (int8_t level)
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 isConflict ()
bool isMemoryFull ()
bool setPinOutput (int8_t pin, int8_t value)
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 ()

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

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 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 (deafult)

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 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 a low output (0V)

OUTPUT_HIGH 

Pin is a high output (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 

Pin IO1

IO2 

Pin IO2

IO3 

Pin IO3

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

Flags used by custom grammars

Enumerator:
GF_TRIGGER 

A bit mask that indicate grammar is a trigger (opposed to commands)

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 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_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_SW_STACK_OVERFLOW 

no room left in software stack

ERR_INTERNAL_T2SI_BAD_SETUP 

T2SI test mode error


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:
sthe 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:
trueif a compatible module has been found
bool stop ( )

Interrupts pending recognition or playback operations.

Return values:
trueif the request is satisfied and the module is back to ready
int8_t getID ( )

Gets the module identification number (firmware version).

Return values:
integeris 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:
trueif 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:
trueif the operation is successful
bool setKnob ( int8_t  knob)

Sets the confidence threshold to use for recognition of built-in words.

Parameters:
knob(0-4) is one of values in Knob
Return values:
trueif 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:
trueif 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:
trueif 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:
baudis one of values in Baudrate
Return values:
trueif the operation is successful
bool sleep ( int8_t  mode)

Puts the module in sleep mode.

Parameters:
modeis one of values in WakeMode, optionally combined with one of the values in ClapSense
Return values:
trueif 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:
trueif 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:
trueif 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
Return values:
trueif 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
nameis a string containing the label to be assigned to the specified command
Return values:
trueif the operation is successful
bool getGroupMask ( uint32_t &  mask)

Gets a bit mask of groups that contain at least one command.

Parameters:
maskis a variable to hold the group mask when the function returns
Return values:
trueif 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:
integeris 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
namepoints to an array of at least 32 characters that holds the command label when the function returns
trainingis 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:
trueif the operation is successful
int8_t getGrammarsCount ( void  )

Gets the total number of grammars available, including built-in and custom.

Return values:
integeris 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
flagsis a variable that holds some grammar flags when the function returns. See GrammarFlag
countis a variable that holds the number of words in the grammar when the function returns.
Return values:
trueif 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:
namepoints to an array of at least 32 characters that holds the command label when the function returns
Return values:
trueif 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:
trueif 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:
integeris 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:
trueif a timeout occurred
bool isConflict ( )

Retrieves the conflict indicator.

Return values:
trueis 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:
trueif a command could not be added because of memory size constaints (up to 32 custom commands can be created)
bool setPinOutput ( int8_t  pin,
int8_t  value 
)

Configures an I/O pin as an output and sets its value

Parameters:
pin(1-3) is one of values in PinNumber
pin(0-1) is one of the output values in PinConfig, or Arduino style HIGH and LOW macros
Return values:
trueif 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 values in PinNumber
pin(2-4) is one of the input values in PinConfig
Return values:
integeris 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
tokenis 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
tokenis the index of the SonicNet token to play (0-255 for 8-bit tokens or 0-15 for 4-bit tokens)
Return values:
trueif 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:
bits(4 or 8) specifies the length of trasmitted token
tokenis 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
Return values:
trueif 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:
indexis 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:
indexis the index of the target sound in the sound table
volume(0-31) may be one of the values in SoundVolume
Return values:
trueif 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:
namepoints to an array of at least 32 characters that holds the sound table label when the function returns
countis a variable that holds the number of sounds when the function returns
Return values:
trueif the operation is successful
bool playPhoneTone ( int8_t  tone,
uint8_t  duration 
)

Plays a phone tone and waits for completion

Parameters:
toneis 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:
trueif the operation is successful
bool resetAll ( )

Empties internal memory for custom commands and groups.

Return values:
trueif the operation is successful
Note:
It will take about 35 seconds for the whole process to complete 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.