An implementation of the EasyVR communication protocol. More...

Public Types
enum	Baudrate { B115200 = 1, B57600 = 2, B38400 = 3, B19200 = 6, B9600 = 12 }
	Constants to use for baudrate settings. More...

enum	BridgeMode { BRIDGE_NONE, BRIDGE_NORMAL, BRIDGE_BOOT, BRIDGE_ESCAPE_CHAR = '?' }
	Type of Bridge mode requested. More...

enum	ClapSense { CLAP_SENSE_LOW = 0, CLAP_SENSE_MID = 1, CLAP_SENSE_HIGH = 2 }
	Hands-clap sensitivity for wakeup from sleep mode. More...

enum	CommandLatency { MODE_NORMAL, MODE_FAST }
	Latency settings used for recognition of custom commands or passwords (excluding the mixed trigger group) More...

enum	Distance { HEADSET = 1, ARMS_LENGTH, FAR_MIC }
	Microphone distance from the user's mouth, used by all recognition technologies. More...

enum	ErrorCode { ERR_DATACOL_TOO_LONG = 0x02, ERR_DATACOL_TOO_NOISY = 0x03, ERR_DATACOL_TOO_SOFT = 0x04, ERR_DATACOL_TOO_LOUD = 0x05, ERR_DATACOL_TOO_SOON = 0x06, ERR_DATACOL_TOO_CHOPPY = 0x07, ERR_DATACOL_BAD_WEIGHTS = 0x08, ERR_DATACOL_BAD_SETUP = 0x09, ERR_RECOG_FAIL = 0x11, ERR_RECOG_LOW_CONF = 0x12, ERR_RECOG_MID_CONF = 0x13, ERR_RECOG_BAD_TEMPLATE = 0x14, ERR_RECOG_BAD_WEIGHTS = 0x15, ERR_RECOG_DURATION = 0x17, ERR_T2SI_EXCESS_STATES = 0x21, ERR_T2SI_BAD_VERSION = 0x22, ERR_T2SI_OUT_OF_RAM = 0x23, ERR_T2SI_UNEXPECTED = 0x24, ERR_T2SI_OVERFLOW = 0x25, ERR_T2SI_PARAMETER = 0x26, ERR_T2SI_NN_TOO_BIG = 0x29, ERR_T2SI_NN_BAD_VERSION = 0x2A, ERR_T2SI_NN_NOT_READY = 0x2B, ERR_T2SI_NN_BAD_LAYERS = 0x2C, ERR_T2SI_TRIG_OOV = 0x2D, ERR_T2SI_TOO_SHORT = 0x2F, ERR_RP_BAD_LEVEL = 0x31, ERR_RP_NO_MSG = 0x38, ERR_RP_MSG_EXISTS = 0x39, ERR_SYNTH_BAD_VERSION = 0x4A, ERR_SYNTH_ID_NOT_SET = 0x4B, ERR_SYNTH_TOO_MANY_TABLES = 0x4C, ERR_SYNTH_BAD_SEN = 0x4D, ERR_SYNTH_BAD_MSG = 0x4E, ERR_CUSTOM_NOTA = 0x80, ERR_CUSTOM_INVALID = 0x81, ERR_SW_STACK_OVERFLOW = 0xC0, ERR_INTERNAL_T2SI_BAD_SETUP = 0xCC }
	Error codes used by various functions. More...

enum	GrammarFlag { GF_TRIGGER = 0x10 }
	Flags used by custom grammars. More...

enum	Group { TRIGGER = 0, PASSWORD = 16 }
	Special group numbers for recognition of custom commands. More...

enum	Knob { LOOSER, LOOSE, TYPICAL, STRICT, STRICTER }
	Confidence thresholds for the knob settings, used for recognition of built-in words or custom grammars (not used for the mixed trigger group) More...

enum	Language { ENGLISH, ITALIAN, JAPANESE, GERMAN, SPANISH, FRENCH }
	Language to use for recognition of built-in words. More...

enum	Level { EASY = 1, NORMAL, HARD, HARDER, HARDEST }
	Strictness values for the level settings, used for recognition of custom commands (not used for the mixed trigger group) More...

enum	LipsyncThreshold { RTLS_THRESHOLD_DEF = 270, RTLS_THRESHOLD_MAX = 1023 }
	Threshold for real-time lip-sync. More...

enum	MessageAttenuation { ATTEN_NONE, ATTEN_2DB2, ATTEN_4DB5, ATTEN_6DB7 }
	Playback attenuation for recorded messages. More...

enum	MessageSpeed { SPEED_NORMAL, SPEED_FASTER }
	Playback speed for recorded messages. More...

enum	MessageType { MSG_EMPTY = 0, MSG_8BIT = 8 }
	Type of recorded message. More...

enum	ModuleId { VRBOT, EASYVR, EASYVR2, EASYVR2_3, EASYVR3 = 8, EASYVR3_1, EASYVR3_2, EASYVR3_3, EASYVR3_4, EASYVR3_5, EASYVR3PLUS = 16 }
	Module identification number (firmware version) More...

enum	PinConfig { OUTPUT_LOW, OUTPUT_HIGH, INPUT_HIZ, INPUT_STRONG, INPUT_WEAK }
	Pin configuration options for the extra I/O connector. More...

enum	PinNumber { IO1 = 1, IO2 = 2, IO3 = 3, IO4 = 4, IO5 = 5, IO6 = 6 }
	Available pin numbers on the extra I/O connector. More...

enum	RejectionLevel { REJECTION_MIN, REJECTION_AVG, REJECTION_MAX }
	Noise rejection level for SonicNet token detection (higher value, fewer results) More...

enum	SoundIndex { BEEP = 0 }
	Special sound index values, always available even when no soundtable is present. More...

enum	SoundVolume { VOL_MIN = 0, VOL_HALF = 7, VOL_FULL = 15, VOL_DOUBLE = 31 }
	Some quick volume settings for the sound playback functions (any value in the range 0-31 can be used) More...

enum	TrailingSilence { TRAILING_MIN = 0, TRAILING_DEF = 12, TRAILING_MAX = 31, TRAILING_100MS = 0, TRAILING_200MS = 4, TRAILING_300MS = 8, TRAILING_400MS = 12, TRAILING_500MS = 16, TRAILING_600MS = 20, TRAILING_700MS = 24, TRAILING_800MS = 28 }
	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. More...

enum	WakeMode { WAKE_ON_CHAR = 0, WAKE_ON_WHISTLE = 1, WAKE_ON_LOUDSOUND = 2, WAKE_ON_2CLAPS = 3, WAKE_ON_3CLAPS = 6 }
	Constants for choosing wake-up method in sleep mode. More...

enum	Wordset { TRIGGER_SET, ACTION_SET, DIRECTION_SET, NUMBER_SET }
	Index of built-in word sets. More...

Public Member Functions
bool	addCommand (int8_t group, int8_t index)
	Adds a new custom command to a group. More...

void	bridgeLoop (Stream &port)
	Performs bridge mode between the EasyVR serial port and the specified port in a continuous loop. More...

int	bridgeRequested (Stream &port)
	Tests if bridge mode has been requested on the specified port. More...

bool	changeBaudrate (int8_t baud)
	Sets the new communication speed. More...

bool	checkMessages ()
	Performs a memory check for consistency. More...

bool	detect ()
	Detects an EasyVR module, waking it from sleep mode and checking it responds correctly. More...

void	detectToken (int8_t bits, int8_t rejection, uint16_t timeout)
	Starts listening for a SonicNet token. More...

bool	dumpCommand (int8_t group, int8_t index, char *name, uint8_t &training)
	Retrieves the name and training data of a custom command. More...

bool	dumpGrammar (int8_t grammar, uint8_t &flags, uint8_t &count)
	Retrieves the contents of a built-in or a custom grammar. More...

bool	dumpMessage (int8_t index, int8_t &type, int32_t &length)
	Retrieves the type and length of a recorded message. More...

bool	dumpSoundTable (char *name, int16_t &count)
	Retrieves the name of the sound table and the number of sounds it contains. More...

	EasyVR (Stream &s)
	Creates an EasyVR object, using a communication object implementing the #Stream interface (such as #HardwareSerial, or the modified #SoftwareSerial and #NewSoftSerial). More...

bool	embedToken (int8_t bits, uint8_t token, uint16_t delay)
	Schedules playback of a SonicNet token after the next sound starts playing. More...

bool	eraseCommand (int8_t group, int8_t index)
	Erases the training data of a custom command. More...

void	eraseMessageAsync (int8_t index)
	Erases a recorded message. More...

bool	exportCommand (int8_t group, int8_t index, uint8_t *data)
	Retrieves all internal data associated to a custom command. More...

bool	fetchMouthPosition (int8_t &value)
	Retrieves the current mouth position during lip-sync. More...

bool	fixMessages (bool wait=true)
	Performs a memory check and attempt recovery if necessary. More...

int8_t	getCommand ()
	Gets the recognised command index if any. More...

int8_t	getCommandCount (int8_t group)
	Gets the number of commands in the specified group. More...

int16_t	getError ()
	Gets the last error code if any. More...

int8_t	getGrammarsCount (void)
	Gets the total number of grammars available, including built-in and custom. More...

bool	getGroupMask (uint32_t &mask)
	Gets a bit mask of groups that contain at least one command. More...

int8_t	getID ()
	Gets the module identification number (firmware version). More...

bool	getNextWordLabel (char *name)
	Retrieves the name of a command contained in a custom grammar. More...

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. More...

int16_t	getToken ()
	Gets the index of the received SonicNet token if any. More...

int8_t	getWord ()
	Gets the recognised word index if any, from built-in sets or custom grammars. More...

bool	hasFinished ()
	Polls the status of on-going recognition, training or asynchronous playback tasks. More...

bool	importCommand (int8_t group, int8_t index, const uint8_t *data)
	Overwrites all internal data associated to a custom command. More...

bool	isAwakened ()
	Retrieves the wake-up indicator (only valid after hasFinished() has been called). More...

bool	isConflict ()
	Retrieves the conflict indicator. More...

bool	isInvalid ()
	Retrieves the invalid protocol indicator. More...

bool	isMemoryFull ()
	Retrieves the memory full indicator (only valid after addCommand() returned false). More...

bool	isTimeout ()
	Retrieves the timeout indicator. More...

void	playMessageAsync (int8_t index, int8_t speed, int8_t atten)
	Starts playback of a recorded message. More...

bool	playPhoneTone (int8_t tone, uint8_t duration)
	Plays a phone tone and waits for completion. More...

bool	playSound (int16_t index, int8_t volume)
	Plays a sound from the sound table and waits for completion. More...

void	playSoundAsync (int16_t index, int8_t volume)
	Starts playback of a sound from the sound table. More...

bool	realtimeLipsync (int16_t threshold, uint8_t timeout)
	Starts real-time lip-sync on the input voice signal. More...

void	recognizeCommand (int8_t group)
	Starts recognition of a custom command. More...

void	recognizeWord (int8_t wordset)
	Starts recognition of a built-in word. More...

void	recordMessageAsync (int8_t index, int8_t bits, int8_t timeout)
	Starts recording a message. More...

bool	removeCommand (int8_t group, int8_t index)
	Removes a custom command from a group. More...

bool	resetAll (bool wait=true)
	Empties internal memory for custom commands/groups and messages. More...

bool	resetCommands (bool wait=true)
	Empties internal memory for custom commands/groups only. More...

bool	resetMessages (bool wait=true)
	Empties internal memory used for messages only. More...

bool	sendToken (int8_t bits, uint8_t token)
	Plays a SonicNet token and waits for completion. More...

void	sendTokenAsync (int8_t bits, uint8_t token)
	Starts immediate playback of a SonicNet token. More...

bool	setCommandLabel (int8_t group, int8_t index, const char *name)
	Sets the name of a custom command. More...

bool	setCommandLatency (int8_t mode)
	Enables or disables fast recognition for custom commands and passwords. More...

bool	setDelay (uint16_t millis)
	Sets the delay before any reply of the module. More...

bool	setKnob (int8_t knob)
	Sets the confidence threshold to use for recognition of built-in words or custom grammars. More...

bool	setLanguage (int8_t lang)
	Sets the language to use for recognition of built-in words. More...

bool	setLevel (int8_t level)
	Sets the strictness level to use for recognition of custom commands. More...

bool	setMicDistance (int8_t dist)
	Sets the operating distance of the microphone. More...

bool	setPinOutput (int8_t pin, int8_t config)
	Configures an I/O pin as an output and sets its value. More...

bool	setTimeout (int8_t seconds)
	Sets the timeout to use for any recognition task. More...

bool	setTrailingSilence (int8_t dur)
	Sets the trailing silence duration for recognition of built-in words or custom grammars. More...

bool	sleep (int8_t mode)
	Puts the module in sleep mode. More...

bool	stop ()
	Interrupts pending recognition or playback operations. More...

void	trainCommand (int8_t group, int8_t index)
	Starts training of a custom command. More...

void	verifyCommand (int8_t group, int8_t index)
	Verifies training of a custom command (useful after import). More...

Detailed Description

An implementation of the EasyVR communication protocol.

Member Enumeration Documentation

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 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.

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 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 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 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 GrammarFlag

Flags used by custom grammars.

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

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 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 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 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 LipsyncThreshold

Threshold for real-time lip-sync.

Enumerator
RTLS_THRESHOLD_DEF	Default threshold.
RTLS_THRESHOLD_MAX	Maximum threshold.

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 MessageSpeed

Playback speed for recorded messages.

Enumerator
SPEED_NORMAL	Normal playback speed.
SPEED_FASTER	Faster playback speed.

enum MessageType

Type of recorded message.

Enumerator
MSG_EMPTY	Empty message slot.
MSG_8BIT	Message recorded with 8-bits PCM.

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 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 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 SoundIndex

Special sound index values, always available even when no soundtable is present.

Enumerator
BEEP	Beep sound.

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 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 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 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.

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

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)

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.

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

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

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

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

Return values

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.

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

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 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 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 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.

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

int16_t getError ( )

Gets the last error code if any.

Return values

(0-255) is the error code, (-1) if no error occurred

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

Gets the module identification number (firmware version).

Return values

integer is one of the values in ModuleId

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

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

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

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

bool hasFinished ( )

Polls the status of on-going recognition, training or asynchronous playback tasks.

Return values

true	if the operation has completed

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

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

Retrieves the invalid protocol indicator.

Return values

true	if an invalid sequence has been detected in the communication protocol

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

Retrieves the timeout indicator.

Return values

true	if a timeout occurred

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

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 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.

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

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

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

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

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

Return values

true	if the operation is successful

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

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

Interrupts pending recognition or playback operations.

Return values

true	if the request is satisfied and the module is back to ready

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

EasyVR-Arduino

Arduino library for the EasyVR Shield and EasyVR module

EasyVR Library 1.11.1

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation